@wherabouts/sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `@wherabouts/sdk` are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/) and the
+[Keep a Changelog](https://keepachangelog.com/) format.
+
+## [0.2.0] - 2026-06-08
+
+First publishable release. Renamed from the internal `@wherabouts.com/sdk`.
+
+### Added
+
+- **Full API coverage** — 22 methods across six resource namespaces
+  (`addresses`, `geocode`, `zones`, `devices`, `webhooks`, `regions`),
+  replacing the previous addresses-only surface.
+- **Automatic retries** for transient failures (`408/425/429/5xx`, network errors,
+  timeouts) with exponential backoff + full jitter; honours `Retry-After`.
+- **Per-request timeouts** (`timeoutMs`, default 30s) and `AbortSignal` support.
+- **Idempotent writes** — `POST`/`PUT` calls auto-attach an `Idempotency-Key`;
+  override via per-call `options.idempotencyKey`.
+- **Per-request `options`** on every method (`timeoutMs`, `maxRetries`, `signal`,
+  `idempotencyKey`, `headers`).
+- **Richer errors** — `WheraboutsApiError` now exposes `requestId`, `docUrl`, and
+  `fields` (forward-compatible with the API's expanded error envelope).
+- **Published build** — dual ESM + CJS with bundled `.d.ts`, verified by
+  `publint` and `are-the-types-wrong`.
+
+### Changed
+
+- Package renamed `@wherabouts.com/sdk` → **`@wherabouts/sdk`** (npm scopes cannot
+  contain a dot). No backward-compat alias — the prior version was unpublished.
+- Client surface is now resource-namespaced (`client.zones.create(...)`), replacing
+  the earlier flat methods.
+
+[0.2.0]: https://github.com/amani-joseph/wherabouts.com/releases/tag/sdk-v0.2.0

package/README.md

@@ -0,0 +1,138 @@
+# @wherabouts/sdk
+
+Official TypeScript SDK for the [Wherabouts](https://wherabouts.com) location API —
+Australian geocoding, geofencing zones, device tracking, and webhooks over
+authoritative G‑NAF / ABS data.
+
+- **Dependency-free** and runtime-agnostic (Node, edge, browser) — built on `fetch`.
+- **Fully typed**, resource-namespaced surface (`client.zones.create(...)`).
+- **Resilient by default**: automatic retries with backoff, per-request timeouts,
+  `AbortSignal` support, and idempotent writes.
+
+## Install
+
+```sh
+npm install @wherabouts/sdk
+# or: pnpm add @wherabouts/sdk · yarn add @wherabouts/sdk
+```
+
+Requires Node.js 18+ (or any runtime with a global `fetch`).
+
+## Quickstart (60 seconds)
+
+```ts
+import { createWheraboutsClient } from "@wherabouts/sdk";
+
+const client = createWheraboutsClient({
+  apiKey: process.env.WHERABOUTS_API_KEY!,
+});
+
+// Classify a coordinate into official ABS/ASGS regions
+const regions = await client.regions.classify({
+  lat: -37.8136,
+  lng: 144.9631,
+});
+
+// Autocomplete an address
+const { results } = await client.addresses.autocomplete({ q: "123 collins st" });
+
+// Create a geofence zone
+const zone = await client.zones.create({
+  name: "Melbourne CBD depot",
+  geometry: {
+    type: "Polygon",
+    coordinates: [
+      [
+        [144.95, -37.82],
+        [144.97, -37.82],
+        [144.97, -37.8],
+        [144.95, -37.8],
+        [144.95, -37.82],
+      ],
+    ],
+  },
+});
+```
+
+## Resources
+
+| Namespace | Methods |
+|---|---|
+| `client.addresses` | `autocomplete`, `getById`, `nearby`, `reverse` |
+| `client.geocode` | `forward`, `batch.submit`, `batch.poll`, `batch.results` |
+| `client.zones` | `create`, `list`, `get`, `update`, `delete`, `contains`, `addresses` |
+| `client.devices` | `pushLocation`, `zones` |
+| `client.webhooks` | `create`, `list`, `delete`, `reactivate` |
+| `client.regions` | `classify` |
+
+## Configuration
+
+```ts
+const client = createWheraboutsClient({
+  apiKey: "wh_...",          // required
+  baseUrl: "https://api.wherabouts.com", // optional override
+  maxRetries: 2,              // optional, default 2
+  timeoutMs: 30_000,          // optional, default 30s
+  fetch: customFetch,         // optional fetch implementation
+  headers: { "x-app": "..." } // optional default headers
+});
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `apiKey` | — | Your Wherabouts API key (`wh_...`). Required. |
+| `baseUrl` | `https://api.wherabouts.com` | API origin override. |
+| `maxRetries` | `2` | Automatic retries for transient failures (429/5xx/network/timeout). |
+| `timeoutMs` | `30000` | Per-request timeout. |
+| `fetch` | `globalThis.fetch` | Custom `fetch` implementation. |
+| `headers` | — | Default headers added to every request. |
+
+### Per-request options
+
+Every method accepts an optional trailing `options` argument to override the client
+defaults for a single call:
+
+```ts
+await client.addresses.autocomplete(
+  { q: "123 collins st" },
+  { timeoutMs: 5000, signal: AbortSignal.timeout(5000) }
+);
+
+// Writes auto-attach an Idempotency-Key; supply your own to dedupe explicitly:
+await client.zones.create(zoneBody, { idempotencyKey: "order-42" });
+```
+
+## Resilience
+
+- **Retries** transient failures (HTTP `408/425/429/500/502/503/504`, network errors,
+  and timeouts) up to `maxRetries`, using exponential backoff with full jitter
+  (200 ms base, 5 s cap). A `Retry-After` response header is honoured when present.
+- **Idempotent writes**: `POST`/`PUT` calls automatically send an `Idempotency-Key`
+  header so retries are safe. Pass `options.idempotencyKey` to control it.
+- **Timeouts & cancellation**: each request times out after `timeoutMs`; pass
+  `options.signal` to cancel a call yourself.
+
+## Error handling
+
+Failed requests reject with a `WheraboutsApiError`:
+
+```ts
+import { WheraboutsApiError } from "@wherabouts/sdk";
+
+try {
+  await client.zones.get(999);
+} catch (err) {
+  if (err instanceof WheraboutsApiError) {
+    err.status;     // HTTP status (e.g. 404)
+    err.code;       // machine code (e.g. "not_found")
+    err.message;    // human-readable message
+    err.requestId;  // correlation id for support, if provided
+    err.docUrl;     // link to error docs, if provided
+    err.fields;     // field-level validation detail, if provided
+  }
+}
+```
+
+## License
+
+UNLICENSED — © Wherabouts. Contact the maintainers for usage terms.

package/dist/index.cjs

@@ -0,0 +1,431 @@
+'use strict';
+
+// src/errors.ts
+var WheraboutsApiError = class extends Error {
+  code;
+  payload;
+  status;
+  /** Correlation id from the `X-Request-Id` header or error body, if present. */
+  requestId;
+  /** Documentation link for this error, if the API provided one. */
+  docUrl;
+  /** Field-level validation detail, if the API provided any. */
+  fields;
+  constructor(options) {
+    super(options.message);
+    this.name = "WheraboutsApiError";
+    this.status = options.status;
+    this.code = options.code ?? "unknown_error";
+    this.payload = options.payload ?? null;
+    this.requestId = options.requestId ?? null;
+    this.docUrl = options.docUrl ?? null;
+    this.fields = options.fields ?? null;
+  }
+};
+
+// src/shared-types.ts
+var WHERABOUTS_API_VERSION = "v1";
+var WHERABOUTS_SDK_VERSION = "0.2.0";
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://api.wherabouts.com";
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var BACKOFF_BASE_MS = 200;
+var BACKOFF_CAP_MS = 5e3;
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
+var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT"]);
+var createBaseHeaders = (config) => {
+  const headers = new Headers(config.headers);
+  headers.set("accept", "application/json");
+  headers.set("authorization", `Bearer ${config.apiKey}`);
+  headers.set(
+    "x-wherabouts-sdk",
+    `js-ts/${WHERABOUTS_SDK_VERSION} api/${WHERABOUTS_API_VERSION}`
+  );
+  return headers;
+};
+var generateIdempotencyKey = () => {
+  const cryptoObj = globalThis.crypto;
+  if (cryptoObj?.randomUUID) {
+    return cryptoObj.randomUUID();
+  }
+  return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+};
+var buildRequestHeaders = (baseHeaders, opts) => {
+  const headers = new Headers(baseHeaders);
+  if (opts.headers) {
+    for (const [key, value] of Object.entries(opts.headers)) {
+      headers.set(key, value);
+    }
+  }
+  if (opts.body !== void 0) {
+    headers.set("content-type", "application/json");
+  }
+  if (WRITE_METHODS.has(opts.method)) {
+    headers.set(
+      "idempotency-key",
+      opts.idempotencyKey ?? generateIdempotencyKey()
+    );
+  } else if (opts.idempotencyKey) {
+    headers.set("idempotency-key", opts.idempotencyKey);
+  }
+  return headers;
+};
+var readRequestId = (response) => response.headers.get("x-request-id") ?? response.headers.get("x-wherabouts-request-id");
+var parseApiError = async (response) => {
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch {
+    payload = null;
+  }
+  const message = payload?.error.message ?? `Wherabouts request failed with status ${response.status}`;
+  return new WheraboutsApiError({
+    status: response.status,
+    message,
+    code: payload?.error.code ?? "unknown_error",
+    payload,
+    requestId: payload?.error.request_id ?? readRequestId(response),
+    docUrl: payload?.error.doc_url ?? null,
+    fields: payload?.error.fields ?? null
+  });
+};
+var parseRetryAfter = (value) => {
+  if (!value) {
+    return null;
+  }
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) {
+    return Math.max(0, seconds * 1e3);
+  }
+  const dateMs = Date.parse(value);
+  if (Number.isNaN(dateMs)) {
+    return null;
+  }
+  return Math.max(0, dateMs - Date.now());
+};
+var computeBackoff = (attempt) => {
+  const exponential = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
+  return Math.random() * exponential;
+};
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) {
+    reject(signal.reason ?? new Error("Aborted"));
+    return;
+  }
+  const timer = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  const onAbort = () => {
+    clearTimeout(timer);
+    reject(signal?.reason ?? new Error("Aborted"));
+  };
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+var createRequester = (config) => {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error(
+      "A fetch implementation is required to create the SDK client."
+    );
+  }
+  const baseUrl = new URL(config.baseUrl ?? DEFAULT_BASE_URL);
+  const baseHeaders = createBaseHeaders(config);
+  return async (opts) => {
+    const url = new URL(opts.path, baseUrl);
+    if (opts.query) {
+      for (const [key, value] of Object.entries(opts.query)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const headers = buildRequestHeaders(baseHeaders, opts);
+    const hasBody = opts.body !== void 0;
+    const body = hasBody ? JSON.stringify(opts.body) : void 0;
+    const maxRetries = opts.maxRetries ?? config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const timeoutMs = opts.timeoutMs ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const callerSignal = opts.signal;
+    let attempt = 0;
+    while (true) {
+      const controller = new AbortController();
+      let timedOut = false;
+      const timeoutId = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, timeoutMs);
+      const onCallerAbort = () => controller.abort();
+      if (callerSignal) {
+        if (callerSignal.aborted) {
+          controller.abort();
+        } else {
+          callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+        }
+      }
+      try {
+        const response = await fetchImpl(url, {
+          method: opts.method,
+          headers,
+          body,
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          if (RETRYABLE_STATUSES.has(response.status) && attempt < maxRetries) {
+            const wait = parseRetryAfter(response.headers.get("retry-after")) ?? computeBackoff(attempt);
+            attempt++;
+            await sleep(Math.min(wait, BACKOFF_CAP_MS), callerSignal);
+            continue;
+          }
+          throw await parseApiError(response);
+        }
+        if (response.status === 204) {
+          return void 0;
+        }
+        const text = await response.text();
+        return text ? JSON.parse(text) : void 0;
+      } catch (error) {
+        if (callerSignal?.aborted) {
+          throw error;
+        }
+        if (timedOut) {
+          if (attempt < maxRetries) {
+            attempt++;
+            await sleep(computeBackoff(attempt - 1), callerSignal);
+            continue;
+          }
+          throw new WheraboutsApiError({
+            status: 0,
+            code: "timeout",
+            message: `Request timed out after ${timeoutMs}ms.`
+          });
+        }
+        if (error instanceof WheraboutsApiError) {
+          throw error;
+        }
+        if (attempt < maxRetries) {
+          attempt++;
+          await sleep(computeBackoff(attempt - 1), callerSignal);
+          continue;
+        }
+        throw error;
+      } finally {
+        clearTimeout(timeoutId);
+        callerSignal?.removeEventListener("abort", onCallerAbort);
+      }
+    }
+  };
+};
+
+// src/resources/addresses.ts
+var createAddresses = (request) => ({
+  autocomplete: (params, options) => request({
+    method: "GET",
+    path: "/api/v1/addresses/autocomplete",
+    query: {
+      q: params.q,
+      country: params.country,
+      state: params.state,
+      limit: params.limit
+    },
+    ...options
+  }),
+  getById: (id, options) => request({
+    method: "GET",
+    path: `/api/v1/addresses/${id}`,
+    ...options
+  }),
+  nearby: (params, options) => request({
+    method: "GET",
+    path: "/api/v1/addresses/nearby",
+    query: {
+      lat: params.lat,
+      lng: params.lng,
+      radius: params.radius,
+      limit: params.limit,
+      country: params.country
+    },
+    ...options
+  }),
+  reverse: (params, options) => request({
+    method: "GET",
+    path: "/api/v1/addresses/reverse",
+    query: { lat: params.lat, lng: params.lng },
+    ...options
+  })
+});
+
+// src/resources/devices.ts
+var createDevices = (request) => ({
+  pushLocation: (deviceId, body, options) => request({
+    method: "POST",
+    path: `/api/v1/devices/${deviceId}/location`,
+    body,
+    ...options
+  }),
+  zones: (deviceId, options) => request({
+    method: "GET",
+    path: `/api/v1/devices/${deviceId}/zones`,
+    ...options
+  })
+});
+
+// src/resources/geocode.ts
+var createGeocode = (request) => ({
+  forward: (params, options) => request({
+    method: "GET",
+    path: "/api/v1/addresses/geocode",
+    query: {
+      q: params.q,
+      structured: params.structured,
+      street: params.street,
+      locality: params.locality,
+      state: params.state,
+      postcode: params.postcode,
+      country: params.country
+    },
+    ...options
+  }),
+  batch: {
+    submit: (body, options) => request({
+      method: "POST",
+      path: "/api/v1/geocode/batch",
+      body,
+      ...options
+    }),
+    poll: (jobId, options) => request({
+      method: "GET",
+      path: `/api/v1/geocode/batch/${jobId}`,
+      ...options
+    }),
+    results: (jobId, options) => request({
+      method: "GET",
+      path: `/api/v1/geocode/batch/${jobId}/results`,
+      ...options
+    })
+  }
+});
+
+// src/resources/regions.ts
+var createRegions = (request) => ({
+  classify: (params, options) => request({
+    method: "GET",
+    path: "/api/v1/regions",
+    query: { lat: params.lat, lng: params.lng, layers: params.layers },
+    ...options
+  })
+});
+
+// src/resources/routing.ts
+var createRouting = (request) => ({
+  directions: (params, options) => request({
+    method: "GET",
+    path: "/api/v1/routing/directions",
+    query: {
+      from: params.from,
+      to: params.to,
+      fromAddressId: params.fromAddressId,
+      toAddressId: params.toAddressId,
+      profile: params.profile
+    },
+    ...options
+  })
+});
+
+// src/resources/webhooks.ts
+var createWebhooks = (request) => ({
+  create: (body, options) => request({
+    method: "POST",
+    path: "/api/v1/webhooks",
+    body,
+    ...options
+  }),
+  list: (options) => request({
+    method: "GET",
+    path: "/api/v1/webhooks",
+    ...options
+  }),
+  delete: (id, options) => request({
+    method: "DELETE",
+    path: `/api/v1/webhooks/${id}`,
+    ...options
+  }),
+  reactivate: (id, options) => request({
+    method: "POST",
+    path: `/api/v1/webhooks/${id}/reactivate`,
+    ...options
+  })
+});
+
+// src/resources/zones.ts
+var createZones = (request) => ({
+  create: (body, options) => request({
+    method: "POST",
+    path: "/api/v1/zones",
+    body,
+    ...options
+  }),
+  list: (params, options) => request({
+    method: "GET",
+    path: "/api/v1/zones",
+    query: { page: params?.page, limit: params?.limit },
+    ...options
+  }),
+  get: (id, options) => request({
+    method: "GET",
+    path: `/api/v1/zones/${id}`,
+    ...options
+  }),
+  update: (id, body, options) => request({
+    method: "PUT",
+    path: `/api/v1/zones/${id}`,
+    body,
+    ...options
+  }),
+  delete: (id, options) => request({
+    method: "DELETE",
+    path: `/api/v1/zones/${id}`,
+    ...options
+  }),
+  contains: (params, options) => request({
+    method: "GET",
+    path: "/api/v1/zones/contains",
+    query: { lat: params.lat, lng: params.lng },
+    ...options
+  }),
+  addresses: (id, params, options) => request({
+    method: "GET",
+    path: `/api/v1/zones/${id}/addresses`,
+    query: { page: params?.page, limit: params?.limit },
+    ...options
+  })
+});
+
+// src/client.ts
+var createWheraboutsClient = (config) => {
+  const request = createRequester(config);
+  return {
+    addresses: createAddresses(request),
+    geocode: createGeocode(request),
+    zones: createZones(request),
+    devices: createDevices(request),
+    webhooks: createWebhooks(request),
+    regions: createRegions(request),
+    routing: createRouting(request)
+  };
+};
+
+exports.WHERABOUTS_API_VERSION = WHERABOUTS_API_VERSION;
+exports.WHERABOUTS_SDK_VERSION = WHERABOUTS_SDK_VERSION;
+exports.WheraboutsApiError = WheraboutsApiError;
+exports.createAddresses = createAddresses;
+exports.createDevices = createDevices;
+exports.createGeocode = createGeocode;
+exports.createRegions = createRegions;
+exports.createRouting = createRouting;
+exports.createWebhooks = createWebhooks;
+exports.createWheraboutsClient = createWheraboutsClient;
+exports.createZones = createZones;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map