@andco/sdk 0.0.3 → 0.0.4

package/dist/intents.js

@@ -1,31 +1,64 @@
-import { CALLBACK_STATE_FROM, callbackStateCreate, RANDOM_UUID, SafeURL, } from "@andco/protocol";
-import { ANDCO_INTENT_AUTHORIZATION_URL, subscribeFinancialEvents, } from "@andco/protocol/transport";
+import { ANDCO_INTENT_PROPOSAL_MEDIA_TYPE, ANDCO_SIGNED_INSTRUCTION_MEDIA_TYPE, CALLBACK_STATE_FROM, callbackStateCreate, RANDOM_UUID, SafeURL, safeParseIntentCancellation, safeParseIntentRejection, } from "@andco/protocol";
+import { ANDCO_INTENT_AUTHORIZATION_URL, INTENT_ID_SYNTAX, subscribeFinancialEvents, } from "@andco/protocol/transport";
 import { ANDCO_ERROR_CODES, AndcoError, Result } from "./errors.js";
-const INTENT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+import { resolveGlobals } from "./globals.js";
+/** Derived from the transport's strict check so this layer cannot accept what it would reject. */
+const INTENT_ID_PATTERN = /* @__PURE__ */ new RegExp(INTENT_ID_SYNTAX, "i");
 const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+/** A compact JWS envelope. Whether it verifies, and what it says, are the server's answers to give. */
