@qoniai/qoni 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -4,18 +4,6 @@ declare function buildStringToSign(method: string, pathname: string, headers: He
 declare function buildSignature(secretKey: string, stringToSign: string): string;
 declare function buildAuthorization(accessKey: string, secretKey: string, stringToSign: string): string;
 
-/**
- * The interaction `type` discriminator — the single field a consumer
- * switches on to pick a card / typed handle.
- */
-declare const InteractionTypes: {
-    readonly SiteLogin: "site_login";
-    readonly Clarification: "clarification";
-    readonly Confirmation: "confirmation";
-    readonly TakeControl: "take_control";
-    readonly Wait: "wait";
-};
-type InteractionType = (typeof InteractionTypes)[keyof typeof InteractionTypes];
 /**
  * Interaction lifecycle status (backend-authoritative):
  * pending → active → resolved | expired | canceled.
@@ -172,8 +160,15 @@ interface DelegateTokenInteractiveInput extends DelegateTokenBaseInput {
     mode: "interactive";
     redirectUri: string;
     state: string;
+    /**
+     * @deprecated The authorization page identifies the signed-in user; the
+     * delegation service ignores a user sent with an interactive request.
+     */
     user?: UserRef;
-    /** Alternative to user.id; optional for interactive authorization. */
+    /**
+     * @deprecated The authorization page identifies the signed-in user; the
+     * delegation service ignores a user id sent with an interactive request.
+     */
     userId?: string;
 }
 type DelegateTokenInput = DelegateTokenSilentInput | DelegateTokenInteractiveInput;
