@chatlychat/sdk-node 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# @chatlychat/sdk-node
+
+## 0.2.0
+
+The typed surface goes from 9 methods to 55, and the SDK gains the behaviour
+`packages/sdk-spec/CONTRACT.md` requires of every Chatly SDK.
+
+### Added
+
+- **55 typed methods** across 13 namespaces — contacts, conversations,
+  tickets, macros, KB, search, CDP events, webhook deliveries, reports,
+  channels, billing and workspace — every one a route an API key can actually
+  call. The list is `packages/sdk-spec/surface.json`, shared with the Python,
+  Go, Ruby, PHP, Java, .NET and Rust SDKs, and each SDK proves its coverage by
+  executing every method and writing `surface.lock.json`.
+- **A typed error hierarchy.** `ChatlyApiError` with `status`, `code`,
+  `message`, `requestId`, `body` and `retryAfter`, plus
+  `ChatlyAuthenticationError` (401), `ChatlyPermissionError` (403),
+  `ChatlyNotFoundError` (404), `ChatlyConflictError` (409),
+  `ChatlyValidationError` (400/422), `ChatlyRateLimitError` (429),
+  `ChatlyServerError` (5xx) and a separate `ChatlyTransportError` for a
+  request that never got a response. Previously every failure was
+  `new Error("livechat 403: …")`, so telling "wrong key" from "missing scope"
+  meant matching on a string.
+- **Retries.** Three attempts by default on a connection failure, a 429 or a
+  5xx, with exponential backoff and jitter, honouring `Retry-After`. Never on
+  any other 4xx. One idempotency key is reused across the attempts of a single
+  call, which is the only reason the header is safe to retry under.
+- **Auto-pagination.** `listAll()` on every cursor-paginated list, as an async
+  generator. It stops on a null cursor and throws rather than looping forever
+  if the server repeats one.
+- **`request(method, path, { query, body })`** — the escape hatch. 86 of the
+  141 key-accessible routes have no typed method; this reaches all of them
+  through the same auth, idempotency, retry and error handling.
+- `chatlyIdentityHash` and `verifyWebhookSignature` are unchanged and still
+  exported from the package root.
+
+### Fixed
+
+- **Three writes sent key names the API discards.** zod strips unknown keys,
+  so each returned 200 having done nothing: `contacts.merge` sent
+  `{ sourceContactId }` where the schema wants `{ mergedId }`;
+  `contacts.addTags` sent `{ tags: [...] }` where the route takes one
+  `{ tag }`; `contacts.unsubscribe` sent `{}` where `unsubscribed` is
+  required. `tickets.merge` now takes `{ loserId }`.
+- **`search.kb()` was not narrowing anything.** It sent `kinds[]=kb`, and the
+  search query schema is a zod object with a key named `kinds`, so the
+  bracketed key was stripped and the search ran across contacts,
+  conversations, messages and tickets — returning a valid 200 the caller could
+  not tell from a filtered one. It now sends a plain repeated `kinds`.
+- **`retryAfter` was always null on a real 429.** The API's throttler names
+  its buckets and emits `Retry-After-{bucket}`, never a plain `Retry-After`.
+  The SDK reads both now and takes the longest; the API also derives the plain
+  header.
+- **`MessageInput.kind` was missing `attachment_only`** — the one kind you
+  send when there are no words, only a file.
+- Error bodies are read from the API's real nested envelope,
+  `{ error: { code, message } }`, with a flat body as a fallback for proxy
+  errors.
+- `withIdempotencyKey()` no longer hand-rebuilds each namespace. The previous
+  clone forgot `search`, so a derived client's search methods still dispatched
+  through the parent — harmless while both were reads, a live bug the moment
+  one was not.
+- The published tarball no longer contains the compiled test files.
+
+## 0.1.0
+
+First release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chatly Engineering
+
+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

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @chatlychat/sdk-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server-side client for the Chatly API. Authenticates with an API key, so it is
+for your backend — not a browser, where the key would be readable.
+
+```bash
+pnpm add @chatlychat/sdk-node
+```
+
+## Quick start
+
+```ts
+import { ChatlyClient } from '@chatlychat/sdk-node';
+
+const chatly = new ChatlyClient({
+  apiKey: process.env.CHATLY_API_KEY!, // ck_live_…
+  apiUrl: 'https://api.chatlychat.com', // optional
+});
+
+const contacts = await chatly.contacts.list({ limit: 20 });
+```
+
+Create a key under **Workspace → Developer → API keys**. The token is shown
+once and stored only as a hash — if you lose it, revoke and mint another.
+
+Make `whoami()` your first call. It returns the workspace the key belongs to
+and the scopes it actually holds, so a mis-scoped key fails loudly at
+integration time instead of surfacing as a puzzling 403 from an unrelated
+endpoint in production:
+
+```ts
+const { workspaceId, scopes } = await chatly.whoami();
+```
+
+It is the only api-keys route a key may call: minting or listing keys with a
+key would let a leaked read-only key escalate itself.
+
+## What the client can do
+
+Every method below maps to an endpoint that accepts key authentication. Scope
+the key to only what your integration needs; a key can never do more than the
+scopes ticked when it was created.
+
+| Call                                                   | Scope required       |
+| ------------------------------------------------------ | -------------------- |
+| `chatly.whoami()`                                      | `workspace:read`     |
+| `chatly.contacts.list({ cursor?, limit? })`            | `contacts:read`      |
+| `chatly.contacts.upsert({ email, name, … })`           | `contacts:write`     |
+| `chatly.conversations.list({ cursor?, limit? })`       | `conversations:read` |
+| `chatly.conversations.messages(conversationId)`        | `conversations:read` |
+| `chatly.conversations.send({ conversationId, body })`  | `messages:write`     |
+| `chatly.search.query('refund', { … })`                 | `search:read`        |
+| `chatly.search.kb('refund')`                           | `search:read`        |
+| `chatly.events.track({ contactId, name, properties })` | `contacts:write`     |
+
+Messages you send with a key are recorded as sent by an integration, not by
+the person who created the key — a key outlives whoever issued it, so
+attributing its writes to them would be wrong the moment they leave.
+
+## Not included, and why
+
+Reactions and channel/widget configuration are absent on purpose. A reaction
+records _who_ reacted and a key is not a person, so those endpoints require a
+signed-in user. Channel configuration needs a scope no key can hold. Both used
+to be here and both returned 403 to every caller.
+
+## Idempotency
+
+Writes accept an idempotency key so a retry after a network failure does not
+duplicate work:
+
+```ts
+await chatly.withIdempotencyKey('order-4471-refund').contacts.upsert({ … });
+```
+
+## Verifying webhooks
+
+```ts
+import { verifyWebhookSignature } from '@chatlychat/sdk-node';
+
+const ok = verifyWebhookSignature({
+  body: rawBody, // the EXACT bytes, before JSON.parse
+  signatureHeader: req.headers['x-livechat-signature'] as string,
+  secret: process.env.CHATLY_WEBHOOK_SECRET!,
+});
+```
+
+Pass the raw body — re-serialising parsed JSON reorders keys and changes
+whitespace, so the digest will not match.
+
+The scheme is `t=<unix seconds>,v1=<hex>`, where `v1` is HMAC-SHA256 over
+`` `${t}.${body}` ``. The timestamp is inside the signed string, so a captured
+delivery stops verifying once it falls outside `toleranceSeconds`.
+
+> **This example was wrong until 2026-10-12, in three ways** — it said
+> `payload` (the field is `body`), `signature` (it is `signatureHeader`) and
+> `x-chatly-signature` (webhooks use **`x-livechat-signature`**). In
+> TypeScript the old snippet was a compile error; in plain JavaScript it was
+> worse than returning `false`, because the verifier splits
+> `input.signatureHeader` first and an absent one throws a `TypeError` out of
+> your webhook handler.
+>
+> The header name is the trap worth knowing: **`x-chatly-signature` is real,
+> but it belongs to four other surfaces** — external-agent deliveries, custom
+> AI tool calls, customer cards and the workflow `fire_webhook` action — and
+> each of those constructs its base string differently. Outbound event
+> webhooks are the one surface using `x-livechat-signature`. Do not share one
+> verifier across them without checking the construction.

