{"_id":"@acuris-geo/agentic-checkout","name":"@acuris-geo/agentic-checkout","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@acuris-geo/agentic-checkout","version":"0.1.0","description":"Agentic-checkout-ready address validation — converts Acuris /validate results into UCP (Universal Commerce Protocol) messages and ACP (Agentic Commerce Protocol) message errors inside merchant checkout-session endpoints.","keywords":["acuris","ucp","universal-commerce-protocol","acp","agentic-commerce-protocol","agentic-commerce","address-validation","checkout","ai-agents"],"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-agentic-connector/tree/main/packages/acuris-agentic-checkout#readme","repository":{"type":"git","url":"git+https://github.com/Acuris-GmbH/acuris-agentic-connector.git","directory":"packages/acuris-agentic-checkout"},"bugs":{"url":"https://github.com/Acuris-GmbH/acuris-agentic-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/agentic-checkout@0.1.0","gitHead":"b9f6c967abbc3daf150c80eecc9385ab43e71abb","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-CFrivnkJFha0zL565Ip43/ZkluuTr6rUK9XBZycz8j7w90Xa1zklsa/CBFh5GBhcnNwqkCHIIkK4whLS9RRsjA==","shasum":"53d64eb294bae2c1ba8c99866953ff0ee12dddec","tarball":"https://registry.npmjs.org/@acuris-geo/agentic-checkout/-/agentic-checkout-0.1.0.tgz","fileCount":28,"unpackedSize":75756,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDx261TGlDzRPuZZWsVXPS+2zoVR/Zh/koN79XxXb5bGAIgDSs3fTBrYa0du3K51K12r4yL2QC4cWyN2lM5UPfGUe8="}]},"_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/agentic-checkout_0.1.0_1781300447706_0.9648989156708887"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-12T21:40:47.427Z","0.1.0":"2026-06-12T21:40:47.846Z","modified":"2026-06-12T21:40:48.216Z"},"maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"description":"Agentic-checkout-ready address validation — converts Acuris /validate results into UCP (Universal Commerce Protocol) messages and ACP (Agentic Commerce Protocol) message errors inside merchant checkout-session endpoints.","homepage":"https://github.com/Acuris-GmbH/acuris-agentic-connector/tree/main/packages/acuris-agentic-checkout#readme","keywords":["acuris","ucp","universal-commerce-protocol","acp","agentic-commerce-protocol","agentic-commerce","address-validation","checkout","ai-agents"],"repository":{"type":"git","url":"git+https://github.com/Acuris-GmbH/acuris-agentic-connector.git","directory":"packages/acuris-agentic-checkout"},"author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"bugs":{"url":"https://github.com/Acuris-GmbH/acuris-agentic-connector/issues"},"license":"MIT","readme":"# @acuris-geo/agentic-checkout\n\nAddress validation for **agentic commerce**. When an AI agent drives checkout\n— Google's [Universal Commerce Protocol (UCP)](https://ucp.dev) or\nOpenAI/Stripe's [Agentic Commerce Protocol (ACP)](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol)\n— there is no human watching an address form, and no widget to catch typos.\nBoth protocols make address validation **the merchant's job** inside the\ncheckout-session endpoint, with structured messages as the only feedback\nchannel to the agent.\n\nThis package runs [Acuris Address Validation](https://acuris-geo.com) inside\nthat endpoint and emits each protocol's native message shapes, so a bad\naddress is caught **before** payment instead of after a failed delivery.\n\n```bash\nnpm install @acuris-geo/agentic-checkout\n```\n\n## UCP (v2026-04-08)\n\nInside your `POST /checkout-sessions` / `PUT /checkout-sessions/{id}` handler:\n\n```ts\nimport { validateUcpDestination } from \"@acuris-geo/agentic-checkout\";\n\nconst destination = checkout.fulfillment.methods[0].destinations[0];\nconst check = await validateUcpDestination(destination, {\n  apiKey: process.env.ACURIS_API_KEY,\n});\n\ncheckout.messages.push(...check.messages);\nif (check.correctedDestination) {\n  // Echo the standardized form back as the authoritative destination.\n  checkout.fulfillment.methods[0].destinations[0] = {\n    ...check.correctedDestination,\n    id: destination.id ?? \"dest_validated\",\n  };\n}\n```\n\nEmitted codes follow the UCP core spec and Google's UCP error-code registry:\n\n| Outcome | Message |\n| --- | --- |\n| Verified at address level | *(no message)* |\n| Verified after standardization | `warning` `address_standardized` + `correctedDestination` |\n| House number not on street | `error` `address_undeliverable` (core standard error) |\n| No confident match | `error` `address_unverifiable`, per-field RFC 9535 `path` |\n| Required field absent | `error` `missing_fulfillment_info`, per-field `path` |\n\nAll errors use `severity: \"recoverable\"` per the spec's standard-error\nguidance — the agent platform can fix the input via API and retry. Paths\ndefault to `$.fulfillment.methods[0].destinations[0].<field>` and are\nconfigurable via `methodIndex` / `destinationIndex` / `basePath`.\n\n## ACP (2026-04-17 and 2025-09-29)\n\nInside your `POST /checkout_sessions` / `POST /checkout_sessions/{id}` handler:\n\n```ts\nimport { validateAcpAddress } from \"@acuris-geo/agentic-checkout\";\n\nconst check = await validateAcpAddress(session.fulfillment_address, {\n  apiKey: process.env.ACURIS_API_KEY,\n  version: \"2025-09-29\", // ChatGPT Instant Checkout as deployed; default 2026-04-17\n});\n\nsession.messages.push(...check.messages);\nif (check.correctedAddress) session.fulfillment_address = check.correctedAddress;\n```\n\nOnly the codes `missing` and `invalid` are emitted — both exist in the closed\n2025-09-29 enum and the 2026-04-17 enum, so the output validates against\neither version. Targeting 2026-04-17 adds `resolution: \"recoverable\"` and the\n`$.fulfillment_details.address.*` param base.\n\n## Behaviour notes\n\n- **Fail-open by default.** Countries Acuris does not cover and transient\n  upstream errors produce *no* messages (verdicts `unsupported_country` /\n  `unavailable`) — an agentic checkout should not break because validation is\n  unavailable. Set `failClosed: true` to block instead.\n- **Verdicts** (`deliverable`, `correctable`, `undeliverable`, `unverifiable`,\n  `missing_fields`, `unsupported_country`, `unavailable`) are returned\n  alongside the messages so you can implement your own policy (e.g. block\n  `undeliverable` but allow `unverifiable`).\n- Pure mappers `toUcpMessages` / `toAcpMessages` and the protocol wire types\n  are exported for custom flows (billing addresses, batch re-checks).\n- ISO-2 ⇄ ISO-3 country conversion is handled internally (Acuris uses ISO-3).\n\n## License\n\nMIT © Acuris GmbH\n","readmeFilename":"README.md","_rev":"1-bcfe02343a9045246803f8f9aacb05e0"}