saasco-sdk 0.1.45 → 0.2.3

package/dist/support-chat.d.cts

@@ -0,0 +1,184 @@
+/**
+ * Iframe-side half of the cross-origin bridge. Runs inside the Saasco
+ * `/embed/support-chat` page and talks to the host page's loader over
+ * `postMessage`:
+ *
+ * - inbound host messages (boot/identify/updateJwt/setStateSnapshot/viewport/
+ *   open/close) are validated by `event.origin` against the project's trusted
+ *   domains, then written into the {@link registry} the live widget subscribes to;
+ * - outbound round-trips (page-context lookups, host-registered client tools) are
+ *   promise-based with a `requestId` and a per-call timeout so a missing or slow
+ *   host handler can never hang a streaming turn.
+ *
+ * The first valid inbound message pins the parent origin; every reply targets
+ * that pinned origin (never `"*"`). The initial `ready` and any pre-boot resize
+ * carry no secrets, so they fall back to `"*"` until the origin is known.
+ */
+
+/**
+ * Wires the message listener and announces readiness. Idempotent. `allowedOrigins`
+ * is the project's trusted-domain allowlist plus the Saasco origin itself (so
+ * same-origin dogfooding works); patterns accept full origins, bare hosts and
+ * `*.example.com` wildcards (see `matchesOriginPattern`).
+ */
+declare function initEmbedBridge(options: {
+    allowedOrigins: string[];
+}): void;
+
+/** Snapshot of host-app state appended to the agent's system prompt each turn. */
+declare function setStateSnapshot(snapshot: unknown): void;
+
+/**
+ * Public types for the embeddable support chat widget. These restate the
+ * server wire contracts (`libs/support/shared` / `libs/chat/shared`) locally
+ * so the published package carries zero workspace dependencies.
+ */
+/**
+ * A minimal structural JSON Schema object describing a tool's arguments. It is
+ * declared locally (no `json-schema` package import) so the published SDK stays
+ * dependency-free. The root must be a `type: "object"` schema; additional JSON
+ * Schema keywords (`$schema`, `$defs`, …) are allowed via the index signature.
+ */
+type JSONSchema7Object = {
+    additionalProperties?: boolean | Record<string, unknown>;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    type: "object";
+    [key: string]: unknown;
+};
+/**
+ * The runtime shape of a tool the support widget can run in the browser. Tools
+ * are authored in the dashboard (stored in `Meta`) and served by the public
+ * settings endpoint as a `PublicChatTool`, which the widget rebuilds into this
+ * shape via `reconstructDashboardTool`.
+ *
+ * `execute` runs in the host app's browser when the agent calls a host tool
+ * and may touch in-page state, mutations, or SDKs. Server tools (dashboard
+ * `execution: "server"`) are proxied by the agent instead and never reach the
+ * widget; the reconstructed `execute` is only a same-origin `credentials:
+ * "include"` fallback. Tools marked `destructive` pause for an explicit
+ * Approve/Reject before running.
+ */
+type SupportChatTool = {
+    /** Shown to the model; 1–2000 chars. */
+    description: string;
+    /** Pauses for an explicit Approve/Reject before running. */
+    destructive?: boolean;
+    /**
+     * Where the call runs. `"host"` round-trips to the host page's loader, which
+     * runs the consumer's `registerTool` handler in the host realm; `"server"` is
+     * run by the agent (proxied to `endpoint`), so the widget never calls
+     * `execute` for it. Destructive tools always run host-side behind the
+     * approval gate.
+     */
+    execution?: "host" | "server";
+    /**
+     * REST URL template for server-proxied or host-executed HTTP tools. Ignored
+     * for in-browser-only tools.
+     */
+    endpoint?: string;
+    execute: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+    /** JSON Schema (object) for the args; travels over the wire to the agent. */
+    inputSchema: JSONSchema7Object;
+    /** HTTP method for REST execution. */
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Display name shown in the dashboard and chat UI. */
+    name: string;
+    /**
+     * Parameter names filled from visitor context at call time — not supplied by
+     * the model. See `getStateSnapshot` on {@link WidgetConfig}.
+     */
+    contextParameters?: string[];
+};
+/** A canned prompt offered in the empty state; clicking it fills the input. */
+type SupportChatSuggestion = {
+    /** Optional second line shown under the label. */
+    description?: string;
+    label: string;
+    /** The text placed in the input when the suggestion is picked. */
+    prompt: string;
+};
+type WidgetConfig = {
+    /** Origin of the saasco app hosting the support-chat API, e.g. https://app.example.com */
+    baseUrl: string;
+    /** Read at submit time and appended to the agent's system prompt. */
+    getStateSnapshot?: () => unknown;
+    /** Input placeholder. */
+    placeholder?: string;
+    projectId: string;
+    /** Canned prompts offered before the first message. */
+    suggestions?: SupportChatSuggestion[];
+};
+
+/**
+ * Plain-fetch transport for the public support-chat REST endpoints. The
+ * embedding origin must be on the project's allowlist (configured in the
+ * support widget settings) for cross-origin calls to pass CORS.
+ */
+
+type ChatSession = {
+    attachments?: ConversationImageAttachment[];
+    conversationId: string;
+    sessionToken: string;
+};
+type ConversationImageAttachment = {
+    contentType?: string;
+    fileName?: string;
+    url: string;
+};
+type ChatThreadMessage = {
+    attachments?: ConversationImageAttachment[];
+    /** Replier's first name — present for `role: "team"` (human) messages only. */
+    authorName?: string;
+    /** Rich body (HTML when from email); not shown in the widget. */
+    content: string | null;
+    createdAt: number;
+    id: string;
+    /** Resolved help-center sources referenced by `[[kb:…]]` markers in plainBody. */
+    kbCitations?: {
+        id: string;
+        title: string;
+        url: string;
+    }[];
+    /** Plain-text body for bubbles and session previews. */
+    plainBody: string | null;
+    role: "user" | "team" | "bot";
+};
+type ChatThread = {
+    /** False while a human has taken over — the widget goes persist-only. */
+    agentEnabled: boolean;
+    conversationId: string;
+    messages: ChatThreadMessage[];
+    state: "open" | "closed" | "snoozed";
+};
+
+/**
+ * Embeddable customer-facing support chat for third-party apps — an
+ * Intercom-style messenger (Home + Messages tabs, branded workspace rows, a
+ * restyled chat with a workspace header and per-message meta lines) on top of the
+ * persisted support channel:
+ *
+ * - the customer talks to a streaming AI support agent that can call the
+ *   project's dashboard-configured tools (loaded from the public settings
+ *   endpoint), with an Approve/Reject gate for tools marked `destructive`,
+ * - an email gate captures a reply-to address before the first message when the
+ *   host app hasn't already identified the visitor; every message is persisted
+ *   into the saasco support inbox under `projectId`, with human replies merged
+ *   into the open chat by polling the thread endpoint, and
+ * - once a human takes the conversation over the agent stream is muted, the
+ *   customer sees a handoff acknowledgment, a "Waiting for a teammate" indicator
+ *   until someone replies, then "{name} has joined the conversation" above the
+ *   first team message.
+ *
+ * The per-conversation session token (and the captured email) are persisted in
+ * the Saasco iframe-origin `localStorage` so anonymous threads survive reloads
+ * (best-effort — Safari/strict-Firefox partition third-party storage; identified
+ * users resume server-side via the JWT instead). This component is the iframe
+ * app entry: it renders directly into the `/embed/support-chat` page (no host-
+ * realm blank-iframe wrapper), and the host integrates over the postMessage
+ * bridge — identity, JWT, state snapshots, viewport and open/close all arrive
+ * through {@link initEmbedBridge} and are read here from the registry.
+ */
+declare function SupportChatWidgetInner({ baseUrl, getStateSnapshot, placeholder, projectId, suggestions, }: WidgetConfig): React.ReactElement;
+
+export { type ChatSession, type ChatThread, type ChatThreadMessage, type JSONSchema7Object, type SupportChatSuggestion, type SupportChatTool, SupportChatWidgetInner, type WidgetConfig, initEmbedBridge, setStateSnapshot };

