{"_id":"@cratetf/item-url-codec","name":"@cratetf/item-url-codec","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@cratetf/item-url-codec","version":"1.0.0","description":"Canonical Crate.tf item URL generation and TF2 SKU path parsing.","license":"MIT","author":{"name":"CrateTF"},"type":"module","sideEffects":false,"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./test-vectors.json":"./test-vectors.json"},"scripts":{"build":"tsc -p tsconfig.build.json","typecheck":"tsc -p tsconfig.json --noEmit","test":"npm run build && node --test test/*.test.mjs","check":"npm run typecheck && npm test","prepare":"npm run build","prepack":"npm run check"},"engines":{"node":">=20.0.0"},"packageManager":"npm@11.8.0","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/CrateTF/item-url-codec.git"},"bugs":{"url":"https://github.com/CrateTF/item-url-codec/issues"},"homepage":"https://github.com/CrateTF/item-url-codec#readme","keywords":["cratetf","tf2","sku","url","codec"],"devDependencies":{"typescript":"^7.0.2"},"gitHead":"10decfa9feffb33981078590a2052b691a200d8e","_id":"@cratetf/item-url-codec@1.0.0","_nodeVersion":"22.21.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-hG/cRjBiesu1lycvDzgCmltRV6TP6YSA45pO0ppBCpkEJ7xLOdLhMdqETZoKZmDbSfW1UEjEwBeBLpZjPQyqVw==","shasum":"79ed308a73939927ad034029ec41e79c9ef9e73b","tarball":"https://registry.npmjs.org/@cratetf/item-url-codec/-/item-url-codec-1.0.0.tgz","fileCount":13,"unpackedSize":23016,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBZzbv+mpOe4pDXEp6KO7CYHPMOOFE9E6BjOcuhyBR8/AiAKUTvSHcGNI0B2kc2Jc0iB3uCvIEm2K5ISdLmfYRvGfQ=="}]},"_npmUser":{"name":"osc44r","email":"oski90091@gmail.com"},"directories":{},"maintainers":[{"name":"osc44r","email":"oski90091@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/item-url-codec_1.0.0_1784668057987_0.9577957900394867"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T21:07:37.788Z","1.0.0":"2026-07-21T21:07:38.150Z","modified":"2026-07-21T21:07:38.419Z"},"maintainers":[{"name":"osc44r","email":"oski90091@gmail.com"}],"description":"Canonical Crate.tf item URL generation and TF2 SKU path parsing.","homepage":"https://github.com/CrateTF/item-url-codec#readme","keywords":["cratetf","tf2","sku","url","codec"],"repository":{"type":"git","url":"git+https://github.com/CrateTF/item-url-codec.git"},"author":{"name":"CrateTF"},"bugs":{"url":"https://github.com/CrateTF/item-url-codec/issues"},"license":"MIT","readme":"# Crate.tf item URL codec\n\nThe official, dependency-free reference implementation for converting TF2 SKUs\nto canonical Crate.tf item links and parsing supported item URL segments back to\nAPI SKUs.\n\nThis repository is the public integration contract for websites, bots, browser\nextensions, and other tools linking to Crate.tf item pages. Crate.tf backend\nAPIs continue to use authoritative semicolon-delimited TF2 SKUs; public item\nURLs use a readable hyphenated representation.\n\n## Why this exists\n\nA naive replacement works in the forward direction when the input is already a\ncanonical TF2 SKU, but it cannot safely parse URLs in reverse. Some valid SKU\nattributes contain native hyphens:\n\n```text\n9258;5;uncraftable;td-31154\n```\n\nThe corresponding public path is:\n\n```text\n/item/9258-5-uncraftable-td-31154\n```\n\nThe codec recognizes the TF2 SKU grammar and preserves attributes such as\n`td-31154`, `kt-2`, and `od-456`.\n\n## Installation\n\nInstall the package from npm:\n\n```bash\nnpm install @cratetf/item-url-codec\n```\n\nNon-JavaScript integrations can implement the language-neutral contract from\n[CONTRACT.md](./CONTRACT.md) and verify their implementation against\n[test-vectors.json](./test-vectors.json).\n\n## Usage\n\n```ts\nimport {\n  toApiSkuFromItemPathSegment,\n  toCrateTfItemUrl,\n  toItemPathFromSku,\n} from '@cratetf/item-url-codec'\n\ntoItemPathFromSku('5978;6;c151')\n// '/item/5978-6-c151'\n\ntoCrateTfItemUrl('9258;5;uncraftable;td-31154')\n// 'https://crate.tf/item/9258-5-uncraftable-td-31154'\n\ntoApiSkuFromItemPathSegment('9258-5-uncraftable-td-31154')\n// '9258;5;uncraftable;td-31154'\n```\n\nFor outbound links, integrations normally need only `toCrateTfItemUrl()` or\n`toItemPathFromSku()`. Reverse parsing is primarily useful to Crate.tf itself.\n\n## Public API\n\n### `normalizeTf2Sku(rawSku)`\n\nNormalizes case, whitespace, `untradeable`, and known tolerant numeric\nattribute spellings while preserving the semicolon-delimited API representation.\n\n### `toCanonicalItemPathSegment(rawSku)`\n\nReturns the canonical hyphenated item path segment.\n\n### `toItemPathFromSku(rawSku)`\n\nReturns the canonical site-relative `/item/<segment>` path.\n\n### `toCrateTfItemUrl(rawSku, baseUrl?)`\n\nReturns an absolute item URL. It defaults to `https://crate.tf` and rejects an\nempty SKU or non-HTTP(S) base URL.\n\n### `toApiSkuFromItemPathSegment(pathSegment)`\n\nReturns the normalized API SKU for a canonical or supported legacy segment.\nReturns an empty string for ambiguous or unsupported segments.\n\n### `isCanonicalItemPathSegment(value)`\n\nReturns whether the input is already the exact canonical path representation.\n\n## Canonical examples\n\n| API SKU | Canonical path |\n| --- | --- |\n| `5021;6` | `/item/5021-6` |\n| `5978;6;c151` | `/item/5978-6-c151` |\n| `30911;5;u144` | `/item/30911-5-u144` |\n| `9258;5;uncraftable;td-31154` | `/item/9258-5-uncraftable-td-31154` |\n| `123;6;kt-2` | `/item/123-6-kt-2` |\n| `123;6;od-456;oq6` | `/item/123-6-od-456-oq6` |\n\n## Requirements and compatibility\n\n- Zero runtime dependencies.\n- ESM package with bundled TypeScript declarations.\n- Browser and Node.js compatible.\n- Node.js `20` or newer for package tooling and automated tests.\n- Semantic Versioning for public API and contract changes.\n\nThe package does not check whether an SKU currently exists in the Crate.tf\ncatalog. It only normalizes and converts identifiers. A correctly formed link\nmay still return `404` when the item is not present in the live catalog.\n\n## Development\n\n```bash\nnpm ci\nnpm run check\nnpm pack --dry-run\n```\n\n`npm run check` performs strict TypeScript validation, builds declarations and\nsource maps, and executes the conformance tests.\n\n## Security\n\nThis package processes public identifiers and does not access credentials,\nnetwork services, or the filesystem. Report security concerns according to\n[SECURITY.md](./SECURITY.md).\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md). Changes to parsing behavior must include\nportable contract vectors and tests.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-536fe974c3a2838ce50234ed38bdbe1c"}