package/dist/errors.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The error model.
+ *
+ * This SDK used to throw `new Error(`livechat ${status}: ${text}`)` for every
+ * failure, which forced every caller into string matching to tell "the key is
+ * wrong" from "the key is missing a scope" from "the contact does not exist".
+ * Those three need different handling — re-auth, ask an admin, create it — and
+ * a caller that cannot distinguish them retries all three or none.
+ *
+ * Nothing here extends the monorepo's `AppError`: this package is published to
+ * people who must not install our internals, so it stays dependency-free by
+ * design.
+ */
+/** The parsed body of an API error response, as far as it could be read. */
+export interface ApiErrorShape {
+    readonly code?: string;
+    readonly message?: string;
+}
+/** Base for everything this SDK throws. `instanceof ChatlyError` catches all of it. */
+export declare class ChatlyError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The API answered, and the answer was a failure status.
+ *
+ * `requestId` is the `x-request-id` header. Quote it in a support request —
+ * it is the only way to find the exact call in our traces.
+ */
+export declare class ChatlyApiError extends ChatlyError {
+    readonly name: string;
+    readonly status: number;
+    readonly code: string | null;
+    readonly requestId: string | null;
+    /** The raw response text. Everything `code`/`message` could not represent. */
+    readonly body: string;
+    /** Seconds the server asked us to wait, from `Retry-After`. Only on 429/503. */
+    readonly retryAfter: number | null;
+    constructor(input: {
+        status: number;
+        code: string | null;
+        message: string;
+        requestId: string | null;
+        body: string;
+        retryAfter: number | null;
+    });
+}
+/** 401 — the key is missing, malformed, revoked or belongs to no workspace. */
+export declare class ChatlyAuthenticationError extends ChatlyApiError {
+    readonly name: string;
+}
+/** 403 — the key is valid and lacks the scope this route needs. Check `whoami()`. */
+export declare class ChatlyPermissionError extends ChatlyApiError {
+    readonly name: string;
+}
+/** 404 — no such resource in this workspace. */
+export declare class ChatlyNotFoundError extends ChatlyApiError {
+    readonly name: string;
+}
+/**
+ * 409 — most often an idempotency conflict: this `Idempotency-Key` was already
+ * used with a DIFFERENT body. Mint a new key, or send the original body.
+ */
+export declare class ChatlyConflictError extends ChatlyApiError {
+    readonly name: string;
+}
+/** 422 (and 400) — the request body or query failed validation. */
+export declare class ChatlyValidationError extends ChatlyApiError {
+    readonly name: string;
+}
+/** 429 — rate limited. `retryAfter` carries the server's own advice, in seconds. */
+export declare class ChatlyRateLimitError extends ChatlyApiError {
+    readonly name: string;
+}
+/** 5xx — our problem. Safe to retry; the SDK already did, up to its limit. */
+export declare class ChatlyServerError extends ChatlyApiError {
+    readonly name: string;
+}
+/**
+ * The request never produced an HTTP response: DNS, TCP, TLS, timeout, abort.
+ *
+ * Deliberately NOT a subclass of {@link ChatlyApiError} — there is no status
+ * to branch on, and code that does `err.status >= 500` must not silently read
+ * `undefined` here.
+ */
+export declare class ChatlyTransportError extends ChatlyError {
+    readonly name: string;
+    constructor(message: string, cause?: unknown);
+}
+/** Seconds, from a `Retry-After` that may be a delta or an HTTP date. */
+export declare function parseRetryAfter(header: string | null, nowMs: number): number | null;
+/** Map a failure response onto the narrowest error class that fits. */
+export declare function errorForResponse(input: {
+    status: number;
+    body: string;
+    requestId: string | null;
+    retryAfter: number | null;
+}): ChatlyApiError;
+/**
+ * The retry advice, from whichever spelling the server used.
+ *
+ * `@nestjs/throttler` names its buckets, so Chatly emits
+ * `Retry-After-{bucket}` and — until 2026-10-12 — never a plain
+ * `Retry-After`. Our own published docs said so. This SDK read only the plain
+ * header, so `retryAfter` was null on every real 429. The API now derives the
+ * plain header as well, but a deployment that has not taken that change still
+ * sends only the suffixed ones, so read both and take the LONGEST: backing
+ * off for the shortest bucket retries into a limit that is still closed.
+ */
+export declare function retryAfterHeader(headers: Headers): string | null;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,uFAAuF;AACvF,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAyB,IAAI,EAAE,MAAM,CAAiB;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAGlE;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,SAAyB,IAAI,EAAE,MAAM,CAAoB;IACzD,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,SAAgB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,8EAA8E;IAC9E,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,SAAgB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEvB,KAAK,EAAE;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B;CAQF;AAED,+EAA+E;AAC/E,qBAAa,yBAA0B,SAAQ,cAAc;IAC3D,SAAyB,IAAI,EAAE,MAAM,CAA+B;CACrE;AACD,qFAAqF;AACrF,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,SAAyB,IAAI,EAAE,MAAM,CAA2B;CACjE;AACD,gDAAgD;AAChD,qBAAa,mBAAoB,SAAQ,cAAc;IACrD,SAAyB,IAAI,EAAE,MAAM,CAAyB;CAC/D;AACD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;IACrD,SAAyB,IAAI,EAAE,MAAM,CAAyB;CAC/D;AACD,mEAAmE;AACnE,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,SAAyB,IAAI,EAAE,MAAM,CAA2B;CACjE;AACD,oFAAoF;AACpF,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,SAAyB,IAAI,EAAE,MAAM,CAA0B;CAChE;AACD,8EAA8E;AAC9E,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,SAAyB,IAAI,EAAE,MAAM,CAAuB;CAC7D;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,WAAW;IACnD,SAAyB,IAAI,EAAE,MAAM,CAA0B;gBAC5C,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAGpD;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAanF;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GAAG,cAAc,CAsCjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgBhE"}

