@isnap/sdk 0.0.0-next.3

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `@isnap/sdk` will be documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-1.0 versions may introduce breaking changes between 0.x → 0.(x+1) minor bumps.
+
+## [Unreleased]
+
+### Added
+- Initial public surface targeting iSnap API contract `v1.0.0`.
+- `ISnapClient` with retries (jittered exponential backoff on 429/5xx), per-attempt timeout, auto-`Idempotency-Key` for mutating verbs, header injection, abortable requests.
+- Resource classes: `messages`, `chats`, `lines`, `lookup`, `attachments`, `webhooks`, `byod`, `trial`.
+- `attachments.upload()` — transparent 3-step (POST register → presigned R2 PUT → poll until `ready`) with 5 GB cap and four typed failure modes.
+- Cursor pagination as `AsyncIterable` with optional `AbortSignal` on `messages.list`, `webhooks.deliveries`, `webhooks.events`.
+- Webhook helpers: `verifyWebhook` (HMAC-SHA256 + 5min replay window + multi-secret rotation), `parseWebhookEvent`, prefix-based type guards (`isMessageEvent`, `isReactionEvent`, `isLineEvent`, `isTypingEvent`, `isTrialEvent`).
+- Error hierarchy mirroring contract §6: `APIError` + 13 subclasses, all carrying `status`, `code`, `traceId`, `requestId`. Connection failures surface as `APIConnectionError` with native `Error.cause`.
+- Generated TypeScript types (`src/generated/openapi.d.ts`) compiled from the backend's frozen `openapi.json`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iSnap
+
+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,242 @@
+# @isnap/sdk
+
+Official TypeScript SDK for the [iSnap](https://isnap.ai) P2P telephony API — real iMessage / SMS / RCS lines from real handsets, exposed as a single typed client.
+
+> Pre-1.0. Targets contract `docs/api-contract.md` v1.0.0. Public surface is stable across the v0.x line; breaking changes will bump 0.x → 0.(x+1) until 1.0.0.
+
+## Install
+
+```bash
+bun add @isnap/sdk
+# or
+npm install @isnap/sdk
+```
+
+Requires Node 20+ (or Bun 1.2+). The SDK uses native `fetch`, `node:crypto`, and ES2022 `Error.cause` — no polyfills.
+
+## Quick start
+
+```ts
+import { ISnapClient } from '@isnap/sdk'
+
+const client = new ISnapClient({ apiKey: process.env.ISNAP_API_KEY! })
+
+const message = await client.messages.send({
+  line_id: 'line_01HX...',
+  to: '+15551234567',
+  body: 'Hello from iSnap'
+})
+
+console.log(message.id, message.status)
+```
+
+## Configuration
+
+```ts
+new ISnapClient({
+  apiKey: 'sk_live_...',          // required
+  baseUrl: 'https://api.isnap.ai', // default
+  maxRetries: 3,                  // default 3 — retries on 429/5xx with jittered backoff
+  timeoutMs: 30_000,              // per-attempt timeout
+  idempotencyKey: 'auto',         // 'auto' generates UUIDs for POST/PATCH/PUT/DELETE; 'manual' = pass via opts
+  fetch: undefined,               // override (e.g. an instrumented fetch)
+  onRetry: (info) => console.warn('retry', info)
+})
+```
+
+Every resource method accepts an optional `RequestOptions` final argument: `{ signal, idempotencyKey, headers, query, maxRetries }`.
+
+## Resources
+
+| Resource | What it does |
+|---|---|
+| `client.messages` | Send / get / cancel / list messages, add reactions |
+| `client.chats` | Mark a chat read, send typing indicators, share a contact card |
+| `client.lines` | List, configure, and inspect rented + BYOD lines, plus quota and queue snapshots |
+| `client.lookup` | Test if a number is iMessage-capable before sending |
+| `client.attachments` | Upload images / video / files (transparent 3-step flow) |
+| `client.webhooks` | CRUD subscriptions, rotate secrets, list deliveries, replay events |
+| `client.byod` | Pair a customer-owned Mac+iPhone or Android device |
+| `client.trial` | Start, check, and convert trial sessions |
+
+## Sending a message
+
+```ts
+const msg = await client.messages.send({
+  line_id: 'line_01HX...',
+  to: '+15551234567',
+  body: 'Order #1242 is on its way',
+  service: 'iMessage' // optional — falls back to SMS/RCS via the line's degradation chain
+})
+```
+
+`messages.send` is **idempotent by default** — the SDK auto-generates an `Idempotency-Key` for every POST. Retrying the same call with the same key returns the original message without sending a duplicate.
+
+## Listing with cursor pagination
+
+`list()` returns an `AsyncIterable` that threads cursors automatically:
+
+```ts
+for await (const msg of client.messages.list({ line_id: 'line_01HX...', limit: 100 })) {
+  console.log(msg.id, msg.created_at)
+}
+```
+
+To stop early, pass an `AbortSignal`. Aborting surfaces as a thrown `APIConnectionError` on the next page boundary, so wrap the loop:
+
+```ts
+import { APIConnectionError } from '@isnap/sdk'
+
+const ac = new AbortController()
+setTimeout(() => ac.abort(), 5_000)
+
+try {
+  for await (const msg of client.messages.list({}, { signal: ac.signal })) {
+    // ...
+  }
+} catch (err) {
+  if (!(err instanceof APIConnectionError)) throw err
+  // expected — signal aborted the iterator
+}
+```
+
+## Uploading an attachment
+
+`attachments.upload()` wraps the 3-step contract (register → presigned PUT → poll) into one call:
+
+```ts
+import { readFile } from 'node:fs/promises'
+
+const file = await readFile('./photo.jpg')
+
+const attachment = await client.attachments.upload(file, {
+  filename: 'photo.jpg',
+  contentType: 'image/jpeg'
+})
+
+await client.messages.send({
+  line_id: 'line_01HX...',
+  to: '+15551234567',
+  body: 'Here you go',
+  attachment_ids: [attachment.id]
+})
+```
+
+5 GB cap. Four documented failure modes — note that the R2 PUT and the server-side `failed` transition share the same `upload_failed` code:
+
+| Failure | `code` |
+|---|---|
+| `size_bytes` exceeds the 5 GB cap | `attachment_exceeds_storage_limit` |
+| R2 presigned PUT returns non-2xx | `upload_failed` |
+| Server transitions to `status: failed` | `upload_failed` |
+| Polling exhausted before `status: ready` | `upload_timeout` |
+
+## Verifying webhooks
+
+```ts
+import { verifyWebhook, isMessageEvent } from '@isnap/sdk'
+
+// Express / Hono / native handler — give us the RAW body bytes (string).
+async function handle(rawBody: string, headers: Record<string, string>) {
+  const event = verifyWebhook(rawBody, headers, process.env.ISNAP_WEBHOOK_SECRET!)
+
+  // Dedupe by event_id — delivery is at-least-once.
+  if (await alreadyProcessed(event.event_id)) return
+
+  if (isMessageEvent(event)) {
+    console.log(event.event_type, event.data.message.id)
+  }
+}
+```
+
+During a `rotate-secret` grace window pass both secrets:
+
+```ts
+verifyWebhook(rawBody, headers, [newSecret, oldSecret])
+```
+
+Throws `WebhookSignatureError` on missing headers, expired timestamp (5min tolerance), or signature mismatch.
+
+If verification happens behind a trusted gateway, use `parseWebhookEvent(rawBody)` to skip HMAC and just type the envelope.
+
+## Errors
+
+All API errors extend `APIError` and carry `status`, `code`, `message`, `traceId`, `requestId`. Subclasses match the §6 contract codes:
+
+```ts
+import {
+  APIError,
+  APIConnectionError,
+  AuthenticationError,
+  BadRequestError,
+  ConflictError,
+  GoneError,
+  InternalServerError,
+  NotFoundError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  QuotaExceededError,
+  RateLimitError,
+  ServiceUnavailableError,
+  UnprocessableEntityError,
+  WebhookSignatureError
+} from '@isnap/sdk'
+
+try {
+  await client.messages.send({
+    line_id: 'line_01HX...',
+    to: '+15551234567',
+    body: 'hello'
+  })
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    // retry-after handled automatically by the retry loop, but visible here too
+  } else if (err instanceof QuotaExceededError) {
+    // pause sending until next quota window
+  } else if (err instanceof APIError) {
+    console.error(err.status, err.code, err.traceId)
+  } else if (err instanceof APIConnectionError) {
+    // network issue / timeout — already retried per `maxRetries`
+  } else {
+    throw err
+  }
+}
+```
+
+Retries: 429 + 5xx are retried automatically with jittered exponential backoff up to `maxRetries`. The retry budget is per-call.
+
+## Examples
+
+Runnable scripts in [`examples/`](https://github.com/WhatSnap/iSnap-App/tree/main/packages/sdk/examples) (browse on GitHub — they live in the repo, not the published tarball):
+
+- `send-message.ts` — minimal send
+- `paginate-messages.ts` — async iterator + abort
+- `upload-attachment.ts` — file upload + send with attachment
+- `handle-webhook.ts` — `node:http` server that verifies and dispatches events
+
+Run them against a local backend:
+
+```bash
+ISNAP_API_KEY=sk_test_... bun run examples/send-message.ts
+```
+
+## Development
+
+```bash
+bun install
+bun run --filter '@isnap/sdk' test
+bun run --filter '@isnap/sdk' typecheck
+bun run --filter '@isnap/sdk' lint
+bun run --filter '@isnap/sdk' build
+```
+
+To regenerate types from the backend's frozen OpenAPI spec:
+
+```bash
+bun run --filter '@isnap/backend' dump-openapi   # writes packages/backend/openapi.json
+bun run --filter '@isnap/sdk' generate           # regenerates src/generated/openapi.d.ts
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+import { type ClientConfig } from './config.js';
+import { AttachmentsResource } from './resources/attachments.js';
+import { ByodResource } from './resources/byod.js';
+import { ChatsResource } from './resources/chats.js';
+import { LinesResource } from './resources/lines.js';
+import { LookupResource } from './resources/lookup.js';
+import { MessagesResource } from './resources/messages.js';
+import { TrialResource } from './resources/trial.js';
+import { WebhooksResource } from './resources/webhooks.js';
+import type { HttpMethod, RequestOptions } from './types.js';
+export declare class ISnapClient {
+    private readonly config;
+    readonly attachments: AttachmentsResource;
+    readonly byod: ByodResource;
+    readonly chats: ChatsResource;
+    readonly lines: LinesResource;
+    readonly lookup: LookupResource;
+    readonly messages: MessagesResource;
+    readonly trial: TrialResource;
+    readonly webhooks: WebhooksResource;
+    constructor(config: ClientConfig);
+    /**
+     * Direct fetch with no SDK auth, no envelope parsing, no retry — used
+     * internally by resource methods that must call URLs OUTSIDE the iSnap
+     * API surface (e.g. presigned R2 PUTs during `attachments.upload`).
+     *
+     * The leading underscore signals "internal but unavoidably public": it
+     * lives on the public class because resource classes cannot reach the
+     * private `config.fetch` otherwise. SDK consumers should use the typed
+     * resource methods or `request()` for everything in `/v1/*` — calling
+     * this directly bypasses the SDK contract.
+     *
+     * Applies the same `config.timeoutMs` ceiling as `request()` so a
+     * stalled R2 PUT cannot hang the upload indefinitely.
+     *
+     * @internal
+     */
+    _externalFetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Low-level request method. Resource classes wrap this with typed
+     * camelCase signatures; advanced users can call it directly for
+     * endpoints not yet covered by a resource.
+     */
+    request<T>(method: HttpMethod, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    private dispatch;
+    private buildUrl;
+    private buildHeaders;
+    private connectionErrorMessage;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EAElB,MAAM,aAAa,CAAA;AAQpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAA;AAc9E,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAA;IACzC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;gBAEvB,MAAM,EAAE,YAAY;IAYhC;;;;;;;;;;;;;;;OAeG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAoB5E;;;;OAIG;IACG,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,CAAC,CAAC;YAwBC,QAAQ;IAyGtB,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,sBAAsB;CAO/B"}

package/dist/client.js

@@ -0,0 +1,242 @@
+import { resolveConfig, validateMaxRetries } from './config.js';
+import { APIConnectionError, APIError, ServiceUnavailableError, fromEnvelope } from './errors.js';
+import { generateIdempotencyKey } from './idempotency.js';
+import { AttachmentsResource } from './resources/attachments.js';
+import { ByodResource } from './resources/byod.js';
+import { ChatsResource } from './resources/chats.js';
+import { LinesResource } from './resources/lines.js';
+import { LookupResource } from './resources/lookup.js';
+import { MessagesResource } from './resources/messages.js';
+import { TrialResource } from './resources/trial.js';
+import { WebhooksResource } from './resources/webhooks.js';
+import { withRetries } from './retry.js';
+import { SDK_VERSION } from './version.js';
+const MUTATING = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
+const NON_JSON_PREVIEW = 200;
+// Hard cap on response body size. Server-side limits are stricter in
+// practice; this is defense-in-depth against a misbehaving proxy or test
+// harness streaming an unbounded body.
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const USER_AGENT = `@isnap/sdk/${SDK_VERSION}`;
+export class ISnapClient {
+    config;
+    attachments;
+    byod;
+    chats;
+    lines;
+    lookup;
+    messages;
+    trial;
+    webhooks;
+    constructor(config) {
+        this.config = resolveConfig(config);
+        this.attachments = new AttachmentsResource(this);
+        this.byod = new ByodResource(this);
+        this.chats = new ChatsResource(this);
+        this.lines = new LinesResource(this);
+        this.lookup = new LookupResource(this);
+        this.messages = new MessagesResource(this);
+        this.trial = new TrialResource(this);
+        this.webhooks = new WebhooksResource(this);
+    }
+    /**
+     * Direct fetch with no SDK auth, no envelope parsing, no retry — used
+     * internally by resource methods that must call URLs OUTSIDE the iSnap
+     * API surface (e.g. presigned R2 PUTs during `attachments.upload`).
+     *
+     * The leading underscore signals "internal but unavoidably public": it
+     * lives on the public class because resource classes cannot reach the
+     * private `config.fetch` otherwise. SDK consumers should use the typed
+     * resource methods or `request()` for everything in `/v1/*` — calling
+     * this directly bypasses the SDK contract.
+     *
+     * Applies the same `config.timeoutMs` ceiling as `request()` so a
+     * stalled R2 PUT cannot hang the upload indefinitely.
+     *
+     * @internal
+     */
+    async _externalFetch(url, init = {}) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        const callerSignal = init.signal;
+        let abortListener;
+        if (callerSignal) {
+            if (callerSignal.aborted)
+                controller.abort(callerSignal.reason);
+            else {
+                abortListener = () => controller.abort(callerSignal.reason);
+                callerSignal.addEventListener('abort', abortListener, { once: true });
+            }
+        }
+        try {
+            return await this.config.fetch(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timeoutId);
+            if (abortListener)
+                callerSignal?.removeEventListener('abort', abortListener);
+        }
+    }
+    /**
+     * Low-level request method. Resource classes wrap this with typed
+     * camelCase signatures; advanced users can call it directly for
+     * endpoints not yet covered by a resource.
+     */
+    async request(method, path, body, opts = {}) {
+        const url = this.buildUrl(path, opts.query);
+        const idempotencyKey = opts.idempotencyKey ??
+            (this.config.idempotencyKey === 'auto' && MUTATING.has(method)
+                ? generateIdempotencyKey()
+                : undefined);
+        const headers = this.buildHeaders(idempotencyKey, body !== undefined, opts.headers);
+        const init = {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined
+        };
+        const maxRetries = opts.maxRetries !== undefined ? validateMaxRetries(opts.maxRetries) : this.config.maxRetries;
+        return withRetries(() => this.dispatch(url, init, opts), {
+            maxRetries,
+            onRetry: this.config.onRetry,
+            signal: opts.signal
+        });
+    }
+    async dispatch(url, init, opts) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        // Track the abort listener so we can detach it in `finally`. Without
+        // detachment, a long-lived caller signal (e.g. a Node process-wide
+        // shutdown signal) accumulates one closure per request — leaking the
+        // per-attempt AbortController, the caller's `opts`, and any captured
+        // closure state until the signal eventually fires. Detaching at the
+        // end of the dispatch resolves the leak immediately.
+        const callerSignal = opts.signal;
+        let abortListener;
+        if (callerSignal) {
+            if (callerSignal.aborted)
+                controller.abort(callerSignal.reason);
+            else {
+                abortListener = () => controller.abort(callerSignal.reason);
+                callerSignal.addEventListener('abort', abortListener, { once: true });
+            }
+        }
+        let response;
+        try {
+            response = await this.config.fetch(url, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            throw new APIConnectionError(this.connectionErrorMessage(err), { cause: err });
+        }
+        finally {
+            clearTimeout(timeoutId);
+            if (abortListener)
+                callerSignal?.removeEventListener('abort', abortListener);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        const headerTrace = response.headers.get('x-trace-id') ?? '';
+        const headerRequest = response.headers.get('x-request-id') ?? '';
+        const declaredLength = response.headers.get('content-length');
+        if (declaredLength) {
+            const n = Number.parseInt(declaredLength, 10);
+            if (Number.isFinite(n) && n > MAX_RESPONSE_BYTES) {
+                throw new APIError({
+                    status: response.status,
+                    code: 'response_too_large',
+                    message: `Response body exceeds ${MAX_RESPONSE_BYTES} bytes (Content-Length: ${n})`,
+                    traceId: headerTrace,
+                    requestId: headerRequest
+                });
+            }
+        }
+        const text = await response.text();
+        const payload = (() => {
+            if (!text)
+                return null;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (!payload) {
+            const message = `Server returned non-JSON response (HTTP ${response.status})${text ? `: ${text.slice(0, NON_JSON_PREVIEW)}` : ''}`;
+            // 5xx without an envelope is still transient infra (Cloudflare HTML, LB
+            // 502 page) — surface as ServiceUnavailableError so the retry loop
+            // kicks in. 4xx without an envelope is a misbehaving proxy; surface
+            // immediately as base APIError so the caller sees the raw response.
+            if (response.status >= 500) {
+                throw new ServiceUnavailableError({
+                    status: response.status,
+                    code: 'invalid_response',
+                    message,
+                    traceId: headerTrace,
+                    requestId: headerRequest
+                });
+            }
+            throw new APIError({
+                status: response.status,
+                code: 'invalid_response',
+                message,
+                traceId: headerTrace,
+                requestId: headerRequest
+            });
+        }
+        const traceId = payload.trace_id ?? headerTrace;
+        const requestId = payload.request_id ?? headerRequest;
+        if (!response.ok || payload.success === false || payload.error) {
+            const envelope = payload.error ?? {
+                status: response.status,
+                code: 'unknown_error',
+                message: `HTTP ${response.status} (no error envelope)`
+            };
+            throw fromEnvelope(envelope, traceId, requestId);
+        }
+        return payload.data;
+    }
+    buildUrl(path, query) {
+        const fullPath = path.startsWith('/') ? path : `/${path}`;
+        let url = this.config.baseUrl + fullPath;
+        if (query) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (value === undefined || value === null)
+                    continue;
+                params.append(key, String(value));
+            }
+            const qs = params.toString();
+            if (qs)
+                url += (url.includes('?') ? '&' : '?') + qs;
+        }
+        return url;
+    }
+    buildHeaders(idempotencyKey, hasBody, custom) {
+        const headers = new Headers();
+        // Defaults set first so caller-supplied headers can override them.
+        headers.set('User-Agent', USER_AGENT);
+        headers.set('Accept', 'application/json');
+        if (hasBody)
+            headers.set('Content-Type', 'application/json');
+        if (custom) {
+            const merged = new Headers(custom);
+            merged.forEach((value, key) => headers.set(key, value));
+        }
+        // Locked headers — set last so caller-supplied custom values cannot
+        // override the SDK-managed authentication or idempotency contract.
+        headers.set('Authorization', `Bearer ${this.config.apiKey}`);
+        if (idempotencyKey)
+            headers.set('Idempotency-Key', idempotencyKey);
+        return headers;
+    }
+    connectionErrorMessage(err) {
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return `Request aborted after ${this.config.timeoutMs}ms`;
+        }
+        if (err instanceof Error)
+            return `Network error: ${err.message}`;
+        return 'Network error';
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+import type { RetryInfo } from './retry.js';
+export interface ClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    maxRetries?: number;
+    timeoutMs?: number;
+    idempotencyKey?: 'auto' | 'manual';
+    fetch?: typeof fetch;
+    onRetry?: (info: RetryInfo) => void;
+}
+export interface ResolvedConfig {
+    apiKey: string;
+    baseUrl: string;
+    maxRetries: number;
+    timeoutMs: number;
+    idempotencyKey: 'auto' | 'manual';
+    fetch: typeof fetch;
+    onRetry?: (info: RetryInfo) => void;
+}
+export declare const DEFAULTS: {
+    baseUrl: string;
+    maxRetries: number;
+    timeoutMs: number;
+    idempotencyKey: "auto";
+};
+export declare function resolveConfig(config: ClientConfig): ResolvedConfig;
+/**
+ * Validate `maxRetries` — must be a non-negative integer. NaN, negatives,
+ * or non-integers (e.g. `Infinity`, `2.5`) would silently break the
+ * `for (let attempt = 0; attempt <= config.maxRetries; attempt++)` loop in
+ * `withRetries` and produce confusing failure modes (zero attempts, or
+ * fractional comparisons). Validate at the boundary so the error surfaces
+ * at construction, not on the first request. Exported for reuse from
+ * per-call `RequestOptions.maxRetries` overrides.
+ */
+export declare function validateMaxRetries(value: number | undefined): number;
+/**
+ * Validate `timeoutMs` — must be a finite positive number. NaN, zero,
+ * negative, or `Infinity` would either abort every request immediately or
+ * never time out at all.
+ */
+export declare function validateTimeoutMs(value: number | undefined): number;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,cAAc,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAClC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAA;IACjC,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;CACpC;AAED,eAAO,MAAM,QAAQ;;;;;CAKpB,CAAA;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAiBlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQpE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQnE"}