@@ -197,6 +192,10 @@ interface DelegateTokenResponse {
     expiresIn: number;
     grantId: string;
     auditId: string;
+    /**
+     * @deprecated The delegation service does not return the granted scopes.
+     * Read them from `qoni.genauth.introspectDelegationToken({ token }).data.scope`.
+     */
     grantedScopes?: string[];
 }
 type DelegateTokenSilentResponse = DelegateTokenResponse & {
@@ -281,6 +280,29 @@ interface QoniTransport {
  * button/method only exists when the backend declared the action (structurally
  * closing off "dead recovery affordances").
  */
+/**
+ * The interaction types a consumer handles. DoAnything asks for the user in
+ * five abstract ways — by what the user has to do, never by business — plus
+ * the system `wait`:
+ *
+ * - `site_login`: sign in to a site in the live browser.
+ * - `take_control`: operate the browser by hand (captcha, 2FA, …).
+ * - `ask_user`: answer a question, shaped by `answerType` / `options`.
+ * - `confirmation`: allow or reject an action.
+ * - `wait`: the system is waiting (rate limit, external event); no decision.
+ *
+ * The wire may still say `clarification`; the SDK presents it as `ask_user`.
+ */
+declare const InteractionTypes: {
+    readonly SiteLogin: "site_login";
+    readonly TakeControl: "take_control";
+    readonly AskUser: "ask_user";
+    readonly Confirmation: "confirmation";
+    readonly Wait: "wait";
+    /** @deprecated `clarification` is presented as `ask_user`; use `InteractionTypes.AskUser`. */
+    readonly Clarification: "ask_user";
+};
+type InteractionType = "site_login" | "take_control" | "ask_user" | "confirmation" | "wait";
 /** A declared action a consumer can take on an interaction. */
 interface Action {
     /** What this action does — maps to a typed method on {@link InteractionHandle}. */
@@ -309,11 +331,26 @@ interface SiteLoginPayload {
     /** Set when the login is for a Track monitor (monitor.needs_login reuse). */
     monitorId?: string;
 }
-interface ClarificationPayload {
-    question: string;
-    /** Hint for how the answer should be collected (e.g. "text", "choice"). */
-    inputType?: string;
+/** How an `ask_user` answer is shaped; decides which control the app renders. */
+type AskUserAnswerType = "text" | "number" | "boolean" | "single_choice" | "multiple_choice";
+interface AskUserOption {
+    /** What `answer()` submits. */
+    value: string;
+    /** What the user sees. */
+    label: string;
 }
+interface AskUserPayload {
+    /** The question to show the user. */
+    question: string;
+    /** `text` → string, `number` → number, `boolean` → boolean, `single_choice` → one option value, `multiple_choice` → option values. */
+    answerType: AskUserAnswerType;
+    /** Candidates for `single_choice` / `multiple_choice`. */
+    options?: AskUserOption[];
+}
+/** An `ask_user` answer; its type follows the payload's `answerType`. */
+type AskUserAnswer = string | number | boolean | string[];
+/** @deprecated `clarification` is presented as `ask_user`; use {@link AskUserPayload}. */
+type ClarificationPayload = AskUserPayload;
 interface ConfirmationPayload {
     summary: string;
 }
@@ -332,21 +369,15 @@ interface WaitPayload {
 /** Maps each interaction `type` to its narrowed payload shape. */
 interface InteractionPayloadByType {
     site_login: SiteLoginPayload;
-    clarification: ClarificationPayload;
-    confirmation: ConfirmationPayload;
     take_control: TakeControlPayload;
+    ask_user: AskUserPayload;
+    confirmation: ConfirmationPayload;
     wait: WaitPayload;
 }
-/**
- * A typed interaction object. Generic over `type` so the `payload` narrows to
- * the matching shape; the bare `Interaction` (T = InteractionType) is the union
- * a consumer switches on.
- */
-interface Interaction<T extends InteractionType = InteractionType> {
+/** Fields every interaction carries, whatever its type. */
+interface InteractionBase {
     /** Stable identity across the interaction's lifecycle. */
     id: string;
-    /** The discriminator — the single field a consumer switches on. */
-    type: T;
     /** Backend-authoritative lifecycle status. */
     status: InteractionStatus;
     createdAt: string;
@@ -360,9 +391,20 @@ interface Interaction<T extends InteractionType = InteractionType> {
     evidence?: InteractionEvidence | null;
     /** Declared actions — drives the typed methods + UI buttons. */
     actions: Action[];
+}
+/**
+ * A typed interaction object, distributed over `type`: the bare `Interaction`
+ * is a union, so `switch (interaction.type)` narrows `payload` in each branch.
+ * `Interaction<"site_login">` picks one member.
+ */
+type Interaction<T extends InteractionType = InteractionType> = T extends InteractionType ? InteractionBase & {
+    /** The discriminator — the single field a consumer switches on. */
+    type: T;
     /** Type-specific fields. */
     payload: InteractionPayloadByType[T];
-}
+} : never;
+/** The interaction union `onInteraction` hands out; same as the bare {@link Interaction}. */
+type TypedInteraction = Interaction;
 /**
  * Posts an interaction action to its declared endpoint. The product namespace
  * supplies this (token + run addressing already bound); the handle below uses
@@ -392,9 +434,13 @@ interface OpenLoginResult {
     /** Unmodified response body (escape hatch — shape may evolve with the API). */
     raw: JsonObject;
     /**
+     * @deprecated {@link InteractionHandle.confirmSignedIn} saves the login
+     * itself; call it once the user has signed in, without `confirm()`.
+     *
      * Persist the login into the profile after the user signs in
      * (`POST /profiles/{profileId}/confirm`). Confirming ends this login
-     * session and closes its browser, whatever the outcome:
+     * session and closes its browser, except when the backend could not save
+     * it yet (`release_failed`, below):
      *
      * - `active: true` — the login is saved; call
      *   {@link InteractionHandle.confirmSignedIn}.
@@ -407,9 +453,13 @@ interface OpenLoginResult {
      *   already ended on providers that report it this way, or the profile no
      *   longer exists for this user. Handle it like `no_session`: call
      *   `confirmSignedIn()`, and the agent asks again if it is still signed out.
+     * - `active: false` with `probeResult: "release_failed"` — the backend kept
+     *   the session but could not save it yet; call `confirm()` again.
      * - `active: false` with any other `probeResult` — the user was not signed
      *   in. Start a new session with `openLogin({ siteId, profileId })` and show
      *   its new `liveUrl`; the old one no longer works.
+     * - Throws `QoniValidationError` when a newer `openLogin()` replaced this
+     *   backend session; confirm the newer result instead.
      *
      * Requires `QoniScopes.SITE_LOGIN_CONFIRM`.
      */
@@ -432,6 +482,44 @@ interface ConfirmLoginResult {
     /** Unmodified response body (escape hatch — shape may evolve with the API). */
     raw: JsonObject;
 }
+/** A login session `openLogin()` opened on one interaction. */
+interface LoginSession {
+    profileId: string;
+    siteId: string;
+    /** The backend's login session; reopening may return the same one. */
+    sessionId: string;
+    /** Latest `openLogin()` call on the interaction that returned it (1, 2, …). */
+    call: number;
+    /** A newer backend session took over: this one can no longer be saved. */
+    replaced?: boolean;
+    /** Saved and rechecked: nothing left to do for this session. */
+    completed?: boolean;
+    /** The save in flight or done; cleared when it fails so a retry saves again. */
+    save?: Promise<ConfirmLoginResult>;
+    /** `confirmSignedIn()` in flight or done: one save and one recheck per session. */
+    done?: Promise<void>;
+}
+/** Per interaction: how many `openLogin()` calls were made, and the session of the latest call that succeeded. */
+interface LoginSessionSlot {
+    calls: number;
+    /** `openLogin()` calls still waiting for the backend. */
+    inflight: number;
+    /** The interaction settled (resolved, expired or canceled): nothing will confirm this login any more. */
+    ended?: boolean;
+    session?: LoginSession;
+}
+/** Login sessions by interaction id, shared by the handles one RunHandle / MonitorHandle hands out. */
+type LoginSessionStore = Map<string, LoginSessionSlot>;
+/** A control session returned by `connectControl()` / `refreshControl()`. */
+interface ControlSession {
+    /** Signed URL of the browser the user now controls; show it only to that user. */
+    liveUrl: string;
+    /** When `liveUrl` stops working; call `refreshControl()` for a new one. */
+    expiresAt?: string;
+    status?: string;
+    /** Unmodified response body (escape hatch — shape may evolve with the API). */
+    raw: JsonObject;
+}
 /**
  * Typed wrapper over an {@link Interaction} that exposes one method per
  * action kind. Each method finds the matching declared action and posts to its
@@ -442,16 +530,28 @@ interface ConfirmLoginResult {
 declare class InteractionHandle<T extends InteractionType = InteractionType> {
     #private;
     private readonly post;
+    private readonly loginSessions;
     readonly interaction: Interaction<T>;
-    constructor(interaction: Interaction<T>, post: InteractionActionPoster);
+    /**
+     * @param loginSessions Login sessions opened on interactions, by interaction
+     *   id. A RunHandle / MonitorHandle shares one store across the handles it
+     *   hands out, so `confirmSignedIn()` finds the login `openLogin()` opened
+     *   even on the handle of a later event.
+     */
+    constructor(interaction: Interaction<T>, post: InteractionActionPoster, loginSessions?: LoginSessionStore);
     get id(): string;
     get type(): T;
     get status(): InteractionStatus;
     get actions(): Action[];
     /** Whether the backend declared an action of this kind on the interaction. */
     can(kind: ActionKind): boolean;
-    /** Answer a clarification ask. */
-    answer(text: string): Promise<void>;
+    /**
+     * Answer an `ask_user` question. The value follows `payload.answerType`:
+     * `text` → string, `number` → number, `boolean` → boolean, `single_choice` →
+     * one option `value`, `multiple_choice` → an array of option values. A value
+     * that does not fit throws `QoniValidationError` before anything is sent.
+     */
+    answer(value: AskUserAnswer): Promise<void>;
     /** Skip / dismiss the interaction (proceed without acting on it). */
     skip(): Promise<void>;
     /** Confirm a pending confirmation (approve the plan / destructive op). */
@@ -462,18 +562,29 @@ declare class InteractionHandle<T extends InteractionType = InteractionType> {
      * Start an interactive login session for a `site_login` interaction. The
      * backend needs the site to sign in to: pass `siteId`, or omit it when the
      * interaction lists exactly one site. Show `liveUrl` to the user; when they
-     * finish, call `confirm()` on the result to save the login, and act on its
-     * outcome (see {@link OpenLoginResult.confirm}) before {@link confirmSignedIn}.
+     * say they are signed in, call {@link confirmSignedIn}, which saves the login
+     * and lets the agent continue.
      * The delegation must include `QoniScopes.SITE_LOGIN_REQUEST` and
      * `QoniScopes.SITE_LOGIN_CONFIRM`; the AccessKey policy must allow both.
      */
     openLogin(options?: OpenLoginOptions): Promise<OpenLoginResult>;
-    /** Tell the agent the user has finished signing in. */
+    /**
+     * The user finished signing in through the live browser `openLogin()`
+     * opened. Saves that login (so later tasks reuse it), then tells the agent
+     * to recheck the site and continue. If the user is not signed in after all,
+     * the agent raises a new `site_login` interaction.
+     *
+     * Saving needs `QoniScopes.SITE_LOGIN_CONFIRM` on the delegation; without
+     * `openLogin()` on this interaction, only the recheck is sent.
+     */
     confirmSignedIn(): Promise<void>;
-    /** Connect to the live browser for a take_control interaction. */
-    connectControl(): Promise<void>;
-    /** Refresh the live control surface / live url. */
-    refreshControl(): Promise<void>;
+    /**
+     * Take over the live browser for a take_control interaction. Resolves to the
+     * signed control URL to show the user (`liveUrl`) and when it expires.
+     */
+    connectControl(): Promise<ControlSession>;
+    /** Get a fresh control URL when the current one expired. */
+    refreshControl(): Promise<ControlSession>;
     /** Hand control back to the agent. */
     releaseControl(): Promise<void>;
     /** Retry a wait interaction now. */
@@ -779,7 +890,10 @@ declare class RunHandle<E extends RunEvent = RunEvent> {
      * Wrap an {@link Interaction} (from `event.data` of an `interaction` event)
      * in a typed {@link InteractionHandle} bound to this run. The handle's action
      * methods (`answer` / `confirmSignedIn` / `releaseControl` / …) post to the
-     * endpoint the backend declared for that action.
+     * endpoint the backend declared for that action. Handles this RunHandle
+     * hands out share the login sessions `openLogin()` opens, so
+     * `confirmSignedIn()` on the handle of a later event still saves that login.
+     * A RunHandle from another `attach()` (or process) does not see them.
      */
     interactionHandle(interaction: Interaction): InteractionHandle;
     /**
@@ -1215,6 +1329,7 @@ interface MonitorWireOps {
  * token or an id.
  */
 declare class MonitorHandle {
+    #private;
     private readonly ops;
     readonly id: string;
     constructor(ops: MonitorWireOps, id: string);
@@ -1247,7 +1362,8 @@ declare class MonitorHandle {
      * Wrap an {@link Interaction} (from `event.data` of an `interaction` event on
      * the monitor stream — e.g. a `site_login` to unlock a `needs_reauth` park)
      * in a typed {@link InteractionHandle}. The handle's action methods post to
-     * the endpoint the backend declared for that action.
+     * the endpoint the backend declared for that action. Handles of one
+     * MonitorHandle share the login sessions `openLogin()` opens.
      */
     interactionHandle(interaction: Interaction): InteractionHandle;
     /**
@@ -1479,6 +1595,11 @@ declare const QoniScopes: {
     readonly TRACK_MANAGE: "webagent.track:manage";
     readonly SITE_LOGIN_REQUEST: "webagent.site_login:request";
     readonly SITE_LOGIN_CONFIRM: "webagent.site_login:confirm";
+    readonly USER_PROFILE_READ: "user.profile:read";
+    readonly USER_PROFILE_WRITE: "user.profile:write";
+    readonly USER_PAYMENT_USE: "user.payment:use";
+    readonly AGENT_MAIL_READ: "agent.mail:read";
+    readonly AGENT_MAIL_SEND: "agent.mail:send";
 };
 type QoniScope = (typeof QoniScopes)[keyof typeof QoniScopes];
 /** Product names accepted by `delegateToken({ products })`. */
@@ -1498,4 +1619,4 @@ declare const QoniScopeBundles: {
     readonly TRACK: readonly ["webagent.track:read", "webagent.track:manage"];
 };
 
-export { type Action, type ActionKind, ActionKinds, type Artifact, type BrowserProxyOptions, type BrowserbaseRegion, type CaptureOptions, type ClarificationPayload, type CompleteDelegateAgentInput, type CompleteDelegateTokenInput, type ConfirmLoginOptions, type ConfirmLoginResult, type ConfirmationPayload, type CoreRunEvent, type DeepResearchAttachOptions, type DeepResearchEvent, type DeepResearchRunOptions, type DelegateAgentInput, type DelegateAgentResponse, type DelegateAgentTokenResponse, type DelegateTokenInput, type DelegateTokenInteractiveInput, type DelegateTokenResponse, type DelegateTokenResult, type DelegateTokenSilentInput, type DelegateTokenSilentResponse, type DelegationMode, type DelegationTokenResponse, type DoAnythingAttachOptions, type DoAnythingEvent, type DoAnythingRunOptions, type DoAnythingSnapshot, type GenAuthAccessTokenInput, type GenAuthAdminToken, type GenAuthAdminTokenOverrideInput, type GenAuthDelegationIntrospectionInput, type GenAuthUserCreateBatchInput, type GenAuthUserCreateInput, type GenAuthUserDeleteBatchInput, type GenAuthUserGetBatchInput, type GenAuthUserGetInput, type GenAuthUserListInput, type GenAuthUserUpdateInput, type Interaction, type InteractionEvidence, InteractionHandle, type InteractionPayloadByType, type InteractionSite, type InteractionStatus, InteractionStatuses, type InteractionType, InteractionTypes, type InteractiveDelegationResponse, type JsonObject, type MonitorEvent, type MonitorEventsOptions, MonitorHandle, type MonitorRunsOptions, type OpenLoginOptions, type OpenLoginResult, Qoni, QoniAuthError, QoniDelegationRequiredError, QoniError, type QoniErrorCode, type QoniErrorOptions, type QoniEvent, type QoniEventType, QoniEventTypes, type QoniMeta, type QoniOptions, QoniPermissionDeniedError, type QoniProduct, type QoniProductName, QoniProductScopes, QoniRateLimitError, type QoniResponse, type QoniRuntimeConfig, type QoniSSEEvent, QoniScopeBundles, QoniScopes, QoniTimeoutError, QoniTokenExpiredError, QoniUpstreamError, QoniValidationError, type RawRequestInput, type RunBrowserLiveUrlChangedData, type RunDoneData, type RunEvent, type RunEventsOptions, RunHandle, type RunImage, type RunLimits, type RunMessageData, type RunReconnectInfo, type RunResult, type RunScreenshotData, type RunStatus, type RunWaitOptions, type RuntimeTokenInput, type SessionRef, type SiteLoginPayload, type SnapshotAction, type SnapshotImage, type TakeControlPayload, type TokenInput, type TrackAttachOptions, type TrackCreateOptions, type WaitKind, type WaitPayload, type WebSearchAttachOptions, type WebSearchEvent, type WebSearchRunOptions, buildAuthorization, buildSignature, buildStringToSign };
+export { type Action, type ActionKind, ActionKinds, type Artifact, type AskUserAnswer, type AskUserAnswerType, type AskUserOption, type AskUserPayload, type BrowserProxyOptions, type BrowserbaseRegion, type CaptureOptions, type ClarificationPayload, type CompleteDelegateAgentInput, type CompleteDelegateTokenInput, type ConfirmLoginOptions, type ConfirmLoginResult, type ConfirmationPayload, type ControlSession, type CoreRunEvent, type DeepResearchAttachOptions, type DeepResearchEvent, type DeepResearchRunOptions, type DelegateAgentInput, type DelegateAgentResponse, type DelegateAgentTokenResponse, type DelegateTokenInput, type DelegateTokenInteractiveInput, type DelegateTokenResponse, type DelegateTokenResult, type DelegateTokenSilentInput, type DelegateTokenSilentResponse, type DelegationMode, type DelegationTokenResponse, type DoAnythingAttachOptions, type DoAnythingEvent, type DoAnythingRunOptions, type DoAnythingSnapshot, type GenAuthAccessTokenInput, type GenAuthAdminToken, type GenAuthAdminTokenOverrideInput, type GenAuthDelegationIntrospectionInput, type GenAuthUserCreateBatchInput, type GenAuthUserCreateInput, type GenAuthUserDeleteBatchInput, type GenAuthUserGetBatchInput, type GenAuthUserGetInput, type GenAuthUserListInput, type GenAuthUserUpdateInput, type Interaction, type InteractionBase, type InteractionEvidence, InteractionHandle, type InteractionPayloadByType, type InteractionSite, type InteractionStatus, InteractionStatuses, type InteractionType, InteractionTypes, type InteractiveDelegationResponse, type JsonObject, type MonitorEvent, type MonitorEventsOptions, MonitorHandle, type MonitorRunsOptions, type OpenLoginOptions, type OpenLoginResult, Qoni, QoniAuthError, QoniDelegationRequiredError, QoniError, type QoniErrorCode, type QoniErrorOptions, type QoniEvent, type QoniEventType, QoniEventTypes, type QoniMeta, type QoniOptions, QoniPermissionDeniedError, type QoniProduct, type QoniProductName, QoniProductScopes, QoniRateLimitError, type QoniResponse, type QoniRuntimeConfig, type QoniSSEEvent, QoniScopeBundles, QoniScopes, QoniTimeoutError, QoniTokenExpiredError, QoniUpstreamError, QoniValidationError, type RawRequestInput, type RunBrowserLiveUrlChangedData, type RunDoneData, type RunEvent, type RunEventsOptions, RunHandle, type RunImage, type RunLimits, type RunMessageData, type RunReconnectInfo, type RunResult, type RunScreenshotData, type RunStatus, type RunWaitOptions, type RuntimeTokenInput, type SessionRef, type SiteLoginPayload, type SnapshotAction, type SnapshotImage, type TakeControlPayload, type TokenInput, type TrackAttachOptions, type TrackCreateOptions, type TypedInteraction, type WaitKind, type WaitPayload, type WebSearchAttachOptions, type WebSearchEvent, type WebSearchRunOptions, buildAuthorization, buildSignature, buildStringToSign };