{"_id":"@1dex-fr/connector","name":"@1dex-fr/connector","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@1dex-fr/connector","version":"0.2.0","description":"JavaScript connector for the public and professional 1dex API surface: overview, subscriber address details, autocomplete, score, preview, account usage, and map routes.","type":"module","exports":{".":{"types":"./src/index.d.ts","default":"./src/index.js"}},"keywords":["1dex","cadastre","dvf","travaux","parcelles","geojson","sdk"],"homepage":"https://blipn.github.io/1dex-connector/","repository":{"type":"git","url":"git+https://github.com/blipn/1dex-connector.git","directory":"packages/js"},"bugs":{"url":"https://github.com/blipn/1dex-connector/issues"},"engines":{"node":">=22"},"license":"MIT","_id":"@1dex-fr/connector@0.2.0","_integrity":"sha512-/jafWe0Y6StVRjo2zQ4CS1BpTlEf8lVt8l5B0EofI7xKpHW5CrnIZJNCBsIPqte7soeH6cle/1GkxPAEMcarjA==","_resolved":"/tmp/1dex-sdk-bootstrap-3321932-20260907/1dex-fr-connector-0.2.0.tgz","_from":"file:/tmp/1dex-sdk-bootstrap-3321932-20260907/1dex-fr-connector-0.2.0.tgz","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-/jafWe0Y6StVRjo2zQ4CS1BpTlEf8lVt8l5B0EofI7xKpHW5CrnIZJNCBsIPqte7soeH6cle/1GkxPAEMcarjA==","shasum":"9412a96330ea4b9a66623ad4bba25c604a36bdc4","tarball":"https://registry.npmjs.org/@1dex-fr/connector/-/connector-0.2.0.tgz","fileCount":5,"unpackedSize":51044,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEJ55yP+lVBYhtZZn0iqgr8QToc/mokcE8SHupyAhOQyAiBufBoPtO1YXqDWIDtQd5JeiA3utlgClnwQghP9rXxFcA=="}]},"_npmUser":{"name":"1dex-fr","email":"service@1dex.fr"},"directories":{},"maintainers":[{"name":"1dex-fr","email":"service@1dex.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/connector_0.2.0_1788793914657_0.23481557315568136"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T15:11:54.454Z","0.2.0":"2026-09-07T15:11:54.776Z","modified":"2026-09-07T15:11:55.031Z"},"maintainers":[{"name":"1dex-fr","email":"service@1dex.fr"}],"description":"JavaScript connector for the public and professional 1dex API surface: overview, subscriber address details, autocomplete, score, preview, account usage, and map routes.","homepage":"https://blipn.github.io/1dex-connector/","keywords":["1dex","cadastre","dvf","travaux","parcelles","geojson","sdk"],"repository":{"type":"git","url":"git+https://github.com/blipn/1dex-connector.git","directory":"packages/js"},"bugs":{"url":"https://github.com/blipn/1dex-connector/issues"},"license":"MIT","readme":"# @1dex-fr/connector\n\nJavaScript and TypeScript connector for the public and professional `1dex.fr` API surface.\n\nInstall the npm package:\n\n```bash\nnpm i @1dex-fr/connector\n```\n\n```js\nimport { OneDexClient } from \"@1dex-fr/connector\";\n```\n\n## Public reads\n\nPublic overview access is intended for manual, one-off checks within public quotas. Automation and integrations require active API rights. Some map layers also require an authorized Explorer session; an API key alone does not grant access to detailed DVF or works layers.\n\n```js\nimport { OneDexClient } from \"@1dex-fr/connector\";\n\nconst client = new OneDexClient();\n\nconst overview = await client.overview.address({\n  address: \"10 rue des cordeliers aix\",\n  dvf_radius_m: 600,\n});\n\nconst suggestions = await client.autocomplete.address({\n  q: \"10 rue des cordeliers aix\",\n  limit: 5,\n});\n\nconst score = await client.score.address({\n  items: [{ address: \"10 rue des cordeliers aix\" }],\n});\n\nconst viewport = await client.map.viewport({\n  layers: \"context,iris\",\n  address: \"10 rue des cordeliers aix\",\n});\n```\n\n## Authentication and detailed reads\n\nComplete address details and unlock flows require a 1dex API key. Professional Free accounts can issue a demo key only when a demo is published in that environment. Demo keys are pinned to the configured address; live keys use the account's subscription and activation rights. Check current offer availability on `1dex.fr`. Keep live keys in your backend, never in browser code or URLs. Create or manage keys at <https://1dex.fr/compte/api>.\n\nPass the key explicitly or through `ONEDEX_API_KEY`:\n\n```js\nimport { OneDexApiError, OneDexClient } from \"@1dex-fr/connector\";\n\nconst client = new OneDexClient({\n  apiKey: process.env.ONEDEX_API_KEY,\n});\n```\n\nRecommended subscriber flow:\n\n1. Check the V2 `api_addresses` usage view (or the legacy V1 response during rollout) with `client.account.usage()`.\n2. Try `client.address.details(...)` with an address, parcel, coordinates, or a `normalizedAddressKey`, plus a caller-generated idempotency key.\n3. If the API raises `address_unlock_required`, call `client.address.unlock(...)` with the returned `normalized_address_key`, or post the returned `unlock_request` object when present.\n4. Follow the returned `details_url` with `client.address.detailsUrl(...)`; the helper rejects another origin or route.\n\n```js\nimport { randomUUID } from \"node:crypto\";\n\nconst usage = await client.account.usage();\n\ntry {\n  const details = await client.address.details({\n    address: \"10 rue des cordeliers aix\",\n    fields: [\"summary\", \"rail\"],\n    idempotencyKey: randomUUID(),\n  }, { retry: true });\n  console.log(details.fields);\n} catch (error) {\n  if (!(error instanceof OneDexApiError)) {\n    throw error;\n  }\n  if (error.status !== 402 || error.body?.error !== \"address_unlock_required\") {\n    throw error;\n  }\n\n  const unlockIdempotencyKey = randomUUID();\n  const unlock = error.body.unlock_request\n    ? await client.address.unlock({\n        ...error.body.unlock_request,\n        idempotencyKey: unlockIdempotencyKey,\n      }, { retry: true })\n    : await client.address.unlock({\n        normalizedAddressKey: error.body.normalized_address_key,\n        idempotencyKey: unlockIdempotencyKey,\n      }, { retry: true });\n\n  const details = unlock.details_url\n    ? await client.address.detailsUrl(unlock.details_url, {\n        idempotencyKey: randomUUID(),\n        retry: true,\n      })\n    : await client.address.details({\n        normalizedAddressKey: unlock.normalized_address_key,\n        fields: [\"summary\", \"rail\"],\n        idempotencyKey: randomUUID(),\n      }, { retry: true });\n\n  console.log(usage.version, details.fields);\n}\n```\n\n`retry: true` retries `202`, `429`, and `503` with the exact same idempotency key and honors `Retry-After`. A `409` is never retried: it means the key identifies another intention. Pass an `AbortSignal` to cancel both the active request and any retry wait.\n\nCommon professional API errors:\n\n- `invalid_api_key`: the API key is missing, invalid, or revoked.\n- `api_subscription_required`: the account needs an active subscription.\n- `api_professional_required`: the endpoint requires a professional plan.\n- `address_unlock_required`: the detailed address must be unlocked before reading.\n- `insufficient_credits`: the account has no remaining address credits for the requested unlock.\n\n## Helpers\n\nThe client exposes helpers for the current `/api/v1` routes:\n\n- `client.overview.address(...)`\n- `client.address.details(...)`\n- `client.address.detailsUrl(...)`\n- `client.address.unlock(...)`\n- `client.account.usage()`\n- `client.autocomplete.address(...)`\n- `client.communes.search(...)`\n- `client.score.address(...)`, `client.score.compare(...)`, `client.score.grid(...)`, `client.score.addressSuggest(...)`\n- `client.preview.byPath(...)`\n- `client.addressPages.state(...)`\n- `client.map.layer(...)`, `client.map.viewport(...)`, `client.map.focus.address(...)`, `client.map.focus.publicLocation(...)`, `client.map.focus.parcelle(...)`, `client.map.focus.parcelles(...)`, `client.map.focus.feature(...)`\n\nFor command-line usage, install `@1dex-fr/1dex`.\n\nSupported runtimes: Node 22 and 24. Type declarations cover both legacy account usage and `account-usage-v2` during rollout.\n\n## Transport limits\n\nThe base URL accepts either `https://1dex.fr` or `https://1dex.fr/api/v1`. HTTP redirects are rejected so credentials and mutations are never forwarded to an unexpected URL. A retry wait budget stops retries when `Retry-After` exceeds it; it never shortens the server’s delay. Errors retain the HTTP status even when an upstream response contains text or HTML.\n","readmeFilename":"README.md","_rev":"1-741f3b05b274309125333ed885fa8cb0"}