saasco-sdk 0.2.3 → 0.2.5

package/dist/{support-chat.d.cts → support.d.cts}

@@ -1,6 +1,6 @@
 /**
  * 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
+ * `/embed/support` page and talks to the host page's loader over
  * `postMessage`:
  *
  * - inbound host messages (boot/identify/updateJwt/setStateSnapshot/viewport/
@@ -25,11 +25,8 @@ 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
+ * Public types for the embeddable support widget. These restate the
  * server wire contracts (`libs/support/shared` / `libs/chat/shared`) locally
  * so the published package carries zero workspace dependencies.
  */
@@ -49,18 +46,17 @@ type JSONSchema7Object = {
 /**
  * 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
+ * settings endpoint as a `PublicSupportTool`, 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.
+ * `execution: "server"`) are proxied by the agent instead — the widget must
+ * not browser-fetch their absolute endpoints (that causes CORS noise). Tools
+ * marked `destructive` pause for an explicit Approve/Reject before running.
  */
-type SupportChatTool = {
-    /** Shown to the model; 1–2000 chars. */
+type SupportTool = {
+    /** Shown to the model. Active tools require a non-empty description. */
     description: string;
     /** Pauses for an explicit Approve/Reject before running. */
     destructive?: boolean;
@@ -91,7 +87,7 @@ type SupportChatTool = {
     contextParameters?: string[];
 };
 /** A canned prompt offered in the empty state; clicking it fills the input. */
-type SupportChatSuggestion = {
+type SupportSuggestion = {
     /** Optional second line shown under the label. */
     description?: string;
     label: string;
@@ -99,24 +95,26 @@ type SupportChatSuggestion = {
     prompt: string;
 };
 type WidgetConfig = {
-    /** Origin of the saasco app hosting the support-chat API, e.g. https://app.example.com */
+    /** Origin of the saasco app hosting the support 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;
+    /** Dashboard / embed preview: open the panel on mount. */
+    startOpen?: boolean;
     /** Canned prompts offered before the first message. */
-    suggestions?: SupportChatSuggestion[];
+    suggestions?: SupportSuggestion[];
 };
 
 /**
- * Plain-fetch transport for the public support-chat REST endpoints. The
+ * Plain-fetch transport for the public support 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 = {
+type SupportSession = {
     attachments?: ConversationImageAttachment[];
     conversationId: string;
     sessionToken: string;
@@ -126,7 +124,7 @@ type ConversationImageAttachment = {
     fileName?: string;
     url: string;
 };
-type ChatThreadMessage = {
+type SupportConversationMessage = {
     attachments?: ConversationImageAttachment[];
     /** Replier's first name — present for `role: "team"` (human) messages only. */
     authorName?: string;
@@ -144,16 +142,28 @@ type ChatThreadMessage = {
     plainBody: string | null;
     role: "user" | "team" | "bot";
 };
-type ChatThread = {
+type SupportConversation = {
     /** False while a human has taken over — the widget goes persist-only. */
     agentEnabled: boolean;
     conversationId: string;
-    messages: ChatThreadMessage[];
+    messages: SupportConversationMessage[];
     state: "open" | "closed" | "snoozed";
 };
 
 /**
- * Embeddable customer-facing support chat for third-party apps — an
+ * Iframe-side state store with subscribe/notify (same pattern as the internal
+ * AgentContext). In the cross-origin embed the widget UI runs inside the Saasco
+ * `/embed/support` iframe; the host page's loader pushes identity, the
+ * signed JWT, host-state snapshots, the host viewport and open/close commands
+ * over `postMessage`, and the embed bridge writes them here so the live widget
+ * (subscribed via `useSyncExternalStore`) picks them up without a reboot.
+ */
+
+/** Snapshot of host-app state appended to the agent's system prompt each turn. */
+declare function setStateSnapshot(snapshot: unknown): void;
+
+/**
+ * Embeddable customer-facing support 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:
@@ -164,21 +174,21 @@ type ChatThread = {
  * - 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
+ *   into the open chat by polling the conversation 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.
+ *   while they are waiting on a reply (open, customer last), 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-
+ * (best-effort — Safari/strict-Firefox partition third-party storage;
+ * identified users resume server-side). This component is the iframe
+ * app entry: it renders directly into the `/embed/support` 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;
+declare function SupportWidgetInner({ baseUrl, getStateSnapshot, placeholder, projectId, startOpen, suggestions, }: WidgetConfig): React.ReactElement;
 
-export { type ChatSession, type ChatThread, type ChatThreadMessage, type JSONSchema7Object, type SupportChatSuggestion, type SupportChatTool, SupportChatWidgetInner, type WidgetConfig, initEmbedBridge, setStateSnapshot };
+export { type JSONSchema7Object, type SupportConversation, type SupportConversationMessage, type SupportSession, type SupportSuggestion, type SupportTool, SupportWidgetInner, type WidgetConfig, initEmbedBridge, setStateSnapshot };

package/dist/{support-chat.d.ts → support.d.ts}

@@ -1,6 +1,6 @@
 /**
  * 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
+ * `/embed/support` page and talks to the host page's loader over
  * `postMessage`:
  *
  * - inbound host messages (boot/identify/updateJwt/setStateSnapshot/viewport/
@@ -25,11 +25,8 @@ 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
+ * Public types for the embeddable support widget. These restate the
  * server wire contracts (`libs/support/shared` / `libs/chat/shared`) locally
  * so the published package carries zero workspace dependencies.
  */
@@ -49,18 +46,17 @@ type JSONSchema7Object = {
 /**
  * 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
+ * settings endpoint as a `PublicSupportTool`, 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.
+ * `execution: "server"`) are proxied by the agent instead — the widget must
+ * not browser-fetch their absolute endpoints (that causes CORS noise). Tools
+ * marked `destructive` pause for an explicit Approve/Reject before running.
  */
-type SupportChatTool = {
-    /** Shown to the model; 1–2000 chars. */
+type SupportTool = {
+    /** Shown to the model. Active tools require a non-empty description. */
     description: string;
     /** Pauses for an explicit Approve/Reject before running. */
     destructive?: boolean;
@@ -91,7 +87,7 @@ type SupportChatTool = {
     contextParameters?: string[];
 };
 /** A canned prompt offered in the empty state; clicking it fills the input. */
-type SupportChatSuggestion = {
+type SupportSuggestion = {
     /** Optional second line shown under the label. */
     description?: string;
     label: string;
@@ -99,24 +95,26 @@ type SupportChatSuggestion = {
     prompt: string;
 };
 type WidgetConfig = {
-    /** Origin of the saasco app hosting the support-chat API, e.g. https://app.example.com */
+    /** Origin of the saasco app hosting the support 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;
+    /** Dashboard / embed preview: open the panel on mount. */
+    startOpen?: boolean;
     /** Canned prompts offered before the first message. */
-    suggestions?: SupportChatSuggestion[];
+    suggestions?: SupportSuggestion[];
 };
 
 /**
- * Plain-fetch transport for the public support-chat REST endpoints. The
+ * Plain-fetch transport for the public support 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 = {
+type SupportSession = {
     attachments?: ConversationImageAttachment[];
     conversationId: string;
     sessionToken: string;
@@ -126,7 +124,7 @@ type ConversationImageAttachment = {
     fileName?: string;
     url: string;
 };
-type ChatThreadMessage = {
+type SupportConversationMessage = {
     attachments?: ConversationImageAttachment[];
     /** Replier's first name — present for `role: "team"` (human) messages only. */
     authorName?: string;
@@ -144,16 +142,28 @@ type ChatThreadMessage = {
     plainBody: string | null;
     role: "user" | "team" | "bot";
 };
-type ChatThread = {
+type SupportConversation = {
     /** False while a human has taken over — the widget goes persist-only. */
     agentEnabled: boolean;
     conversationId: string;
-    messages: ChatThreadMessage[];
+    messages: SupportConversationMessage[];
     state: "open" | "closed" | "snoozed";
 };
 
 /**
- * Embeddable customer-facing support chat for third-party apps — an
+ * Iframe-side state store with subscribe/notify (same pattern as the internal
+ * AgentContext). In the cross-origin embed the widget UI runs inside the Saasco
+ * `/embed/support` iframe; the host page's loader pushes identity, the
+ * signed JWT, host-state snapshots, the host viewport and open/close commands
+ * over `postMessage`, and the embed bridge writes them here so the live widget
+ * (subscribed via `useSyncExternalStore`) picks them up without a reboot.
+ */
+
+/** Snapshot of host-app state appended to the agent's system prompt each turn. */
+declare function setStateSnapshot(snapshot: unknown): void;
+
+/**
+ * Embeddable customer-facing support 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:
@@ -164,21 +174,21 @@ type ChatThread = {
  * - 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
+ *   into the open chat by polling the conversation 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.
+ *   while they are waiting on a reply (open, customer last), 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-
+ * (best-effort — Safari/strict-Firefox partition third-party storage;
+ * identified users resume server-side). This component is the iframe
+ * app entry: it renders directly into the `/embed/support` 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;
+declare function SupportWidgetInner({ baseUrl, getStateSnapshot, placeholder, projectId, startOpen, suggestions, }: WidgetConfig): React.ReactElement;
 
-export { type ChatSession, type ChatThread, type ChatThreadMessage, type JSONSchema7Object, type SupportChatSuggestion, type SupportChatTool, SupportChatWidgetInner, type WidgetConfig, initEmbedBridge, setStateSnapshot };
+export { type JSONSchema7Object, type SupportConversation, type SupportConversationMessage, type SupportSession, type SupportSuggestion, type SupportTool, SupportWidgetInner, type WidgetConfig, initEmbedBridge, setStateSnapshot };