+const SIGNED_INSTRUCTION_PATTERN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+/** Where a presentation that leaves this document waits for {@link AndcoIntents.fromCallback}. */
+const PENDING_PRESENTATION_KEY = "andco.intent_presentation";
+/** Statuses after which an Intent never changes again. `failed.*` sub-statuses are terminal too. */
+const TERMINAL_INTENT_STATUSES = /* @__PURE__ */ new Set([
+    "succeeded",
+    "completed",
+    "closed",
+    "cancelled",
+    "rejected",
+    "expired",
+]);
 /**
- * Creates and reads Intents under the current Grant, and observes the durable facts they produce.
+ * Creates, presents, reads and follows Intents under the current Grant.
  *
- * This is the domain-neutral Intent lifecycle only. Deposit, withdrawal, automatic charge, and the
- * four typed event subscriptions that used to live here now belong to the Bank Resource Server
- * Definition, which composes `create`, `events`, and `subscribe` exactly as a third party would —
- * a defect in this extension point is meant to surface in Andco's own code first.
+ * Every method that names an existing Intent takes the Intent or its id. Presentation is one
+ * controller for three shapes — popup, new tab, redirect — and the SDK always generates and checks
+ * the callback `state`, so an application never correlates callbacks itself.
  *
  * @example
  * ```ts
- * const { data: deposit } = await andco.intents.create("deposit", depositInput);
+ * const { data: deposit } = await bank.intents.createDeposit(input);
+ * const presentation = andco.intents.present(deposit, { presentation: "popup" });
+ * const { data } = await presentation.result;
+ * if (data?.outcome === "complete") refreshBalance();
  * ```
  */
 export class AndcoIntents {
     #rest;
     #config;
     #presenter;
-    #crypto;
+    #globals;
+    #storage;
+    /** Window presentations still open, by Intent id: what makes `present` idempotent per Intent. */
+    #presenting = new Map();
     constructor(options) {
         this.#rest = options.rest;
         this.#config = options.config;
         this.#presenter = options.presenter;
-        this.#crypto = options.crypto;
+        this.#globals = options.globals ?? resolveGlobals();
+        this.#storage = options.presentationStorage ?? defaultPresentationStorage();
+    }
+    /**
+     * Whether an Intent has reached a status it never leaves: succeeded, completed, closed, cancelled,
+     * rejected, expired, or any `failed` status.
+     *
+     * @example
+     * ```ts
+     * if (AndcoIntents.isTerminal(intent)) stopPolling();
+     * ```
+     */
+    static isTerminal(intent) {
+        return TERMINAL_INTENT_STATUSES.has(intent.status) || intent.status.startsWith("failed");
     }
     /**
      * Creates an Intent of the given type. The exact Grant determines what it may do and where.
@@ -39,7 +72,7 @@ export class AndcoIntents {
      * Definition names its own response type here.
      */
     async create(type, input, options = {}) {
-        const idempotencyKey = options.idempotencyKey ?? RANDOM_UUID(this.#crypto);
+        const idempotencyKey = options.idempotencyKey ?? RANDOM_UUID(this.#globals.crypto);
         if (!IDEMPOTENCY_KEY_PATTERN.test(idempotencyKey)) {
             return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, { message: "malformed Idempotency-Key" });
         }
@@ -48,6 +81,9 @@ export class AndcoIntents {
             ({ data } = await this.#rest.http
                 // The generated body type is a bank-specific union; this method is neutral over `type`.
                 .POST("/intents", {
+                // The endpoint answers to two content types. This is the proposal half, and saying so is
+                // what keeps it from depending on which one the transport happens to default to.
+                headers: { "Content-Type": ANDCO_INTENT_PROPOSAL_MEDIA_TYPE },
                 params: { header: { "Idempotency-Key": idempotencyKey } },
                 body: { ...input, type },
             })
@@ -62,116 +98,369 @@ export class AndcoIntents {
         return Result.ok(data);
     }
     /**
-     * The Andco-owned URL that presents one Intent, with its callbacks bound.
+     * Sends one already-signed Instruction: the `application/jwt` half of the same creation.
+     *
+     * The body is the compact JWS itself, and every value the operation uses comes from its verified
+     * claims — nothing is read from the envelope carrying them, so `type` is only checked against the
+     * response here and never written into a request. No `Idempotency-Key` accompanies it either: the
+     * key is the `jti` inside the signature, and the server answers `400 idempotency_key_not_allowed`
+     * to a second candidate rather than quietly picking one.
+     */
+    async createSigned(type, instruction) {
+        if (!SIGNED_INSTRUCTION_PATTERN.test(instruction)) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, { message: "malformed Signed Instruction" });
+        }
+        let data;
+        try {
+            ({ data } = await this.#rest.http
+                .POST("/intents", {
+                headers: { "Content-Type": ANDCO_SIGNED_INSTRUCTION_MEDIA_TYPE },
+                // A compact JWS is already serialized; the default serializer would JSON-quote it.
+                bodySerializer: (body) => body,
+                body: instruction,
+            })
+                .throwOnError());
+        }
+        catch (cause) {
+            return Result.fail(cause);
+        }
+        if (data?.type !== type) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_RESPONSE, { message: `expected a ${type} intent` });
+        }
+        return Result.ok(data);
+    }
+    /**
+     * The Andco-owned URL that presents one Intent, with its callbacks bound. Synchronous: it reads
+     * the Intent's own `authorization_url`, checks it belongs to the instance's interaction origin,
+     * and adds the four parameters Platform requires (`return_uri`, `error_return_uri`,
+     * `presentation`, `state`) — a bare `authorization_url` is an input, not a destination.
      *
-     * Published rather than folded into `present` because the Hosted Intent Button needs the same URL
-     * with a different `state`: its callback returns to the widget that opened the window, not to
-     * this document. Two constructions of one URL is precisely the drift ADR-0014 records, and a bare
-     * `authorization_url` is an input to presentation, not a destination — Platform renders a 404 for
-     * any of the four parameters below that is missing.
+     * Never intercepted by a native Host: it is a URL, not a presentation. Use it to redirect a payer
+     * from a server, or to put the link somewhere the SDK does not open itself. When only the id is at
+     * hand, {@link AndcoIntents.presentationURLFor} reads the Intent first.
+     *
+     * @example
+     * ```ts
+     * const { data: url } = andco.intents.presentationURL(deposit, { presentation: "redirect", returnTo });
+     * return Response.redirect(url);
+     * ```
      */
-    async presentationURL(options) {
+    presentationURL(intent, options) {
         if (!this.#config)
             return Result.fail(presentationUnsupported());
-        const invalid = assertIntentId(options.intentId);
-        if (invalid)
-            return Result.fail(invalid);
-        if (options.returnTo.origin !== options.errorReturnTo.origin) {
-            // Platform refuses a mismatch by rendering a 404. Failing here says why instead.
-            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
-                message: "returnTo and errorReturnTo must share one origin",
-            });
-        }
-        const read = await this.get(options.intentId);
-        if (read.error)
-            return Result.fail(read.error);
+        const callbacks = this.#callbacks(options);
+        if (callbacks.error)
+            return Result.fail(callbacks.error);
+        const { returnTo, errorReturnTo } = callbacks.data;
         let url;
+        let state;
         try {
-            url = ANDCO_INTENT_AUTHORIZATION_URL(read.data, this.#config.endpoints.api);
+            url = ANDCO_INTENT_AUTHORIZATION_URL(intent, this.#config.endpoints.api);
+            state = options.state ?? callbackStateCreate(returnTo.origin, RANDOM_UUID(this.#globals.crypto));
         }
         catch (cause) {
+            console.error("[AndcoIntents.presentationURL] invalid authorization_url %o", cause);
             return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.INVALID_RESPONSE));
         }
-        url.searchParams.set("return_uri", options.returnTo.href);
-        url.searchParams.set("error_return_uri", options.errorReturnTo.href);
+        url.searchParams.set("return_uri", returnTo.href);
+        url.searchParams.set("error_return_uri", errorReturnTo.href);
         url.searchParams.set("presentation", options.presentation);
-        url.searchParams.set("state", options.state);
+        url.searchParams.set("state", state);
+        console.debug("[AndcoIntents.presentationURL] built %s for %s", options.presentation, url.origin + url.pathname);
         return Result.ok(url);
     }
     /**
-     * Presents one Intent and answers with its authoritative outcome.
+     * {@link AndcoIntents.presentationURL} for a caller holding only the id: reads the Intent, then
+     * builds the same URL. The one asynchronous way to a presentation URL.
+     *
+     * @example
+     * ```ts
+     * const { data: url } = await andco.intents.presentationURLFor(intentId, { presentation: "popup" });
+     * ```
+     */
+    async presentationURLFor(intentId, options) {
+        if (!this.#config)
+            return Result.fail(presentationUnsupported());
+        const read = await this.get(intentId);
+        if (read.error)
+            return Result.fail(read.error);
+        return this.presentationURL(read.data, options);
+    }
+    /**
+     * Presents one Intent and hands back a controller for it at once.
+     *
+     * `"popup"` and `"newtab"` open a window during the current user activation — call this
+     * synchronously from the click handler — and `result` settles when it closes, with the Intent read
+     * again: a callback reports that a window finished, which is not the same fact as a completed
+     * deposit, and a dismissal is read too because the person may have closed the window on an
+     * operation the bank had already accepted. Inside the first-party native Host both are presented
+     * by the Host instead of a window.
+     *
+     * `"redirect"` navigates this document away; `status` becomes `"navigated"` and `result` never
+     * settles. The return page reads the outcome with {@link AndcoIntents.fromCallback}.
      *
-     * This is the Direct Popup Presentation: the programmatic path for UI that cannot mount a Hosted
-     * Intent Button. It owns the whole interaction — the window, the four callback parameters, the
-     * correlation, and the read afterwards — so that no Project has to reach for a window primitive
-     * to complete a financial operation.
+     * `state` is always generated here and checked on the way back. The source may be a factory,
+     * resolved only after the window is open, so creating the Intent on the click does not get the
+     * popup blocked.
      *
-     * The Intent is read again once the window settles, because a callback reports that a window
-     * finished and that is not the same fact as a completed deposit. A dismissal is read too: the
-     * user may have closed the window on an operation the bank had already accepted.
+     * Idempotent per Intent within one Andco Instance: while a presentation of the same Intent id is
+     * still `"presenting"`, another call focuses the window already open and returns the SAME
+     * controller — never a second popup or tab, whatever options the second call carried. Once that
+     * presentation settles, a new call opens a new one. A `"redirect"` is unaffected, since it replaces
+     * the document, and a factory cannot be matched before it resolves, so it always presents.
+     *
+     * That is the window's idempotency. The Intent's own is server-side: a fixed-amount deposit or a
+     * transfer cannot be paid or confirmed twice however many windows reach it, whereas an open
+     * collection (no amount) accepts several contributions by design.
      *
      * @example
      * ```ts
-     * const { data, error } = await andco.intents.present<AndCoDepositIntent>({
-     *   intentId: async () => (await bank.intents.createDeposit(input)).data.id,
-     * });
+     * const presentation = andco.intents.present(() => createDeposit(), { presentation: "popup" });
+     * cancelButton.onclick = () => presentation.close();
+     * const { data, error } = await presentation.result;
      * if (data?.outcome === "complete") refreshBalance();
      * ```
      */
-    async present(options) {
-        if (!this.#config || !this.#presenter)
-            return Result.fail(presentationUnsupported());
-        const returnTo = options.returnTo ? new SafeURL(options.returnTo) : this.#config.redirectTo;
-        if (!returnTo) {
-            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
-                message: "an Intent Presentation needs a returnTo, and this instance has no redirectTo",
+    present(source, options = {}) {
+        const presentation = options.presentation ?? "popup";
+        const intentId = typeof source === "string" ? source : typeof source === "object" ? source.id : undefined;
+        if (intentId !== undefined && presentation !== "redirect") {
+            const existing = this.#presenting.get(intentId);
+            if (existing && existing.controller.status === "presenting") {
+                console.debug("[AndcoIntents.present] %s is already presenting; focusing %s", intentId, existing.presentationId);
+                this.#presenter?.focus?.(existing.presentationId);
+                return existing.controller;
+            }
+        }
+        let status = "presenting";
+        const abort = new AbortController();
+        if (options.signal?.aborted)
+            abort.abort();
+        options.signal?.addEventListener("abort", () => abort.abort(), { once: true });
+        const presentationId = RANDOM_UUID(this.#globals.crypto);
+        // Called synchronously: everything up to the presenter runs inside the caller's user activation.
+        const result = this.#present(source, options, presentationId, abort.signal, (next) => {
+            status = next;
+        });
+        const controller = {
+            get status() {
+                return status;
+            },
+            result,
+            close: () => {
+                console.debug("[AndcoIntents.present] close requested while %s", status);
+                abort.abort();
+            },
+        };
+        if (intentId !== undefined && presentation !== "redirect") {
+            this.#presenting.set(intentId, {
+                controller: controller,
+                presentationId,
             });
+            const release = () => {
+                if (this.#presenting.get(intentId)?.controller === controller)
+                    this.#presenting.delete(intentId);
+            };
+            void result.then(release, release);
         }
-        const errorReturnTo = options.errorReturnTo ? new SafeURL(options.errorReturnTo) : returnTo;
-        const presentationId = RANDOM_UUID(this.#crypto);
+        return controller;
+    }
+    async #present(source, options, presentationId, signal, setStatus) {
+        const fail = (error) => {
+            console.error("[AndcoIntents.present] %o", error);
+            setStatus("error");
+            return Result.fail(error);
+        };
+        if (!this.#config || !this.#presenter) {
+            return fail(presentationUnsupported());
+        }
+        const presentation = options.presentation ?? "popup";
+        const callbacks = this.#callbacks(options);
+        if (callbacks.error) {
+            return fail(callbacks.error);
+        }
+        const { returnTo, errorReturnTo } = callbacks.data;
         // The same encoding OAuth uses: it binds the opener origin the callback must post back to, and
         // its alphabet is the one Platform accepts for `state`.
         const state = callbackStateCreate(returnTo.origin, presentationId);
-        // Resolved inside the thunk, so the window is already open when the Intent is created.
+        const urlOptions = { presentation, returnTo, errorReturnTo, state };
         let intentId;
-        const presented = await this.#presenter.present({
-            kind: "intent",
-            presentation: "popup",
-            url: async () => {
+        const destination = (intent) => {
+            const built = this.presentationURL(intent, urlOptions);
+            if (built.error)
+                throw built.error;
+            intentId = intent.id;
+            // A presentation that leaves this document is read back on another load; remember it there.
+            if (presentation !== "popup")
+                this.#remember(presentationId, { intentId: intent.id, presentation });
+            return built.data;
+        };
+        // An Intent in hand builds its URL with no round trip; an id or a factory resolves after the
+        // presenter has its window.
+        let url;
+        if (typeof source === "object") {
+            try {
+                url = destination(source);
+            }
+            catch (cause) {
+                return fail(AndcoError.from(cause, ANDCO_ERROR_CODES.INVALID_RESPONSE));
+            }
+        }
+        else {
+            url = async () => {
+                let resolved;
                 try {
-                    intentId = typeof options.intentId === "string" ? options.intentId : await options.intentId();
+                    resolved = typeof source === "string" ? source : await source();
                 }
                 catch (cause) {
-                    return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.INVALID_CONFIGURATION));
+                    throw AndcoError.from(cause, ANDCO_ERROR_CODES.INVALID_CONFIGURATION);
                 }
-                return this.presentationURL({ intentId, presentation: "popup", returnTo, errorReturnTo, state });
-            },
+                if (typeof resolved === "object" && "authorization_url" in resolved) {
+                    return destination(resolved);
+                }
+                const read = await this.get(typeof resolved === "string" ? resolved : resolved.id);
+                if (read.error) {
+                    throw read.error;
+                }
+                return destination(read.data);
+            };
+        }
+        console.debug("[AndcoIntents.present] presenting %s presentationId=%s", presentation, presentationId);
+        const presented = await this.#presenter.present({
+            kind: "intent",
+            presentation,
+            url,
             get intentId() {
                 return intentId ?? "";
             },
             returnTo,
             errorReturnTo,
             presentationId,
-            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            signal,
         });
-        if (presented.error)
-            return Result.fail(presented.error);
+        if (presented.error) {
+            this.#forget(presentationId);
+            return fail(presented.error);
+        }
         if (!intentId) {
             // The presenter settled without ever asking for a destination, so nothing was presented.
-            return Result.fail(presentationUnsupported());
+            return fail(presentationUnsupported());
+        }
+        else if (presentation === "redirect" && presented.data === null) {
+            // The document is being replaced; the return page owns the result now.
+            console.debug("[AndcoIntents.present] navigated away intentId=%s", intentId);
+            setStatus("navigated");
+            return new Promise(() => { });
         }
+        // Settled in this document after all, so nothing is left for a return page to read.
+        this.#forget(presentationId);
         const outcome = INTENT_RESULT_FROM(presented.data, { presentationId });
-        if (outcome.error)
-            return Result.fail(outcome.error);
-        console.debug("[AndcoIntents.present] settled: %s %o", outcome.data, { intentId, presentationId });
+        if (outcome.error) {
+            return fail(outcome.error);
+        }
+        console.debug("[AndcoIntents.present] settled: %s intentId=%s presentationId=%s", outcome.data, intentId, presentationId);
         // Authoritative, and read on a dismissal too: a closed window says nothing about the money.
         const intent = await this.get(intentId);
-        if (intent.error)
-            return Result.fail(intent.error);
+        if (intent.error) {
+            return fail(intent.error);
+        }
+        setStatus(outcome.data === "complete" ? "complete" : "dismissed");
         return Result.ok({ outcome: outcome.data, intent: intent.data });
     }
-    /** Reads the authoritative state of one Intent. This, not a callback, is the source of truth. */
-    async get(intentId) {
+    /**
+     * Reads an Intent Presentation's outcome on the page its callback landed on — the return page of
+     * a `"redirect"`, or of a `"newtab"` whose opener is gone — then reads the Intent again.
+     *
+     * The callback's `state` must belong to a presentation this browser started with
+     * {@link AndcoIntents.present}; anything else is refused with `invalid_callback`, and each
+     * presentation is consumed once. A server that built the URL with
+     * {@link AndcoIntents.presentationURL} passes the `state` it kept instead.
+     *
+     * @example
+     * ```ts
+     * const { data, error } = await andco.intents.fromCallback(window.location.href);
+     * if (data?.outcome === "complete") showReceipt(data.intent);
+     * ```
+     */
+    async fromCallback(callbackUrl, options = {}) {
+        const mismatch = (message) => {
+            console.error("[AndcoIntents.fromCallback] %s", message);
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK, { message });
+        };
+        let url;
+        try {
+            url = new URL(callbackUrl);
+        }
+        catch {
+            return mismatch("the callback is not a URL");
+        }
+        const state = url.searchParams.get("state");
+        const parsed = state ? CALLBACK_STATE_FROM(state) : null;
+        if (!state || !parsed)
+            return mismatch("the callback carries no valid state");
+        const returnedId = url.searchParams.get("intent_id");
+        let intentId;
+        if (options.state !== undefined) {
+            if (state !== options.state)
+                return mismatch("the callback does not belong to this presentation");
+            intentId = returnedId;
+        }
+        else {
+            const pending = this.#recall(parsed.presentationId);
+            if (!pending)
+                return mismatch("the callback does not belong to a presentation this browser started");
+            this.#forget(parsed.presentationId);
+            if (returnedId && returnedId !== pending.intentId) {
+                return mismatch("the callback names a different Intent than the one presented");
+            }
+            intentId = pending.intentId;
+        }
+        if (!intentId) {
+            return mismatch("the callback names no Intent");
+        }
+        const outcome = url.searchParams.get("andco_intent_result");
+        if (outcome !== "complete" && outcome !== "dismiss") {
+            return mismatch("the callback carries no Intent result");
+        }
+        console.debug("[AndcoIntents.fromCallback] %s intentId=%s", outcome, intentId);
+        const intent = await this.get(intentId);
+        if (intent.error) {
+            return Result.fail(intent.error);
+        }
+        return Result.ok({ outcome, intent: intent.data });
+    }
+    /**
+     * Reads the authoritative state of one Intent, as the Resource Server has it right now.
+     *
+     * This, never a callback, a window message or a webhook alone, is the source of truth: a callback
+     * reports that a window finished, and only this read says whether money moved. Accepts the Intent
+     * or just its id.
+     *
+     * Typical uses: re-reading after a page reload (keep the id, call `get`, or `watch` to follow it
+     * on); reading once `present` resolves, which {@link AndcoIntents.present} already does for
+     * its own `intent`; and, on your server, confirming `status` before marking an order paid or
+     * shipping goods — never trust the browser's word for it.
+     *
+     * Never throws; failures arrive as `error.code`:
+     * - `invalid_intent_id`: the id is not a well-formed UUID; no request was made.
+     * - `not_found`: no such Intent for this Project, or it belongs to another one. The API answers
+     *   the same either way so ids cannot be probed.
+     * - `insufficient_authorization`: the Grant does not cover reading Intents of this family.
+     * - network and server failures carry their own code and are safe to retry.
+     *
+     * @example
+     * ```ts
+     * const { data: intent, error } = await andco.intents.get(intentOrId);
+     * if (error?.code === "not_found") return showUnknownOrder();
+     * if (intent && AndcoIntents.isTerminal(intent)) settleOrder(intent.status);
+     *
+     * // On the server, before marking the order paid:
+     * const { data } = await andco.intents.get(order.intentId);
+     * if (data?.status === "completed") await markPaid(order);
+     * ```
+     */
+    async get(intent) {
+        const intentId = idOf(intent);
         const invalid = assertIntentId(intentId);
         if (invalid)
             return Result.fail(invalid);
@@ -185,32 +474,166 @@ export class AndcoIntents {
             return Result.fail(cause);
         }
     }
-    /** Executes an intent whose Grant permits it. Completion must still be confirmed with `get`. */
-    async execute(intentId) {
+    /**
+     * Follows one Intent until it is terminal and answers it. The one call to re-attach to an Intent
+     * after a reload: keep the id, `watch` it, and the page is back where it was.
+     *
+     * Terminal means succeeded, completed, closed, cancelled, rejected, expired, or any `failed`
+     * status ({@link AndcoIntents.isTerminal}); the `result` then holds the Intent as the Resource
+     * Server has it. Built on {@link AndcoIntents.get}, which it repeats every `pollIntervalMs` — the
+     * authority, and the only way to notice an expiry — and on {@link AndcoIntents.subscribe}, whose
+     * events wake it up sooner. A read that fails is retried, so a dropped connection does not end
+     * the wait; a malformed id fails at once with `invalid_intent_id`.
+     *
+     * `stop()` or `signal` end it with `watch_stopped`; `intent` keeps the last read. Terminal means
+     * the Intent stopped changing, not that it succeeded: look at `status` before acting on money.
+     *
+     * @example
+     * ```ts
+     * const watch = andco.intents.watch(intentId);
+     * onUnmount(() => watch.stop());
+     * const { data: intent, error } = await watch.result;
+     * if (intent?.status === "completed") showReceipt(intent);
+     *
+     * // A milestone before the terminal status, with a deadline:
+     * andco.intents.watch(transfer, { types: ["transfer.accepted"], signal: AbortSignal.timeout(60_000) });
+     * ```
+     */
+    watch(intent, options = {}) {
+        const intentId = idOf(intent);
+        const pollIntervalMs = Math.max(options.pollIntervalMs ?? 1_000, 100);
+        let status = "watching";
+        let latest = null;
+        let timer;
+        let unsubscribe = () => { };
+        let finish = () => { };
+        const result = new Promise((resolve) => {
+            finish = (outcome, next) => {
+                if (status !== "watching")
+                    return;
+                status = next;
+                clearTimeout(timer);
+                unsubscribe();
+                options.signal?.removeEventListener("abort", stop);
+                console.debug("[AndcoIntents.watch] %s ended %s %o", intentId, next, outcome.error ?? outcome.data?.status);
+                resolve(outcome);
+            };
+        });
+        const stop = () => finish(Result.fail(ANDCO_ERROR_CODES.WATCH_STOPPED), "stopped");
+        const controller = {
+            get status() {
+                return status;
+            },
+            get intent() {
+                return latest;
+            },
+            result,
+            stop,
+        };
+        const invalid = assertIntentId(intentId);
+        if (invalid) {
+            finish(Result.fail(invalid), "settled");
+            return controller;
+        }
+        if (options.signal?.aborted) {
+            stop();
+            return controller;
+        }
+        options.signal?.addEventListener("abort", stop, { once: true });
+        let reading = false;
+        let milestone = false;
+        const read = async () => {
+            // One read in flight at a time: an event feed replaying history must not fan out into N reads.
+            if (reading)
+                return;
+            reading = true;
+            clearTimeout(timer);
+            const current = await this.get(intentId);
+            reading = false;
+            if (status !== "watching")
+                return;
+            if (current.error) {
+                console.error("[AndcoIntents.watch] read of %s failed, retrying: %o", intentId, current.error);
+                options.onError?.(current.error);
+            }
+            else {
+                latest = current.data;
+                options.onChange?.(current.data);
+                if (milestone || AndcoIntents.isTerminal(current.data)) {
+                    return finish(Result.ok(current.data), "settled");
+                }
+            }
+            timer = setTimeout(() => void read(), pollIntervalMs);
+        };
+        const types = options.types ? new Set(options.types) : null;
+        console.debug("[AndcoIntents.watch] %s until=%s types=%o", intentId, options.until ?? "terminal", options.types);
+        // Events wake the read up; whether the Intent is terminal is still decided by the read itself.
+        unsubscribe = this.subscribe(intentId, { pollIntervalMs, onError: () => { } }, (event) => {
+            if (types?.has(event.type))
+                milestone = true;
+            void read();
+        });
+        void read();
+        return controller;
+    }
+    /**
+     * Approves an Intent with this credential's Grant, which must hold `approve` on the family that
+     * releases it (`bank_transfer` for a transfer) for the same subject, within its maximum. The
+     * approver may be another app than the creator: dual control is two Grants. Answers the Intent;
+     * accepted is not moved, so wait for `transfer.succeeded` or `transfer.failed`.
+     *
+     * Fails with `amount_out_of_grant` above the approver's maximum (the Intent stays pending for
+     * another approver), `interaction_required` when a person still has to pick the source, and
+     * `intent_expired` past its deadline.
+     *
+     * @example
+     * ```ts
+     * const approver = andco.with(approverCredentials).intents;
+     * await approver.approve(transfer);
+     * await approver.approve(transferId, { grant: grantId }); // pin the approving Grant
+     * ```
+     */
+    async approve(intent, options = {}) {
+        const intentId = idOf(intent);
         const invalid = assertIntentId(intentId);
         if (invalid)
             return Result.fail(invalid);
+        console.debug("[AndcoIntents.approve] approving %s with grant %o", intentId, options.grant ?? "selected");
         try {
-            await this.#rest.http
-                .POST("/intents/{intent_id}/execute", { params: { path: { intent_id: intentId } } })
+            const { data } = await this.#rest.http
+                .POST("/intents/{intent_id}/approve", { params: { path: { intent_id: intentId } } }, { grant: options.grant })
                 .throwOnError();
-            return Result.ok(undefined);
+            return Result.ok(data);
         }
         catch (cause) {
             return Result.fail(cause);
         }
     }
-    /** Reads one page of durable Intent facts, replaying after an opaque checkpoint. */
-    async events(intentId, after, signal) {
+    /**
+     * Rejects an Intent as an approver, naming why. This credential's Grant must hold `reject` on the
+     * family that releases it for the same subject; no maximum applies. Recorded as a Rejection, which
+     * the audit keeps apart from the creator's Cancellation.
+     *
+     * @example
+     * ```ts
+     * await andco.with(approverCredentials).intents.reject(transferId, { reason: "duplicated_invoice" });
+     * ```
+     */
+    async reject(intent, options) {
+        const intentId = idOf(intent);
         const invalid = assertIntentId(intentId);
         if (invalid)
             return Result.fail(invalid);
+        const parsed = safeParseIntentRejection({ reason: options.reason });
+        if (!parsed.success) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                message: "rejection reason must be 1-280 characters",
+            });
+        }
+        console.debug("[AndcoIntents.reject] rejecting %s", intentId);
         try {
             const { data } = await this.#rest.http
-                .GET("/intents/{intent_id}/events", {
-                params: { path: { intent_id: intentId }, query: { after, limit: 100 } },
-                signal,
-            })
+                .POST("/intents/{intent_id}/reject", { params: { path: { intent_id: intentId } }, body: { reason: parsed.output.reason } }, { grant: options.grant })
                 .throwOnError();
             return Result.ok(data);
         }
@@ -219,48 +642,130 @@ export class AndcoIntents {
         }
     }
     /**
-     * Subscribes to a durable, paged feed of facts, reusing the Protocol Contract's paging, cursor,
-     * checkpoint, and poll-interval reconciliation.
-     *
-     * Domain-neutral by design: the caller supplies both the page fetcher (`read`) and the `subject`
-     * that scopes its cursor namespace, so nothing here assumes an Intent, an account, or any other
-     * kind of subject. That is what lets a Resource Server Definition — the Bank one included —
-     * compose this loop for its own event feed instead of rebuilding paging and checkpointing from
-     * scratch, which is the one genuinely difficult piece of this surface.
-     *
-     * Every subscription returns its own unsubscribe function, so binding one to a framework effect —
-     * `useEffect`, Svelte's `$effect`, Vue's `watchEffect` — is a single line.
+     * Withdraws an Intent this app created, naming why. Only the creator cancels; an approver
+     * declining it uses {@link AndcoIntents.reject}, and the audit keeps the two apart. Answers
+     * `intent_expired` when the Intent's deadline has already passed.
      *
      * @example
      * ```ts
-     * const unsubscribe = andco.intents.subscribe(
-     *   { kind: "intent", id: intentId },
-     *   (after, signal) => andco.intents.events(intentId, after, signal),
-     *   (event) => (event.type.startsWith("deposit.") ? event : null),
-     *   (event) => setDeposit(event),
-     *   { onError },
-     * );
+     * await andco.intents.cancel(transfer, { reason: "rejected_by_erp" });
      * ```
      */
