open-chat-studio-widget 0.7.0 → 0.9.0

package/dist/types/components/ocs-chat/ocs-chat.d.ts

@@ -83,6 +83,7 @@ export declare class OcsChat {
     userName?: string;
     /**
      * Whether to persist session data to local storage to allow resuming previous conversations after page reload.
+     * Ignored when `sessionId` is provided.
      */
     persistentSession: boolean;
     /**
@@ -117,9 +118,22 @@ export declare class OcsChat {
      * This is for internal use only and is not intended for public-facing widgets.
      */
     versionNumber?: number;
+    /**
+     * The ID of an existing chat session to connect to. When provided, the widget
+     * is bound to that session: local session persistence is disabled and the
+     * message history is loaded from the server. Intended for host pages that
+     * create the session server-side (e.g. the OCS web chat page).
+     */
+    sessionId?: string;
+    /**
+     * A session token proving access to the session named by `session-id`. Host
+     * pages that create the session server-side pass a server-minted token here so
+     * the widget can authenticate its requests. Only meaningful with `session-id`.
+     */
+    sessionToken?: string;
     error: string;
     messages: ChatMessage[];
-    sessionId?: string;
+    activeSessionId?: string;
     isLoading: boolean;
     isTyping: boolean;
     typingProgressMessage: string;
@@ -168,12 +182,20 @@ export declare class OcsChat {
     private positionInitialized;
     private internalPageContext?;
     private sessionEpoch;
+    private currentSessionToken?;
     host: HTMLElement;
     componentWillLoad(): Promise<void>;
     componentDidLoad(): void;
     disconnectedCallback(): void;
+    private applySessionToken;
     private getChatService;
     private addErrorMessage;
+    /**
+     * Recover from a rejected session token (403). Unbound widgets discard the
+     * dead session/token, show a notice, and start fresh on the next send; bound
+     * widgets cannot restart a host-owned session, so they surface an error.
+     */
+    private handleSessionAccessError;
     private handleError;
     private parseJSONProp;
     private parseWelcomeMessages;
@@ -183,6 +205,11 @@ export declare class OcsChat {
     private loadTranslationsFromUrl;
     private cleanup;
     private startSession;
+    /**
+     * Load the full message history for a session provided via the `session-id`
+     * prop, then begin regular polling.
+     */
+    private loadBoundSessionHistory;
     private uploadFiles;
     private sendMessage;
     private handleStarterQuestionClick;
@@ -274,6 +301,7 @@ export declare class OcsChat {
     private restoreVisibleState;
     private clearSessionStorage;
     private isKioskMode;
+    private isSessionBound;
     private isLocalStorageAvailable;
     private showConfirmationDialog;
     private hideConfirmationDialog;

package/dist/types/components.d.ts

@@ -65,7 +65,7 @@ export namespace Components {
          */
         "pageContext"?: Record<string, any>;
         /**
-          * Whether to persist session data to local storage to allow resuming previous conversations after page reload.
+          * Whether to persist session data to local storage to allow resuming previous conversations after page reload. Ignored when `sessionId` is provided.
           * @default true
          */
         "persistentSession": boolean;
@@ -79,6 +79,14 @@ export namespace Components {
           * @default 'right'
          */
         "position": 'left' | 'center' | 'right';
+        /**
+          * The ID of an existing chat session to connect to. When provided, the widget is bound to that session: local session persistence is disabled and the message history is loaded from the server. Intended for host pages that create the session server-side (e.g. the OCS web chat page).
+         */
+        "sessionId"?: string;
+        /**
+          * A session token proving access to the session named by `session-id`. Host pages that create the session server-side pass a server-minted token here so the widget can authenticate its requests. Only meaningful with `session-id`.
+         */
+        "sessionToken"?: string;
         /**
           * Whether to show the launcher button. Set to false to hide the button and open the chat window programmatically via the `visible` property.
           * @default true
@@ -184,7 +192,7 @@ declare namespace LocalJSX {
          */
         "pageContext"?: Record<string, any>;
         /**
-          * Whether to persist session data to local storage to allow resuming previous conversations after page reload.
+          * Whether to persist session data to local storage to allow resuming previous conversations after page reload. Ignored when `sessionId` is provided.
           * @default true
          */
         "persistentSession"?: boolean;
@@ -198,6 +206,14 @@ declare namespace LocalJSX {
           * @default 'right'
          */
         "position"?: 'left' | 'center' | 'right';
+        /**
+          * The ID of an existing chat session to connect to. When provided, the widget is bound to that session: local session persistence is disabled and the message history is loaded from the server. Intended for host pages that create the session server-side (e.g. the OCS web chat page).
+         */
+        "sessionId"?: string;
+        /**
+          * A session token proving access to the session named by `session-id`. Host pages that create the session server-side pass a server-minted token here so the widget can authenticate its requests. Only meaningful with `session-id`.
+         */
+        "sessionToken"?: string;
         /**
           * Whether to show the launcher button. Set to false to hide the button and open the chat window programmatically via the `visible` property.
           * @default true

package/dist/types/services/chat-session-service.d.ts

@@ -1,3 +1,8 @@
+export declare class SessionAccessError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(status: number, code: string | undefined, message: string);
+}
 export type ChatRole = 'system' | 'user' | 'assistant';
 export interface ChatAttachment {
     name: string;
@@ -13,6 +18,7 @@ export interface ChatMessage {
 }
 export interface ChatStartSessionResponse {
     session_id: string;
+    session_token?: string | null;
     chatbot: unknown;
     participant: unknown;
 }
@@ -35,6 +41,7 @@ export interface ChatSessionServiceOptions {
     apiBaseUrl: string;
     embedKey?: string;
     widgetVersion: string;
+    sessionToken?: string;
     csrfTokenProvider?: (apiBaseUrl: string) => string | undefined;
     taskPollingIntervalMs?: number;
     taskPollingMaxAttempts?: number;
@@ -61,19 +68,39 @@ export declare class ChatSessionService {
     private readonly apiBaseUrl;
     private readonly embedKey?;
     private readonly widgetVersion;
+    private sessionToken?;
     private readonly csrfTokenProvider;
     private readonly taskPollingIntervalMs;
     private readonly taskPollingMaxAttempts;
     private readonly messagePollingIntervalMs;
     private messagePollingTimer?;
+    private loggedSunsetLevel?;
+    private static readonly MAX_HISTORY_PAGES;
     constructor(options: ChatSessionServiceOptions);
     startSession(requestBody: Record<string, unknown>): Promise<ChatStartSessionResponse>;
     sendMessage(sessionId: string, payload: Record<string, unknown>): Promise<ChatSendMessageResponse>;
     pollTaskOnce(sessionId: string, taskId: string): Promise<ChatTaskPollResponse>;
     pollTask(sessionId: string, taskId: string, callbacks: TaskPollingCallbacks): TaskPollingHandle;
     fetchMessages(sessionId: string, since?: string): Promise<ChatPollResponse>;
+    /**
+     * Fetch the complete message history for a session by paging through the
+     * poll endpoint until no more messages remain.
+     */
+    fetchAllMessages(sessionId: string): Promise<ChatMessage[]>;
     startMessagePolling(sessionId: string, callbacks: MessagePollingCallbacks): MessagePollingHandle;
     stopMessagePolling(): void;
+    setSessionToken(token?: string): void;
+    private request;
+    /**
+     * Log a deprecation warning (RFC 8594 `Deprecation`/`Sunset`/`Link` headers)
+     * when the server reports that this widget version is deprecated. Warns
+     * during the deprecation window and errors once the sunset date has passed.
+     * Logs at most once per level so polling does not flood the console.
+     */
+    private checkSunsetHeaders;
+    private parseSunsetDate;
+    private parseSuccessorUrl;
+    private raiseForStatus;
     private getJsonHeaders;
     private getCommonHeaders;
 }

package/dist/types/services/file-attachment-manager.d.ts

@@ -19,11 +19,13 @@ export interface UploadContext {
     sessionId: string;
     participantId: string;
     participantName?: string;
+    sessionToken?: string;
 }
 export interface UploadResult {
     selectedFiles: SelectedFile[];
     uploadedIds: number[];
     errorMessage?: string;
+    tokenRejected?: boolean;
 }
 export declare class FileAttachmentManager {
     private readonly supportedExtensions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-chat-studio-widget",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Chat component for Open Chat Studio",
   "main": "dist/index.cjs.js",
   "exports": "./dist/esm/open-chat-studio-widget.js",