@agent-cards/sdk 0.20.0

package/dist/voice-types.js

@@ -0,0 +1,16 @@
+export class AgentcardError extends Error {
+    code;
+    status;
+    details;
+    constructor(
+    /** The API's error code (`invalid_return_url`, `action_unavailable`, `voice_not_enrolled`, `slow_down`, `invalid_grant`), or the client's own (`unreachable`, `connect_timeout`, `oauth_failed`, `state_mismatch`). */
+    code, message, status, 
+    /** The rest of the API's error envelope: `slow_down` carries `interval`, `grant_requires_exchange` carries `request_id`. */
+    details = {}) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = 'AgentcardError';
+    }
+}

package/dist/voice.d.ts

@@ -0,0 +1,365 @@
+/**
+ * The voice module of the SDK: `agentcard.voice.*`. One client, one pair of
+ * credentials, one token for the paused request and the voice approval. It
+ * connects a person to your product once (the connect link, its exchange, a
+ * returning person, a revocation), creates the purchase, asks for the key
+ * word, streams or receives the answer, and reads results.
+ *
+ * One base URL. Test and live are decided by the credentials, never by host.
+ * The phone half is its own package, `@agent-cards/voice`: it ships to phones
+ * and holds no secret.
+ */
+import type { PausedRequest } from './client.js';
+import { ApiModule, type ApiTransport } from './api-module.js';
+import { type StreamFormat, type StreamHandle, type ChannelKind } from './voice-stream.generated.js';
+import { type PkceCrypto } from './voice-pkce.js';
+import type { Language, LanguageInfo } from './languages.js';
+import { type Action, type ActionState, type AppVoiceKeyDescription, type ApprovalPosture, type Authorization, type AuthorizationResult, type Cancelled, type CancelReason, type Connected, type ConnectInput, type ConnectResult, type CreateAuthorizationInput, type Done, type Exchanged, type ExchangeInput, type HostApprovalBundle, type Person, type Proposed, type RegisteredAppVoiceKey, type RevokedAppVoiceKey, type Revoked, type SessionState, type VaultSessionStep, type VoiceChallenge, type VoiceResetInput } from './voice-types.js';
+export { stripePaymentIntentConfirm, type MintedIntent } from './requests.js';
+/**
+ * The voice half of the client's options: named once, per business, when the
+ * product approves purchases by voice. A client built without it is a
+ * checkout client; every `voice.*` verb on it throws `missing_approval_posture`.
+ */
+export interface VoiceOptions {
+    /**
+     * Required: how this product approves purchases. One choice per business,
+     * not per purchase. `'sheet'`: the person approves on Agentcard's page with
+     * a credential Agentcard verifies. `'in_app'`: hold-to-talk in your app,
+     * judged on the phone and by Agentcard, signed by a key in your app.
+     * Sandbox and live behave the same. No default.
+     */
+    approval: ApprovalPosture;
+    /** Where the Vault sends the person back when a call names no `return_url` of its own. Exactly one of your registered links. */
+    returnUrl?: string;
+    /**
+     * The verifier's address for the streaming door when your server pushes the
+     * audio itself (`wss://…`). A call may name `stream_url` instead, and a
+     * challenge minted by an API that names `verifier_url` needs neither.
+     */
+    verifierUrl?: string;
+    /** Deadline for the await calls; the poll spacing is the client's `pollIntervalMs`. Default 60 s. */
+    pollTimeoutMs?: number;
+    /** Test seam: the retry pauses. */
+    backoffMs?: readonly number[];
+    /**
+     * The pause between two polls. An app may pass one that also wakes when it
+     * returns to the foreground, so the answer does not wait for the next tick.
+     */
+    wait?: (ms: number) => Promise<void>;
+    /**
+     * Where the grant's random bytes and SHA-256 come from when the runtime has
+     * no WebCrypto (a phone runtime running this module). Node, browsers and
+     * workers need nothing here.
+     */
+    pkce?: PkceCrypto;
+}
+/** @deprecated The transport every module shares is `ApiTransport`; this name stays for one release. */
+export type VoiceTransport = ApiTransport & {
+    options: VoiceOptions | undefined;
+};
+export declare const GRANT_REQUIRES_EXCHANGE_MESSAGE = "This session is an authorization grant: its result is not read by polling. Hand the return link to voice.completeConnect(url), or its code and state to voice.exchange({ code, state, session_id }).";
+export declare function stepOf(v: unknown): VaultSessionStep | null;
+export declare function reasonOf(v: unknown): string | null;
+/** The business's words for withdrawing a purchase (`authorizations.cancel`); anything else is refused before any call. */
+export declare const CANCEL_REASONS: readonly CancelReason[];
+/**
+ * The origin a paused request pays from, when its `origin` header is one Agentcard admits as `checkout_origin`
+ * (an exact https origin, or http://localhost for a local run); null otherwise. The Stripe request builders
+ * set that header, so a create that names no `checkout_origin` still carries the app's.
+ */
+export declare function checkoutOriginOf(request: PausedRequest): string | null;
+export declare const MISSING_APPROVAL_POSTURE_MESSAGE = "Name how your product approves purchases: voice: { approval: 'sheet' } (the person approves on Agentcard's page with a credential Agentcard verifies) or voice: { approval: 'in_app' } (hold-to-talk in your app, judged on the phone and by Agentcard, signed by a key in your app). There is no default.";
+/**
+ * The posture as named. Throws `missing_approval_posture` when `voice` was
+ * given without a valid posture, or, with `required`, when it was not given.
+ */
+export declare function approvalPostureOf(options: VoiceOptions | undefined, required: boolean): ApprovalPosture | undefined;
+export { streamAddress } from './voice-stream.generated.js';
+/**
+ * The sandbox request: a first run's purchase, naming no processor. Under a
+ * sandbox client `voice.authorizations.create({ request: 'sandbox' })` sends
+ * this; the sandbox completes it without reaching any processor. A live
+ * client refuses it before any call (`sandbox_request_in_live`).
+ */
+export declare const SANDBOX_REQUEST: PausedRequest;
+/** The sealed bundle for the host, from a typed challenge; refuses one the frame cannot sign for. */
+export declare function bundleOf(ch: VoiceChallenge): HostApprovalBundle;
+/** `agentcard.voice`: constructed by the client, never on its own. */
+export declare class VoiceModule extends ApiModule {
+    private readonly options;
+    private readonly clientIsSandbox;
+    /** The approval posture the client was constructed with, one per business; `undefined` when the client named none, and then every verb throws `missing_approval_posture`. */
+    readonly approval: ApprovalPosture | undefined;
+    /** The grants this client minted, by session id: the verifier and the state, then the exchanged result. Memory only. */
+    private readonly grants;
+    /** Session id by minted `state`, so a return link finds its grant without naming the session. */
+    private readonly grantsByState;
+    constructor(t: ApiTransport, options: VoiceOptions | undefined, clientIsSandbox: () => boolean);
+    private posture;
+    /** Where the Vault sends the person back when a call names nothing, as the client was constructed. */
+    get returnUrl(): string | undefined;
+    /**
+     * The languages Agentcard speaks, as the API lists them (`{ tag, name }`),
+     * read once and kept for ten minutes. Every call that names a `lang` checks
+     * it against this list first and refuses one not on it with
+     * `unsupported_language` before anything is sent. `null` on an API that
+     * does not serve the list yet; tags then travel unchecked.
+     */
+    languages(): Promise<LanguageInfo[] | null>;
+    private remember;
+    private forget;
+    /**
+     * Mints the connect link. The person signs in, stores a card if none, sets
+     * up their voice if the app requires it, and comes back. Open `url` in the
+     * in-app sheet. The link is an OAuth authorization grant: the client mints
+     * `state` and a PKCE challenge, keeps the verifier, and the return link
+     * comes back as `yourapp://connected?code=…&state=…`; hand it to
+     * `completeConnect(url)`, once, within 60 seconds. With no return link there
+     * is nothing to carry the code, so the mint polls (`grant: 'poll'`, then
+     * `awaitConnected`); `pkce: false` asks for that shape outright (deprecated).
+     * A grant asks for the terms it names in `authorization_details`, and for
+     * all three when it names none; the terms are enforced from then on. The
+     * result carries the client's approval posture as `approval`, for the app.
+     */
+    connect(input?: ConnectInput): Promise<ConnectResult>;
+    /**
+     * The grant's exchange: the `code` from the return link, under this client's
+     * credentials, with the verifier the client kept for the session. Answers
+     * once, within 60 seconds of the link. A `state` that is not the one minted
+     * for the session is refused here, before any call (`state_mismatch`). When
+     * another instance minted the link, pass the `code_verifier` AND the
+     * `expected_state` that `connect` returned there: the link's `state` is
+     * compared with `expected_state` locally, and no exchange is made without
+     * that comparison. The API's refusals come through verbatim: `invalid_grant`,
+     * `not_linked` (the person is not done; try again), `code_expired`,
+     * `already_exchanged`, `revoked`. `completeConnect(url)` reads the link and
+     * calls this.
+     */
+    exchange(input: ExchangeInput): Promise<Exchanged>;
+    /**
+     * The return link, as the sheet handed it back (`yourapp://connected?code=…&state=…`):
+     * finds the grant by its `state`, checks it, and exchanges the code. Throws
+     * `missing_code` when the link carries none (a session minted to poll, a
+     * reset or an action link: read those with `awaitConnected`).
+     */
+    completeConnect(returnUrl: string, opts?: {
+        session_id?: string;
+        code_verifier?: string;
+        expected_state?: string;
+    }): Promise<Exchanged>;
+    /**
+     * Resolves once the session is linked: who, and what the app may use.
+     * For a grant this client minted it resolves when `exchange` (or
+     * `completeConnect`) has answered for that session, and reads nothing
+     * meanwhile; for a polling mint it polls the session. Throws
+     * `connect_timeout` at the deadline, and `grant_requires_exchange` when the
+     * API says the session is a grant this client does not hold the verifier for.
+     * For one read with no wait, `sessions.get(session_id)`.
+     */
+    awaitConnected(sessionId: string, opts?: {
+        timeout_ms?: number;
+    }): Promise<Connected>;
+    readonly sessions: {
+        /**
+         * Where a link stands, in one read and with no wait: its status, how its result is collected (`grant`), and
+         * the diary (`last_step`, `reason`) that says why a link came back with nothing. On a linked grant the
+         * connected result stays behind the exchange (`exchange_required: true`, the person's fields null); a
+         * polling mint reads its result here as `awaitConnected` gives it. `slow_down` is waited out.
+         */
+        get: (sessionId: string) => Promise<SessionState>;
+    };
+    /**
+     * Revokes the connection a session made: the token its exchange minted is
+     * revoked, and an unexchanged code refuses from then on. Idempotent.
+     */
+    disconnect(sessionId: string): Promise<Revoked>;
+    readonly people: {
+        /**
+         * A returning person: what they already have with this business, without
+         * minting a link or sending them anywhere. Store `user_id` from the first
+         * exchange; on a later launch read here first, and `connect` only for what
+         * is missing (no card, or `voice: 'required'` and no voice for the bot's
+         * language). 404 `connection_not_found` when the person never connected
+         * through this client (or disconnected). The `user_id` in the answer is
+         * the effective one: a merged account answers with its survivor, worth
+         * storing from then on.
+         */
+        get: (userId: string) => Promise<Person>;
+    };
+    readonly authorizations: {
+        /**
+         * Creates the purchase, paused for approval, for the person `user_id`
+         * names (the `user_id` the connect exchange returned; required, so a
+         * server serving many people never charges the wrong one).
+         * `execution_mode: 'autopilot'` means the person's rule took it and no
+         * voice step follows. The return link (the call's, else the client's
+         * `returnUrl`) goes in the create, so Agentcard stores it on the request
+         * and the approval page reads it from there; the `approval_url` returned
+         * is id-only. `request: 'sandbox'` is the first-run form: under a sandbox
+         * client (`sandbox: true`, an `sk_test_` credential, or a mode the token
+         * exchange named) it sends the sandbox request and names no processor; a
+         * live client refuses it before the create leaves (`sandbox_request_in_live`). Every
+         * create carries an idempotency key, so a retried call makes one purchase.
+         */
+        create: (input: CreateAuthorizationInput) => Promise<Authorization>;
+        /**
+         * Names the card that pays, before the approval (decision 213): the person said "another card", or chose
+         * one from `cards`. `cardId` is one of the person's stored cards as `cards` lists them; a card that is not
+         * theirs is `card_not_found`. Refused once the purchase is decided (`already_finalized`) or while the card is
+         * with the processor (`replay_in_progress`). Answers the purchase as `get` reads it, `card` and `cards`
+         * included. Ask for the key word after this, so the line names the card that will pay.
+         */
+        setCard: (authorizationId: string, cardId: string) => Promise<AuthorizationResult>;
+        /**
+         * One read of a purchase, with no wait: its status, what approved it, the
+         * request fields, the settlement once it finished, and what a paused
+         * page resumes with. The way to ask "is it decided yet?" from a handler
+         * that cannot wait; `awaitResult` is the way to wait. `slow_down` is
+         * waited out.
+         */
+        get: (authorizationId: string) => Promise<AuthorizationResult>;
+        /**
+         * Withdraws a purchase that still awaits the person, in the business's own words: the person closed the
+         * sheet (`person_closed_sheet`), the person changed their mind (`person_changed_mind`), or a reason of the
+         * business's own (`business_cancelled`). The purchase reads `status: 'cancelled'` from then on, the reason
+         * is its `terminal_reason` on every read and on the `checkout_authorization.cancelled` webhook, and
+         * `awaitResult` reads `status: 'cancelled'` at once. Idempotent: a purchase already
+         * withdrawn answers what it became. One that the person already approved cannot be withdrawn
+         * (`409 already_finalized` once it finished, `409 outcome_unknown` while the card is with the processor).
+         */
+        cancel: (authorizationId: string, opts: {
+            reason: CancelReason;
+        }) => Promise<Cancelled>;
+    };
+    readonly approvals: {
+        /**
+         * The purchase's approval page on the Vault. It offers whichever doors the
+         * device has (voice, Face ID, Touch ID, the master password), so it is the
+         * way in for a person who forgot the passphrase, a bot with no microphone,
+         * or an agent with no screen, and it is the person-held tier of an in-app
+         * approval (`approve` from the app half opens it in the sheet). The read
+         * names the return link (this call's, else the client's `returnUrl`),
+         * the exact registered link the Vault sends the person back to once
+         * approved, and Agentcard stores it on the request, so the sheet closes on
+         * its own; the link returned is id-only, the page reads the return from
+         * Agentcard. Open it (or send it), then `awaitResult`. Null once the
+         * purchase no longer awaits a person.
+         */
+        approvalUrl: (authorizationId: string, opts?: {
+            return_url?: string;
+        }) => Promise<string | null>;
+    };
+    /**
+     * Asks for the one-time key word. Your bot says `say[lang]` when the
+     * person wears headphones, `say_private[lang]` when the phone plays through
+     * its speaker or the route is unknown (the line then points at the screen,
+     * where your app shows `word`). With `voice: 'braxter'` the response also
+     * carries `audio_url`, Agentcard's own voice saying the line, when the
+     * deployment has it; `delivery: 'screen'` asks for the private form of that
+     * audio. Every field is typed: `challenge` and `intent` are what the app's
+     * hosted frame signs over, `verifier_url` and `answer_token` where and with
+     * what the phone streams. `lang` defaults to `en` and is checked against
+     * `languages()` first. 409 `voice_not_enrolled` when the person has no
+     * voice key for apps.
+     */
+    challenge(authorizationId: string, opts?: {
+        lang?: Language;
+        voice?: 'braxter';
+        delivery?: 'spoken' | 'screen';
+    }): Promise<VoiceChallenge>;
+    /**
+     * The key word for an in-app approval, as one sealed bundle: mints the
+     * challenge and hands back the object your app forwards to
+     * `VoiceHost.approve` unread. It carries the word and both lines, Agentcard's
+     * audio when asked for, the nonce and the intent the frame signs over, and
+     * the verifier's address with the answer token the phone streams with (both
+     * absent from an API older than them). Refuses with `challenge_incomplete`
+     * when the API minted no nonce or intent, since the frame cannot sign
+     * without them.
+     */
+    challengeForHost(authorizationId: string, opts?: {
+        lang?: Language;
+        voice?: 'braxter';
+        delivery?: 'spoken' | 'screen';
+    }): Promise<HostApprovalBundle>;
+    readonly appKeys: {
+        /**
+         * Registers the app voice key your app's hosted frame minted (`VoiceHost.provision` relays its description),
+         * under this client's credentials, against the person connected to your app. Hand the `credential` back to
+         * the phone and nothing else. `user_id` is the person the connect exchange returned; required. 404
+         * `connection_not_found` when the person never connected through this client; 409 `credential_exists`
+         * when the credential id already names a different key. The same key again answers with a fresh credential.
+         */
+        register: (key: AppVoiceKeyDescription, opts: {
+            user_id: string;
+        }) => Promise<RegisteredAppVoiceKey>;
+        /** Revokes one app voice key of the person `user_id` names; the person's other keys, the card and the connection stay. Idempotent. */
+        revoke: (keyId: string, opts: {
+            user_id: string;
+        }) => Promise<RevokedAppVoiceKey>;
+    };
+    /**
+     * The streaming door from your server, the push direction: your pipeline
+     * already has the person's audio, so hand it to the verifier as it comes.
+     * `push` the bytes in `format`, `end` when the person is done (or let the
+     * verifier close the span itself), and read `hearing` and `verdict`. A
+     * finished recording is a short stream: see `streamBuffer`. The bearer is
+     * this client's token. The address is `stream_url` on the call, else the
+     * client's `voice.verifierUrl`, else the `verifier_url` the challenge
+     * itself carries. `lang` defaults to the challenge's language, else `en`.
+     */
+    stream(challenge: VoiceChallenge | HostApprovalBundle, opts: {
+        format: StreamFormat;
+        lang?: Language;
+        authorization_id?: string;
+        stream_url?: string;
+        channel?: ChannelKind;
+    }): Promise<StreamHandle>;
+    /**
+     * "I forgot my passphrase." Mints a voice-only link that starts the
+     * person's voice key over: the Vault forgets the device key, revokes the
+     * enrolment, and runs set-up again. Open `url` in the sheet, then
+     * `awaitConnected(session_id)`; `voice` reads `['en']` once it is done.
+     */
+    reset(input?: VoiceResetInput): Promise<ConnectResult>;
+    /**
+     * Polls the purchase until it leaves `awaiting_approval`; `{ status: 'timeout' }`
+     * at the deadline. The first read's `interval` (seconds) is the least this
+     * waits between reads, and a `slow_down` answer backs off to the interval
+     * it names and keeps polling. The result carries `request_id`,
+     * `terminal_reason`, `interaction_evidence`, `intent` and the other request
+     * fields beside `status`, and on a finished purchase the `settlement`
+     * answer the finishing webhook carries. For one read with no wait,
+     * `authorizations.get(id)`.
+     */
+    awaitResult(authorizationId: string, opts?: {
+        timeout_ms?: number;
+    }): Promise<AuthorizationResult>;
+    readonly actions: {
+        /**
+         * Mints the link that carries one action. Open `url` in the sheet:
+         * Agentcard's voice reads the action back, the person confirms it with the
+         * secure passphrase and the key word, the Vault runs it and returns.
+         * Throws `action_unavailable` for a kind the Vault cannot carry out yet.
+         */
+        propose: (action: Action, input?: {
+            return_url?: string;
+            lang?: Language;
+        }) => Promise<Proposed>;
+        /**
+         * One read of an action's link, with no wait: whether the action is done and confirmed, whether a rule
+         * covers the card now, the link's status, and the last step and reason its page recorded.
+         */
+        get: (sessionId: string) => Promise<ActionState>;
+        /**
+         * Polls the action's session until it reads done, or the deadline; the last state comes back either
+         * way, with the last step the Vault's page reached and the last reason it recorded, so a bot that
+         * gets `done: false` can say why ("your voice didn't confirm it", "that browser holds no voice key").
+         * For one read with no wait, `actions.get(session_id)`.
+         */
+        awaitDone: (sessionId: string, opts?: {
+            timeout_ms?: number;
+        }) => Promise<Done>;
+    };
+}