@egain/ai-agent-sdk 0.1.0

package/dist/core/message/handlers/HeartbeatHandler.d.ts

@@ -0,0 +1,12 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { Message } from '../Message.js';
+import { MessageHandlerResult } from '../types.js';
+/**
+ * Handler for heartbeat messages
+ * Processes system heartbeat messages indicating the agent is processing/typing
+ */
+export declare class HeartbeatHandler extends BaseMessageHandler {
+    canHandle(message: Message): boolean;
+    handle(message: Message): MessageHandlerResult;
+}
+//# sourceMappingURL=HeartbeatHandler.d.ts.map

package/dist/core/message/handlers/HeartbeatHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeartbeatHandler.d.ts","sourceRoot":"","sources":["../../../../src/core/message/handlers/HeartbeatHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,kBAAkB;IACtD,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAOpC,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,oBAAoB;CAsC/C"}

package/dist/core/message/handlers/HeartbeatHandler.js

@@ -0,0 +1,46 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { PERSONA, ROLE } from '../types.js';
+/**
+ * Handler for heartbeat messages
+ * Processes system heartbeat messages indicating the agent is processing/typing
+ */
+export class HeartbeatHandler extends BaseMessageHandler {
+    canHandle(message) {
+        return (message.persona === PERSONA.SYSTEM &&
+            message.role === ROLE.HEARTBEAT);
+    }
+    handle(message) {
+        const sessionId = message.sessionId;
+        const agentId = message.agentId;
+        // Build from object - system/agent is the sender
+        const from = {
+            name: message.from || 'AI Agent',
+            isAi: true,
+        };
+        // Build to object - customer is the recipient
+        const to = {
+            name: message.to || 'Customer',
+            isAi: false,
+        };
+        // Build message object with persona, role, content, and raw data
+        const messageObj = {
+            persona: message.persona,
+            role: message.role,
+            content: message.content,
+            raw: message.messageData || {},
+        };
+        // Build result in the required format
+        const result = {
+            type: 'heartbeat_processed',
+            messageId: message.messageId,
+            timestamp: message.timestamp || Date.now(),
+            sessionId: sessionId,
+            agentId: agentId,
+            from: from,
+            to: to,
+            message: messageObj,
+        };
+        return result;
+    }
+}
+//# sourceMappingURL=HeartbeatHandler.js.map

package/dist/core/message/handlers/HeartbeatHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeartbeatHandler.js","sourceRoot":"","sources":["../../../../src/core/message/handlers/HeartbeatHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAE5C;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,kBAAkB;IACtD,SAAS,CAAC,OAAgB;QACxB,OAAO,CACL,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,MAAM;YAClC,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,SAAS,CAChC,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAgB;QACrB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAEhC,iDAAiD;QACjD,MAAM,IAAI,GAAG;YACX,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,UAAU;YAChC,IAAI,EAAE,IAAI;SACX,CAAC;QAEF,8CAA8C;QAC9C,MAAM,EAAE,GAAG;YACT,IAAI,EAAE,OAAO,CAAC,EAAE,IAAI,UAAU;YAC9B,IAAI,EAAE,KAAK;SACZ,CAAC;QAEF,iEAAiE;QACjE,MAAM,UAAU,GAAG;YACjB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,GAAG,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;SAC/B,CAAC;QAEF,sCAAsC;QACtC,MAAM,MAAM,GAAyB;YACnC,IAAI,EAAE,qBAAqB;YAC3B,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;YAC1C,SAAS,EAAE,SAAS;YACpB,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,IAAI;YACV,EAAE,EAAE,EAAE;YACN,OAAO,EAAE,UAAU;SACpB,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/core/message/handlers/TokenRefreshHandler.d.ts