-    subscribe(subject, read, decode, handler, options) {
+    async cancel(intent, options) {
+        const intentId = idOf(intent);
+        const invalid = assertIntentId(intentId);
+        if (invalid)
+            return Result.fail(invalid);
+        const parsed = safeParseIntentCancellation({ reason: options.reason });
+        if (!parsed.success) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                message: "cancellation reason must be 1-280 characters",
+            });
+        }
+        console.debug("[AndcoIntents.cancel] cancelling %s", intentId);
+        try {
+            const { data } = await this.#rest.http
+                .POST("/intents/{intent_id}/cancel", { params: { path: { intent_id: intentId } }, body: { reason: parsed.output.reason } }, { grant: options.grant })
+                .throwOnError();
+            return Result.ok(data);
+        }
+        catch (cause) {
+            return Result.fail(cause);
+        }
+    }
+    /** Reads one page of durable Intent facts, replaying after an opaque checkpoint. */
+    async events(intent, after, signal) {
+        const intentId = idOf(intent);
+        const invalid = assertIntentId(intentId);
+        if (invalid)
+            return Result.fail(invalid);
+        try {
+            const { data } = await this.#rest.http
+                .GET("/intents/{intent_id}/events", {
+                params: { path: { intent_id: intentId }, query: { after, limit: 100 } },
+                signal,
+            })
+                .throwOnError();
+            return Result.ok(data);
+        }
+        catch (cause) {
+            return Result.fail(cause);
+        }
+    }
+    subscribe(intent, optionsOrHandler, maybeHandler) {
+        const options = typeof optionsOrHandler === "function" ? {} : optionsOrHandler;
+        const handler = typeof optionsOrHandler === "function" ? optionsOrHandler : maybeHandler;
+        const intentId = idOf(intent);
+        const onError = options.onError ?? ((error) => console.error("[AndcoIntents.subscribe] %s %o", intentId, error));
+        const invalid = assertIntentId(intentId);
+        if (invalid) {
+            queueMicrotask(() => onError(invalid));
+            return () => { };
+        }
+        const types = options.types ? new Set(options.types) : null;
+        console.debug("[AndcoIntents.subscribe] %s types=%o after=%s", intentId, options.types, options.after);
         const subscription = subscribeFinancialEvents(async (after, signal) => {
-            const page = await read(after, signal);
+            const page = await this.events(intentId, after, signal);
             if (page.error)
                 throw page.error;
             return page.data;
-        }, decode, 
+        }, (event) => (types === null || types.has(event.type) ? event : null), 
         // The checkpoint is pushed only once a handler has succeeded, so persisting it can never
         // acknowledge an event the application failed to process.
         async (event) => {
             await handler(event);
             options.onCheckpoint?.(event.cursor);
-        }, {
-            ...(options.after === undefined ? {} : { after: options.after }),
-            onError: options.onError,
-            ...(options.pollIntervalMs === undefined ? {} : { pollIntervalMs: options.pollIntervalMs }),
-        }, subject);
+        }, { after: options.after, onError, pollIntervalMs: options.pollIntervalMs }, { kind: "intent", id: intentId });
         return () => subscription.unsubscribe();
     }
