@chatlychat/sdk-node 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `@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.
+ *
+ * Declared here rather than imported from `@livechat/shared`: this package is
+ * published to consumers who must not have to install monorepo internals, so
+ * it stays dependency-free by design. The shape mirrors
+ * `@livechat/shared/reactions` and is covered by the API's own contract tests.
+ */
+export interface MessageReactions {
+    readonly messageId: string;
+    readonly entries: ReadonlyArray<{
+        emoji: string;
+        count: number;
+        reacted: boolean;
+    }>;
+}
+/**
+ * Widget behaviour config. Structural, for the same reason as above — pass a
+ * plain object; the API validates it against the authoritative zod schema and
+ * rejects anything malformed.
+ */
+export type WidgetFeatureConfig = Record<string, unknown>;
+export declare class ChatlyClient {
+    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);
+    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 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();
+     *   for (let attempt = 0; attempt < 3; attempt++) {
+     *     try {
+     *       return await chatly.withIdempotencyKey(key).contacts.upsert(body);
+     *     } catch (err) { ...backoff }
+     *   }
+     *   ```
+     */
+    withIdempotencyKey(key: string): ChatlyClient;
+    /**
+     * Describe the credential this client is using: which workspace it belongs
+     * to and which scopes it was granted.
+     *
+     * `GET /v1/api-keys/whoami` is deliberately the ONLY route on the api-keys
+     * controller that accepts an API key (managing keys with a key is a
+     * privilege-escalation shape). It is the call to make first: it turns a
+     * mis-scoped key into an obvious error at integration time rather than a
+     * 403 from an unrelated endpoint later.
+     *
+     * It was reachable over raw HTTP but appeared in no SDK and no doc, so
+     * there was no way for an integrator to discover it.
+     */
+    whoami(): Promise<{
+        workspaceId: string;
+        scopes: readonly string[];
+    }>;
+    /**
+     * Call any route, including the 85 key-accessible ones with no typed method
+     * here. Goes through the same auth, idempotency, retry and error handling.
+     *
+     *   ```ts
+     *   const flags = await chatly.request<Flags>('GET', '/v1/feature-flags');
+     *   ```
+     */
+    request<T>(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', path: string, options?: {
+        query?: Query;
+        body?: unknown;
+    }): Promise<T>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,116 @@
+/**
+ * `@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 {
+    transport;
+    contacts;
+    conversations;
+    tickets;
+    macros;
+    kb;
+    search;
+    events;
+    webhooks;
+    reports;
+    channels;
+    billing;
+    workspace;
+    constructor(optsOrTransport) {
+        /*
+         * Every namespace is built from THIS instance's transport.
+         *
+         * 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.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 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();
+     *   for (let attempt = 0; attempt < 3; attempt++) {
+     *     try {
+     *       return await chatly.withIdempotencyKey(key).contacts.upsert(body);
+     *     } catch (err) { ...backoff }
+     *   }
+     *   ```
+     */
+    withIdempotencyKey(key) {
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new TypeError('withIdempotencyKey: key must be a non-empty string');
+        }
+        return new ChatlyClient(this.transport.withPinnedKey(key));
+    }
+    /**
+     * Describe the credential this client is using: which workspace it belongs
+     * to and which scopes it was granted.
+     *
+     * `GET /v1/api-keys/whoami` is deliberately the ONLY route on the api-keys
+     * controller that accepts an API key (managing keys with a key is a
+     * privilege-escalation shape). It is the call to make first: it turns a
+     * mis-scoped key into an obvious error at integration time rather than a
+     * 403 from an unrelated endpoint later.
+     *
+     * It was reachable over raw HTTP but appeared in no SDK and no doc, so
+     * there was no way for an integrator to discover it.
+     */
+    async whoami() {
+        return this.transport.get('/v1/api-keys/whoami');
+    }
+    /**
+     * Call any route, including the 85 key-accessible ones with no typed method
+     * here. Goes through the same auth, idempotency, retry and error handling.
+     *
+     *   ```ts
+     *   const flags = await chatly.request<Flags>('GET', '/v1/feature-flags');
+     *   ```
+     */
+    async request(method, path, options = {}) {
+        return this.transport.send(method, path, options.query ?? {}, options.body);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/pagination.d.ts

@@ -0,0 +1,32 @@
+import type { Query, Transport } from './transport.js';
+export interface PageQuery {
+    cursor?: string;
+    limit?: number;
+}
+export interface Page<T> {
+    items: ReadonlyArray<T>;
+    nextCursor: string | null;
+}
+/** A list method as the auto-paginator sees it: give me a cursor, get a page. */
+export type PageFetcher<T> = (cursor: string | undefined) => Promise<Page<T>>;
+/**
+ * Walk every page of a cursor-paginated list.
+ *
+ * ```ts
+ * for await (const contact of chatly.contacts.listAll()) { … }
+ * ```
+ *
+ * Two safeguards, both earned. It stops when `nextCursor` is null — and also
+ * when the server hands back a cursor it already gave us, which would
+ * otherwise be an infinite loop issuing the same request forever. And it never
+ * paginates on `id`: ids in this product are a mix of UUID v4 and v7, so id
+ * order is not time order and keyset paging on it silently reorders results.
+ * Eighteen list endpoints were doing exactly that.
+ */
+export declare function autoPaginate<T>(fetchPage: PageFetcher<T>): AsyncGenerator<T, void, void>;
+/** Build a list namespace's two shapes — one page, and every page — from one path. */
+export declare function listable<T>(transport: Transport, path: string, extra?: Query): {
+    list: (query?: PageQuery & Query) => Promise<Page<T>>;
+    listAll: (query?: Query) => AsyncGenerator<T, void, void>;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9E;;;;;;;;;;;;;GAaG;AACH,wBAAuB,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAqB/F;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,CAAC,EACxB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,KAAU,GAChB;IACD,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;CAC3D,CAQA"}

package/dist/pagination.js

@@ -0,0 +1,43 @@
+/**
+ * Walk every page of a cursor-paginated list.
+ *
+ * ```ts
+ * for await (const contact of chatly.contacts.listAll()) { … }
+ * ```
+ *
+ * Two safeguards, both earned. It stops when `nextCursor` is null — and also
+ * when the server hands back a cursor it already gave us, which would
+ * otherwise be an infinite loop issuing the same request forever. And it never
+ * paginates on `id`: ids in this product are a mix of UUID v4 and v7, so id
+ * order is not time order and keyset paging on it silently reorders results.
+ * Eighteen list endpoints were doing exactly that.
+ */
+export async function* autoPaginate(fetchPage) {
+    const seen = new Set();
+    let cursor;
+    for (;;) {
+        const page = await fetchPage(cursor);
+        for (const item of page.items) {
+            yield item;
+        }
+        const next = page.nextCursor;
+        if (next === null || next === undefined || next === '') {
+            return;
+        }
+        if (seen.has(next)) {
+            throw new Error(`Chatly pagination stopped: the server repeated cursor "${next}". ` +
+                'Continuing would issue the same request forever.');
+        }
+        seen.add(next);
+        cursor = next;
+    }
+}
+/** Build a list namespace's two shapes — one page, and every page — from one path. */
+export function listable(transport, path, extra = {}) {
+    const list = (query = {}) => transport.get(path, { ...extra, ...query });
+    return {
+        list,
+        listAll: (query = {}) => autoPaginate((cursor) => list({ ...query, ...(cursor === undefined ? {} : { cursor }) })),
+    };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,YAAY,CAAI,SAAyB;IAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,IAAI,MAA0B,CAAC;IAC/B,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;QACrC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,MAAM,IAAI,CAAC;QACb,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC;QAC7B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YACvD,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,0DAA0D,IAAI,KAAK;gBACjE,kDAAkD,CACrD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,QAAQ,CACtB,SAAoB,EACpB,IAAY,EACZ,QAAe,EAAE;IAKjB,MAAM,IAAI,GAAG,CAAC,QAA2B,EAAE,EAAoB,EAAE,CAC/D,SAAS,CAAC,GAAG,CAAU,IAAI,EAAE,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IACvD,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,CAAC,QAAe,EAAE,EAAE,EAAE,CAC7B,YAAY,CAAI,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;KAC/F,CAAC;AACJ,CAAC"}

package/dist/resources.d.ts

@@ -0,0 +1,237 @@
+import { type Page, type PageQuery } from './pagination.js';
+import type { Query, Transport } from './transport.js';
+/**
+ * ── These shapes are READ OFF THE ZOD SCHEMAS, not guessed ───────────────
+ *
+ * The API validates every body with zod and zod DROPS unknown keys. A write
+ * with the wrong key name therefore returns 200 having done nothing, which no
+ * caller can distinguish from success. Three of this SDK's own writes were
+ * built that way until the Ruby SDK's author read the controllers:
+ *
+ *   contacts.merge        sent { sourceContactId } — schema wants { mergedId }
+ *   contacts.addTags      sent { tags: [...] }     — schema wants { tag }, ONE
+ *   contacts.unsubscribe  sent { }                 — `unsubscribed` is REQUIRED
+ *
+ * The first two silently did nothing. The third 400'd, which is the lucky
+ * case. If you add a method here, open the schema.
+ */
+export interface MergeContactInput {
+    /** The contact to merge INTO the target, and then retire. `contactMergeSchema`. */
+    mergedId: string;
+}
+export interface UnsubscribeContactInput {
+    /** Required. `false` re-subscribes. */
+    unsubscribed: boolean;
+    reason?: string;
+}
+export interface AgentHandlingInput {
+    /** `setAgentHandlingSchema` — the settable states, not the read states. */
+    state: string;
+    reason?: string | null;
+}
+export interface ScheduleMessageInput {
+    body: string;
+    /** ISO 8601 with offset. */
+    sendAt: string;
+}
+export interface ContactInput {
+    externalId?: string;
+    email?: string;
+    phone?: string;
+    name?: string;
+    attributes?: Record<string, unknown>;
+}
+export interface MessageInput {
+    conversationId: string;
+    body: string;
+    /**
+     * Mirrors `messageKindSchema`, all five members.
+     *
+     * `attachment_only` was missing here — the union listed four — so TypeScript
+     * refused the one kind you send when there are no words, only a file.
+     */
+    kind?: 'text' | 'rich' | 'note' | 'system_event' | 'attachment_only';
+}
+export interface MergeTicketsInput {
+    /**
+     * The ticket that LOSES — it is closed and its history moves to the one in
+     * the path. `{ loserId }`, not `{ sourceTicketId }`: a merge can only be
+     * read one way and the route is `:winnerId/merge`.
+     */
+    loserId: string;
+}
+export interface TrackEventInput {
+    contactId: string;
+    name: string;
+    properties?: Record<string, unknown>;
+}
+/** Query for `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;
+}
+/** A result shape we do not model field-by-field. The API validates; we pass through. */
+export type Unmodelled = Record<string, unknown>;
+export declare function contactsResource(t: Transport): {
+    get: (id: string) => Promise<Unmodelled>;
+    upsert: (body: ContactInput) => Promise<Unmodelled>;
+    /** Up to the API's documented batch ceiling per call. One idempotency key covers the batch. */
+    bulkUpsert: (contacts: ReadonlyArray<ContactInput>) => Promise<Unmodelled>;
+    merge: (id: string, body: MergeContactInput) => Promise<Unmodelled>;
+    /**
+     * Add ONE tag. The route's body is `{ tag }`, singular.
+     *
+     * Kept plural in the cross-language manifest (`contacts.add_tags`) because
+     * eight SDKs have locked that name, but the wire shape is one tag per
+     * call: loop for several. This sent `{ tags: [...] }`, which zod dropped,
+     * so it returned 200 and added nothing.
+     */
+    addTags: (id: string, tag: string) => Promise<Unmodelled>;
+    removeTag: (id: string, tag: string) => Promise<void>;
+    /**
+     * Opt the contact out of outbound email, or back in.
+     *
+     * `unsubscribed` is required — there is no default, and omitting it is a
+     * 400. Honoured across campaigns and workflows.
+     */
+    unsubscribe: (id: string, body: UnsubscribeContactInput) => Promise<Unmodelled>;
+    /** The contact's timeline: conversations, events, tickets, in one ordered read. */
+    journey: (id: string, query?: Query) => Promise<Unmodelled>;
+    list: (query?: PageQuery & Query) => Promise<Page<Unmodelled>>;
+    listAll: (query?: Query) => AsyncGenerator<Unmodelled, void, void>;
+};
+export declare function conversationsResource(t: Transport): {
+    get: (id: string) => Promise<Unmodelled>;
+    /**
+     * 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, query?: PageQuery & Query) => Promise<Page<Unmodelled>>;
+    send: (body: MessageInput) => Promise<Unmodelled>;
+    /** Open conversations with no agent reply yet — the queue a bot or a rota works from. */
+    unattended: (query?: Query) => Promise<Unmodelled>;
+    /** Is a human or a bot driving this thread right now. */
+    agentHandling: (id: string) => Promise<Unmodelled>;
+    /** Hand the thread to a bot, or take it back. `{ state, reason? }`. */
+    setAgentHandling: (id: string, body: AgentHandlingInput) => Promise<Unmodelled>;
+    /** Drafts the AI produced for this thread, newest first. */
+    generatedReplies: (id: string, query?: Query) => Promise<Unmodelled>;
+    /** Ask for a draft now. Returns the draft; it is not sent until you send it. */
+    generateReply: (id: string, body?: Unmodelled) => Promise<Unmodelled>;
+    scheduledMessages: (id: string, query?: Query) => Promise<Unmodelled>;
+    scheduleMessage: (id: string, body: ScheduleMessageInput) => Promise<Unmodelled>;
+    cancelScheduled: (scheduledId: string) => Promise<void>;
+    list: (query?: PageQuery & Query) => Promise<Page<Unmodelled>>;
+    listAll: (query?: Query) => AsyncGenerator<Unmodelled, void, void>;
+};
+export declare function ticketsResource(t: Transport): {
+    comments: (id: string, query?: Query) => Promise<Unmodelled>;
+    /** The ticket auto-created from a conversation, if there is one. */
+    forConversation: (conversationId: string) => Promise<Unmodelled>;
+    queues: () => Promise<Unmodelled>;
+    /** `id` is the WINNER; the body names the loser. */
+    merge: (id: string, body: MergeTicketsInput) => Promise<Unmodelled>;
+    split: (id: string, body: Unmodelled) => Promise<Unmodelled>;
+    /** One status, assignee or queue change applied to many tickets under one key. */
+    bulk: (body: Unmodelled) => Promise<Unmodelled>;
+    list: (query?: PageQuery & Query) => Promise<Page<Unmodelled>>;
+    listAll: (query?: Query) => AsyncGenerator<Unmodelled, void, void>;
+};
+export declare function macrosResource(t: Transport): {
+    create: (body: Unmodelled) => Promise<Unmodelled>;
+    update: (id: string, body: Unmodelled) => Promise<Unmodelled>;
+    delete: (id: string) => Promise<void>;
+    list: (query?: PageQuery & Query) => Promise<Page<Unmodelled>>;
+    listAll: (query?: Query) => AsyncGenerator<Unmodelled, void, void>;
+};
+export declare function kbResource(t: Transport): {
+    /** One article by slug — the same slug the help centre serves it under. */
+    article: (slug: string) => Promise<Unmodelled>;
+    collections: () => Promise<Unmodelled>;
+    list: (query?: PageQuery & Query) => Promise<Page<Unmodelled>>;
+    listAll: (query?: Query) => AsyncGenerator<Unmodelled, void, void>;
+};
+export declare function searchResource(t: Transport): {
+    /** Full-text across contacts, conversations, messages, tickets and the KB. */
+    query: (q: string, opts?: Query) => Promise<Unmodelled>;
+    /**
+     * Help-centre articles only.
+     *
+     * Sends `kinds=kb` as a repeated PLAIN key. It used to send `kinds[]=kb`,
+     * and `searchQuerySchema` is an object schema, so zod stripped the
+     * bracketed key and the search ran UNNARROWED — this method returned
+     * contacts, conversations, messages and tickets with a 200 and nothing to
+     * indicate the filter had been ignored. The MCP server's `search_kb` tool
+     * and the dashboard sent the same spelling. The schema now folds
+     * `kinds[]` and a scalar `kinds` as well, but the plain repeated key is
+     * the form to send.
+     */
+    kb: (q: string, opts?: Query) => Promise<Unmodelled>;
+};
+export declare function eventsResource(t: Transport): {
+    track: (input: TrackEventInput) => Promise<Unmodelled>;
+    /**
+     * Read back what was tracked — the same `/v1/cdp/events` collection
+     * `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: (query?: EventListQuery) => Promise<Page<Unmodelled>>;
+    listAll: (query?: Query) => AsyncGenerator<Unmodelled, void, void>;
+};
+export declare function webhooksResource(t: Transport): {
+    /** One delivery, with its request, response and attempt history. */
+    delivery: (id: string) => Promise<Unmodelled>;
+    /** Send it again. The receiver sees the same payload with a fresh signature. */
+    redeliver: (id: string) => Promise<Unmodelled>;
+    list: (query?: PageQuery & Query) => Promise<Page<Unmodelled>>;
+    listAll: (query?: Query) => AsyncGenerator<Unmodelled, void, void>;
+};
+export declare function reportsResource(t: Transport): {
+    overview: (query?: Query) => Promise<Unmodelled>;
+    agents: (query?: Query) => Promise<Unmodelled>;
+    conversationsByDay: (query?: Query) => Promise<Unmodelled>;
+    sla: (query?: Query) => Promise<Unmodelled>;
+};
+export declare function channelsResource(t: Transport): {
+    list: (query?: Query) => Promise<Unmodelled>;
+    get: (id: string) => Promise<Unmodelled>;
+};
+export declare function billingResource(t: Transport): {
+    /** The plan catalogue this deployment can actually sell. */
+    plans: () => Promise<Unmodelled>;
+    /** Current period usage, including AI spend against the workspace ceiling. */
+    usage: (query?: Query) => Promise<Unmodelled>;
+};
+export declare function workspaceResource(t: Transport): {
+    settings: () => Promise<Unmodelled>;
+    labels: () => Promise<Unmodelled>;
+    inboxes: () => Promise<Unmodelled>;
+    /**
+     * One team's roster. The only team read an API key can make.
+     *
+     * The workspace-wide `GET /v1/teams` list carries no `@AllowApiKey()` —
+     * it reads a calling user id, and a key is not a person — so it answers
+     * every key with 403. This manifest listed it anyway for a day, because
+     * the script that derived the key-accessible surface took the nearest
+     * `@AllowApiKey()` in either direction and credited the list route with
+     * the decorator belonging to this one. Get a team id from a workflow, an
+     * inbox's `settings.routingTeamId`, or a conversation's `teamId`.
+     */
+    teamMembers: (teamId: string) => Promise<Unmodelled>;
+    /**
+     * The workspace's skill taxonomy — the distinct labels routing matches on.
+     *
+     * `GET /v1/agents` has no handler at all; the agents controller serves
+     * only `/agents/skills` and `/agents/{userId}/skills`. There is no
+     * key-accessible way to list the people with a seat here.
+     */
+    agentSkills: () => Promise<Unmodelled>;
+};
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

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