@chatlychat/sdk-node 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,34 +1,23 @@
-export interface ClientOptions {
-    apiKey: string;
-    apiUrl?: string;
-    timeoutMs?: number;
-    fetchFn?: typeof fetch;
-}
-export interface PageQuery {
-    cursor?: string;
-    limit?: number;
-}
-export interface Page<T> {
-    items: ReadonlyArray<T>;
-    nextCursor: string | null;
-}
-/** Query for {@link ChatlyClient.events}.list — a page, optionally one contact's. */
-export interface EventListQuery extends PageQuery {
-    /** Restrict the stream to one contact. Omit for the whole workspace. */
-    contactId?: string;
-}
-export interface ContactInput {
-    externalId?: string;
-    email?: string;
-    phone?: string;
-    name?: string;
-    attributes?: Record<string, unknown>;
-}
-export interface MessageInput {
-    conversationId: string;
-    body: string;
-    kind?: 'text' | 'rich' | 'note' | 'system_event';
-}
+/**
+ * `@chatlychat/sdk-node` — the official Node.js SDK for the Chatly API.
+ *
+ * Authenticate with a workspace API key (`ck_…`) from server-side code. This
+ * is NOT the browser SDK: the key is a bearer credential for the whole
+ * workspace and must never be shipped to a browser. For in-page work use
+ * `@chatlychat/sdk-js`.
+ *
+ * The route surface is `packages/sdk-spec/surface.json`, which all ten Chatly
+ * SDKs implement; the behavioural contract is `packages/sdk-spec/CONTRACT.md`.
+ */
+import { billingResource, channelsResource, contactsResource, conversationsResource, eventsResource, kbResource, macrosResource, reportsResource, searchResource, ticketsResource, webhooksResource, workspaceResource } from './resources.js';
+import { Transport, type Query, type TransportOptions } from './transport.js';
+export type ClientOptions = TransportOptions;
+export { ChatlyError, ChatlyApiError, ChatlyAuthenticationError, ChatlyPermissionError, ChatlyNotFoundError, ChatlyConflictError, ChatlyValidationError, ChatlyRateLimitError, ChatlyServerError, ChatlyTransportError, } from './errors.js';
+export { DEFAULT_API_URL, DEFAULT_RETRY, SDK_VERSION, type Query, type RetryPolicy } from './transport.js';
+export { autoPaginate, type Page, type PageQuery } from './pagination.js';
+export { verifyWebhookSignature, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, type VerifyWebhookSignatureInput, } from './webhooks.js';
+export { chatlyIdentityHash } from './identity.js';
+export type { AgentHandlingInput, ContactInput, EventListQuery, MergeContactInput, MergeTicketsInput, MessageInput, ScheduleMessageInput, UnsubscribeContactInput, TrackEventInput, Unmodelled, } from './resources.js';
 /**
  * Reaction payload.
  *
@@ -52,32 +41,32 @@ export interface MessageReactions {
  */
 export type WidgetFeatureConfig = Record<string, unknown>;
 export declare class ChatlyClient {
-    private readonly base;
-    private readonly baseHeaders;
-    private readonly timeoutMs;
-    private readonly fetchFn;
-    /**
-     * When set, every write made through this client instance uses this
-     * exact `Idempotency-Key` instead of minting a fresh UUID per call.
-     * Created via {@link withIdempotencyKey}; the original client is left
-     * untouched (the method returns a derived view, not a mutation).
-     */
-    private readonly pinnedIdempotencyKey;
+    private readonly transport;
+    readonly contacts: ReturnType<typeof contactsResource>;
+    readonly conversations: ReturnType<typeof conversationsResource>;
+    readonly tickets: ReturnType<typeof ticketsResource>;
+    readonly macros: ReturnType<typeof macrosResource>;
+    readonly kb: ReturnType<typeof kbResource>;
+    readonly search: ReturnType<typeof searchResource>;
+    readonly events: ReturnType<typeof eventsResource>;
+    readonly webhooks: ReturnType<typeof webhooksResource>;
+    readonly reports: ReturnType<typeof reportsResource>;
+    readonly channels: ReturnType<typeof channelsResource>;
+    readonly billing: ReturnType<typeof billingResource>;
+    readonly workspace: ReturnType<typeof workspaceResource>;
     constructor(opts: ClientOptions);
-    /**
-     * Private clone constructor — used by {@link withIdempotencyKey} so we
-     * can return a derived client without mutating the original (and
-     * without re-running the public ctor's defaulting logic).
-     */
-    private static derive;
+    constructor(transport: Transport);
     /**
      * Pin a specific `Idempotency-Key` for one or more upcoming writes.
      *
-     * Returns a derived client (the original is unchanged). Use this when
-     * you want to retry the *same* logical operation: the API treats two
-     * writes with the same key + same body as a single accepted operation
-     * and replays the cached response. Two writes with the same key but a
-     * different body return HTTP 409.
+     * Returns a derived client (the original is unchanged). Use this when you
+     * want to retry the *same* logical operation across process boundaries: the
+     * API treats two writes with the same key + same body as a single accepted
+     * operation and replays the cached response. Two writes with the same key
+     * but a different body return HTTP 409.
+     *
+     * You do not need this for ordinary retries — the SDK already reuses one key
+     * across its own attempts of a single call.
      *
      *   ```ts
      *   const key = crypto.randomUUID();
@@ -106,120 +95,17 @@ export declare class ChatlyClient {
         workspaceId: string;
         scopes: readonly string[];
     }>;
-    contacts: {
-        list: (q?: PageQuery) => Promise<Page<unknown>>;
-        upsert: (body: ContactInput) => Promise<unknown>;
-    };
-    conversations: {
-        list: (q?: PageQuery) => Promise<Page<unknown>>;
-        /**
-         * Read a thread before replying to it.
-         *
-         * The MCP server has exposed this as `get_messages` since it shipped and
-         * the SDK did not, so an integrator writing "read the conversation, then
-         * decide" against the SDK had to hand-roll the request while the same
-         * capability sat behind a tool call.
-         */
-        messages: (conversationId: string, q?: PageQuery) => Promise<Page<unknown>>;
-        send: (body: MessageInput) => Promise<unknown>;
-    };
     /**
-     * Reactions and channel configuration are deliberately absent.
+     * Call any route, including the 85 key-accessible ones with no typed method
+     * here. Goes through the same auth, idempotency, retry and error handling.
      *
-     * Both were here and neither worked: a reaction records *who* reacted, and
-     * a key is not a person, so those routes require a signed-in user and
-     * return 403 to any key. Channel configuration needs `channels:write`,
-     * which no key-accessible route grants. Shipping methods that always fail
-     * is worse than not shipping them — the failure arrives at runtime, in
-     * production, in someone else's integration.
-     */
-    /** Full-text search across contacts, conversations, messages, tickets, KB. */
-    search: {
-        query: (q: string, opts?: Record<string, unknown>) => Promise<unknown>;
-        /**
-         * Help-centre articles only.
-         *
-         * The same `/v1/search` route narrowed to `kinds[]=kb`, which is exactly
-         * what the MCP server's `search_kb` tool does. Worth its own method
-         * because "find the article that answers this" is the common case and
-         * getting there otherwise means knowing the `kinds[]` parameter exists.
-         */
-        kb: (q: string, opts?: Record<string, unknown>) => Promise<unknown>;
-    };
-    events: {
-        track: (input: {
-            contactId: string;
-            name: string;
-            properties?: Record<string, unknown>;
-        }) => Promise<unknown>;
-        /**
-         * Read back what was tracked — the same `/v1/cdp/events` collection
-         * {@link track} writes to, cursor-paginated newest-first.
-         *
-         * The SDK could write events and never read them, so "did my tracking
-         * call actually land?" had no answer outside the dashboard. Pass
-         * `contactId` to scope the stream to one person.
-         */
-        list: (q?: EventListQuery) => Promise<Page<unknown>>;
-    };
-    private get;
-    private post;
-    /** PATCH. Same idempotency contract as `post` — it is a write. */
-    private patch;
-    private dispatch;
-}
-/** Freshness window for `t`, in seconds. Matches what the docs recommend. */
-export declare const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300;
-export interface VerifyWebhookSignatureInput {
-    /**
-     * The EXACT bytes we POSTed. Pass the raw body — re-serialising parsed JSON
-     * reorders keys and changes whitespace, and the digest will not match.
-     */
-    body: string | Uint8Array;
-    /** The `x-livechat-signature` header value: `t=<unix seconds>,v1=<hex>`. */
-    signatureHeader: string;
-    /** The endpoint's `whsec_…` signing secret.  */
-    secret: string;
-    /**
-     * How far `t` may be from now before the delivery is treated as a replay.
-     * Defaults to {@link WEBHOOK_SIGNATURE_TOLERANCE_SECONDS}; pass `Infinity`
-     * only when re-verifying an archived delivery.
+     *   ```ts
+     *   const flags = await chatly.request<Flags>('GET', '/v1/feature-flags');
+     *   ```
      */
-    toleranceSeconds?: number;
-    /** Escape hatch for tests. Unix seconds. */
-    nowSeconds?: number;
+    request<T>(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', path: string, options?: {
+        query?: Query;
+        body?: unknown;
+    }): Promise<T>;
 }
