@epam/ai-dial-chat-hooks 1.3.0-dev.5 → 1.3.0-dev.55

package/mcp-apps.d.ts

@@ -1,256 +1,2 @@
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { DeploymentItemDto } from '@epam/ai-dial-chat-api-client';
-import { DialToolsetDto } from '@epam/ai-dial-chat-api-client';
-import { Implementation } from '@modelcontextprotocol/sdk/types.js';
-import { McpAppToolSummaryDto } from '@epam/ai-dial-chat-api-client';
-import { McpUiHostContext } from '@mcp-ui/client';
-import { Message } from '@epam/ai-dial-chat-shared';
-import { ToolsetsApi } from '@epam/ai-dial-chat-api-client';
-
-/** A cached MCP App resource fetch plus its resolved tool result. */
-declare interface CachedMcpAppResponse {
-    /** The fetched resource's HTML body. */
-    html: string;
-    /** The tool call's resolved result, if any. */
-    toolResult?: CallToolResult;
-}
-
-/** Host-provided function that forwards an MCP App's tool call through the host's backend. */
-declare type CallMcpAppTool = (
-toolsetId: string,
-toolName: string,
-args: unknown,
-kind: McpDeploymentKind,
-) => Promise<CallToolResult>;
-
-/**
- * Wraps the generated `ToolsetsApi` in the surface `useMcpAppTools`,
- * `useOpenMcpAppCanvas`, and `@epam/ai-dial-mcp-apps`'s hooks/utilities call,
- * so a host app configures one `ToolsetsApi` instance (base URL, auth
- * headers, CSRF) and passes it here once. Mirrors `createPublishApiClient`.
- */
-export declare const createMcpAppsApiClient: (toolsetsApi: ToolsetsApi) => McpAppsApiClient;
-
-/** Host-provided function that fetches a toolset's MCP Apps `ui://` resource and resolves to its HTML body. */
-declare type FetchMcpAppResourceHtml = (
-toolsetId: string,
-resourceUri: string,
-) => Promise<string>;
-
-/** Display mode an MCP App can ask the host to switch to via `ui/request-display-mode` — the MCP UI protocol's `inline`/`fullscreen`/`pip` union. */
-declare type McpAppDisplayMode = NonNullable<McpUiHostContext['displayMode']>;
-
-/**
- * Dependencies the host must inject into `useMcpAppInlinePreview` /
- * `McpAppInlinePreview` — everything that requires host context (theming,
- * locale, the configured API client) rather than being derivable from the
- * hook's own arguments.
- */
-declare interface McpAppHostAdapter {
-    /** `McpUiHostContext` to deliver to the mounted app's `ui/initialize` handshake. */
-    hostContext: McpUiHostContext;
-    /** Host identity (`name`/`version`) to deliver to the mounted app's `ui/initialize` handshake. */
-    hostInfo: Implementation;
-    /** Operator-configured MCP Apps sandbox-proxy URL, or `null` when unconfigured. */
-    sandboxUrl: string | null;
-    /** Fetches the matched tool's MCP Apps `ui://` resource. */
-    fetchResourceHtml: FetchMcpAppResourceHtml;
-    /** Forwards a tool call the mounted app makes on its own (`onToolCall`) or the live re-call `resolveMcpAppToolResult` performs. */
-    callTool: CallMcpAppTool;
-}
-
-/** Host values `useMcpAppHostContext` needs but cannot read itself — a lib must not import the app's theme/i18n/config context. */
-export declare interface McpAppHostContextParams {
-    /** Host's current theme id (e.g. `'light'`/`'dark'`), used when `mcpAppTheme` is unset. */
-    theme: string;
-    /** Operator-configured MCP App theme override, if any. */
-    mcpAppTheme?: string;
-    /** Host's current i18n locale (BCP 47). */
-    locale: string;
-    /** Operator-configured MCP App user-agent override. Defaults to the browser's own `navigator.userAgent`. */
-    mcpAppUserAgent?: string;
-    /**
-     * Display modes the host can switch an app between via
-     * `ui/request-display-mode`. Defaults to `['inline', 'fullscreen']` — the
-     * compact inline preview and the full-width canvas.
-     */
-    availableDisplayModes?: McpAppDisplayMode[];
-}
-
-/** Thrown by `McpAppsApiClient.fetchResourceHtml` on a non-OK response, carrying the HTTP status so callers can distinguish `403` (forbidden) from any other failure. */
-export declare class McpAppResourceFetchError extends Error {
-    readonly status: number;
-    constructor(status: number);
-}
-
-/** Reads/writes `useMcpAppResponseCache`'s per-conversation cache. */
-declare interface McpAppResponseCache {
-    /**
-     * Returns the cached entry only if it was written for this exact
-     * `seedKey` (`computeMcpAppSeedKey`) and is younger than the cache's TTL;
-     * otherwise `undefined` (a miss), so a stale or seed-mismatched entry is
-     * never served.
-     */
-    get: (
-    key: string,
-    seedKey: string | undefined,
-    ) => CachedMcpAppResponse | undefined;
-    /** Writes an entry for `key`, tagged with the seed it was resolved from. */
-    set: (
-    key: string,
-    value: CachedMcpAppResponse,
-    seedKey: string | undefined,
-    ) => void;
-    /** Removes the cached entry for `key`, if any. */
-    invalidate: (key: string) => void;
-    /**
-     * Returns the fresh cached entry for `(key, seedKey)` if one exists
-     * (same rules as `get`); otherwise runs `fetchFn` and caches its result.
-     * Concurrent calls for the same `(key, seedKey)` before `fetchFn` settles
-     * are coalesced onto the same in-flight promise instead of each starting
-     * their own — without this, a component re-rendered before its first
-     * fetch resolves (e.g. React StrictMode's dev-only double effect
-     * invocation) would race two independent fetches/live tool re-calls for
-     * the same message.
-     */
-    getOrFetch: (
-    key: string,
-    seedKey: string | undefined,
-    fetchFn: () => Promise<CachedMcpAppResponse>,
-    ) => Promise<CachedMcpAppResponse>;
-}
-
-/** The MCP Apps API surface produced by {@link createMcpAppsApiClient}. */
-export declare interface McpAppsApiClient {
-    /** Fetches a toolset's MCP Apps `ui://` resource and resolves to its HTML body. Throws `McpAppResourceFetchError` on a non-OK response. */
-    fetchResourceHtml: FetchMcpAppResourceHtml;
-    /** Forwards an MCP App's tool call (self-initiated, or `@epam/ai-dial-mcp-apps`'s live re-call) through chat-api. */
-    callTool: CallMcpAppTool;
-    /** Lists the tools of an MCP-capable deployment that declare an MCP Apps UI resource. */
-    listAppTools: (deploymentId: string, kind: McpDeploymentKind) => Promise<McpAppToolSummary[]>;
-    /** Lists every tool name exposed by an MCP-capable deployment's `tools/list`, unfiltered. */
-    listToolNames: (deploymentId: string, kind: McpDeploymentKind) => Promise<string[]>;
-}
-
-/** Original tool call's arguments/result, seeded into the mounted app so it renders that invocation immediately instead of an empty initial state. */
-declare interface McpAppToolCallSeed {
-    /** The tool call's real structured arguments. */
-    toolInput?: Record<string, unknown>;
-    /** The tool call's result, if already known. */
-    toolResult?: CallToolResult;
-}
-
-/**
- * How a tool was discovered — determines whether it's safe to live-re-call
- * (see `resolveMcpAppToolResult`) or treat as "always available" for a
- * message with no other evidence (see `findMcpAppForMessage`).
- *
- * - `'direct'`: the active deployment itself IS this MCP server (whether
- *   it's a bare Toolset or an Application declaring `features.mcp`) — the
- *   host is talking to it directly, so which tool a mounted app's own
- *   invocation targets is unambiguous.
- * - `'indirect'`: a different, tool-calling deployment's message happened to
- *   call a name prefixed with a toolset's display name; the toolset is a
- *   name-prefix *guess*, not a confirmed link the host was told about, so
- *   re-calling it live risks hitting the wrong tool or re-triggering a
- *   non-idempotent side effect.
- */
-declare type McpAppToolDiscovery = 'direct' | 'indirect';
-
-/** A tool's declared MCP Apps UI resource, keyed by the toolset it was discovered on. */
-declare interface McpAppToolRef {
-    /** Id of the toolset/application this tool was discovered on. */
-    toolsetId: string;
-    /** The tool's declared `ui://` resource. */
-    resourceUri: string;
-    /** Name used to correlate this ref against a message's real tool-call data (`resolveMcpAppToolCallSeed`/`findMcpAppForMessage`). */
-    toolName: string;
-    /** The tool's real name as declared by its owning toolset's `tools/list` — what must be passed to the mounted app/`onToolCall`. */
-    mcpToolName: string;
-    /** Deployment kind — determines which host MCP proxy route resolves `tools/call` for this tool. */
-    kind: McpDeploymentKind;
-    /** How this tool was discovered — see `McpAppToolDiscovery`. */
-    discovery: McpAppToolDiscovery;
-}
-
-/** A single MCP tool that declares an MCP Apps UI resource. */
-export declare type McpAppToolSummary = McpAppToolSummaryDto;
-
-/** Which of the host's two MCP proxy routes a deployment id resolves through — a plain toolset, or an application that is itself an MCP server. */
-declare type McpDeploymentKind = 'toolset' | 'application';
-
-/**
- * Builds the `McpAppHostAdapter` a host injects into `@epam/ai-dial-mcp-apps`'s
- * hooks/components, wiring the library's host-context/tool-call/resource-fetch
- * contract to a configured `McpAppsApiClient` and this app's theme/locale/config
- * values (`hostContextParams`, `sandboxUrl`), plus the host's own identity
- * (`hostInfo`) — this hook itself never reads app context, so a host builds
- * those values wherever it already has them.
- */
-export declare const useMcpAppHostAdapter: (displayMode: "inline" | "fullscreen", client: McpAppsApiClient, sandboxUrl: string | null, hostContextParams: McpAppHostContextParams, hostInfo: Implementation) => McpAppHostAdapter;
-
-/**
- * Builds the `McpUiHostContext` delivered to a mounted MCP App during its
- * `ui/initialize` handshake, shared by every place that mounts an app —
- * a full-width attachment canvas (`displayMode: 'fullscreen'`) and a compact
- * inline preview under a message (`displayMode: 'inline'`) — so the app can
- * size/style itself differently for each, and knows (via
- * `availableDisplayModes`) which surfaces it may ask the host to switch to.
- */
-export declare const useMcpAppHostContext: (displayMode: "inline" | "fullscreen", { theme, mcpAppTheme, locale, mcpAppUserAgent, availableDisplayModes, }: McpAppHostContextParams) => McpUiHostContext;
-
-/**
- * Discovers MCP Apps-capable tools available to the current conversation, merging two
- * sources:
- *
- * 1. **Direct** — the active deployment itself, when it declares `features.mcp` (a
- *    toolset, or an application that is itself an MCP server).
- * 2. **Indirect** — any toolset in `toolsets` whose name prefixes a tool-call name
- *    actually seen in `messages` (e.g. `weather_get_weather` implies the `weather`
- *    toolset). This covers a quick app that has no MCP capability of its own but
- *    internally delegates to an MCP-capable toolset — a link the host does not
- *    otherwise expose. Tool names discovered this way are re-prefixed with the
- *    toolset's name so they match the `{toolset}_{tool}` form seen in real tool
- *    calls, keeping downstream name-matching (`findMcpAppForMessage`) unchanged.
- *
- * Empty until loaded, or if neither source yields anything.
- */
-export declare const useMcpAppTools: (client: McpAppsApiClient, deployment: DeploymentItemDto | undefined, messages: Message[], toolsets: DialToolsetDto[]) => McpAppToolRef[];
-
-/**
- * Returns `openMcpAppCanvas`, an async function that opens the attachment
- * canvas for a discovered MCP App tool. `canvasKey`, when passed, is
- * forwarded as the canvas's `attachmentId` (and as the key into `cache`) so
- * callers can compare it against `useAttachmentCanvas().attachmentId` to
- * know whether this exact canvas is the one currently open. `toolCall`, when
- * passed, seeds the mounted app's initial `toolInput`/`toolResult`. Returns
- * `true` if the canvas was opened, `false` if `hostAdapter.sandboxUrl` isn't
- * configured or the resource failed to load.
- *
- * `cache` (shared with `@epam/ai-dial-mcp-apps`'s `useMcpAppInlinePreview` via
- * the same cache instance) is checked before fetching the resource or
- * re-resolving the tool result — reopening the canvas for a message already
- * seen (inline or in a prior canvas open) reuses that fetch instead of
- * repeating it, and a concurrent in-flight fetch for the same message (e.g.
- * the inline preview hasn't finished loading yet) is coalesced onto rather
- * than raced against (`cache.getOrFetch`). Pass `forceReload: true` (wired to
- * the canvas header's reload button, `content.onReload`) to bypass and
- * refresh the cache entry.
- *
- * `onBeforeOpen`, if passed, runs before the canvas opens (e.g. to close
- * other panels a host keeps mutually exclusive with the canvas) — this hook
- * has no opinion on what else is open in the host UI.
- */
-export declare const useOpenMcpAppCanvas: (cache: McpAppResponseCache, hostAdapter: McpAppHostAdapter, labels: UseOpenMcpAppCanvasLabels, onBeforeOpen?: () => void) => {
-    openMcpAppCanvas: (match: McpAppToolRef, canvasKey?: string, toolCall?: McpAppToolCallSeed, forceReload?: boolean) => Promise<boolean>;
-};
-
-/** User-facing text `useOpenMcpAppCanvas` needs but cannot resolve itself — a lib must not call `t()`. */
-export declare interface UseOpenMcpAppCanvasLabels {
-    /** Error label shown when the resource fetch is forbidden (HTTP 403). */
-    forbiddenErrorLabel: string;
-    /** Error label shown for any other resource-load/tool-call failure. */
-    loadErrorLabel: string;
-}
-
-export { }
+export * from './entry-points/mcp-apps.js'
+export {}