@@ -0,0 +1,30 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { Message } from '../Message.js';
+import { MessageHandlerResult } from '../types.js';
+/**
+ * Options for TokenRefreshHandler
+ */
+export interface TokenRefreshHandlerOptions {
+    /**
+     * Function to get a new access token
+     * @returns Promise resolving to the access token string
+     */
+    getAccessToken?: () => Promise<string>;
+    /**
+     * Function to send a message to the connection
+     * @param payload - The message payload to send
+     */
+    sendToConnection?: (payload: any) => Promise<void> | void;
+}
+/**
+ * Handler for stale or expired token messages
+ * Processes metadata messages indicating token refresh is required
+ */
+export declare class TokenRefreshHandler extends BaseMessageHandler {
+    private getAccessToken?;
+    private sendToConnection?;
+    constructor(options?: TokenRefreshHandlerOptions);
+    canHandle(message: Message): boolean;
+    handle(message: Message): Promise<MessageHandlerResult>;
+}
+//# sourceMappingURL=TokenRefreshHandler.d.ts.map

package/dist/core/message/handlers/TokenRefreshHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenRefreshHandler.d.ts","sourceRoot":"","sources":["../../../../src/core/message/handlers/TokenRefreshHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3D;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,kBAAkB;IACzD,OAAO,CAAC,cAAc,CAAC,CAAwB;IAC/C,OAAO,CAAC,gBAAgB,CAAC,CAAyC;gBAEtD,OAAO,CAAC,EAAE,0BAA0B;IAMhD,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAiB9B,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAmE9D"}

package/dist/core/message/handlers/TokenRefreshHandler.js

