@incodetech/core 2.4.1-agentic.2 → 2.4.1-agentic.3

package/dist/step-up.d.ts

@@ -0,0 +1,387 @@
+import { t as Manager } from "./Manager-C9T5amUN.js";
+import "./Actor-DpTj5PFb.js";
+import { n as FinishStatus } from "./flowCompletionService-BlAHsKyv.js";
+//#region src/modules/step-up/types.d.ts
+/**
+ * One scope the agent class asks for, as shown on the permissions screen.
+ */
+type StepUpScope = {
+  /** Machine name sent back in `approvedScopes`, e.g. `tx.read`. */
+  name: string;
+  /** Human label, e.g. `Read transactions`. Falls back to `name`. */
+  displayName: string;
+  description?: string;
+  /**
+   * Whether the permissions screen starts with this scope ticked (contract
+   * v0.5). Incode sets it from the agent class: the scope that triggered the
+   * step-up and `auto-select` scopes are ticked, `dynamic-select` ones only
+   * when suggested; missing means unticked.
+   */
+  autoSelect?: boolean;
+  /**
+   * `auto-select`: always part of the approval, so the screen shows it ticked
+   * and locked. `dynamic-select`: the person may untick it. Missing reads as
+   * `dynamic-select`.
+   */
+  selectionMode?: 'auto-select' | 'dynamic-select';
+};
+/**
+ * The permissions block of a step-up, exactly as the Decision API start
+ * response returns it (contract v0.2 §6.1: camelCase everywhere).
+ */
+type StepUpPermissions = {
+  agentClassId?: string;
+  purpose?: string;
+  scopes: StepUpScope[];
+  /** Limits keyed by scope name; only scopes that have one are listed. */
+  limits?: Record<string, StepUpLimit>;
+  /**
+   * How long the approval lasts, in seconds. The Decision API omits it when it
+   * has none; the permissions screen then shows no duration.
+   */
+  durationSeconds?: number;
+};
+/** The agent class's limit on one scope. Amounts carry no currency. */
+type StepUpLimit = {
+  budgetLimit?: number;
+  usageLimit?: number;
+  /** What one use is called, e.g. `reads`. */
+  usageLimitLabel?: string;
+};
+/** When the SDK's permissions screen shows, relative to the face check. */
+type StepUpPermissionsOrder = 'afterFaceCheck' | 'beforeFaceCheck';
+/**
+ * The Decision API's step-up modes: `embedded` runs the workflow in this page,
+ * `hosted` frames Incode's hosted page at `onboardingUrl`.
+ */
+type StepUpMode = 'embedded' | 'hosted';
+type StepUpPermissionsUi = 'sdk' | 'none';
+/**
+ * What `onFinish` receives. A hint only: the bank server's status read
+ * (`GET /step-ups/{id}`) is what checks the face check and activates the
+ * mandate.
+ */
+type StepUpResult = {
+  stepUpId: string;
+  approvedScopes: string[];
+};
+/**
+ * Error codes on {@link StepUpError.code} (contract v0.2 §6.3). Public API:
+ * hosts branch on them.
+ *
+ * - `INVALID_OPTIONS` — `renderStepUp` was called with bad options (thrown).
+ * - `USER_DENIED` — the user pressed Deny on the permissions screen.
+ * - `FACE_CHECK_FAILED` — the face check ran and failed: the workflow finished
+ *   `rejected` or with score `FAIL` / `MANUAL_FAIL`, or the hosted page
+ *   reported `FACE_CHECK_FAILED`.
+ * - `VERIFICATION_PENDING` — the workflow ended without a result yet (async
+ *   resolution, e.g. manual review), or the hosted page reported
+ *   `VERIFICATION_PENDING`. The bank server's status read answers `pending`
+ *   until Incode decides.
+ * - `VERIFICATION_ERROR` — the verification could not finish: network,
+ *   expired token, camera denied, any other workflow or hosted-page error, a
+ *   hosted result that approved none of the agent class's scopes, a hosted
+ *   page that never sent `ready` (`detail.code` `READY_TIMEOUT`), or an
+ *   `onPermissionsApproved` that rejected (`detail.code`
+ *   `PERMISSIONS_NOT_SAVED`).
+ *   {@link StepUpError.detail} carries the original code and message.
+ * - `IFRAME_ORIGIN_MISMATCH` — the step-up iframe posted from an origin other
+ *   than `onboardingUrl`'s (for example it was redirected elsewhere).
+ */
+type StepUpErrorCode = 'INVALID_OPTIONS' | 'USER_DENIED' | 'FACE_CHECK_FAILED' | 'VERIFICATION_PENDING' | 'VERIFICATION_ERROR' | 'IFRAME_ORIGIN_MISMATCH';
+/** The codes the verification step (workflow or hosted page) can end with. */
+type StepUpVerificationErrorCode = Extract<StepUpErrorCode, 'FACE_CHECK_FAILED' | 'VERIFICATION_PENDING' | 'VERIFICATION_ERROR'>;
+/**
+ * What the workflow or hosted page reported underneath a step-up error, as
+ * given (for logs and support; not stable API).
+ */
+type StepUpErrorDetail = {
+  /** E.g. a workflow module error code, an HTTP status, or a hosted code. */
+  code?: string;
+  message?: string;
+};
+/** Options validated by core. The DOM container is checked by the UI layer. */
+type StepUpOptionsInput = {
+  stepUpId: string;
+  sessionToken: string;
+  interviewId?: string;
+  permissions: StepUpPermissions;
+  mode?: StepUpMode;
+  onboardingUrl?: string;
+  permissionsUi?: StepUpPermissionsUi;
+  /**
+   * Embedded mode: show the permissions screen before the face check
+   * (default) or after it. Ignored with `permissionsUi: 'none'`.
+   *
+   * `'afterFaceCheck'` with `onPermissionsApproved` needs Incode to accept the
+   * scope choice after the face check, which it does not yet: the bank gets
+   * 409 `STEP_UP_NOT_PENDING`, so the step-up ends with `VERIFICATION_ERROR`
+   * (`detail.code` `PERMISSIONS_NOT_SAVED`).
+   */
+  permissionsOrder?: StepUpPermissionsOrder;
+  /**
+   * Embedded mode: called when the person approves, with the scopes they kept.
+   * The step-up waits for the returned promise, then runs the face check (or
+   * finishes, after it). Use it to record the choice on the bank server
+   * before the interview finishes. A rejection ends the step-up with
+   * `VERIFICATION_ERROR`, `detail.code` `PERMISSIONS_NOT_SAVED`.
+   */
+  onPermissionsApproved?: (result: StepUpResult) => void | Promise<unknown>;
+  /**
+   * Hosted mode: how long to wait for the hosted page's `ready` before
+   * failing with `VERIFICATION_ERROR` (`detail.code` `READY_TIMEOUT`).
+   * Default 15000.
+   */
+  readyTimeoutMs?: number;
+  /** Default language, as `<incode-workflow lang>`. Embedded mode. */
+  lang?: string;
+  /** Skips the tenant's dashboard theme, as on `<incode-workflow>`. Embedded mode. */
+  disableDashboardTheme?: boolean;
+  onFinish: (result: StepUpResult) => void;
+  onError?: (error: Error) => void;
+};
+/** Options after validation: defaults filled in, permissions normalized. */
+type NormalizedStepUpOptions = {
+  stepUpId: string;
+  sessionToken: string;
+  interviewId?: string;
+  permissions: StepUpPermissions;
+  mode: StepUpMode;
+  onboardingUrl?: string;
+  /** Exact origin of `onboardingUrl` (hosted mode only). */
+  onboardingOrigin?: string;
+  permissionsUi: StepUpPermissionsUi;
+  permissionsOrder: StepUpPermissionsOrder;
+  readyTimeoutMs: number;
+  lang?: string;
+  disableDashboardTheme: boolean;
+  onPermissionsApproved?: (result: StepUpResult) => void | Promise<unknown>;
+  onFinish: (result: StepUpResult) => void;
+  onError?: (error: Error) => void;
+};
+/** Duration in the largest whole unit, for the i18n layer to phrase. */
+type StepUpDuration = {
+  unit: 'days' | 'hours' | 'minutes' | 'seconds';
+  count: number;
+};
+/** What a message from the hosted onboarding page means to the step-up. */
+type HostedPageMessage = {
+  kind: 'ready';
+} | {
+  kind: 'finished';
+  approvedScopes: string[];
+} | {
+  kind: 'error';
+  code: string;
+  message?: string;
+} | {
+  kind: 'originMismatch';
+} | {
+  kind: 'ignored';
+};
+//#endregion
+//#region src/modules/step-up/stepUpStateMachine.d.ts
+type StepUpInput = {
+  stepUpId: string;
+  permissions: StepUpPermissions;
+  permissionsUi: StepUpPermissionsUi;
+  permissionsOrder: StepUpPermissionsOrder;
+  /** The host saves the approved scopes before the step-up goes on. */
+  hostSavesPermissions: boolean;
+};
+//#endregion
+//#region src/modules/step-up/stepUpActor.d.ts
+type CreateStepUpActorOptions = StepUpInput;
+//#endregion
+//#region src/modules/step-up/stepUpManager.d.ts
+type StepUpVerifyingState = {
+  status: 'verifying';
+};
+type StepUpPermissionsState = {
+  status: 'permissions';
+  purpose?: string;
+  /** `locked`: an `auto-select` scope, always approved and not toggleable. */
+  scopes: Array<StepUpScope & {
+    checked: boolean;
+    locked: boolean;
+    limit?: StepUpLimit;
+  }>;
+  /** Missing when the step-up has no `durationSeconds`. */
+  duration?: StepUpDuration;
+  /** False when no scope is checked: Approve needs at least one. */
+  canApprove: boolean;
+  /** Approved; the host is saving the choice before the step-up goes on. */
+  saving: boolean;
+};
+type StepUpFinishedState = {
+  status: 'finished';
+  result: StepUpResult;
+};
+type StepUpClosedState = {
+  status: 'closed';
+};
+type StepUpErrorState = {
+  status: 'error';
+  /** The `StepUpError` code to report. */
+  code: StepUpVerificationErrorCode;
+  error: string;
+  detail?: StepUpErrorDetail;
+};
+/** The parts of the workflow's `FinishStatus` the step-up reads. */
+type StepUpWorkflowResult = Pick<FinishStatus, 'action' | 'scoreStatus'>;
+/**
+ * What the workflow's `onFinish` result means for the step-up:
+ * - `failed` — `action: 'rejected'`, or score `FAIL` / `MANUAL_FAIL`.
+ * - `pending` — no result (the workflow went to async resolution).
+ * - `passed` — anything else, `WARN` and `UNKNOWN` included. That is only a
+ *   UI hint: Incode passes the face check only on `OK` / `MANUAL_OK`, so
+ *   `onFinish` is never an approval.
+ */
+declare function readWorkflowResult(result: StepUpWorkflowResult | undefined): 'passed' | 'failed' | 'pending';
+type StepUpState = StepUpVerifyingState | StepUpPermissionsState | StepUpFinishedState | StepUpClosedState | StepUpErrorState;
+type CreateStepUpManagerOptions = {
+  stepUpId: string;
+  permissions: StepUpPermissions;
+  permissionsUi?: CreateStepUpActorOptions['permissionsUi'];
+  permissionsOrder?: CreateStepUpActorOptions['permissionsOrder'];
+  /** Approve waits for `permissionsSaved()` before going on. */
+  hostSavesPermissions?: boolean;
+};
+/**
+ * Creates the step-up manager. Pass permissions already normalized by
+ * `validateStepUpOptions` / `normalizeStepUpPermissions`.
+ */
+declare function createStepUpManager(options: CreateStepUpManagerOptions): Manager<StepUpState> & {
+  /** Verification passed: show the permissions (or finish, `'none'`). */
+  verificationFinished(): void;
+  /**
+   * The workflow's `onFinish`, with its result. A failed face check goes to
+   * `error` (`FACE_CHECK_FAILED`) and no result to `error`
+   * (`VERIFICATION_PENDING`); neither shows the permissions.
+   */
+  workflowFinished(result?: StepUpWorkflowResult): void;
+  /**
+   * The workflow or hosted page ended without a passed check. `code`
+   * defaults to `VERIFICATION_ERROR` (could not finish); pass
+   * `FACE_CHECK_FAILED` only for a check that ran and failed.
+   */
+  verificationFailed(error: string, code?: StepUpVerificationErrorCode, detail?: StepUpErrorDetail): void;
+  /** Hosted mode: the hosted page finished, with the scopes it approved. */
+  hostedFinished(approvedScopes: string[]): void;
+  /** Hosted mode: the user denied on the hosted page. */
+  hostedDenied(): void;
+  toggleScope(name: string): void;
+  /** Ignored while no scope is checked. */
+  approve(): void;
+  deny(): void;
+  /** The host saved the approved scopes: go on to the face check or finish. */
+  permissionsSaved(): void;
+  /** The host could not save them: the step-up ends in error. */
+  permissionsSaveFailed(error: string): void;
+};
+type StepUpManager = ReturnType<typeof createStepUpManager>;
+//#endregion
+//#region src/modules/step-up/stepUpError.d.ts
+/**
+ * Error passed to the step-up `onError` callback (and thrown for invalid
+ * options). `code` is stable; `message` is for developers, not end users.
+ * `detail` is what the workflow or hosted page reported underneath (set for
+ * `VERIFICATION_ERROR`, and for `FACE_CHECK_FAILED` from the workflow).
+ */
+declare class StepUpError extends Error {
+  readonly code: StepUpErrorCode;
+  readonly stepUpId?: string;
+  readonly detail?: StepUpErrorDetail;
+  constructor(code: StepUpErrorCode, message: string, stepUpId?: string, detail?: StepUpErrorDetail);
+}
+declare function isStepUpError(error: unknown): error is StepUpError;
+//#endregion
+//#region src/modules/step-up/stepUpOptions.d.ts
+/**
+ * Checks the permissions block from the start response and fills in
+ * `displayName` (falls back to the scope name). Keeps each scope's boolean
+ * `autoSelect` and known `selectionMode`, and the valid limits of known
+ * scopes. A missing or `null` `durationSeconds` is left out. Throws
+ * `INVALID_OPTIONS` when a required field is missing, or `durationSeconds` is
+ * given but not a positive number.
+ */
+declare function normalizeStepUpPermissions(raw: unknown): StepUpPermissions;
+/**
+ * Exact origin (`scheme://host[:port]`) of an absolute http(s) URL, or
+ * `undefined` when the URL is not one.
+ */
+declare function getUrlOrigin(url: string): string | undefined;
+/**
+ * Validates the `renderStepUp` options (everything except the DOM container,
+ * which the UI layer checks) and fills in defaults:
+ * `mode: 'embedded'`, `permissionsUi: 'sdk'`,
+ * `permissionsOrder: 'beforeFaceCheck'` (`'afterFaceCheck'` in hosted mode),
+ * `readyTimeoutMs: DEFAULT_STEP_UP_READY_TIMEOUT_MS` (15 s),
+ * `disableDashboardTheme: false`.
+ *
+ * Throws {@link StepUpError} with code `INVALID_OPTIONS`.
+ */
+declare function validateStepUpOptions(raw: unknown): NormalizedStepUpOptions;
+/**
+ * Picks the largest unit that divides the duration exactly, so
+ * 36000 s → 10 hours, 5400 s → 90 minutes. A duration that is not a whole
+ * number of minutes is rounded up to minutes (never shown shorter than it is),
+ * and anything under a minute stays in seconds. No duration gives `undefined`.
+ */
+declare function describeStepUpDuration(durationSeconds: number | undefined): StepUpDuration | undefined;
+//#endregion
+//#region src/modules/step-up/stepUpHostedMessage.d.ts
+/**
+ * Tag on every step-up `postMessage`, both directions. Matches the local
+ * step-up mock's hosted page (contract P4.7 §6.6 reference implementation).
+ */
+declare const STEP_UP_MESSAGE_SOURCE = "incode-step-up";
+/**
+ * The parts of a browser `MessageEvent` the check needs. Kept structural so
+ * core never touches DOM types.
+ */
+type HostedMessageEventLike = {
+  origin: string;
+  data: unknown;
+};
+/**
+ * True only when the message came from exactly `expectedOrigin`
+ * (scheme, host and port). No suffix or prefix matching:
+ * `https://onboarding.incode.com.evil.com` does not match
+ * `https://onboarding.incode.com`.
+ */
+declare function isTrustedHostedOrigin(origin: string, expectedOrigin: string): boolean;
+/**
+ * Reads a `postMessage` from the hosted step-up page.
+ *
+ * Pass only messages whose `source` is the step-up iframe's own window. The
+ * page tags messages `{ source: 'incode-step-up', type, ... }`:
+ * - `ready` — loaded; the parent answers with {@link createStepUpInitMessage}.
+ * - `finish` — `{ stepUpId, approvedScopes }`; the hosted page ran the face
+ *   check and its own permissions screen. Read only when `stepUpId` is
+ *   exactly `expectedStepUpId`; otherwise (missing or another step-up's)
+ *   it is ignored, not relayed.
+ * - `error` — `{ code, message? }`, e.g. `USER_DENIED` or
+ *   `FACE_CHECK_FAILED`. Ignored when it names another `stepUpId`.
+ *
+ * A tagged message from another origin returns `originMismatch` (the frame
+ * left the onboarding origin, for example after a redirect). Untagged
+ * messages are ignored.
+ */
+declare function readHostedPageMessage(event: HostedMessageEventLike, expectedOrigin: string, expectedStepUpId: string): HostedPageMessage;
+/** Message the parent posts to the hosted page after its `ready`. */
+type StepUpInitMessage = {
+  source: typeof STEP_UP_MESSAGE_SOURCE;
+  type: 'init';
+  permissions: StepUpPermissions;
+  parentOrigin: string;
+};
+/**
+ * Builds the `init` message that hands the hosted page the permissions and
+ * the parent's origin (contract v0.2 §6.6; the page checks `parentOrigin`
+ * against its `returnOrigin`). The caller posts it with `targetOrigin` set to
+ * the exact onboarding origin, never `'*'`.
+ */
+declare function createStepUpInitMessage(permissions: StepUpPermissions, parentOrigin: string): StepUpInitMessage;
+//#endregion
+export { type CreateStepUpManagerOptions, type HostedMessageEventLike, type HostedPageMessage, type NormalizedStepUpOptions, STEP_UP_MESSAGE_SOURCE, type StepUpClosedState, type StepUpDuration, StepUpError, type StepUpErrorCode, type StepUpErrorDetail, type StepUpErrorState, type StepUpFinishedState, type StepUpInitMessage, type StepUpLimit, type StepUpManager, type StepUpMode, type StepUpOptionsInput, type StepUpPermissions, type StepUpPermissionsOrder, type StepUpPermissionsState, type StepUpPermissionsUi, type StepUpResult, type StepUpScope, type StepUpState, type StepUpVerificationErrorCode, type StepUpVerifyingState, type StepUpWorkflowResult, createStepUpInitMessage, createStepUpManager, describeStepUpDuration, getUrlOrigin, isStepUpError, isTrustedHostedOrigin, normalizeStepUpPermissions, readHostedPageMessage, readWorkflowResult, validateStepUpOptions };