feat!: type marketplace lookups with literal unions

.github/dependabot.yml

@@ -20,10 +20,9 @@ updates:
     groups:
       jest:
         patterns:
-          - "@jest/types"
+          - "@jest/*"
           - "@swc/core"
           - "@swc/jest"
-          - "@types/jest"
           - "jest"
           - "jest-junit"
       lint:

CLAUDE.md

@@ -30,10 +30,11 @@ pnpm test        # tests (Jest with SWC)
 
 ```text
 src/
-  index.ts              # Main entry point — exports Marketplace type and lookup functions
-  marketplaces.json     # Marketplace data (34 entries)
+  index.ts              # Main entry point — exports the lookup functions and re-exports the types
+  marketplaces.ts       # Marketplace data (34 entries) + the types derived from it
 tests/
   index.spec.ts         # Jest test suite
+  index.test-d.ts       # Type-level assertions (checked by `pnpm check:ts`, ignored by Jest)
 dist/                   # Build output (tsdown): index.mjs (ESM), index.cjs (CJS), type declarations
 .github/
   workflows/
@@ -50,6 +51,8 @@ dist/                   # Build output (tsdown): index.mjs (ESM), index.cjs (CJS
 - **Package runner**: use `pnpx` instead of `npx`
 - **Node version**: 24 (see `.node-version`)
 - **Lookup functions**: `getMarketplaceById`, `getMarketplaceByCode`, `getMarketplaceByDomain` — all return `undefined` for unknown inputs
+- **Derived types**: `marketplaces.ts` holds the data as `as const satisfies readonly Marketplace[]`, from which `MarketplaceCode`, `MarketplaceId`, `MarketplaceRegion` and `MarketplaceDomain` are derived. `MarketplaceCode`/`MarketplaceDomain` only cover entries having a `domain`
+- **Overloads**: each lookup has a literal overload returning `Marketplace` and a `string` overload returning `Marketplace | undefined`; keep them in that order and cover changes in `tests/index.test-d.ts`
 - **Case handling**: code and domain lookups are case-insensitive; domain lookup strips `www.` prefix
 - **Marketplace data**: each entry has `code`, `id`, `name`, `region`, `currencyCode`, and optional fields (`domain`, `advertisingApiDomain`, `imagesDomain`, `vendorId`, `sellerCentralDomain`, `vendorCentralDomain`)
 

README.md

@@ -21,6 +21,23 @@ npm install --save @bizon/amazon-ids
 
 ## API
 
+All three lookup functions are overloaded: passing a known literal (or a value typed
+with one of the unions below) returns a `Marketplace`, while passing an arbitrary
+`string` returns `Marketplace | undefined`.
+
+```ts
+import {getMarketplaceByCode, type MarketplaceCode} from '@bizon/amazon-ids'
+
+getMarketplaceByCode('fr').domain // Marketplace — no optional chaining needed
+getMarketplaceByCode(someString)?.domain // Marketplace | undefined
+```
+
+The exported unions are `MarketplaceCode`, `MarketplaceId`, `MarketplaceRegion` and
+`MarketplaceDomain`. `MarketplaceCode` and `MarketplaceDomain` only cover the
+marketplaces served by an Amazon storefront — the multi-channel (`*-non-amazon`),
+invoicing and Amazon Pay entries have no domain, so their codes are not part of the
+union and looking them up returns `Marketplace | undefined`.
+
 ### `marketplaces`
 
 ```js

package.json

@@ -28,17 +28,17 @@
   },
   "scripts": {
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
-    "check:ts": "tsc --noEmit",
+    "check:ts": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
     "build": "tsdown",
     "dev": "tsdown --watch"
   },
   "devDependencies": {
     "@bizon/semantic-release-config": "^3.1.0",
+    "@jest/globals": "^30.4.1",
     "@jest/types": "^30.4.1",
     "@swc/core": "^1.15.47",
     "@swc/jest": "^0.2.39",
     "@tsconfig/node24": "^24.0.4",
-    "@types/jest": "^30.0.0",
     "@types/node": "^24.13.3",
     "eslint-config-xo-bizon": "^4.5.0",
     "jest": "^30.4.2",