@@ -0,0 +1,84 @@
+import { BaseMessageHandler } from '../BaseMessageHandler.js';
+import { PERSONA, ROLE, ERROR_CODES } from '../types.js';
+/**
+ * Handler for stale or expired token messages
+ * Processes metadata messages indicating token refresh is required
+ */
+export class TokenRefreshHandler extends BaseMessageHandler {
+    constructor(options) {
+        super();
+        this.getAccessToken = options?.getAccessToken;
+        this.sendToConnection = options?.sendToConnection;
+    }
+    canHandle(message) {
+        if (message.persona !== PERSONA.METADATA) {
+            return false;
+        }
+        const isStaleToken = message.role === ROLE.STALE_TOKEN &&
+            message.messageData?.error_code === ERROR_CODES.STALE_TOKEN;
+        const isExpiredToken = message.role === ROLE.EXPIRED_TOKEN &&
+            (message.messageData?.error_code?.indexOf(ERROR_CODES.UNAUTHORIZED_PREFIX) === 0 ||
+                message.messageData?.error_code?.indexOf(ERROR_CODES.FORBIDDEN_PREFIX) === 0);
+        return isStaleToken || isExpiredToken;
+    }
+    async handle(message) {
+        const sessionId = message.sessionId;
+        const agentId = message.agentId;
+        const errorCode = message.messageData?.error_code;
+        // Build from object - metadata/system is the sender
+        const from = {
+            name: message.from || 'System',
+            isAi: false,
+        };
+        // Build to object - customer/client is the recipient
+        const to = {
+            name: message.to || 'Client',
+            isAi: false,
+        };
+        // Build message object with persona, role, content, and raw data
+        const messageObj = {
+            persona: message.persona,
+            role: message.role,
+            content: message.content,
+            raw: message.messageData || {},
+            errorCode,
+        };
+        // Build result in the required format
+        const result = {
+            type: 'token_refresh_required',
+            messageId: message.messageId,
+            timestamp: message.timestamp || Date.now(),
+            sessionId: sessionId,
+            agentId: agentId,
+            from: from,
+            to: to,
+            message: messageObj,
+            role: message.role,
+            errorCode,
+        };
+        // If callbacks are provided, perform the token refresh automatically
+        if (this.getAccessToken && this.sendToConnection) {
+            try {
+                const authToken = await this.getAccessToken();
+                const payload = {
+                    persona: PERSONA.METADATA,
+                    role: ROLE.TOKEN,
+                    messageData: {
+                        token: authToken,
+                    },
+                };
+                await this.sendToConnection(payload);
+                // Update result to indicate refresh was successful
+                result.type = 'token_refreshed';
+                result.tokenRefreshed = true;
+            }
+            catch (error) {
+                // Update result to indicate refresh failed
+                result.type = 'token_refresh_failed';
+                result.tokenRefreshError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=TokenRefreshHandler.js.map

package/dist/core/message/handlers/TokenRefreshHandler.js.map

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

package/dist/core/message/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Message type constants
+ */
+export declare const PERSONA: Readonly<{
+    readonly METADATA: "metadata";
+    readonly SYSTEM: "system";
+    readonly AGENT: "agent";
+    readonly CUSTOMER: "customer";
+}>;
+export declare const ROLE: Readonly<{
+    readonly STALE_TOKEN: "stale_token";
+    readonly EXPIRED_TOKEN: "expired_token";
+    readonly TOKEN: "token";
+    readonly CHAT_HISTORY: "chat history";
+    readonly ERROR: "error";
+    readonly HEARTBEAT: "heartbeat";
+    readonly FOLLOW_UP_QUESTION: "follow up question agent";
+    readonly CUSTOMER_SUPPORT: "customer support agent";
+    readonly CONTEXT: "context";
+    readonly GRACEFUL_DISCONNECT: "graceful disconnect";
+    readonly ESCALATION: "escalation";
+    readonly FEEDBACK: "feedback";
+    readonly HUMAN: "human";
+}>;
+export declare const ERROR_CODES: Readonly<{
+    readonly STALE_TOKEN: "401-012";
+    readonly UNAUTHORIZED_PREFIX: "401";
+    readonly FORBIDDEN_PREFIX: "403";
+}>;
+/**
+ * Type definitions for persona values
+ */
+export type Persona = typeof PERSONA[keyof typeof PERSONA];
+/**
+ * Type definitions for role values
+ */
+export type Role = typeof ROLE[keyof typeof ROLE];
+/**
+ * Message data structure
+ */
+export interface MessageData {
+    [key: string]: any;
+    error_code?: string;
+    chat_history?: any[];
+    options?: string[];
+    escalation?: boolean;
+    escalationData?: {
+        live?: boolean;
+        phone?: boolean;
+        phoneNumber?: string;
+        sms?: boolean;
+        smsNumber?: string;
+        email?: boolean;
+    };
+    sources?: any[];
+    reasoning?: string;
+    context?: object;
+    feedback?: {
+        rating: any;
+        answerMessageId: string;
+    };
+    escalationEvent?: any;
+    token?: string;
+    workflowType?: "preChatWorkflow" | "escalationWorkflow" | "agentWorkflow" | null;
+    workflowNodeType?: string | null;
+    inputType?: string | null;
+}
+/**
+ * Result returned by message handlers
+ */
+export interface MessageHandlerResult {
+    type: string;
+    messageId?: string | number;
+    timestamp: number;
+    sessionId?: string | number;
+    agentId?: string | number;
+    from: {
+        name: string;
+        isAi: boolean;
+    };
+    to: {
+        name: string;
+        isAi: boolean;
+    };
+    message: {
+        persona: string;
+        role: string;
+        content?: string;
+        raw: any;
+        escalationType?: string | null;
+        escalationData?: any;
+        sources?: any[];
+        reasoning?: string;
+        showReasoning?: boolean;
+        showFeedback?: boolean;
+        showOptions?: boolean;
+    };
+    isEscalation?: boolean;
+    [key: string]: any;
+}
+export interface SessionContext {
+    agentId: string;
+    sessionId: string;
+    customerName: string;
+    agentName: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/message/types.d.ts.map

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

package/dist/core/message/types.js

@@ -0,0 +1,30 @@
+/**
+ * Message type constants
+ */
+export const PERSONA = Object.freeze({
+    METADATA: "metadata",
+    SYSTEM: "system",
+    AGENT: "agent",
+    CUSTOMER: "customer",
+});
+export const ROLE = Object.freeze({
+    STALE_TOKEN: "stale_token",
+    EXPIRED_TOKEN: "expired_token",
+    TOKEN: "token",
+    CHAT_HISTORY: "chat history",
+    ERROR: "error",
+    HEARTBEAT: "heartbeat",
+    FOLLOW_UP_QUESTION: "follow up question agent",
+    CUSTOMER_SUPPORT: "customer support agent",
+    CONTEXT: "context",
+    GRACEFUL_DISCONNECT: "graceful disconnect",
+    ESCALATION: "escalation",
+    FEEDBACK: "feedback",
+    HUMAN: "human",
+});
+export const ERROR_CODES = Object.freeze({
+    STALE_TOKEN: "401-012",
+    UNAUTHORIZED_PREFIX: "401",
+    FORBIDDEN_PREFIX: "403",
+});
+//# sourceMappingURL=types.js.map

package/dist/core/message/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/message/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IACnC,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;CACZ,CAAC,CAAC;AAEZ,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC;IAChC,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,eAAe;IAC9B,KAAK,EAAE,OAAO;IACd,YAAY,EAAE,cAAc;IAC5B,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,WAAW;IACtB,kBAAkB,EAAE,0BAA0B;IAC9C,gBAAgB,EAAE,wBAAwB;IAC1C,OAAO,EAAE,SAAS;IAClB,mBAAmB,EAAE,qBAAqB;IAC1C,UAAU,EAAE,YAAY;IACxB,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;CACN,CAAC,CAAC;AAEZ,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,WAAW,EAAE,SAAS;IACtB,mBAAmB,EAAE,KAAK;IAC1B,gBAAgB,EAAE,KAAK;CACf,CAAC,CAAC"}

package/dist/core/platform/HookContract.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Bidirectional facade between the SDK and platform connector scripts.
+ *
+ * The SDK builds an implementation internally (closing over `AiAgent` state)
+ * and passes it to the connector via `PlatformComponentService.setHookContract()`.
+ * Connector authors can type their code against these interfaces.
+ *
+ * **Not intended for SDK consumers** — only for platform connector authors.
+ *
+ * @module HookContract
+ */
+import type { Portal } from '../types/PortalTypes.js';
+/**
+ * A single entry in the call transcript — the live customer-agent
+ * conversation on the telephony platform (Genesys, Amazon Connect, etc.).
+ *
+ * This is distinct from the AiAgent chat transcript (`Transcript` /
+ * `TranscriptEntry`), which tracks WebSocket messages between the SDK
+ * and the AI Agent backend.
+ */
+export interface CallTranscriptEntry {
+    sender: string;
+    content: string;
+    timestamp: Date;
+}
+/**
+ * Caller information pushed by the platform connector.
+ */
+export interface CallerInfo {
+    name?: string;
+    phone?: string;
+    email?: string;
+    [key: string]: unknown;
+}
+/**
+ * Bidirectional contract between the SDK and a platform connector script.
+ *
+ * Read-only getters return live state (not stale snapshots) because the
+ * implementation closes over the `AiAgent` instance.
+ */
+export interface HookContract {
+    /** Returns the current call transcript entries (telephony conversation, not AI chat). */
+    getTranscript: () => CallTranscriptEntry[];
+    /** Returns a shallow copy of the initialization parameters. */
+    getInitParams: () => Record<string, string>;
+    /** Returns the agent details object. */
+    getAgentDetails: () => any;
+    /** Returns the current MSAL/auth access token. */
+    getMsalAccessToken: () => Promise<string | null>;
+    /** Returns the deployment info object. */
+    getDeploymentInfo: () => any;
+    /** Returns the platform type string (e.g. "genesys"). */
+    getPlatformType: () => string | null;
+    /** Returns the deployment environment ("dev" | "qa" | "prod"). */
+    getEnvironment: () => string;
+    /** Returns the user ID from init params. */
+    getUserId: () => string | null;
+    /** Returns the user context object. */
+    getUserContext: () => Record<string, unknown> | null;
+    /** Returns the conversation ID set by the connector. */
+    getConversationId: () => string | null;
+    /**
+     * Returns effective OAuth resource scopes for the auth flow: after the platform connector runs,
+     * the merged list in `config.scopes` wins; otherwise non-empty `initParams.scopes` (comma-separated)
+     * overrides `config.scopes`, then defaults (including `core.customermgr.read` for customer when
+     * neither query nor config supplies scopes).
+     */
+    getAuthScopes: () => string[];
+    /** Returns the tenant ID from deployment info. */
+    getTenantId: () => string | null;
+    /** Returns the currently selected portal, or null before selection. */
+    getSelectedPortal: () => Portal | null;
+    /** Returns the caller info set by the connector. */
+    getCallerInfo: () => CallerInfo | null;
+    /** Add an entry to the call transcript (telephony conversation, not AI chat). */
+    addToTranscript: (entry: {
+        sender: string;
+        content: string;
+        timestamp?: Date;
+    }) => void;
+    /** Set caller information (e.g. from CTI integration). */
+    setCallerInfo: (callerInfo: CallerInfo) => void;
+    /** Mark the platform as authenticated. */
+    setPlatformAuthenticated: (value: boolean) => void;
+    /** Store a secondary platform-specific token. */
+    setPlatformToken: (token: string) => void;
+    /** Set the conversation/interaction ID. */
+    setConversationId: (id: string) => void;
+    /** Append to the user context (merge, not overwrite). */
+    setUserContext: (userContext: Record<string, unknown>) => void;
+    /** Set filter tags for portal content filtering. */
+    setUserFilterTags: (filterTags: Record<string, string[]>) => void;
+    /** Subscribe to agent widget actions. Returns an unsubscribe function. */
+    subscribeToAgentWidgetActions: (callback: (action: string, data: unknown) => void) => () => void;
+    /** Forward a user message through the SDK's send pipeline. */
+    onUserMessage: (message: string) => void;
+    /** Handle a source click from the connector. */
+    onSourceClick: (source: {
+        id: string;
+        title: string;
+        url?: string;
+        [key: string]: unknown;
+    }) => void;
+    /** Handle an intent confirmation from the connector. */
+    onIntentConfirm: (intent: {
+        id: string;
+        intent: string;
+        confidence: number;
+        [key: string]: unknown;
+    }) => void;
+}
+//# sourceMappingURL=HookContract.d.ts.map

package/dist/core/platform/HookContract.d.ts.map

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

package/dist/core/platform/HookContract.js

@@ -0,0 +1,13 @@
+/**
+ * Bidirectional facade between the SDK and platform connector scripts.
+ *
+ * The SDK builds an implementation internally (closing over `AiAgent` state)
+ * and passes it to the connector via `PlatformComponentService.setHookContract()`.
+ * Connector authors can type their code against these interfaces.
+ *
+ * **Not intended for SDK consumers** — only for platform connector authors.
+ *
+ * @module HookContract
+ */
+export {};
+//# sourceMappingURL=HookContract.js.map

package/dist/core/platform/HookContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HookContract.js","sourceRoot":"","sources":["../../../src/core/platform/HookContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/core/platform/PlatformComponentService.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Interface for platform-specific connector scripts (Genesys, Amazon Connect, etc.).
+ *
+ * Connector scripts register an implementation of this interface on
+ * `window.PlatformComponentService` (browser) or `globalThis.PlatformComponentService`
+ * (non-browser). The SDK calls these methods at defined lifecycle points
+ * during initialization.
+ *
+ * @module PlatformComponentService
+ */
+import type { HookContract } from './HookContract.js';
+import type { Portal } from '../types/PortalTypes.js';
+/**
+ * Contract that platform connector scripts must implement.
+ *
+ * All methods except `initPlatform` are optional — the SDK calls them
+ * when present and silently skips them when absent.
+ */
+export interface PlatformComponentService {
+    /** Main connector initialization (e.g., connecting to Genesys/NICE). Called after authentication, before the CC pipeline starts. */
+    initPlatform: (hookContract: HookContract) => Promise<void>;
+    /** Filter or reorder the portal list after fetching. */
+    getPortalList?: (filteredPortals: Portal[]) => Portal[] | Promise<Portal[]>;
+    /** Auto-select a default portal. Receives the output of `getPortalList`. Return `null` to fall through to count-based logic. */
+    getDefaultPortal?: (portalList: Portal[]) => Portal | null | Promise<Portal | null>;
+    /** Called after a portal is selected. Returns filter tags (`Record<string, string[]>`) stored via `setUserFilterTags`. */
+    onPortalSelected?: (portal: Portal) => Record<string, string[]> | Promise<Record<string, string[]>>;
+    /** Modify OAuth scopes before authentication. Returns the augmented scopes array. */
+    addCustomAuthScopes?: (scopes: string[]) => string[] | Promise<string[]>;
+    /** Register custom hooks on the HookContract. */
+    loadCustomHook?: (hookContract: HookContract) => void;
+    /** Receive the HookContract for bidirectional communication with the SDK. */
+    setHookContract?: (hookContract: HookContract) => void;
+}
+declare global {
+    interface Window {
+        PlatformComponentService?: PlatformComponentService;
+    }
+}
+//# sourceMappingURL=PlatformComponentService.d.ts.map

package/dist/core/platform/PlatformComponentService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformComponentService.d.ts","sourceRoot":"","sources":["../../../src/core/platform/PlatformComponentService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,oIAAoI;IACpI,YAAY,EAAE,CAAC,YAAY,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D,wDAAwD;IACxD,aAAa,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5E,gIAAgI;IAChI,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEpF,0HAA0H;IAC1H,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAEpG,qFAAqF;IACrF,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEzE,iDAAiD;IACjD,cAAc,CAAC,EAAE,CAAC,YAAY,EAAE,YAAY,KAAK,IAAI,CAAC;IAEtD,6EAA6E;IAC7E,eAAe,CAAC,EAAE,CAAC,YAAY,EAAE,YAAY,KAAK,IAAI,CAAC;CACxD;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;KACrD;CACF"}

package/dist/core/platform/PlatformComponentService.js

@@ -0,0 +1,12 @@
+/**
+ * Interface for platform-specific connector scripts (Genesys, Amazon Connect, etc.).
+ *
+ * Connector scripts register an implementation of this interface on
+ * `window.PlatformComponentService` (browser) or `globalThis.PlatformComponentService`
+ * (non-browser). The SDK calls these methods at defined lifecycle points
+ * during initialization.
+ *
+ * @module PlatformComponentService
+ */
+export {};
+//# sourceMappingURL=PlatformComponentService.js.map

package/dist/core/platform/PlatformComponentService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformComponentService.js","sourceRoot":"","sources":["../../../src/core/platform/PlatformComponentService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/core/platform/PlatformScriptLoader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Dynamic loader for platform connector scripts.
+ *
+ * In browser environments, injects a `<script>` tag. In non-browser
+ * environments (Node.js, SSR), falls back to dynamic `import()` using
+ * the same constructed URL.
+ *
+ * @module PlatformScriptLoader
+ */
+export interface LoadPlatformScriptOptions {
+    platform: string;
+    baseUrl: string;
+    overrideUrl?: string;
+    logger: {
+        debug: (msg: string, ctx?: object) => void;
+        info: (msg: string, ctx?: object) => void;
+        warn: (msg: string, ctx?: object) => void;
+        error: (msg: string, err?: Error, ctx?: object) => void;
+    };
+}
+/**
+ * Derive the deployment environment from available state.
+ *
+ * Priority: explicit env string > parsed from domain (dev-/qa- prefix) > "prod".
+ */
+export declare function deriveEnvironment(domain?: string, explicitEnv?: string): string;
+/**
+ * Construct the connector script URL for a given platform and environment.
+ */
+export declare function buildPlatformScriptUrl(platform: string, environment: string): string;
+/**
+ * Load a platform connector script.
+ *
+ * - **Browser:** Injects a `<script>` tag into `document.head`, waits for
+ *   `onload` + 100ms buffer, then verifies `window.PlatformComponentService`.
+ * - **Non-browser:** Uses dynamic `import()` with the same constructed URL.
+ *   The imported module must export `PlatformComponentService` as a default
+ *   or named export.
+ */
+export declare function loadPlatformScript(options: LoadPlatformScriptOptions): Promise<void>;
+//# sourceMappingURL=PlatformScriptLoader.d.ts.map

package/dist/core/platform/PlatformScriptLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformScriptLoader.d.ts","sourceRoot":"","sources":["../../../src/core/platform/PlatformScriptLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QACN,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;QAC3C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;QAC1C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;QAC1C,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;KACzD,CAAC;CACH;AAYD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAW/E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAGpF;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW1F"}