package/oauth/authorize-url.d.ts

@@ -0,0 +1,16 @@
+import { ToolsetOAuthSettings } from './models';
+/**
+ * Resolves the OAuth callback location against the current origin. The
+ * callback path is supplied by the host: this module owns no application
+ * route.
+ */
+export declare const getToolsetRedirectUri: (callbackPath: string) => string;
+/**
+ * Builds the OAuth authorize URL for a given, already-generated `state`
+ * value. The caller owns what `state` carries — see `initiateOAuthLogin`.
+ * Returns `null` rather than throwing for a configuration that cannot
+ * produce a valid URL, including one whose authorization endpoint is not an
+ * `http:`/`https:` URL.
+ */
+export declare const buildToolsetAuthorizeUrl: (auth: ToolsetOAuthSettings, redirectUri: string, state: string) => string | null;
+//# sourceMappingURL=authorize-url.d.ts.map

package/oauth/authorize-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize-url.d.ts","sourceRoot":"","sources":["../../src/oauth/authorize-url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,cAAc,MAAM,KAAG,MACjB,CAAC;AAU7C;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GACnC,MAAM,oBAAoB,EAC1B,aAAa,MAAM,EACnB,OAAO,MAAM,KACZ,MAAM,GAAG,IA0BX,CAAC"}