package/dist/errors.js

@@ -0,0 +1,177 @@
+/**
+ * The error model.
+ *
+ * This SDK used to throw `new Error(`livechat ${status}: ${text}`)` for every
+ * failure, which forced every caller into string matching to tell "the key is
+ * wrong" from "the key is missing a scope" from "the contact does not exist".
+ * Those three need different handling — re-auth, ask an admin, create it — and
+ * a caller that cannot distinguish them retries all three or none.
+ *
+ * Nothing here extends the monorepo's `AppError`: this package is published to
+ * people who must not install our internals, so it stays dependency-free by
+ * design.
+ */
+/** Base for everything this SDK throws. `instanceof ChatlyError` catches all of it. */
+export class ChatlyError extends Error {
+    name = 'ChatlyError';
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/**
+ * The API answered, and the answer was a failure status.
+ *
+ * `requestId` is the `x-request-id` header. Quote it in a support request —
+ * it is the only way to find the exact call in our traces.
+ */
+export class ChatlyApiError extends ChatlyError {
+    name = 'ChatlyApiError';
+    status;
+    code;
+    requestId;
+    /** The raw response text. Everything `code`/`message` could not represent. */
+    body;
+    /** Seconds the server asked us to wait, from `Retry-After`. Only on 429/503. */
+    retryAfter;
+    constructor(input) {
+        super(input.message);
+        this.status = input.status;
+        this.code = input.code;
+        this.requestId = input.requestId;
+        this.body = input.body;
+        this.retryAfter = input.retryAfter;
+    }
+}
+/** 401 — the key is missing, malformed, revoked or belongs to no workspace. */
+export class ChatlyAuthenticationError extends ChatlyApiError {
+    name = 'ChatlyAuthenticationError';
+}
+/** 403 — the key is valid and lacks the scope this route needs. Check `whoami()`. */
+export class ChatlyPermissionError extends ChatlyApiError {
+    name = 'ChatlyPermissionError';
+}
+/** 404 — no such resource in this workspace. */
+export class ChatlyNotFoundError extends ChatlyApiError {
+    name = 'ChatlyNotFoundError';
+}
+/**
+ * 409 — most often an idempotency conflict: this `Idempotency-Key` was already
+ * used with a DIFFERENT body. Mint a new key, or send the original body.
+ */
+export class ChatlyConflictError extends ChatlyApiError {
+    name = 'ChatlyConflictError';
+}
+/** 422 (and 400) — the request body or query failed validation. */
+export class ChatlyValidationError extends ChatlyApiError {
+    name = 'ChatlyValidationError';
+}
+/** 429 — rate limited. `retryAfter` carries the server's own advice, in seconds. */
+export class ChatlyRateLimitError extends ChatlyApiError {
+    name = 'ChatlyRateLimitError';
+}
+/** 5xx — our problem. Safe to retry; the SDK already did, up to its limit. */
+export class ChatlyServerError extends ChatlyApiError {
+    name = 'ChatlyServerError';
+}
+/**
+ * The request never produced an HTTP response: DNS, TCP, TLS, timeout, abort.
+ *
+ * Deliberately NOT a subclass of {@link ChatlyApiError} — there is no status
+ * to branch on, and code that does `err.status >= 500` must not silently read
+ * `undefined` here.
+ */
+export class ChatlyTransportError extends ChatlyError {
+    name = 'ChatlyTransportError';
+    constructor(message, cause) {
+        super(message, { cause });
+    }
+}
+/** Seconds, from a `Retry-After` that may be a delta or an HTTP date. */
+export function parseRetryAfter(header, nowMs) {
+    if (header === null || header.trim() === '') {
+        return null;
+    }
+    const seconds = Number(header.trim());
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds;
+    }
+    const at = Date.parse(header);
+    if (Number.isFinite(at)) {
+        return Math.max(0, Math.round((at - nowMs) / 1000));
+    }
+    return null;
+}
+/** Map a failure response onto the narrowest error class that fits. */
+export function errorForResponse(input) {
+    let parsed = {};
+    try {
+        const json = JSON.parse(input.body);
+        if (typeof json === 'object' && json !== null) {
+            // The API's envelope is `{ code, message }`, sometimes nested under `error`.
+            const outer = json;
+            const inner = typeof outer['error'] === 'object' && outer['error'] !== null
+                ? outer['error']
+                : outer;
+            parsed = {
+                code: typeof inner['code'] === 'string' ? inner['code'] : undefined,
+                message: typeof inner['message'] === 'string' ? inner['message'] : undefined,
+            };
+        }
+    }
+    catch {
+        // Not JSON — an HTML error page from a proxy, or an empty body. `body` keeps it.
+    }
+    const message = parsed.message ?? `Chatly API responded ${String(input.status)}`;
+    const args = {
+        status: input.status,
+        code: parsed.code ?? null,
+        message,
+        requestId: input.requestId,
+        body: input.body,
+        retryAfter: input.retryAfter,
+    };
+    if (input.status === 401)
+        return new ChatlyAuthenticationError(args);
+    if (input.status === 403)
+        return new ChatlyPermissionError(args);
+    if (input.status === 404)
+        return new ChatlyNotFoundError(args);
+    if (input.status === 409)
+        return new ChatlyConflictError(args);
+    if (input.status === 400 || input.status === 422)
+        return new ChatlyValidationError(args);
+    if (input.status === 429)
+        return new ChatlyRateLimitError(args);
+    if (input.status >= 500)
+        return new ChatlyServerError(args);
+    return new ChatlyApiError(args);
+}
+/**
+ * The retry advice, from whichever spelling the server used.
+ *
+ * `@nestjs/throttler` names its buckets, so Chatly emits
+ * `Retry-After-{bucket}` and — until 2026-10-12 — never a plain
+ * `Retry-After`. Our own published docs said so. This SDK read only the plain
+ * header, so `retryAfter` was null on every real 429. The API now derives the
+ * plain header as well, but a deployment that has not taken that change still
+ * sends only the suffixed ones, so read both and take the LONGEST: backing
+ * off for the shortest bucket retries into a limit that is still closed.
+ */
+export function retryAfterHeader(headers) {
+    const plain = headers.get('retry-after');
+    if (plain !== null && plain.trim() !== '') {
+        return plain;
+    }
+    let longest = null;
+    headers.forEach((value, name) => {
+        if (!name.toLowerCase().startsWith('retry-after-')) {
+            return;
+        }
+        const seconds = Number(value);
+        if (Number.isFinite(seconds) && (longest === null || seconds > longest)) {
+            longest = seconds;
+        }
+    });
+    return longest === null ? null : String(longest);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/identity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Compute the `userHash` the widget needs for identity verification.
+ *
+ * When a workspace turns identity verification on, the widget must prove the
+ * `externalId` it claims was issued by the customer's backend rather than
+ * typed into a browser console — otherwise anyone can open a chat as anyone
+ * else's account. This is the backend half of that handshake:
+ *
+ *   const userHash = chatlyIdentityHash(process.env.CHATLY_IDV_SECRET, user.id);
+ *   // then render:
+ *   // Chatly('identify', { externalId: user.id, userHash, email: user.email })
+ *
+ * It lived in the API's own source as a comment-only snippet, where the
+ * people who need it — customers integrating their backend — could never
+ * import it.
+ *
+ * The secret is the workspace's identity-verification secret. It must never
+ * reach the browser; only the digest does.
+ */
+export declare function chatlyIdentityHash(secret: string, externalId: string): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ7E"}

package/dist/identity.js

@@ -0,0 +1,30 @@
+import { createHmac } from 'node:crypto';
+/**
+ * Compute the `userHash` the widget needs for identity verification.
+ *
+ * When a workspace turns identity verification on, the widget must prove the
+ * `externalId` it claims was issued by the customer's backend rather than
+ * typed into a browser console — otherwise anyone can open a chat as anyone
+ * else's account. This is the backend half of that handshake:
+ *
+ *   const userHash = chatlyIdentityHash(process.env.CHATLY_IDV_SECRET, user.id);
+ *   // then render:
+ *   // Chatly('identify', { externalId: user.id, userHash, email: user.email })
+ *
+ * It lived in the API's own source as a comment-only snippet, where the
+ * people who need it — customers integrating their backend — could never
+ * import it.
+ *
+ * The secret is the workspace's identity-verification secret. It must never
+ * reach the browser; only the digest does.
+ */
+export function chatlyIdentityHash(secret, externalId) {
+    if (secret.length === 0) {
+        throw new Error('chatlyIdentityHash: secret is empty');
+    }
+    if (externalId.length === 0) {
+        throw new Error('chatlyIdentityHash: externalId is empty');
+    }
+    return createHmac('sha256', secret).update(externalId).digest('hex');
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,UAAkB;IACnE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC"}