@epam/ai-dial-chat-hooks 1.3.0-dev.34 → 1.3.0-dev.37

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"}

package/oauth/useToolsetLogin/useToolsetLogin.d.ts

@@ -0,0 +1,79 @@
+import { DialToolsetDto, ToolsetLoginBodyDto, ToolsetLogoutBodyDto } from '@epam/ai-dial-chat-api-client';
+import { ToolsetOAuthSettings } from '../models';
+import { ToolsetAuthTypes, ToolsetCredentialsLevel } from '../types';
+/** Terminal outcome kinds `login` can resolve. */
+export declare enum ToolsetLoginOutcomeType {
+    Success = "success",
+    Failure = "failure",
+    PopupBlocked = "popup-blocked",
+    Cancelled = "cancelled"
+}
+/** Discriminated outcome of one login attempt. */
+export interface ToolsetLoginOutcome {
+    /** Which terminal branch the attempt resolved through. */
+    type: ToolsetLoginOutcomeType;
+}
+/** Arguments for one `login` call. */
+export interface ToolsetLoginParams {
+    /** Already-encoded toolset id/url, as returned by `listToolsets`/`getToolset`. */
+    toolsetId: string;
+    /** Credentials level the submitted credentials apply to. */
+    credentialsLevel: ToolsetCredentialsLevel;
+    /** Authentication mechanism the toolset requires. */
+    authenticationType: ToolsetAuthTypes;
+    /** Required for `ToolsetAuthTypes.ApiKey`. */
+    apiKey?: string;
+    /** Required for `ToolsetAuthTypes.OAuth`. */
+    oauthSettings?: ToolsetOAuthSettings;
+    /**
+     * Whether the target level's cached status is currently `FAILED` — API key
+     * logins log that level out first when true. Ignored when `forceStale` is
+     * set, and never consulted for OAuth (OAuth does not log out before
+     * retrying).
+     */
+    isCurrentlyFailed?: boolean;
+    /**
+     * Always logs out the target level first (for both API key and OAuth)
+     * regardless of the cached status — set by callers reacting to a
+     * DIAL-Core-pushed `toolset/signin` event, which is proof the cached
+     * status may be stale even when it still reads `SIGNED_IN`.
+     */
+    forceStale?: boolean;
+    /**
+     * Whether the user agreed an application may use this credential while they
+     * are away. DIAL Core gates every on-behalf-of mint on it, so a toolset
+     * signed in without it works interactively and still fails with
+     * `consent-required` in the background. Absent means not granted.
+     */
+    offlineUsageConsent?: boolean;
+}
+/** Parameters for {@link useToolsetLogin}. */
+export interface UseToolsetLoginParams {
+    /**
+     * The host's OAuth callback route. Resolved against `window.location.origin`
+     * for the `redirect_uri`, and compared against the popup's pathname when
+     * reading a completion marker out of its URL.
+     */
+    callbackPath: string;
+    /** Submits credentials for one toolset at one credentials level. */
+    loginToolset: (toolsetId: string, body: ToolsetLoginBodyDto) => Promise<unknown>;
+    /** Clears stored credentials for one toolset at one credentials level. */
+    logoutToolset: (toolsetId: string, body: ToolsetLogoutBodyDto) => Promise<unknown>;
+    /** Re-reads a toolset so a reported cancellation can be checked against the backend. */
+    getToolset: (toolsetId: string) => Promise<DialToolsetDto>;
+}
+/** Result returned by {@link useToolsetLogin}. */
+export interface UseToolsetLoginResult {
+    /** Runs one API-key or OAuth login attempt and resolves its outcome. */
+    login: (params: ToolsetLoginParams) => Promise<ToolsetLoginOutcome>;
+}
+/**
+ * Shared toolset API-key/OAuth login orchestration, so no two surfaces fork
+ * the popup/`BroadcastChannel` handshake or the stale-credential-clearing
+ * rule. Every backend call arrives as an injected callback: the hook
+ * constructs no client instance and reads no app context. It resolves an
+ * outcome and shows nothing itself — mapping an outcome to notifications is
+ * the caller's job.
+ */
+export declare const useToolsetLogin: ({ callbackPath, loginToolset, logoutToolset, getToolset, }: UseToolsetLoginParams) => UseToolsetLoginResult;
+//# sourceMappingURL=useToolsetLogin.d.ts.map

package/oauth/useToolsetLogin/useToolsetLogin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToolsetLogin.d.ts","sourceRoot":"","sources":["../../../src/oauth/useToolsetLogin/useToolsetLogin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAOtD,OAAO,EAGL,gBAAgB,EAChB,uBAAuB,EAGxB,MAAM,UAAU,CAAC;AAElB,kDAAkD;AAClD,oBAAY,uBAAuB;IACjC,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,YAAY,kBAAkB;IAC9B,SAAS,cAAc;CACxB;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,IAAI,EAAE,uBAAuB,CAAC;CAC/B;AAED,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,qDAAqD;IACrD,kBAAkB,EAAE,gBAAgB,CAAC;IACrC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,YAAY,EAAE,CACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,mBAAmB,KACtB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,0EAA0E;IAC1E,aAAa,EAAE,CACb,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,oBAAoB,KACvB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,wFAAwF;IACxF,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5D;AAED,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,KAAK,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACrE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,4DAK7B,qBAAqB,KAAG,qBAqL1B,CAAC"}