package/oauth/handshake.d.ts

@@ -0,0 +1,30 @@
+import { ToolsetOAuthResult } from './models';
+import { ToolsetCredentialsLevel } from './types';
+/** Name of the same-origin `BroadcastChannel` shared by an OAuth flow's opener and its callback popup. */
+export declare const getToolsetOAuthChannelName: (flowId: string) => string;
+/** Options for {@link waitForToolsetOAuthResult}. */
+export interface WaitForToolsetOAuthResultOptions {
+    /** Resource id echoed back in a success result. */
+    toolsetId: string;
+    /** Credentials level echoed back in a success result. */
+    credentialsLevel: ToolsetCredentialsLevel;
+    /**
+     * The host's callback route — the same path the flow's popup was opened
+     * against. The popup-URL reader treats a same-origin URL as a result only
+     * when its pathname equals this value, so a host serving more than one
+     * callback route passes whichever one it actually opened.
+     */
+    callbackPath: string;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+/**
+ * Waits for the OAuth callback popup to report a result over BroadcastChannel
+ * or through the completion marker in its same-origin URL. A cross-origin
+ * provider can make the retained WindowProxy look closed even while the popup
+ * remains open, so cancellation is confirmed only when the initiating window
+ * regains focus. Reported results are acknowledged so the callback can close
+ * itself even when the retained WindowProxy was severed.
+ */
+export declare const waitForToolsetOAuthResult: (popup: Window, flowId: string, { toolsetId, credentialsLevel, callbackPath, timeoutMs, pollIntervalMs, }: WaitForToolsetOAuthResultOptions) => Promise<ToolsetOAuthResult>;
+//# sourceMappingURL=handshake.d.ts.map

package/oauth/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/oauth/handshake.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8B,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EACL,uBAAuB,EAKxB,MAAM,SAAS,CAAC;AAIjB,0GAA0G;AAC1G,eAAO,MAAM,0BAA0B,GAAI,QAAQ,MAAM,KAAG,MAChB,CAAC;AA4B7C,qDAAqD;AACrD,MAAM,WAAW,gCAAgC;IAC/C,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GACpC,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,2EAMG,gCAAgC,KAClC,OAAO,CAAC,kBAAkB,CAkHzB,CAAC"}

package/oauth/models.d.ts

@@ -0,0 +1,81 @@
+import { OAuthResourceKind, ToolsetCredentialsLevel, ToolsetOAuthChannelControlType, ToolsetOAuthFailureReason, ToolsetOAuthInitiationResultType, ToolsetOAuthResultType } from './types';
+/**
+ * OAuth client settings needed to build an authorize URL — the narrow subset
+ * of a toolset's `authSettings` this module reads. Declared as its own shape
+ * so hosts can keep their wider editor form models app-owned and still pass
+ * them straight in.
+ */
+export interface ToolsetOAuthSettings {
+    clientId?: string;
+    authorizationEndpoint?: string;
+    scopes?: string[];
+    codeChallenge?: string;
+    codeChallengeMethod?: string;
+}
+/**
+ * Redirect state for an OAuth login flow. The flow writes this into the
+ * *popup's own* `sessionStorage` before navigating it to the provider, since
+ * the popup and its opener do not share a `sessionStorage` partition once
+ * navigated cross-origin.
+ */
+export interface ToolsetRedirectState {
+    toolsetId: string;
+    credentialsLevel?: ToolsetCredentialsLevel;
+    redirectUri?: string;
+    /** CSRF state token generated by the client before the OAuth redirect. */
+    state?: string;
+    /**
+     * Which sign-in endpoint the host's callback route should submit the
+     * authorization code to. Defaults to `Toolset` when absent so every
+     * existing redirect state (written before this field existed) keeps
+     * calling the toolset login unchanged. `ExternalService` reuses the same
+     * popup/BroadcastChannel machinery with `toolsetId` repurposed as an
+     * `{appId}::{serviceId}` composite key. `OfflineCredentials` reuses the
+     * same machinery again, with `toolsetId` repurposed as a fixed sentinel
+     * correlation id (`'offline-credentials'`) — the field carries no real
+     * toolset/external-service meaning there, only the opaque
+     * flow-correlation string the shared popup/`BroadcastChannel` utilities
+     * require structurally.
+     */
+    resourceKind?: OAuthResourceKind;
+    /**
+     * Whether the user agreed the application may use the resulting credential
+     * while they are away. Carried through the popup because the choice is made
+     * before the redirect and the code exchange happens after it — the callback
+     * route has no other way to learn it. Absent means "not granted".
+     */
+    offlineUsageConsent?: boolean;
+}
+export type ToolsetOAuthInitiationResult = {
+    type: ToolsetOAuthInitiationResultType.Started;
+    popup: Window;
+    flowId: string;
+} | {
+    type: ToolsetOAuthInitiationResultType.Blocked;
+} | {
+    type: ToolsetOAuthInitiationResultType.InvalidConfig;
+};
+export interface ToolsetOAuthSuccessMessage {
+    type: ToolsetOAuthResultType.Success;
+    toolsetId: string;
+    credentialsLevel: ToolsetCredentialsLevel;
+}
+export interface ToolsetOAuthFailureMessage {
+    type: ToolsetOAuthResultType.Failure;
+    reason: ToolsetOAuthFailureReason;
+}
+/** Confirms that the initiating tab consumed the callback result. */
+export interface ToolsetOAuthResultAcknowledgement {
+    type: ToolsetOAuthChannelControlType.ResultAcknowledged;
+}
+/**
+ * Non-secret result reported by the OAuth callback popup for one flow. Used
+ * unchanged by every resource kind — the callback branch only needs to signal
+ * success/failure, not resource details, back through the channel.
+ */
+export type ToolsetOAuthChannelMessage = ToolsetOAuthSuccessMessage | ToolsetOAuthFailureMessage;
+/** Result resolved by `waitForToolsetOAuthResult` to the tab that initiated the login. */
+export type ToolsetOAuthResult = ToolsetOAuthSuccessMessage | ToolsetOAuthFailureMessage | {
+    type: ToolsetOAuthResultType.Cancelled;
+};
+//# sourceMappingURL=models.d.ts.map

package/oauth/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/oauth/models.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,uBAAuB,EACvB,8BAA8B,EAC9B,yBAAyB,EACzB,gCAAgC,EAChC,sBAAsB,EACvB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,MAAM,4BAA4B,GACpC;IACE,IAAI,EAAE,gCAAgC,CAAC,OAAO,CAAC;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IAAE,IAAI,EAAE,gCAAgC,CAAC,OAAO,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,gCAAgC,CAAC,aAAa,CAAA;CAAE,CAAC;AAE7D,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,sBAAsB,CAAC,OAAO,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,uBAAuB,CAAC;CAC3C;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,sBAAsB,CAAC,OAAO,CAAC;IACrC,MAAM,EAAE,yBAAyB,CAAC;CACnC;AAED,qEAAqE;AACrE,MAAM,WAAW,iCAAiC;IAChD,IAAI,EAAE,8BAA8B,CAAC,kBAAkB,CAAC;CACzD;AAED;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GACpC,0BAA0B,GAAG,0BAA0B,CAAC;AAE1D,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAC1B,0BAA0B,GAC1B,0BAA0B,GAC1B;IAAE,IAAI,EAAE,sBAAsB,CAAC,SAAS,CAAA;CAAE,CAAC"}

package/oauth/popup.d.ts

@@ -0,0 +1,30 @@
+import { ToolsetOAuthInitiationResult, ToolsetOAuthSettings } from './models';
+import { OAuthResourceKind, ToolsetCredentialsLevel } from './types';
+/**
+ * Opens a same-origin, blank popup synchronously — call this as the very
+ * first thing in a click (or click-derived) handler so the browser still
+ * treats it as user-triggered, before doing any `await`. A caller that needs
+ * to fetch the OAuth config first (it isn't known synchronously) opens the
+ * popup with this, then calls `navigateToolsetOAuthPopup` once the config has
+ * been fetched.
+ */
+export declare const openToolsetOAuthPopup: () => Window | null;
+/**
+ * Builds the OAuth authorize URL for an already-open popup and navigates it,
+ * closing the popup and returning `InvalidConfig` if the auth config can't
+ * produce a valid authorize URL. `callbackPath` is the host's own callback
+ * route — this module owns no application route.
+ */
+export declare const navigateToolsetOAuthPopup: (popup: Window, auth: ToolsetOAuthSettings, toolsetId: string, callbackPath: string, credentialsLevel?: ToolsetCredentialsLevel, resourceKind?: OAuthResourceKind, offlineUsageConsent?: boolean) => ToolsetOAuthInitiationResult;
+/**
+ * Builds the OAuth authorize URL, opens a same-origin popup synchronously (so
+ * a blocked popup can be reliably detected), writes the redirect state into
+ * *that popup's own* `sessionStorage` while it is still same-origin
+ * `about:blank`, then navigates it to the provider's authorization page.
+ * `auth` must already be known synchronously here, so the config is validated
+ * *before* opening the popup — unlike `navigateToolsetOAuthPopup`, used when
+ * the auth config can only be fetched asynchronously after the popup is
+ * already open.
+ */
+export declare const initiateOAuthLogin: (auth: ToolsetOAuthSettings, toolsetId: string, callbackPath: string, credentialsLevel?: ToolsetCredentialsLevel, offlineUsageConsent?: boolean) => ToolsetOAuthInitiationResult;
+//# sourceMappingURL=popup.d.ts.map

package/oauth/popup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popup.d.ts","sourceRoot":"","sources":["../../src/oauth/popup.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,4BAA4B,EAC5B,oBAAoB,EAErB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,iBAAiB,EAEjB,uBAAuB,EAExB,MAAM,SAAS,CAAC;AAiDjB;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAO,MAAM,GAAG,IACvB,CAAC;AAE5B;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,OAAO,MAAM,EACb,MAAM,oBAAoB,EAC1B,WAAW,MAAM,EACjB,cAAc,MAAM,EACpB,mBAAkB,uBAAsD,EACxE,eAAc,iBAA6C,EAC3D,sBAAsB,OAAO,KAC5B,4BAkBF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,oBAAoB,EAC1B,WAAW,MAAM,EACjB,cAAc,MAAM,EACpB,mBAAkB,uBAAsD,EACxE,sBAAsB,OAAO,KAC5B,4BAmBF,CAAC"}

package/oauth/toolset-id.d.ts

@@ -0,0 +1,53 @@
+import { DialToolsetAuthSettingsDto } from '@epam/ai-dial-chat-api-client';
+import { ToolsetCredentialsLevel } from './types';
+/**
+ * Percent-encodes each `/`-separated segment of a toolset id so it satisfies
+ * the backend's `DEPLOYMENT_ID_PATTERN`/`TOOLSET_URL_PATTERN` (spaces and
+ * other reserved characters must already be percent-encoded — e.g. `%20`,
+ * not a real space — before this value is used against the toolsets API;
+ * `/` stays a literal path separator). Externally-sourced ids — the raw,
+ * human-readable id an embedded iframe sends over `postMessage`
+ * (e.g. `toolsets/<bucket>/My Toolset__1.0`) — arrive unencoded, unlike the
+ * already-encoded `id`/`toolset` field `listToolsets()`/`DialToolsetDto`
+ * returns. Mirrors `encodeDeploymentId` (`deployment-id.ts`), which exists
+ * for the identical reason on the applications side.
+ */
+export declare const encodeToolsetId: (id: string) => string;
+/**
+ * Inverse of `encodeToolsetId` — decodes each `/`-separated segment back to
+ * its raw, human-readable form. A segment that isn't valid percent-encoding
+ * is passed through unchanged rather than throwing, since this decodes
+ * externally-sourced ids (broadcast toolset-login events).
+ */
+export declare const decodeToolsetId: (id: string) => string;
+/** Whether a toolset id belongs to the `public` bucket (shared with all users), mirroring the legacy `isEntityIdPublic` check. */
+export declare const isPublicToolsetId: (toolsetId: string) => boolean;
+/**
+ * Encodes a toolset id to its single-encoded form regardless of whether the
+ * value received it in was already percent-encoded or the raw,
+ * human-readable form — decoding first then re-encoding once is idempotent
+ * either way, since `decodeToolsetId` on a raw (unencoded) id is a no-op.
+ * Use this instead of `encodeToolsetId` at a boundary that cannot guarantee
+ * which form it receives, such as a `postMessage` payload from an embedded
+ * iframe: calling `encodeToolsetId` directly on a value the sender already
+ * encoded escapes the existing `%` characters a second time (`%20` becomes
+ * `%2520`), which the backend only ever undoes once and so 404s on.
+ */
+export declare const normalizeToolsetId: (toolsetId: string) => string;
+/**
+ * Resolves which credentials level a toolset's login applies to, per DIAL
+ * Core's public/private toolset convention: a `public`-bucket toolset is
+ * shared credentials-wise at `User` level, while a private/workspace toolset
+ * is scoped at `Global` level. Every surface that drives a toolset login
+ * (the sign-in-interrupt dialog, the QuickApps editor iframe bridge,
+ * `useToolsetLogin`) must resolve the level this way rather than assuming one.
+ */
+export declare const resolveToolsetCredentialsLevel: (toolsetId: string) => ToolsetCredentialsLevel.User | ToolsetCredentialsLevel.Global;
+/**
+ * Picks the auth-status field matching one credentials level out of a
+ * toolset's `authSettings` — DIAL Core reports `userLevelAuthStatus` and
+ * `globalAuthStatus` as independent fields rather than one status keyed by
+ * level.
+ */
+export declare const selectToolsetAuthStatus: (authSettings: Pick<DialToolsetAuthSettingsDto, "userLevelAuthStatus" | "globalAuthStatus"> | undefined, credentialsLevel: ToolsetCredentialsLevel) => string | undefined;
+//# sourceMappingURL=toolset-id.d.ts.map

package/oauth/toolset-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolset-id.d.ts","sourceRoot":"","sources":["../../src/oauth/toolset-id.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAEhF,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAIlD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAI/B,CAAC;AAEf;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAU/B,CAAC;AAEf,kIAAkI;AAClI,eAAO,MAAM,iBAAiB,GAAI,WAAW,MAAM,KAAG,OAIrD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,WAAW,MAAM,KAAG,MACV,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GACzC,WAAW,MAAM,KAChB,uBAAuB,CAAC,IAAI,GAAG,uBAAuB,CAAC,MAGtB,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,cACI,IAAI,CACF,0BAA0B,EAC1B,qBAAqB,GAAG,kBAAkB,CAC3C,GACD,SAAS,EACb,kBAAkB,uBAAuB,KACxC,MAAM,GAAG,SAGwB,CAAC"}

package/oauth/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Enums and constants shared by the OAuth authorization-code popup flow and
+ * every host that drives it. These declarations live here (rather than being
+ * copied per host) because TypeScript string enums are nominal: a
+ * structurally identical host-side copy would not type-check against a lib
+ * signature that names the enum.
+ */
+/** Authentication mechanism a toolset requires. */
+export declare enum ToolsetAuthTypes {
+    None = "NONE",
+    ApiKey = "API_KEY",
+    OAuth = "OAUTH"
+}
+/** Sign-in state DIAL Core reports for one credentials level of a toolset. */
+export declare enum ToolsetAuthStatus {
+    SignedIn = "SIGNED_IN",
+    SignedOut = "SIGNED_OUT",
+    Failed = "FAILED"
+}
+/** Scope the credentials submitted by a login apply to. */
+export declare enum ToolsetCredentialsLevel {
+    Global = "GLOBAL",
+    User = "USER",
+    App = "APP"
+}
+/** Whether a toolset authenticates interactively, and whether its client is manually configured. */
+export declare enum WithLogin {
+    WithLogin = "with-login",
+    WithoutLogin = "without-login",
+    WithConfig = "with-config"
+}
+/**
+ * Which kind of resource an OAuth flow is authenticating. Three kinds share
+ * the same popup/`BroadcastChannel` machinery, which is why this module is
+ * named for the concern rather than for toolsets.
+ */
+export declare enum OAuthResourceKind {
+    Toolset = "toolset",
+    ExternalService = "external-service",
+    /**
+     * Proactive Scheduled Tasks offline-credentials consent. Unlike
+     * `Toolset`/`ExternalService`, this kind has no natural per-resource id —
+     * the shared `ToolsetRedirectState.toolsetId` slot is repurposed as a
+     * fixed sentinel correlation id (`'offline-credentials'`) purely for the
+     * popup/`BroadcastChannel` handshake, never as a real toolset/
+     * external-service id.
+     */
+    OfflineCredentials = "offline-credentials"
+}
+/** Outcome of calling `initiateOAuthLogin`. */
+export declare enum ToolsetOAuthInitiationResultType {
+    /** The popup was opened and navigated to the provider's authorize URL. */
+    Started = "started",
+    /** The browser blocked the popup before it could be opened. */
+    Blocked = "blocked",
+    /** The toolset's OAuth configuration is missing required fields. */
+    InvalidConfig = "invalid-config"
+}
+/** Outcome reported back to the tab that initiated an OAuth login. */
+export declare enum ToolsetOAuthResultType {
+    Success = "success",
+    Failure = "failure",
+    /** The popup was closed and focus returned to its opener, or the flow timed out. */
+    Cancelled = "cancelled"
+}
+/** Reason codes the callback popup can report for a failed OAuth login. */
+export declare enum ToolsetOAuthFailureReason {
+    MissingCode = "missing-code",
+    MissingRedirectState = "missing-redirect-state",
+    StateMismatch = "state-mismatch",
+    LoginRequestFailed = "login-request-failed"
+}
+/** Control messages exchanged over a flow-scoped OAuth channel. */
+export declare enum ToolsetOAuthChannelControlType {
+    ResultAcknowledged = "result-acknowledged"
+}
+/** Query parameters written into the callback popup URL after an OAuth flow completes. */
+export declare enum ToolsetOAuthCallbackQuery {
+    Result = "toolsetOAuthResult",
+    FailureReason = "toolsetOAuthFailureReason"
+}
+/** `sessionStorage` key the flow writes its `ToolsetRedirectState` under, in the popup it opens. */
+export declare const TOOLSET_REDIRECT_STATE_KEY = "toolset-redirect-state";
+//# sourceMappingURL=types.d.ts.map

package/oauth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/oauth/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,mDAAmD;AACnD,oBAAY,gBAAgB;IAC1B,IAAI,SAAS;IACb,MAAM,YAAY;IAClB,KAAK,UAAU;CAChB;AAED,8EAA8E;AAC9E,oBAAY,iBAAiB;IAC3B,QAAQ,cAAc;IACtB,SAAS,eAAe;IACxB,MAAM,WAAW;CAClB;AAED,2DAA2D;AAC3D,oBAAY,uBAAuB;IACjC,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAED,oGAAoG;AACpG,oBAAY,SAAS;IACnB,SAAS,eAAe;IACxB,YAAY,kBAAkB;IAC9B,UAAU,gBAAgB;CAC3B;AAED;;;;GAIG;AACH,oBAAY,iBAAiB;IAC3B,OAAO,YAAY;IACnB,eAAe,qBAAqB;IACpC;;;;;;;OAOG;IACH,kBAAkB,wBAAwB;CAC3C;AAED,+CAA+C;AAC/C,oBAAY,gCAAgC;IAC1C,0EAA0E;IAC1E,OAAO,YAAY;IACnB,+DAA+D;IAC/D,OAAO,YAAY;IACnB,oEAAoE;IACpE,aAAa,mBAAmB;CACjC;AAED,sEAAsE;AACtE,oBAAY,sBAAsB;IAChC,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,oFAAoF;IACpF,SAAS,cAAc;CACxB;AAED,2EAA2E;AAC3E,oBAAY,yBAAyB;IACnC,WAAW,iBAAiB;IAC5B,oBAAoB,2BAA2B;IAC/C,aAAa,mBAAmB;IAChC,kBAAkB,yBAAyB;CAC5C;AAED,mEAAmE;AACnE,oBAAY,8BAA8B;IACxC,kBAAkB,wBAAwB;CAC3C;AAED,0FAA0F;AAC1F,oBAAY,yBAAyB;IACnC,MAAM,uBAAuB;IAC7B,aAAa,8BAA8B;CAC5C;AAED,oGAAoG;AACpG,eAAO,MAAM,0BAA0B,2BAA2B,CAAC"}

package/oauth/useOAuthCallbackCompletion/useOAuthCallbackCompletion.d.ts

@@ -0,0 +1,54 @@
+import { ToolsetRedirectState } from '../models';
+import { ToolsetCredentialsLevel, ToolsetOAuthFailureReason } from '../types';
+/** Arguments handed to the host's exchange callback. */
+export interface OAuthExchangeParams {
+    /** One-time authorization code the provider returned. */
+    code: string;
+    /** Redirect URI the code was issued against, to be echoed back to the backend. */
+    redirectUri: string;
+    /** Credentials level resolved from the stored redirect state. */
+    credentialsLevel: ToolsetCredentialsLevel;
+    /** The full redirect state the flow stored before navigating to the provider. */
+    redirectState: ToolsetRedirectState;
+}
+/** Parameters for {@link useOAuthCallbackCompletion}. */
+export interface UseOAuthCallbackCompletionParams {
+    /**
+     * Query parameters of the callback URL. Read once per mount; the hook takes
+     * `code` and `state` from it.
+     */
+    searchParams: URLSearchParams;
+    /**
+     * Path used to build the `redirect_uri` echoed back to the backend when the
+     * stored redirect state carries none — every state written by the current
+     * flow does, so this only covers states written before that field existed.
+     */
+    callbackPath: string;
+    /**
+     * Performs the code-for-credentials exchange. Resolving `null` reports
+     * success; resolving a failure reason reports that reason (for a host-side
+     * validation the hook cannot perform, such as an unparseable resource id);
+     * rejecting reports `LoginRequestFailed`.
+     */
+    exchange: (params: OAuthExchangeParams) => Promise<ToolsetOAuthFailureReason | null>;
+}
+/** State {@link useOAuthCallbackCompletion} exposes for the host page to render. */
+export interface UseOAuthCallbackCompletionResult {
+    /** True until the flow has reported an outcome. */
+    isInProgress: boolean;
+    /** Reason the flow failed, or `null` while in progress or on success. */
+    failureReason: ToolsetOAuthFailureReason | null;
+}
+/**
+ * Completes an OAuth authorization-code flow from inside the callback popup:
+ * reads and clears the redirect state written into this popup's own
+ * `sessionStorage`, scrubs the authorization code from the visible URL before
+ * any request, validates the returned `state`, performs the exchange through
+ * the injected callback, then reports the outcome into the popup URL and over
+ * the flow channel until acknowledged, closing the popup afterwards. Runs its
+ * effect once per mount even under StrictMode double-invocation. Renders
+ * nothing and produces no user-visible text — the host page presents and
+ * announces the returned state in its own language.
+ */
+export declare const useOAuthCallbackCompletion: ({ searchParams, callbackPath, exchange, }: UseOAuthCallbackCompletionParams) => UseOAuthCallbackCompletionResult;
+//# sourceMappingURL=useOAuthCallbackCompletion.d.ts.map

package/oauth/useOAuthCallbackCompletion/useOAuthCallbackCompletion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOAuthCallbackCompletion.d.ts","sourceRoot":"","sources":["../../../src/oauth/useOAuthCallbackCompletion/useOAuthCallbackCompletion.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,oBAAoB,EACrB,MAAM,WAAW,CAAC;AACnB,OAAO,EAEL,uBAAuB,EAGvB,yBAAyB,EAE1B,MAAM,UAAU,CAAC;AAIlB,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,iFAAiF;IACjF,aAAa,EAAE,oBAAoB,CAAC;CACrC;AAED,yDAAyD;AACzD,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,YAAY,EAAE,eAAe,CAAC;IAC9B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,EAAE,CACR,MAAM,EAAE,mBAAmB,KACxB,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;CAChD;AAED,oFAAoF;AACpF,MAAM,WAAW,gCAAgC;IAC/C,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,aAAa,EAAE,yBAAyB,GAAG,IAAI,CAAC;CACjD;AA2ED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,GAAI,2CAIxC,gCAAgC,KAAG,gCAmGrC,CAAC"}