{"_id":"@acuris-geo/commercetools-extension","_rev":"2-bf683414a54a2f2ba85678c0fdc1a417","name":"@acuris-geo/commercetools-extension","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@acuris-geo/commercetools-extension","version":"0.1.0","keywords":["acuris","commercetools","api-extension","address-validation","geocoding","composable-commerce","connect"],"author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"license":"MIT","_id":"@acuris-geo/commercetools-extension@0.1.0","maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"homepage":"https://github.com/Acuris-GmbH/acuris-commercetools-connector/tree/main/packages/acuris-commercetools-extension#readme","bugs":{"url":"https://github.com/Acuris-GmbH/acuris-commercetools-connector/issues"},"dist":{"shasum":"2f697fbeff8a0505c906142216b01118d2224799","tarball":"https://registry.npmjs.org/@acuris-geo/commercetools-extension/-/commercetools-extension-0.1.0.tgz","fileCount":23,"integrity":"sha512-tDjESZwzNJSSoY0A69I+cREWPoYc2F7kqdU8lEemhSAhVVcj7DD7nzX1Guibx2EA3S79c4cFmr9Ks0rciFc5uA==","signatures":[{"sig":"MEUCIQCIgcGlFb71w/YoQQHBPYO/1h6UEb+iwmsxHb1khJJ3mQIgZ3S726JMX4zznGou77FOtbBVGaYK8ILUutN/slDDJp4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42496},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.17.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"464b42c71c83d8a50baac4bb70cf83f6ad51de71","scripts":{"test":"vitest run --coverage","build":"tsc -p tsconfig.json && node ./build-cjs.mjs","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest"},"_npmUser":{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"},"repository":{"url":"git+https://github.com/Acuris-GmbH/acuris-commercetools-connector.git","type":"git","directory":"packages/acuris-commercetools-extension"},"_npmVersion":"10.9.7","description":"commercetools API Extension handler for Acuris Address Validation & Geocoding — gates Cart updates server-side.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"@acuris-geo/av-sdk":"^0.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.4","typescript":"^5.5.4","@types/node":"^20.14.10","@vitest/coverage-v8":"^2.1.4"},"_npmOperationalInternal":{"tmp":"tmp/commercetools-extension_0.1.0_1778692491887_0.2891198374819912","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@acuris-geo/commercetools-extension","version":"0.1.1","description":"commercetools API Extension handler for Acuris Address Validation & Geocoding — gates Cart updates server-side.","keywords":["acuris","commercetools","api-extension","address-validation","geocoding","composable-commerce","connect"],"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsc -p tsconfig.json && node ./build-cjs.mjs","typecheck":"tsc -p tsconfig.json --noEmit","test":"vitest run --coverage","test:watch":"vitest"},"engines":{"node":">=18.17.0"},"license":"MIT","author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"homepage":"https://github.com/Acuris-GmbH/acuris-commercetools-connector/tree/main/packages/acuris-commercetools-extension#readme","repository":{"type":"git","url":"git+https://github.com/Acuris-GmbH/acuris-commercetools-connector.git","directory":"packages/acuris-commercetools-extension"},"bugs":{"url":"https://github.com/Acuris-GmbH/acuris-commercetools-connector/issues"},"publishConfig":{"access":"public"},"dependencies":{"@acuris-geo/av-sdk":"^0.3.0"},"devDependencies":{"@types/node":"^20.14.10","@vitest/coverage-v8":"^2.1.4","typescript":"^5.5.4","vitest":"^2.1.4"},"_id":"@acuris-geo/commercetools-extension@0.1.1","gitHead":"615dc7d445cf4c2373d488e46b6706e6b760b9b5","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-Si9evq1Bzd+GKXZjrRUY6Jkqq88LgDqBcL3bY9K9yyKlH1BFZKiWhQRAmFtMZKxzae/zE0uQiW2J86WSfKvfEA==","shasum":"7965b3d5cf6542b08e5ac32a0d3fbf622e877b26","tarball":"https://registry.npmjs.org/@acuris-geo/commercetools-extension/-/commercetools-extension-0.1.1.tgz","fileCount":23,"unpackedSize":42499,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAHnO/U1M3xHwxjHAb/Q7k7MHnBBFn0HsUcYiMBY5uTzAiEAx+HHGAZdL/LiVy7DuzcdmpI0bl+mL6b/nkez/m8EEiM="}]},"_npmUser":{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"},"directories":{},"maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/commercetools-extension_0.1.1_1781298379706_0.5466660765017293"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-13T17:14:51.817Z","modified":"2026-06-12T21:06:19.983Z","0.1.0":"2026-05-13T17:14:52.028Z","0.1.1":"2026-06-12T21:06:19.863Z"},"bugs":{"url":"https://github.com/Acuris-GmbH/acuris-commercetools-connector/issues"},"author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"license":"MIT","homepage":"https://github.com/Acuris-GmbH/acuris-commercetools-connector/tree/main/packages/acuris-commercetools-extension#readme","keywords":["acuris","commercetools","api-extension","address-validation","geocoding","composable-commerce","connect"],"repository":{"type":"git","url":"git+https://github.com/Acuris-GmbH/acuris-commercetools-connector.git","directory":"packages/acuris-commercetools-extension"},"description":"commercetools API Extension handler for Acuris Address Validation & Geocoding — gates Cart updates server-side.","maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"readme":"# @acuris-geo/commercetools-extension\n\n> commercetools API Extension handler for Acuris Address Validation &\n> Geocoding. Synchronously validates `setShippingAddress` /\n> `setBillingAddress` on Cart updates and either **rewrites** to the\n> canonical address or **rejects** with `InvalidInput`. Server-side, no\n> bypass.\n\n**Status:** beta (`0.1.0`).\n\n## Install\n\n```bash\nnpm install @acuris-geo/commercetools-extension\n```\n\n## Why server-side\n\nStorefront-only address validation can be bypassed: a buyer can call\n`POST /me/carts/{id}` directly with bad data. The API Extension closes\nthat hole by running on every Cart update inside commercetools, before\nthe cart persists. Per\n[docs.commercetools.com/api/projects/api-extensions](https://docs.commercetools.com/api/projects/api-extensions),\nthe handler can either return replacement update actions (200) or abort\nwith structured errors (400). We expose both modes.\n\n## Quick start (AWS Lambda)\n\n```ts\nimport { buildLambdaHandler } from \"@acuris-geo/commercetools-extension\";\n\nexport const handler = buildLambdaHandler({\n  apiKey: process.env.ACURIS_API_KEY!,\n  mode: \"rewrite\",        // rewrite (default), reject, or annotate\n  minConfidence: 0.8,\n});\n```\n\nRegister the Lambda URL in **Merchant Center → Settings → Developer\nsettings → API Extensions** with trigger `Cart: Update` and authentication\nof your choice (AWS Lambda authorizer / X-API-Key / basic auth — the\nextension itself is transport-agnostic).\n\n## Modes\n\n| Mode | Behaviour |\n|---|---|\n| `rewrite` (default) | Replace the inbound address with Acuris's standardized form. Below `minConfidence` the inbound stays as-is. |\n| `reject` | Return `InvalidInput` if confidence is below `minConfidence`. Cart update aborts; buyer sees the error. |\n| `annotate` | Don't change the address; future minor release will attach Custom Fields (`acurisConfidence`, `acurisAccuracyType`). Currently a no-op placeholder for the merchant to slot their own logic. |\n\nIdentity fields (`firstName`, `lastName`, `company`, `apartment`,\n`building`, `pOBox`, `phone`, …) are preserved verbatim in `rewrite` mode\n— only the geographical components are updated.\n\n## Other runtime adapters\n\n```ts\n// Generic async (your own router):\nimport { buildExtensionHandler } from \"@acuris-geo/commercetools-extension\";\nconst handler = buildExtensionHandler({ apiKey });\nconst responseBody = await handler(requestBody);\n\n// Raw Node http (Express, fastify wrappers, etc):\nimport { buildNodeHttpHandler } from \"@acuris-geo/commercetools-extension\";\napp.post(\"/acuris-extension\", buildNodeHttpHandler({ apiKey }));\n```\n\nFor commercetools **Connect** deployments, wrap `processExtension` in a\nConnect-conformant handler — the `processExtension` core takes a parsed\nrequest body and returns the response payload directly.\n\n## Configuration\n\n| Option | Default | Notes |\n|---|---|---|\n| `apiKey` | `process.env.ACURIS_API_KEY` | Required. |\n| `mode` | `\"rewrite\"` | See above. |\n| `minConfidence` | `0.8` | Below this, treated as a no-match. |\n| `baseUrl` | `https://api.acuris-geo.com` | Override for self-hosted. |\n| `timeoutMs` | `3500` | commercetools enforces ≤ 10 s; we default well under. |\n| `skipCountries` | `[]` | ISO-2 codes to bypass entirely. |\n\n## Failure semantics\n\nNetwork errors and Acuris-side outages **do not block** Cart updates.\nThe handler logs internally and lets the inbound action stand — the\nopposite of the buyer-blocking failure mode you'd get from a strict\nimplementation. If you want fail-closed behaviour, raise an issue.\n\n## License\n\nMIT © Acuris GmbH\n","readmeFilename":"README.md"}