@1dex-fr/connector 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1dex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @1dex-fr/connector
+
+JavaScript and TypeScript connector for the public and professional `1dex.fr` API surface.
+
+Install the npm package:
+
+```bash
+npm i @1dex-fr/connector
+```
+
+```js
+import { OneDexClient } from "@1dex-fr/connector";
+```
+
+## Public reads
+
+Public 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.
+
+```js
+import { OneDexClient } from "@1dex-fr/connector";
+
+const client = new OneDexClient();
+
+const overview = await client.overview.address({
+  address: "10 rue des cordeliers aix",
+  dvf_radius_m: 600,
+});
+
+const suggestions = await client.autocomplete.address({
+  q: "10 rue des cordeliers aix",
+  limit: 5,
+});
+
+const score = await client.score.address({
+  items: [{ address: "10 rue des cordeliers aix" }],
+});
+
+const viewport = await client.map.viewport({
+  layers: "context,iris",
+  address: "10 rue des cordeliers aix",
+});
+```
+
+## Authentication and detailed reads
+
+Complete 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>.
+
+Pass the key explicitly or through `ONEDEX_API_KEY`:
+
+```js
+import { OneDexApiError, OneDexClient } from "@1dex-fr/connector";
+
+const client = new OneDexClient({
+  apiKey: process.env.ONEDEX_API_KEY,
+});
+```
+
+Recommended subscriber flow:
+
+1. Check the V2 `api_addresses` usage view (or the legacy V1 response during rollout) with `client.account.usage()`.
+2. Try `client.address.details(...)` with an address, parcel, coordinates, or a `normalizedAddressKey`, plus a caller-generated idempotency key.
+3. 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.
+4. Follow the returned `details_url` with `client.address.detailsUrl(...)`; the helper rejects another origin or route.
+
+```js
+import { randomUUID } from "node:crypto";
+
+const usage = await client.account.usage();
+
+try {
+  const details = await client.address.details({
+    address: "10 rue des cordeliers aix",
+    fields: ["summary", "rail"],
+    idempotencyKey: randomUUID(),
+  }, { retry: true });
+  console.log(details.fields);
+} catch (error) {
+  if (!(error instanceof OneDexApiError)) {
+    throw error;
+  }
+  if (error.status !== 402 || error.body?.error !== "address_unlock_required") {
+    throw error;
+  }
+
+  const unlockIdempotencyKey = randomUUID();
+  const unlock = error.body.unlock_request
+    ? await client.address.unlock({
+        ...error.body.unlock_request,
+        idempotencyKey: unlockIdempotencyKey,
+      }, { retry: true })
+    : await client.address.unlock({
+        normalizedAddressKey: error.body.normalized_address_key,
+        idempotencyKey: unlockIdempotencyKey,
+      }, { retry: true });
+
+  const details = unlock.details_url
+    ? await client.address.detailsUrl(unlock.details_url, {
+        idempotencyKey: randomUUID(),
+        retry: true,
+      })
+    : await client.address.details({
+        normalizedAddressKey: unlock.normalized_address_key,
+        fields: ["summary", "rail"],
+        idempotencyKey: randomUUID(),
+      }, { retry: true });
+
+  console.log(usage.version, details.fields);
+}
+```
+
+`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.
+
+Common professional API errors:
+
+- `invalid_api_key`: the API key is missing, invalid, or revoked.
+- `api_subscription_required`: the account needs an active subscription.
+- `api_professional_required`: the endpoint requires a professional plan.
+- `address_unlock_required`: the detailed address must be unlocked before reading.
+- `insufficient_credits`: the account has no remaining address credits for the requested unlock.
+
+## Helpers
+
+The client exposes helpers for the current `/api/v1` routes:
+
+- `client.overview.address(...)`
+- `client.address.details(...)`
+- `client.address.detailsUrl(...)`
+- `client.address.unlock(...)`
+- `client.account.usage()`
+- `client.autocomplete.address(...)`
+- `client.communes.search(...)`
+- `client.score.address(...)`, `client.score.compare(...)`, `client.score.grid(...)`, `client.score.addressSuggest(...)`
+- `client.preview.byPath(...)`
+- `client.addressPages.state(...)`
+- `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(...)`
+
+For command-line usage, install `@1dex-fr/1dex`.
+
+Supported runtimes: Node 22 and 24. Type declarations cover both legacy account usage and `account-usage-v2` during rollout.
+
+## Transport limits
+
+The 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.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "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"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "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"
+}