+    /** Resolves and checks the two callbacks a presentation returns through. */
+    #callbacks(options) {
+        let returnTo;
+        let errorReturnTo;
+        try {
+            returnTo = options.returnTo ? new SafeURL(options.returnTo) : this.#config?.redirectTo;
+            if (!returnTo) {
+                return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                    message: "an Intent Presentation needs a returnTo, and this instance has no redirectTo",
+                });
+            }
+            errorReturnTo = options.errorReturnTo ? new SafeURL(options.errorReturnTo) : returnTo;
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.INVALID_CONFIGURATION));
+        }
+        if (returnTo.origin !== errorReturnTo.origin) {
+            // Platform refuses a mismatch by rendering a 404. Failing here says why instead.
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                message: "returnTo and errorReturnTo must share one origin",
+            });
+        }
+        return Result.ok({ returnTo, errorReturnTo });
+    }
+    #remember(presentationId, pending) {
+        if (!this.#storage) {
+            console.warn("[AndcoIntents.present] no presentationStorage; fromCallback will refuse this return");
+            return;
+        }
+        this.#storage.setItem(`${PENDING_PRESENTATION_KEY}.${presentationId}`, JSON.stringify(pending));
+    }
+    #recall(presentationId) {
+        const stored = this.#storage?.getItem(`${PENDING_PRESENTATION_KEY}.${presentationId}`);
+        if (!stored)
+            return null;
+        try {
+            const parsed = JSON.parse(stored);
+            return typeof parsed.intentId === "string" && typeof parsed.presentation === "string"
+                ? parsed
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    #forget(presentationId) {
+        this.#storage?.removeItem(`${PENDING_PRESENTATION_KEY}.${presentationId}`);
+    }
 }
 /**
  * Reads the lifecycle outcome out of the callback a presentation came back with.
@@ -285,12 +790,24 @@ function INTENT_RESULT_FROM(callbackUrl, presentation) {
         return Result.ok("dismiss");
     return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK, { message: "the callback carries no Intent result" });
 }
+/** `sessionStorage` when the runtime has one and allows it; nothing on a server. */
+function defaultPresentationStorage() {
+    try {
+        return typeof sessionStorage === "undefined" ? undefined : sessionStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** One message for every surface that has the lifecycle but cannot put a window in front of anyone. */
 function presentationUnsupported() {
     return new AndcoError(ANDCO_ERROR_CODES.PRESENTATION_UNSUPPORTED, {
         message: "this Intent surface was composed without a presenter; present through the Andco Instance instead",
     });
 }
+function idOf(intent) {
+    return typeof intent === "string" ? intent : intent.id;
+}
 /** Intent identifiers are UUIDs; anything else never reaches the network. */
 function assertIntentId(value) {
     return INTENT_ID_PATTERN.test(value)