-/**
- * Verify the signature header on a webhook delivery from the platform.
- *
- * `v1` is HMAC-SHA256 over `` `${t}.${body}` `` — the timestamp is bound INTO
- * the digest, which is what makes the replay window enforceable at all.
- *
- * This used to HMAC the body ALONE, so it rejected every genuine delivery the
- * platform sent: the producer has always signed `${t}.${body}` and our own
- * published documentation has always described that construction. Anyone
- * following either the SDK or the docs got a hard "invalid signature" on 100%
- * of real traffic. The wire format is unchanged — only this verifier was wrong.
- */
-export declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): boolean;
-/**
- * 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=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,96 +1,74 @@
-import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
-/** Node 14.17+ has `crypto.randomUUID`; the SDK targets Node 20+ so it's safe. */
-function nodeRandomUuid() {
-    return randomUUID();
-}
+/**
+ * `@chatlychat/sdk-node` — the official Node.js SDK for the Chatly API.
+ *
+ * Authenticate with a workspace API key (`ck_…`) from server-side code. This
+ * is NOT the browser SDK: the key is a bearer credential for the whole
+ * workspace and must never be shipped to a browser. For in-page work use
+ * `@chatlychat/sdk-js`.
+ *
+ * The route surface is `packages/sdk-spec/surface.json`, which all ten Chatly
+ * SDKs implement; the behavioural contract is `packages/sdk-spec/CONTRACT.md`.
+ */
+import { billingResource, channelsResource, contactsResource, conversationsResource, eventsResource, kbResource, macrosResource, reportsResource, searchResource, ticketsResource, webhooksResource, workspaceResource, } from './resources.js';
+import { Transport } from './transport.js';
+export { ChatlyError, ChatlyApiError, ChatlyAuthenticationError, ChatlyPermissionError, ChatlyNotFoundError, ChatlyConflictError, ChatlyValidationError, ChatlyRateLimitError, ChatlyServerError, ChatlyTransportError, } from './errors.js';
+export { DEFAULT_API_URL, DEFAULT_RETRY, SDK_VERSION } from './transport.js';
+export { autoPaginate } from './pagination.js';
+export { verifyWebhookSignature, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS, } from './webhooks.js';
+export { chatlyIdentityHash } from './identity.js';
 export class ChatlyClient {
-    base;
-    baseHeaders;
-    timeoutMs;
-    fetchFn;
-    /**
-     * When set, every write made through this client instance uses this
-     * exact `Idempotency-Key` instead of minting a fresh UUID per call.
-     * Created via {@link withIdempotencyKey}; the original client is left
-     * untouched (the method returns a derived view, not a mutation).
-     */
-    pinnedIdempotencyKey;
-    constructor(opts) {
+    transport;
+    contacts;
+    conversations;
+    tickets;
+    macros;
+    kb;
+    search;
+    events;
+    webhooks;
+    reports;
+    channels;
+    billing;
+    workspace;
+    constructor(optsOrTransport) {
         /*
-         * Production, not a dev hostname.
-         *
-         * This was `https://api.livechat.local`, which resolves nowhere — so a
-         * developer who followed the published docs and omitted `apiUrl` got an
-         * SDK whose every call failed, and the docs page carried a warning
-         * telling each reader to override it. Reported by a customer who
-         * integrated from the docs alone, not caught here, because every test in
-         * this package passes an explicit `apiUrl`.
+         * Every namespace is built from THIS instance's transport.
          *
-         * A self-hosted install still overrides it; that is the only caller that
-         * ever should.
+         * The previous design hand-wrote a `derive` clone that re-bound each
+         * namespace one by one, and forgot `search` — so a client returned by
+         * `withIdempotencyKey` had search methods still closed over the PARENT's
+         * dispatch. Harmless while both were reads against the same base URL, and
+         * a live bug the moment anything on `search` became a write. Building
+         * namespaces in the constructor from one transport makes the class of bug
+         * unreachable rather than tested for.
          */
-        this.base = opts.apiUrl ?? 'https://api.chatlychat.com';
-        this.baseHeaders = new Headers({
-            authorization: `Bearer ${opts.apiKey}`,
-            'content-type': 'application/json',
-            accept: 'application/json',
-            'user-agent': '@chatlychat/sdk-node/0.1.0',
-        });
-        this.timeoutMs = opts.timeoutMs ?? 15_000;
-        this.fetchFn = opts.fetchFn ?? globalThis.fetch;
-        this.pinnedIdempotencyKey = null;
-    }
-    /**
-     * Private clone constructor — used by {@link withIdempotencyKey} so we
-     * can return a derived client without mutating the original (and
-     * without re-running the public ctor's defaulting logic).
-     */
-    static derive(parent, pinnedIdempotencyKey) {
-        const child = Object.create(ChatlyClient.prototype);
-        Object.assign(child, {
-            base: parent.base,
-            baseHeaders: parent.baseHeaders,
-            timeoutMs: parent.timeoutMs,
-            fetchFn: parent.fetchFn,
-            pinnedIdempotencyKey,
-        });
-        // The route bags are field-initialized below the class body via the
-        // arrow-property pattern; re-bind them so they target the derived
-        // instance and call the child's `post`/`get`.
-        child.contacts = {
-            list: (q = {}) => child.get('/v1/contacts', { ...q }),
-            upsert: (body) => child.post('/v1/contacts', body),
-        };
-        child.conversations = {
-            list: (q = {}) => child.get('/v1/conversations', { ...q }),
-            messages: (conversationId, q = {}) => child.get(`/v1/conversations/${conversationId}/messages`, { ...q }),
-            send: (body) => child.post(`/v1/conversations/${body.conversationId}/messages`, body),
-        };
-        child.events = {
-            track: (input) => child.post('/v1/cdp/events', input),
-            list: (q = {}) => child.get('/v1/cdp/events', { ...q }),
-        };
-        // `search` was never rebound here, so a derived client's search methods
-        // still called the PARENT's `get`. Harmless today because both are reads
-        // against the same base URL, and a live bug the moment anything on
-        // `search` becomes a write or the derived client differs by more than a
-        // pinned key. `derivedSurfaceMatches` in the spec fails if any namespace
-        // is forgotten again — TypeScript only caught `messages` because that
-        // namespace was already rebound.
-        child.search = {
-            query: (q, opts = {}) => child.get('/v1/search', { q, ...opts }),
-            kb: (q, opts = {}) => child.get('/v1/search', { q, 'kinds[]': 'kb', ...opts }),
-        };
-        return child;
+        this.transport =
+            optsOrTransport instanceof Transport ? optsOrTransport : new Transport(optsOrTransport);
+        const t = this.transport;
+        this.contacts = contactsResource(t);
+        this.conversations = conversationsResource(t);
+        this.tickets = ticketsResource(t);
+        this.macros = macrosResource(t);
+        this.kb = kbResource(t);
+        this.search = searchResource(t);
+        this.events = eventsResource(t);
+        this.webhooks = webhooksResource(t);
+        this.reports = reportsResource(t);
+        this.channels = channelsResource(t);
+        this.billing = billingResource(t);
+        this.workspace = workspaceResource(t);
     }
     /**
      * Pin a specific `Idempotency-Key` for one or more upcoming writes.
      *
-     * Returns a derived client (the original is unchanged). Use this when
-     * you want to retry the *same* logical operation: the API treats two
-     * writes with the same key + same body as a single accepted operation
-     * and replays the cached response. Two writes with the same key but a
-     * different body return HTTP 409.
+     * Returns a derived client (the original is unchanged). Use this when you
+     * want to retry the *same* logical operation across process boundaries: the
+     * API treats two writes with the same key + same body as a single accepted
+     * operation and replays the cached response. Two writes with the same key
+     * but a different body return HTTP 409.
+     *
+     * You do not need this for ordinary retries — the SDK already reuses one key
+     * across its own attempts of a single call.
      *
      *   ```ts
      *   const key = crypto.randomUUID();
@@ -105,7 +83,7 @@ export class ChatlyClient {
         if (typeof key !== 'string' || key.length === 0) {
             throw new TypeError('withIdempotencyKey: key must be a non-empty string');
         }
-        return ChatlyClient.derive(this, key);
+        return new ChatlyClient(this.transport.withPinnedKey(key));
     }
     /**
      * Describe the credential this client is using: which workspace it belongs
@@ -121,195 +99,18 @@ export class ChatlyClient {
      * there was no way for an integrator to discover it.
      */
     async whoami() {
-        return this.get('/v1/api-keys/whoami', {});
+        return this.transport.get('/v1/api-keys/whoami');
     }
-    contacts = {
-        list: (q = {}) => this.get('/v1/contacts', { ...q }),
-        upsert: (body) => this.post('/v1/contacts', body),
-    };
-    conversations = {
-        list: (q = {}) => this.get('/v1/conversations', { ...q }),
-        /**
-         * Read a thread before replying to it.
-         *
-         * The MCP server has exposed this as `get_messages` since it shipped and
-         * the SDK did not, so an integrator writing "read the conversation, then
-         * decide" against the SDK had to hand-roll the request while the same
-         * capability sat behind a tool call.
-         */
-        messages: (conversationId, q = {}) => this.get(`/v1/conversations/${conversationId}/messages`, { ...q }),
-        send: (body) => this.post(`/v1/conversations/${body.conversationId}/messages`, body),
-    };
     /**
-     * Reactions and channel configuration are deliberately absent.
+     * Call any route, including the 85 key-accessible ones with no typed method
+     * here. Goes through the same auth, idempotency, retry and error handling.
      *
-     * Both were here and neither worked: a reaction records *who* reacted, and
-     * a key is not a person, so those routes require a signed-in user and
-     * return 403 to any key. Channel configuration needs `channels:write`,
-     * which no key-accessible route grants. Shipping methods that always fail
-     * is worse than not shipping them — the failure arrives at runtime, in
-     * production, in someone else's integration.
+     *   ```ts
+     *   const flags = await chatly.request<Flags>('GET', '/v1/feature-flags');
+     *   ```
      */
-    /** Full-text search across contacts, conversations, messages, tickets, KB. */
-    search = {
-        query: (q, opts = {}) => this.get('/v1/search', { q, ...opts }),
-        /**
-         * Help-centre articles only.
-         *
-         * The same `/v1/search` route narrowed to `kinds[]=kb`, which is exactly
-         * what the MCP server's `search_kb` tool does. Worth its own method
-         * because "find the article that answers this" is the common case and
-         * getting there otherwise means knowing the `kinds[]` parameter exists.
-         */
-        kb: (q, opts = {}) => this.get('/v1/search', { q, 'kinds[]': 'kb', ...opts }),
-    };
-    events = {
-        track: (input) => this.post('/v1/cdp/events', input),
-        /**
-         * Read back what was tracked — the same `/v1/cdp/events` collection
-         * {@link track} writes to, cursor-paginated newest-first.
-         *
-         * The SDK could write events and never read them, so "did my tracking
-         * call actually land?" had no answer outside the dashboard. Pass
-         * `contactId` to scope the stream to one person.
-         */
-        list: (q = {}) => this.get('/v1/cdp/events', { ...q }),
-    };
-    async get(path, q) {
-        const url = new URL(`${this.base}${path}`);
-        for (const [k, v] of Object.entries(q)) {
-            if (v !== undefined) {
-                url.searchParams.set(k, String(v));
-            }
-        }
-        return this.dispatch(url, { method: 'GET' });
-    }
-    async post(path, body) {
-        // Production API requires Idempotency-Key on every write. The
-        // `pinnedIdempotencyKey` path is the supported way to retry the
-        // SAME logical operation (set via `withIdempotencyKey(key)`); when
-        // unset we mint a fresh UUID per call so a fetch-level network
-        // retry inside this SDK still won't double-write upstream.
-        const idempotencyKey = this.pinnedIdempotencyKey ?? nodeRandomUuid();
-        return this.dispatch(new URL(`${this.base}${path}`), {
-            method: 'POST',
-            body: JSON.stringify(body),
-            headers: { 'idempotency-key': idempotencyKey },
-        });
-    }
-    /** PATCH. Same idempotency contract as `post` — it is a write. */
-    async patch(path, body) {
-        const idempotencyKey = this.pinnedIdempotencyKey ?? nodeRandomUuid();
-        return this.dispatch(new URL(`${this.base}${path}`), {
-            method: 'PATCH',
-            body: JSON.stringify(body),
-            headers: { 'idempotency-key': idempotencyKey },
-        });
-    }
-    async dispatch(url, init) {
-        const ctrl = new AbortController();
-        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
-        try {
-            // Merge base auth/content headers with any per-call overrides
-            // (e.g. `idempotency-key` from `post`). Previously this dropped
-            // per-call headers because it reassigned `headers` wholesale —
-            // which silently broke the idempotency contract on every write.
-            const headers = new Headers(this.baseHeaders);
-            if (init.headers !== undefined) {
-                new Headers(init.headers).forEach((value, name) => {
-                    headers.set(name, value);
-                });
-            }
-            const res = await this.fetchFn(url.toString(), {
-                ...init,
-                signal: ctrl.signal,
-                headers,
-            });
-            if (!res.ok) {
-                const text = await res.text();
-                throw new Error(`livechat ${res.status}: ${text}`);
-            }
-            if (res.status === 204) {
-                return undefined;
-            }
-            return (await res.json());
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    }
-}
-/** Freshness window for `t`, in seconds. Matches what the docs recommend. */
-export const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300;
-/**
- * Verify the signature header on a webhook delivery from the platform.
- *
- * `v1` is HMAC-SHA256 over `` `${t}.${body}` `` — the timestamp is bound INTO
- * the digest, which is what makes the replay window enforceable at all.
- *
- * This used to HMAC the body ALONE, so it rejected every genuine delivery the
- * platform sent: the producer has always signed `${t}.${body}` and our own
- * published documentation has always described that construction. Anyone
- * following either the SDK or the docs got a hard "invalid signature" on 100%
- * of real traffic. The wire format is unchanged — only this verifier was wrong.
- */
-export function verifyWebhookSignature(input) {
-    const parts = new Map();
-    for (const part of input.signatureHeader.split(',')) {
-        const eq = part.indexOf('=');
-        if (eq > 0) {
-            parts.set(part.slice(0, eq).trim(), part.slice(eq + 1).trim());
-        }
-    }
-    const rawTs = parts.get('t');
-    const tag = parts.get('v1');
-    if (rawTs === undefined || tag === undefined) {
-        return false;
-    }
-    const issuedAt = Number.parseInt(rawTs, 10);
-    if (!Number.isFinite(issuedAt)) {
-        return false;
-    }
-    const tolerance = input.toleranceSeconds ?? WEBHOOK_SIGNATURE_TOLERANCE_SECONDS;
-    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
-    if (Math.abs(now - issuedAt) > tolerance) {
-        return false;
-    }
-    const hmac = createHmac('sha256', input.secret);
-    hmac.update(`${rawTs}.`);
-    hmac.update(typeof input.body === 'string' ? Buffer.from(input.body, 'utf8') : input.body);
-    const a = Buffer.from(tag, 'hex');
-    const b = Buffer.from(hmac.digest('hex'), 'hex');
-    // Length check first: timingSafeEqual throws on a length mismatch, and a
-    // thrown verifier is an accepted webhook in a handler that forgot try/catch.
-    return a.length === b.length && timingSafeEqual(a, b);
-}
-/**
- * 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');
+    async request(method, path, options = {}) {
+        return this.transport.send(method, path, options.query ?? {}, options.body);
     }
-    return createHmac('sha256', secret).update(externalId).digest('hex');
 }
 //# sourceMappingURL=index.js.map