package/dist/support-chat.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Iframe-side half of the cross-origin bridge. Runs inside the Saasco
+ * `/embed/support-chat` page and talks to the host page's loader over
+ * `postMessage`:
+ *
+ * - inbound host messages (boot/identify/updateJwt/setStateSnapshot/viewport/
+ *   open/close) are validated by `event.origin` against the project's trusted
+ *   domains, then written into the {@link registry} the live widget subscribes to;
+ * - outbound round-trips (page-context lookups, host-registered client tools) are
+ *   promise-based with a `requestId` and a per-call timeout so a missing or slow
+ *   host handler can never hang a streaming turn.
+ *
+ * The first valid inbound message pins the parent origin; every reply targets
+ * that pinned origin (never `"*"`). The initial `ready` and any pre-boot resize
+ * carry no secrets, so they fall back to `"*"` until the origin is known.
+ */
+
+/**
+ * Wires the message listener and announces readiness. Idempotent. `allowedOrigins`
+ * is the project's trusted-domain allowlist plus the Saasco origin itself (so
+ * same-origin dogfooding works); patterns accept full origins, bare hosts and
+ * `*.example.com` wildcards (see `matchesOriginPattern`).
+ */
+declare function initEmbedBridge(options: {
+    allowedOrigins: string[];
+}): void;
+
+/** Snapshot of host-app state appended to the agent's system prompt each turn. */
+declare function setStateSnapshot(snapshot: unknown): void;
+
+/**
+ * Public types for the embeddable support chat widget. These restate the
+ * server wire contracts (`libs/support/shared` / `libs/chat/shared`) locally
+ * so the published package carries zero workspace dependencies.
+ */
+/**
+ * A minimal structural JSON Schema object describing a tool's arguments. It is
+ * declared locally (no `json-schema` package import) so the published SDK stays
+ * dependency-free. The root must be a `type: "object"` schema; additional JSON
+ * Schema keywords (`$schema`, `$defs`, …) are allowed via the index signature.
+ */
+type JSONSchema7Object = {
+    additionalProperties?: boolean | Record<string, unknown>;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    type: "object";
+    [key: string]: unknown;
+};
+/**
+ * The runtime shape of a tool the support widget can run in the browser. Tools
+ * are authored in the dashboard (stored in `Meta`) and served by the public
+ * settings endpoint as a `PublicChatTool`, which the widget rebuilds into this
+ * shape via `reconstructDashboardTool`.
+ *
+ * `execute` runs in the host app's browser when the agent calls a host tool
+ * and may touch in-page state, mutations, or SDKs. Server tools (dashboard
+ * `execution: "server"`) are proxied by the agent instead and never reach the
+ * widget; the reconstructed `execute` is only a same-origin `credentials:
+ * "include"` fallback. Tools marked `destructive` pause for an explicit
+ * Approve/Reject before running.
+ */
+type SupportChatTool = {
+    /** Shown to the model; 1–2000 chars. */
+    description: string;
+    /** Pauses for an explicit Approve/Reject before running. */
+    destructive?: boolean;
+    /**
+     * Where the call runs. `"host"` round-trips to the host page's loader, which
+     * runs the consumer's `registerTool` handler in the host realm; `"server"` is
+     * run by the agent (proxied to `endpoint`), so the widget never calls
+     * `execute` for it. Destructive tools always run host-side behind the
+     * approval gate.
+     */
+    execution?: "host" | "server";
+    /**
+     * REST URL template for server-proxied or host-executed HTTP tools. Ignored
+     * for in-browser-only tools.
+     */
+    endpoint?: string;
+    execute: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+    /** JSON Schema (object) for the args; travels over the wire to the agent. */
+    inputSchema: JSONSchema7Object;
+    /** HTTP method for REST execution. */
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Display name shown in the dashboard and chat UI. */
+    name: string;
+    /**
+     * Parameter names filled from visitor context at call time — not supplied by
+     * the model. See `getStateSnapshot` on {@link WidgetConfig}.
+     */
+    contextParameters?: string[];
+};
+/** A canned prompt offered in the empty state; clicking it fills the input. */
+type SupportChatSuggestion = {
+    /** Optional second line shown under the label. */
+    description?: string;
+    label: string;
+    /** The text placed in the input when the suggestion is picked. */
+    prompt: string;
+};
+type WidgetConfig = {
+    /** Origin of the saasco app hosting the support-chat API, e.g. https://app.example.com */
+    baseUrl: string;
+    /** Read at submit time and appended to the agent's system prompt. */
+    getStateSnapshot?: () => unknown;
+    /** Input placeholder. */
+    placeholder?: string;
+    projectId: string;
+    /** Canned prompts offered before the first message. */
+    suggestions?: SupportChatSuggestion[];
+};
+
+/**
+ * Plain-fetch transport for the public support-chat REST endpoints. The
+ * embedding origin must be on the project's allowlist (configured in the
+ * support widget settings) for cross-origin calls to pass CORS.
+ */
+
+type ChatSession = {
+    attachments?: ConversationImageAttachment[];
+    conversationId: string;
+    sessionToken: string;
+};
+type ConversationImageAttachment = {
+    contentType?: string;
+    fileName?: string;
+    url: string;
+};
+type ChatThreadMessage = {
+    attachments?: ConversationImageAttachment[];
+    /** Replier's first name — present for `role: "team"` (human) messages only. */
+    authorName?: string;
+    /** Rich body (HTML when from email); not shown in the widget. */
+    content: string | null;
+    createdAt: number;
+    id: string;
+    /** Resolved help-center sources referenced by `[[kb:…]]` markers in plainBody. */
+    kbCitations?: {
+        id: string;
+        title: string;
+        url: string;
+    }[];
+    /** Plain-text body for bubbles and session previews. */
+    plainBody: string | null;
+    role: "user" | "team" | "bot";
+};
+type ChatThread = {
+    /** False while a human has taken over — the widget goes persist-only. */
+    agentEnabled: boolean;
+    conversationId: string;
+    messages: ChatThreadMessage[];
+    state: "open" | "closed" | "snoozed";
+};
+
+/**
+ * Embeddable customer-facing support chat for third-party apps — an
+ * Intercom-style messenger (Home + Messages tabs, branded workspace rows, a
+ * restyled chat with a workspace header and per-message meta lines) on top of the
+ * persisted support channel:
+ *
+ * - the customer talks to a streaming AI support agent that can call the
+ *   project's dashboard-configured tools (loaded from the public settings
+ *   endpoint), with an Approve/Reject gate for tools marked `destructive`,
+ * - an email gate captures a reply-to address before the first message when the
+ *   host app hasn't already identified the visitor; every message is persisted
+ *   into the saasco support inbox under `projectId`, with human replies merged
+ *   into the open chat by polling the thread endpoint, and
+ * - once a human takes the conversation over the agent stream is muted, the
+ *   customer sees a handoff acknowledgment, a "Waiting for a teammate" indicator
+ *   until someone replies, then "{name} has joined the conversation" above the
+ *   first team message.
+ *
+ * The per-conversation session token (and the captured email) are persisted in
+ * the Saasco iframe-origin `localStorage` so anonymous threads survive reloads
+ * (best-effort — Safari/strict-Firefox partition third-party storage; identified
+ * users resume server-side via the JWT instead). This component is the iframe
+ * app entry: it renders directly into the `/embed/support-chat` page (no host-
+ * realm blank-iframe wrapper), and the host integrates over the postMessage
+ * bridge — identity, JWT, state snapshots, viewport and open/close all arrive
+ * through {@link initEmbedBridge} and are read here from the registry.
+ */
+declare function SupportChatWidgetInner({ baseUrl, getStateSnapshot, placeholder, projectId, suggestions, }: WidgetConfig): React.ReactElement;
+
+export { type ChatSession, type ChatThread, type ChatThreadMessage, type JSONSchema7Object, type SupportChatSuggestion, type SupportChatTool, SupportChatWidgetInner, type WidgetConfig, initEmbedBridge, setStateSnapshot };