{"_id":"@acuris-geo/av-sdk","_rev":"5-64e5335caa30a5d2b383c1e19a86172f","name":"@acuris-geo/av-sdk","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@acuris-geo/av-sdk","version":"0.1.0","keywords":["acuris","address-validation","geocoding","reverse-geocoding","centra","headless-commerce","typescript","sdk"],"author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"license":"MIT","_id":"@acuris-geo/av-sdk@0.1.0","maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"homepage":"https://github.com/Acuris-GmbH/acuris-centra-connector/tree/main/packages/acuris-av-sdk#readme","bugs":{"url":"https://github.com/Acuris-GmbH/acuris-centra-connector/issues"},"dist":{"shasum":"42eb19ce17060f1c40968f28ab4a71ab0ff486d3","tarball":"https://registry.npmjs.org/@acuris-geo/av-sdk/-/av-sdk-0.1.0.tgz","fileCount":43,"integrity":"sha512-Y43G6jpgJ1YRYOcp2fVPmndDXIhst+rAkyYJTvoH0KVdqOIdG2UYdT5tjR5HDAAA2WdxFDZNrIep4KO1dFKYkw==","signatures":[{"sig":"MEUCIQDsr+1aJ6cFUwtDq2fPGrTZQ1o+2nJANsYihKHToqC/FwIgL9C0B4DL3FxGPIxuYxtZAlKMm+UvIhTLAF+A0+uA7hY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":65820},"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":"27b6f5d4a9eae43266f31680a2ec972476b4d190","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-centra-connector.git","type":"git","directory":"packages/acuris-av-sdk"},"_npmVersion":"10.9.7","description":"TypeScript SDK for the Acuris Address Validation & Geocoding API (api.acuris-geo.com).","directories":{},"_nodeVersion":"22.22.2","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/av-sdk_0.1.0_1778625839550_0.3046004561290969","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@acuris-geo/av-sdk","version":"0.1.1","keywords":["acuris","address-validation","geocoding","reverse-geocoding","centra","headless-commerce","typescript","sdk"],"author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"license":"MIT","_id":"@acuris-geo/av-sdk@0.1.1","maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"homepage":"https://github.com/Acuris-GmbH/acuris-centra-connector/tree/main/packages/acuris-av-sdk#readme","bugs":{"url":"https://github.com/Acuris-GmbH/acuris-centra-connector/issues"},"dist":{"shasum":"2aa0be9da0a407698711313bff06f797b398b7b7","tarball":"https://registry.npmjs.org/@acuris-geo/av-sdk/-/av-sdk-0.1.1.tgz","fileCount":43,"integrity":"sha512-341zUY6TTuHmK7rOJMGY6R8VqQdlg5O84TbwoDC6IUdEOZcU1ae18wmSDjQBJgYFbeuuJxFHpYdgc9u+wWdd/w==","signatures":[{"sig":"MEUCIQDyJjzLKwThbThQwpNHEmPLESK2VELRLdPBxPb8PEoSKQIgWrlUB6IOGN6hBgTrVcBwioolaeYLgwjeFojhoxISrOY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":65820},"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":"93c28919e199d1b030698dbc3b54f4d987cbe406","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-centra-connector.git","type":"git","directory":"packages/acuris-av-sdk"},"_npmVersion":"10.9.7","description":"TypeScript SDK for the Acuris Address Validation & Geocoding API (api.acuris-geo.com).","directories":{},"_nodeVersion":"22.22.2","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/av-sdk_0.1.1_1778631354800_0.7845914017872615","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@acuris-geo/av-sdk","version":"0.1.2","keywords":["acuris","address-validation","geocoding","reverse-geocoding","centra","headless-commerce","typescript","sdk"],"author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"license":"MIT","_id":"@acuris-geo/av-sdk@0.1.2","maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"homepage":"https://github.com/Acuris-GmbH/acuris-centra-connector/tree/main/packages/acuris-av-sdk#readme","bugs":{"url":"https://github.com/Acuris-GmbH/acuris-centra-connector/issues"},"dist":{"shasum":"899f0fd9970aff885dd1e374d00ac719afde20ec","tarball":"https://registry.npmjs.org/@acuris-geo/av-sdk/-/av-sdk-0.1.2.tgz","fileCount":43,"integrity":"sha512-PH/VcLSKNB33EKkUI6hztvzhS2lp5tWty75WdsytEyMws0xPoXYZgG1MaDwZoZHvilqEhKMX0z1VMnYa1gdOBQ==","signatures":[{"sig":"MEQCICqYuqb4qoFsncli9YmVQgur5A/wXsNvU/m3ZtOBno3oAiBSlVo4AADBzYBwDcHSmy2mXLJ39AF/DySCbWZxWIyc5A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":65900},"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":"c8ba34984ef32cbfa79651642cc3c71f8803b8d4","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-centra-connector.git","type":"git","directory":"packages/acuris-av-sdk"},"_npmVersion":"10.9.7","description":"TypeScript SDK for the Acuris Address Validation & Geocoding API (api.acuris-geo.com).","directories":{},"_nodeVersion":"22.22.2","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/av-sdk_0.1.2_1778810400773_0.14484382424396847","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@acuris-geo/av-sdk","version":"0.2.0","keywords":["acuris","address-validation","geocoding","reverse-geocoding","postcode-lookup","uk-postcode","royal-mail-paf","email-validation","email-verification","centra","headless-commerce","typescript","sdk"],"author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"license":"MIT","_id":"@acuris-geo/av-sdk@0.2.0","maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"homepage":"https://github.com/Acuris-GmbH/acuris-centra-connector/tree/main/packages/acuris-av-sdk#readme","bugs":{"url":"https://github.com/Acuris-GmbH/acuris-centra-connector/issues"},"dist":{"shasum":"ecc75fbf9c1c4a2729cbba295c1d9391fb48fa3c","tarball":"https://registry.npmjs.org/@acuris-geo/av-sdk/-/av-sdk-0.2.0.tgz","fileCount":55,"integrity":"sha512-BLeEkuir/NA6v7XCDH5LXuBIoR6T0bZmRnkLbEh9KY162TcXKpcnWLlRy30n61pfBasVTtDHY1bZEWVLFRG7fg==","signatures":[{"sig":"MEUCIFz/iZ9kmCdAwEdOZN6WaxhxG6ylddBpdCmI4Mn3RIC0AiEA4OW0DQTYswUYYcJymSqWNcLM6VbANf8PnHNn17eLhvw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81668},"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":"cc30d25473da99540cce08c5c550b769024df7e2","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-centra-connector.git","type":"git","directory":"packages/acuris-av-sdk"},"_npmVersion":"10.9.7","description":"TypeScript SDK for the Acuris Address Validation, Geocoding, UK PAF Postcode Lookup, and Email Verification API (api.acuris-geo.com).","directories":{},"_nodeVersion":"22.22.2","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/av-sdk_0.2.0_1780248601347_0.22551157863860638","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@acuris-geo/av-sdk","version":"0.3.0","description":"TypeScript SDK for the Acuris Address Validation, Geocoding, UK PAF Postcode Lookup, and Email Verification API (api.acuris-geo.com).","keywords":["acuris","address-validation","geocoding","reverse-geocoding","postcode-lookup","uk-postcode","royal-mail-paf","email-validation","email-verification","centra","headless-commerce","typescript","sdk"],"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-centra-connector/tree/main/packages/acuris-av-sdk#readme","repository":{"type":"git","url":"git+https://github.com/Acuris-GmbH/acuris-centra-connector.git","directory":"packages/acuris-av-sdk"},"bugs":{"url":"https://github.com/Acuris-GmbH/acuris-centra-connector/issues"},"publishConfig":{"access":"public"},"devDependencies":{"@types/node":"^20.14.10","@vitest/coverage-v8":"^2.1.4","typescript":"^5.5.4","vitest":"^2.1.4"},"_id":"@acuris-geo/av-sdk@0.3.0","gitHead":"26b31a56e9c26798e2ea76e1da574b8dabf98c71","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-i2ySfmcYjAZVnmsK84EUXEr4o8m4noAxMd7EfZBbO6W7wVqJqpJKl6F/6kMa5rJNBXqbADe2e1lF2YuX/RHjNQ==","shasum":"1b78f3af4b3ba0a011e558b90e2fe88a6f723bab","tarball":"https://registry.npmjs.org/@acuris-geo/av-sdk/-/av-sdk-0.3.0.tgz","fileCount":67,"unpackedSize":95958,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHK46e/D2cxbJLaB2h0XAFhracNfiMNtybGu6uSG8JCrAiAdwwre1s7cq+vRNGWhwalkoibLoVM9Bs5SblA/1v2NJQ=="}]},"_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/av-sdk_0.3.0_1781298354293_0.14936504292676278"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-12T22:43:59.476Z","modified":"2026-06-12T21:05:54.563Z","0.1.0":"2026-05-12T22:43:59.696Z","0.1.1":"2026-05-13T00:15:55.016Z","0.1.2":"2026-05-15T02:00:00.923Z","0.2.0":"2026-05-31T17:30:01.563Z","0.3.0":"2026-06-12T21:05:54.426Z"},"bugs":{"url":"https://github.com/Acuris-GmbH/acuris-centra-connector/issues"},"author":{"name":"Acuris GmbH","email":"engineering@acuris-geo.com"},"license":"MIT","homepage":"https://github.com/Acuris-GmbH/acuris-centra-connector/tree/main/packages/acuris-av-sdk#readme","keywords":["acuris","address-validation","geocoding","reverse-geocoding","postcode-lookup","uk-postcode","royal-mail-paf","email-validation","email-verification","centra","headless-commerce","typescript","sdk"],"repository":{"type":"git","url":"git+https://github.com/Acuris-GmbH/acuris-centra-connector.git","directory":"packages/acuris-av-sdk"},"description":"TypeScript SDK for the Acuris Address Validation, Geocoding, UK PAF Postcode Lookup, and Email Verification API (api.acuris-geo.com).","maintainers":[{"name":"acurisgeo","email":"l.kandemir@acuris-geo.com"}],"readme":"# @acuris-geo/av-sdk\n\n> TypeScript SDK for the Acuris Address Validation & Geocoding API. Wraps\n> `api.acuris-geo.com` with typed inputs, structured errors, retries, and\n> timeouts. Zero runtime dependencies; works on Node 18+, modern browsers\n> (in a server-only role — see \"Security\" below), and edge runtimes that\n> expose `fetch`.\n\n**Status:** beta (`0.1.0`). API surface may evolve before `1.0.0`.\n\n## Install\n\n```bash\nnpm install @acuris-geo/av-sdk\n```\n\nYou also need an Acuris API key — get one at\n[acuris-geo.com/acuris-pricing](https://acuris-geo.com/acuris-pricing/). The\nSDK reads `process.env.ACURIS_API_KEY` if no `apiKey` is passed.\n\n## Use with AI coding agents\n\nIf you build with Claude Code, Cursor, GitHub Copilot, OpenCode, Codex,\nGemini CLI, or any other tool that supports\n[Agent Skills](https://agentskills.io), install the Acuris agent\ncontext — your assistant gets the correct SDK shape, the right headers\n(`X-Acuris-Key`, not `Authorization: Bearer`), ISO-3 lowercase country\ncodes, the typed error hierarchy, and a library of recipes\n(autocomplete, validation, forward/reverse geocoding, batch cleanup,\nNext.js proxy routes, the Centra/commercetools/SCAYLE storefront\nintegrations, and migrations from libAddressDoctor, Loqate, Experian\nQAS, Melissa, and Smarty). The bundled `acuris-eudi` skill covers the\nEUDI Wallet Verifier (OID4VP / SD-JWT VC) too. Each skill auto-activates\nonly when your task matches its area.\n\n```bash\n# Claude Code (self-hosted marketplace today; official listing pending review):\n/plugin marketplace add Acuris-GmbH/acuris-agent-context\n/plugin install acuris@acuris-plugins\n\n# Cursor, Copilot, Codex, OpenCode, Gemini CLI, Kiro, Goose, others:\nnpx skills add Acuris-GmbH/acuris-agent-context\n```\n\nSource: <https://github.com/Acuris-GmbH/acuris-agent-context> · Docs: <https://acuris-gmbh.github.io/acuris-agent-context/>\n\n## Quick start\n\n```ts\nimport { AcurisClient, validateAddress } from \"@acuris-geo/av-sdk\";\n\nconst client = new AcurisClient({ apiKey: process.env.ACURIS_API_KEY });\n\nconst result = await validateAddress(client, {\n  country: \"deu\",\n  street: \"Friedrichstraße\",\n  house_number: \"43\",\n  city: \"Berlin\",\n  postcode: \"10117\",\n});\n\nconsole.log(result.accuracy_type);       // e.g. \"rooftop\"\nconsole.log(result.confidence);          // 0..1\nconsole.log(result.standardized?.formatted_address);\n```\n\n## API\n\n### `new AcurisClient(options?)`\n\n| Option       | Default                      | Notes                                            |\n| ------------ | ---------------------------- | ------------------------------------------------ |\n| `apiKey`     | `process.env.ACURIS_API_KEY` | Required.                                        |\n| `baseUrl`    | `https://api.acuris-geo.com` | Override for self-hosted / on-prem deployments.  |\n| `timeoutMs`  | `5000`                       | Per-request timeout.                             |\n| `maxRetries` | `3`                          | Only applied to 5xx, 429, network and timeout.   |\n| `fetch`      | `globalThis.fetch`           | Inject a different fetch impl for testing.       |\n| `userAgent`  | _none_                       | Appended after `acuris-av-sdk/<version>`.        |\n\n### `validateAddress(client, input, options?)`\n\nValidates a structured or single-line address. Returns a `ValidationResult`\nwith `accuracy_type`, `confidence`, `match_components`, and a `standardized`\ncanonical form.\n\n```ts\nconst v = await validateAddress(client, \"100 Main St, San Francisco CA 94105\", {\n  country: \"usa\",\n});\n```\n\n### `geocodeAddress(client, input, options?)`\n\nForward-geocode to lat/lng. Same input shape as `validateAddress`. Returns a\n`GeocodingResult` with `lat`, `lng`, and the matched canonical components.\n\n### `reverseGeocode(client, { lat, lng }, options)`\n\nNearest known address within `radius_m` (default `50`, max `5000`). Returns\n`{ hits: [...], query }`. Pass `limit > 1` for multiple results.\n\n```ts\nconst r = await reverseGeocode(client, { lat: 37.7749, lng: -122.4194 }, {\n  country: \"usa\",\n  radius_m: 100,\n  limit: 3,\n});\n```\n\n### `suggestAddress(client, q, options)`\n\nAutocomplete prefix → list of suggestions (`SuggestionHit[]`). Powers the\n`<AcurisAddressInput>` typeahead in `@acuris-geo/centra-checkout`.\n\n```ts\nconst hits = await suggestAddress(client, \"Friedrichstr\", {\n  country: \"deu\",\n  limit: 5,\n});\n```\n\n### `postcodeLookup(client, postcode, options?)` (UK PAF)\n\nLook up every address at a UK Royal Mail postcode. Returns the building\nlist with rooftop coordinates where PAF provides them.\n\n```ts\nconst r = await postcodeLookup(client, \"SW1A 2AA\");\n// → { count: 1, addresses: [{ street: \"DOWNING STREET\",\n//      house_number: \"10\", city: \"LONDON\", lat: 51.503541, ... }] }\n```\n\nCharges 1 `validation_credit` per call (any number of addresses returned).\n\n### `emailValidate(client, email, options?)`\n\nValidate a single email address. MVP checks: format, DNS MX (with A-record\nfallback), disposable / role / free-provider flags, did-you-mean suggestion\nfor common typos.\n\n```ts\nconst r = await emailValidate(client, \"user@gmial.com\");\n// → { deliverable: \"risky\", did_you_mean: \"user@gmail.com\", ... }\n```\n\nCharges 1 `email_credit` per call — a separate pool from address validation\nand geocoding, so the same plan honestly includes \"X address validations\n**AND** X email verifications\".\n\n### `emailValidateBatch(client, emails[], options?)`\n\nValidate up to 1,000 emails in one synchronous request. Atomic billing —\neither all N succeed or none do (HTTP 403 `insufficient_email_credits`\nif the key doesn't have N credits available).\n\n```ts\nconst r = await emailValidateBatch(client, [\n  \"a@gmail.com\",\n  \"b@yahoo.com\",\n  \"c@mailinator.com\",\n]);\n// → { count: 3, results: [...], email_quota_remaining: 247 }\n```\n\nServer-side per-domain DNS cache (5 min TTL) means a batch of 1,000 emails\nsharing 30 unique domains issues ~30 lookups, not 1,000.\n\n## Errors\n\nAll errors extend `AcurisError`:\n\n```ts\nimport {\n  AcurisAuthError,        // 401, 403\n  AcurisValidationError,  // 400, 422\n  AcurisNotFoundError,    // 404\n  AcurisRateLimitError,   // 429 (carries `retryAfterSeconds` if provided)\n  AcurisServerError,      // 5xx\n  AcurisTimeoutError,     // client-side timeout\n  AcurisNetworkError,     // fetch failed\n} from \"@acuris-geo/av-sdk\";\n\ntry {\n  await validateAddress(client, addr, { country: \"deu\" });\n} catch (err) {\n  if (err instanceof AcurisRateLimitError) {\n    // back off\n  }\n}\n```\n\nTransient errors (5xx, 429, network, timeout) retry automatically with\nexponential backoff (3 attempts by default). Other errors propagate\nimmediately.\n\n## Security\n\n**Do not call this SDK from the browser with a real Acuris API key.** Keys\nmust live server-side. The companion package `@acuris-geo/centra-checkout`\nships React components that call _your_ backend endpoint, which then calls\nthis SDK. See `docs/architecture.md` in the repo for the recommended pattern.\n\n## License\n\nMIT © Acuris GmbH\n","readmeFilename":"README.md"}