@andco/sdk 0.0.2 → 0.0.4

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 Andco
+   Copyright 2026 Haulmer
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -1,7 +1,13 @@
 # `@andco/sdk`
 
+> [!WARNING]
+> **Pre-1.0 software.** Until version 1.0.0 is released, any new version may include breaking
+> changes, including minor and patch releases. Expect any API incompatibility and data resets
+> in the Andco environments without prior notice. Pin an exact version and review the release
+> notes before upgrading.
+
 The core AndCo SDK: one client shape (`AndcoClient`) with a builder per runtime — browser,
-server, and CLI. There is no separate `@andco/sdk-js` package; this package is the universal
+server, and CLI. There is no separate `@andco/andco-sdk-js` package; this package is the universal
 one, and its `./browser`, `./server`, and `./cli` subpaths are how it adapts to each runtime.
 
 ## Install
@@ -61,9 +67,8 @@ const andco = createAndcoInstanceForCLI({
 const { data: session } = await andco.auth.signIn();
 ```
 
-Every builder returns an `AndcoClient`. There is no `AndcoSessionClient` — that type was removed;
-`AndcoClient` (unauthenticated arm) and `AndcoClientAuthed` (authenticated arm) are the only two
-client shapes now.
+Every builder returns an `AndcoClient`. There are two client shapes: `AndcoClient`, the
+unauthenticated arm, and `AndcoClientAuthed`, the authenticated one.
 
 ## Public, no credentials involved
 
@@ -75,7 +80,7 @@ const { data, error } = await andco.rest.http.GET("/catalog/permissions");
 if (error) throw error;
 ```
 
-## Binding credentials
+## Attaching credentials
 
 Two ways to get an `AndcoClientAuthed`:
 
@@ -84,8 +89,8 @@ Two ways to get an `AndcoClientAuthed`:
   for the common server case where a handler already pulled a token out of its own session:
 
   ```ts
-  const bound = andco.with(await accessTokenFromCookie(request.headers));
-  const { data } = await bound.rest.http.GET("/accounts");
+  const client = andco.with(await accessTokenFromCookie(request.headers));
+  const { data } = await client.rest.http.GET("/userinfo");
   ```
 
 - `andco.authorized()` returns the instance's own session, seen as authorized — a fresh reference
@@ -98,21 +103,23 @@ Two ways to get an `AndcoClientAuthed`:
 
 `AndcoCredentials` is the entire contract the SDK needs for authorization:
 
-```ts
+```ts nocheck
 export interface AndcoCredentials {
   accessTokenFor(resource: string): Promise<string | null>;
+  readonly config?: AndcoConfig;
 }
 ```
 
-Any object with that one method works — a Better Auth account, a Passport session, a row in your
+`config` is optional: `andco.with()`, `andco.authorized()` and `service.credentials()` carry it, so
+`new Bank(credentials)` takes its client id and endpoint from the credentials instead of declaring
+them again. Any object with `accessTokenFor` works — a Better Auth account, a Passport session, a row in your
 own table, or a plain closure — without adopting the SDK's own persistence.
 
 ## Resource Server Definitions
 
-`AndcoBoundClient` was removed. In its place, a Resource Server Definition is any object that
-implements:
+A Resource Server Definition is any object that implements:
 
-```ts
+```ts nocheck
 interface AndcoResourceServer<Client> {
   readonly id: string;
   readonly resource: string;
@@ -127,67 +134,102 @@ satisfy `AndcoCredentials` and can be passed straight to `use(...)`.
 
 ## Intents
 
-`andco.intents` is domain-neutral: it only knows how to create, read, execute, and observe an
-Intent generically. It does not know about deposits, withdrawals, or any other domain concept —
-those belong to whatever Resource Server Definition owns that domain, composed over this same
-surface (see [Resource Server Definitions](#resource-server-definitions) above), such as the AndCo
-Bank Resource Server Definition in [`@andco/bank-sdk`](../bank-sdk/README.md).
+`andco.intents` is the domain-neutral lifecycle of an Intent: read, present, approve, reject,
+cancel and follow it. Creating one belongs to the Resource Server Definition that owns the domain —
+`bank.transfers.create`, `bank.deposits.create`, `bank.accounts.create` in
+[`@andco/bank-sdk`](https://www.npmjs.com/package/@andco/bank-sdk) — composed over this same
+surface (see [Resource Server Definitions](#resource-server-definitions) above). Every method takes
+the Intent or its id.
 
 ```ts
-const { data: intent, error } = await andco.intents.create(
-  "deposit",
-  depositInput,
-  {
-    idempotencyKey: "deposit:8472",
-  },
+import { Bank } from "@andco/bank-sdk";
+
+const bank = new Bank(andco.authorized());
+
+const { data: deposit, error } = await bank.deposits.create(
+  { amount: { currency: "CLP", value: "25990" } },
+  { idempotencyKey: "deposit:8472" },
 );
 if (error) throw error;
+
+const presentation = andco.intents.present(deposit, { presentation: "popup" });
+const { data } = await presentation.result;
+if (data?.outcome === "complete") console.log("[deposit] %s", data.intent.status);
 ```
 
-- `create(type, input, options?)` — creates an Intent of the given type; `type` is sent as the
-  body's own `type`, so the input never repeats it, and the response's `type` is checked against it.
-  Resolves to `Result<AndcoIntent>` — the Intent union of Andco's own contract — unless a
-  third-party Resource Server Definition names its own response type.
-- `get(intentId)` — reads the authoritative state of one Intent, as `Result<AndcoIntent>` by the
-  same rule.
-- `execute(intentId)` — executes an Intent whose Grant permits it.
-- `events(intentId, after?, signal?)` — reads one page of durable Intent facts.
-- `subscribe(subject, read, decode, handler, options)` — a durable, paged subscription loop, with
-  its own checkpoint and poll-interval reconciliation. Returns an unsubscribe function.
-
-For the actual bank operations — `createDeposit`, `createWithdrawal`, `createAutomaticCharge`,
-`closeDeposit`, and account/intent event listeners — see
-[`@andco/bank-sdk`](../bank-sdk/README.md), whose `Bank` definition composes this same
-domain-neutral surface:
+- `present(intent | id | factory, { presentation, returnTo, errorReturnTo, signal })` — returns a
+  controller `{ status, result, close() }` at once. `presentation` is `"popup"` (default),
+  `"newtab"` or `"redirect"`. The window opens inside the click that called it; `result` settles
+  with `{ outcome, intent }`, the Intent read again afterwards. With `"redirect"` the document is
+  replaced and `result` never settles. The SDK always generates and checks `state`.
+- `fromCallback(url, { state? })` — on the return page of a `"redirect"` or `"newtab"`, reads the
+  outcome and the Intent. It refuses a `state` this browser did not start (`invalid_callback`) and
+  consumes each presentation once.
+- `presentationURL(intent, { presentation })` — synchronous URL that presents the Intent, with its
+  callbacks bound; `presentationURLFor(intentId, options)` reads the Intent first. Never intercepted
+  by a native Host.
+- `get(intent)` — reads the authoritative state of one Intent, as `Result<AndcoIntent>`.
+- `approve(intent, { grant? })` — approves with this credential's Grant, which must hold `approve`
+  on the Intent's family, within its maximum. Fails with `amount_out_of_grant` above the maximum
+  (the Intent stays pending for another approver) and `intent_expired` past its deadline.
+- `reject(intent, { reason })` — rejects as an approver; `cancel(intent, { reason })` withdraws it as
+  the creator. The reason is required, 1–280 characters.
+- `subscribe(intent, [{ types, after, onCheckpoint, onError, pollIntervalMs }], handler)` — follows
+  the Intent's durable facts in order. Returns an unsubscribe function.
+- `events(intent, after?, signal?)` — reads one page of durable Intent facts.
+- `create(type, input, options?)` and `createSigned(type, instruction)` — the generic creation a
+  third-party Resource Server Definition composes. `type` is sent as the body's own `type` and
+  checked against the response.
+
+A Service (`createAndcoService` from `@andco/sdk/server`) gets the same surface, bound to its
+Client Credentials for one Organization, with `service.intents({ subject?, grant? })`:
 
 ```ts
-import { Bank } from "@andco/bank-sdk";
+await service.intents({ subject: { type: "organization", identifier: "123" } }).approve(transferId);
+```
 
-const bankDefinition = new Bank({ clientId, resource: "https://api.andco.cl" });
-const bank = bankDefinition.use(andco.with(session));
+The browser must retrieve the authoritative Intent state after presentation; callback parameters
+are correlation data, not financial state. In React, `useIntent(intentId | null)` from
+`@andco/sdk-react` tracks an Intent until it reaches a terminal status.
 
-const { data: deposit, error } = await bank.intents.createDeposit(
-  depositInput,
-  {
-    idempotencyKey: "deposit:8472",
-  },
-);
-if (error) throw error;
+## Tokens, Grants and Resource Servers
+
+A Resource Server of your own verifies what reaches it with the same instance:
+
+```ts
+const { data: claims, error } = await andco.tokens.verify(bearer, {
+  audience: "https://api.casa-norte.example",
+});
+
+const { data: grant } = await andco.grants.get(bearer);
+
+const orders = andco.resource({ resource: "https://api.casa-norte.example" });
+export async function GET(request: Request) {
+  const outcome = await orders.protect({ scopes: ["orders:read"] })(request);
+  if (outcome instanceof Response) return outcome; // 401 or 403 with WWW-Authenticate
+  return Response.json({ subject: outcome.data?.subject });
+}
 ```
 
-Present the resulting intent with `@andco/sdk-react`, `@andco/sdk-vue`, `@andco/sdk-svelte`, or
-`@andco/sdk-script`. The browser must retrieve the authoritative intent state after presentation;
-callback parameters are correlation data, not financial state.
+- `tokens.verify(token, { audience?, clockToleranceSeconds? })` verifies signature (RS256/ES256),
+  `exp`, `nbf`, `iss` and `aud` offline against the Authorization Server's JWKS, cached by `kid`.
+- `grants.get(token)` reads the live Grant behind a token (`GET /authorization`), in its Grant form.
+- `resource({ resource }).protect({ scopes, authorizationDetails })` is a guard that answers
+  `401`/`403` with `WWW-Authenticate`; `.hono()` and `.express()` adapt it to a framework.
+
+Concurrent token refreshes share one in-flight promise through `AndcoInflight` (`MemoryInflight` by
+default; pass your own as `inflight` to share it across processes). `auth.refresh()` goes through
+it too.
 
 ## Exports
 
 - `@andco/sdk` — `AndcoClient`, `AndcoAuth`, `AndcoConfig`, credential types and helpers,
-  `AndcoIntents`, `AndcoOAuth`, `AndcoRest`, `AndcoSessionStore`, storage adapters, and error
+  `AndcoIntents`, `AndcoTokens`, `AndcoGrants`, `AndcoOAuth`, `AndcoRest`, `AndcoSessionStore`, storage adapters, and error
   types. See `packages/sdk/src/index.ts` for the exhaustive list.
 - `@andco/sdk/browser` — `createAndcoInstanceForBrowser`, `browserPresenter`, the popup/iframe
   bridge, and the Andco Button controller.
 - `@andco/sdk/server` — `createAndcoInstanceForServer`.
-- `@andco/sdk/cli` — `createAndcoInstanceForCLI`, `AndcoCliPresenter`.
+- `@andco/sdk/cli` — `createAndcoInstanceForCLI`, `AndcoPresenterCli`.
 
 There is intentionally no wildcard subpath export. This prevents internal files and runtime-only
 implementations from becoming accidental public API.
@@ -196,6 +238,6 @@ implementations from becoming accidental public API.
 
 - Never place confidential OAuth client secrets in browser code.
 - Use a distinct OAuth client for each environment.
-- Request the smallest scopes needed by the current operation.
+- Request the smallest permissions needed by the current operation: OIDC scopes only for identity, and a Grant Request per resource.
 - Preserve idempotency keys across retries of the same financial operation.
 - Treat all returned identity, account, and profile fields as personal data.

package/dist/auth.d.ts

@@ -1,20 +1,25 @@
-import { type AndCoRandomSource } from "@andco/protocol";
+import type { AndcoConfig } from "./config.js";
 import type { AndcoSession } from "./credentials.js";
 import { Result } from "./errors.js";
+import { type AndcoGlobals } from "./globals.js";
 import type { AndcoAuthorizationOptions, AndcoAuthorizationRequest, AndcoOAuth } from "./oauth.js";
 import type { AndcoPresentation, AndcoPresenter } from "./presenter.js";
 import type { AndcoSessionStore } from "./session-store.js";
+/** Authorization parameters plus the presentation used to start sign-in. */
 export type AndcoSignInOptions = AndcoAuthorizationOptions & {
     presentation?: AndcoPresentation;
 };
+/** Collaborators that prepare, present, exchange, and persist one authorization. */
 export type AndcoAuthOptions = {
+    /** Read for the registered callback, which has to be known before the request is prepared. */
+    config: AndcoConfig;
     oauth: AndcoOAuth;
     store: AndcoSessionStore;
     presenter: AndcoPresenter;
     /** Generates the Presentation ID. Injected so a test can make one deterministic. */
     randomId?: () => string;
-    /** Random source for the Presentation ID, threaded from the client's `globals.crypto`. */
-    crypto?: AndCoRandomSource;
+    /** Platform capabilities; `crypto` sources the Presentation ID. Defaults to the runtime's own. */
+    globals?: AndcoGlobals;
     /**
      * Persists a transaction before it is presented.
      *

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAe,MAAM,iBAAiB,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAqB,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACnG,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GAAG;IAC3D,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,cAAc,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAS;;gBAGD,OAAO,EAAE,gBAAgB;IAI5C;;;;;OAKG;IACU,MAAM,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IA4B3F,iGAAiG;IACpF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAI7C;;;;;;;;OAQG;IACI,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI;IAK7E,gFAAgF;IACnE,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAO/D,uFAAuF;IAC1E,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;CAWtD"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAqB,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,cAAc,CAAC;AACjE,OAAO,KAAK,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACnG,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GAAG;IAC3D,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,8FAA8F;IAC9F,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,cAAc,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACxB,kGAAkG;IAClG,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAS;;gBAID,OAAO,EAAE,gBAAgB;IAK5C;;;;;OAKG;IACU,MAAM,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IA4C3F,iGAAiG;IACpF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAI7C;;;;;;;;OAQG;IACI,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI;IAK7E,gFAAgF;IACnE,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAO/D,uFAAuF;IAC1E,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;CAGtD"}

package/dist/auth.js

@@ -1,5 +1,6 @@
-import { RANDOM_UUID } from "@andco/protocol";
+import { RANDOM_UUID, SafeURL } from "@andco/protocol";
 import { ANDCO_ERROR_CODES, Result } from "./errors.js";
+import { resolveGlobals } from "./globals.js";
 /**
  * Sign-in for a runtime that owns exactly one session.
  *
@@ -19,8 +20,10 @@ import { ANDCO_ERROR_CODES, Result } from "./errors.js";
  */
 export class AndcoAuth {
     #options;
+    #globals;
     constructor(options) {
         this.#options = options;
+        this.#globals = options.globals ?? resolveGlobals();
     }
     /**
      * Runs one authorization end to end.
@@ -29,17 +32,32 @@ export class AndcoAuth {
      * result arrives on the next page load, through the store's own callback consumption.
      */
     async signIn(options = {}) {
-        const { oauth, presenter, store } = this.#options;
-        const presentationId = this.#options.randomId ? this.#options.randomId() : RANDOM_UUID(this.#options.crypto);
-        const prepared = await oauth.createAuthorizationRequest(options);
-        if (prepared.error)
-            return Result.fail(prepared.error);
-        await this.#options.persistTransaction?.(prepared.data);
-        const returnTo = new URL(prepared.data.redirectTo);
+        const { config, oauth, presenter, store } = this.#options;
+        const presentationId = this.#options.randomId ? this.#options.randomId() : RANDOM_UUID(this.#globals.crypto);
+        // The callback has to be known before the request is prepared, because the presenter needs it
+        // to open its window. It is registered configuration, so it is knowable without the round trip.
+        const configured = options.redirectTo ?? config.redirectTo;
+        if (!configured) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                message: "`redirectTo` is required, on the instance or on the request",
+            });
+        }
+        // Deferred: preparing the request may push it (PAR), and a presenter has to open its window
+        // during the user activation rather than after a network round trip.
+        let prepared;
         const presented = await presenter.present({
-            url: prepared.data.authorizationUrl,
+            kind: "oauth",
+            url: async () => {
+                const request = await oauth.createAuthorizationRequest(options);
+                if (request.error) {
+                    throw request.error;
+                }
+                await this.#options.persistTransaction?.(request.data);
+                prepared = request.data;
+                return request.data.authorizationUrl;
+            },
             presentation: options.presentation ?? "popup",
-            returnTo,
+            returnTo: new SafeURL(configured),
             presentationId,
         });
         if (presented.error)
@@ -47,7 +65,9 @@ export class AndcoAuth {
         // Either the document was replaced, or the user dismissed. Neither is an error.
         if (!presented.data)
             return Result.ok(null);
-        const exchanged = await oauth.exchangeCallback({ callbackUrl: presented.data, request: prepared.data });
+        if (!prepared)
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK, { message: "no transaction was prepared" });
+        const exchanged = await oauth.exchangeCallback({ callbackUrl: presented.data, request: prepared });
         if (exchanged.error)
             return Result.fail(exchanged.error);
         const written = await store.set(exchanged.data);
@@ -82,17 +102,6 @@ export class AndcoAuth {
     }
     /** Refreshes now rather than waiting for a token request to find the session stale. */
     async refresh() {
-        const store = this.#options.store;
-        await store.ready;
-        const current = store.getSnapshot();
-        if (!current?.refreshToken)
-            return Result.fail(ANDCO_ERROR_CODES.SESSION_MISSING);
-        const refreshed = await this.#options.oauth.refresh(current.refreshToken);
-        if (refreshed.error)
-            return Result.fail(refreshed.error);
-        const written = await store.set(refreshed.data);
-        if (written.error)
-            return Result.fail(written.error);
-        return Result.ok(refreshed.data);
+        return this.#options.store.refresh();
     }
 }

package/dist/browser/controller.d.ts

@@ -1,22 +1,32 @@
 import type { AndCoClickEvent, AndCoErrorEvent, AndCoReadyEvent, AndCoThemeMode } from "@andco/protocol";
 import type { AndcoClient } from "../client.js";
 import { AndcoError } from "../errors.js";
+import type { AndcoIntentId, AndcoPresentationResult } from "../intents.js";
 import type { AndcoAuthorizationOptions } from "../oauth.js";
 import type { AndcoPresentation } from "../presenter.js";
 /** The hosted workflow an iframe presents. */
 export type AndcoButtonFlow = "authorization" | "intent";
 /** Observable lifecycle of one hosted Andco surface. */
 export type AndcoButtonStatus = "idle" | "connecting" | "ready" | "authorizing" | "complete" | "dismissed" | "error";
+/** Hosted surface URL, lifecycle status, and the most recent failure. */
 export type AndcoButtonSnapshot = {
     status: AndcoButtonStatus;
     iframeURL: string;
     ready: boolean;
     error: AndcoError | null;
 };
+/** Hosted control configuration and callbacks for authorization or Intent presentation. */
 export type AndcoButtonControllerOptions = {
     /** The instance whose configuration, protocol, and session this surface acts on. */
     client: AndcoClient;
+    /** Authorization by default; `intent` requires an `intentId`. */
     flow?: AndcoButtonFlow;
+    /**
+     * Required when `flow` is `"intent"`. Resolved after the user activates, never before: the iframe
+     * holds the activation and opens the window first, so creating the Intent earlier would make one
+     * on every render and lose the activation that the window needs.
+     */
+    intentId?: AndcoIntentId;
     /** Widget release to load. Defaults to the release the SDK was built against. */
     release?: number;
     /** Changes while the application runs, unlike endpoints and versions. */
@@ -28,13 +38,20 @@ export type AndcoButtonControllerOptions = {
     presentation?: AndcoPresentation;
     /** Request-local authorization options, applied when the user activates the surface. */
     authorization?: AndcoAuthorizationOptions;
+    /** Runs after the hosted surface completes its handshake. */
     onReady?: (event: AndCoReadyEvent) => void;
+    /** Runs when the user activates the hosted control, before authorization starts. */
     onActivate?: (event: AndCoClickEvent) => void;
-    onComplete?: () => void;
+    /** Carries the Presentation Result on an Intent flow, and nothing on an authorization. */
+    onComplete?: (outcome?: AndcoPresentationResult) => void;
+    /** Runs when the user closes or declines the presentation. */
     onDismiss?: () => void;
+    /** Receives lifecycle failures; use the error code for diagnostics. */
     onError?: (error: AndcoError, event?: AndCoErrorEvent) => void;
 };
 type Listener = (snapshot: AndcoButtonSnapshot) => void;
+/** Renders a style record — property names only, no camelCase — as inline CSS text. */
+declare function frameStyleText(style: Readonly<Record<string, string>>): string;
 /**
  * Coordinates one hosted Andco iframe without owning how a framework renders it.
  *
@@ -45,6 +62,15 @@ type Listener = (snapshot: AndcoButtonSnapshot) => void;
  * Render `snapshot.iframeURL` in your platform's own iframe element, then hand that element to
  * `connect()` once it mounts.
  *
+ * The frame's fixed attributes and default sizing are published as static data —
+ * {@link AndcoButtonController.IFRAME_SANDBOX}, {@link AndcoButtonController.IFRAME_REFERRER_POLICY},
+ * {@link AndcoButtonController.IFRAME_DEFAULT_STYLE}, and {@link AndcoButtonController.frameProps} for
+ * the snapshot-derived `src`/`hidden` pair — so every binding applies the same contract to its own
+ * element instead of redeclaring it. `sdk-script`'s custom element is the one exception on sizing: it
+ * sizes itself through a stylesheet layer (using {@link AndcoButtonController.DEFAULT_SIZE}, so the
+ * visible default stays the same) and stretches its internal iframe to fill it, so that an author's
+ * own CSS on `andco-button` wins without touching the iframe's inline style.
+ *
  * @example
  * ```ts
  * const controller = new AndcoButtonController({ client: andco, onComplete: reload });
@@ -54,12 +80,39 @@ type Listener = (snapshot: AndcoButtonSnapshot) => void;
  */
 export declare class AndcoButtonController {
     #private;
+    /** @see {@link IFRAME_SANDBOX} */
+    static readonly IFRAME_SANDBOX = "allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox";
+    /** @see {@link IFRAME_REFERRER_POLICY} */
+    static readonly IFRAME_REFERRER_POLICY = "no-referrer";
+    /** @see {@link IFRAME_BASE_STYLE} */
+    static readonly IFRAME_BASE_STYLE: Readonly<Record<string, string>>;
+    /** @see {@link DEFAULT_SIZE} */
+    static readonly DEFAULT_SIZE: Readonly<Record<string, string>>;
+    /** @see {@link IFRAME_DEFAULT_STYLE} */
+    static readonly IFRAME_DEFAULT_STYLE: Readonly<Record<string, string>>;
+    /**
+     * Renders a style record as inline CSS text, for a binding that needs a string rather than an
+     * object — Svelte's `style` attribute and `sdk-script`'s `HTMLElement.style.cssText`.
+     */
+    static readonly frameStyleText: typeof frameStyleText;
+    /**
+     * The two iframe attributes a snapshot drives, mapped from protocol terms to DOM ones.
+     *
+     * Every binding applies this on top of {@link AndcoButtonController.IFRAME_SANDBOX} and
+     * {@link AndcoButtonController.IFRAME_REFERRER_POLICY}: those two are fixed, this pair changes
+     * with the connection.
+     */
+    static frameProps(snapshot: AndcoButtonSnapshot): {
+        src: string;
+        hidden: boolean;
+    };
     constructor(options: AndcoButtonControllerOptions);
     get snapshot(): AndcoButtonSnapshot;
     /** Observes lifecycle changes. The return value is the unsubscribe. */
     subscribe(listener: Listener): () => void;
     /** Attaches a mounted iframe. The return value disconnects it. */
     connect(iframe: HTMLIFrameElement): () => void;
+    /** Detaches the iframe bridge while retaining listeners and the last iframe for reuse. */
     disconnect(): void;
     /**
      * Returns the surface to its ready state so it can be activated again.
@@ -70,6 +123,7 @@ export declare class AndcoButtonController {
      * recover, so this reconnects against the last-connected iframe instead.
      */
     restart(): void;
+    /** Releases the bridge, iframe reference, and all snapshot listeners. */
     destroy(): void;
 }
 export {};

package/dist/browser/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/browser/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAIf,eAAe,EACf,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAqB,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,yBAAyB,EAA6B,MAAM,aAAa,CAAC;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,8CAA8C;AAC9C,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,QAAQ,CAAC;AAEzD,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC;AAErH,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,oFAAoF;IACpF,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,oGAAoG;IACpG,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,wFAAwF;IACxF,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAC3C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAC9C,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;CAChE,CAAC;AAEF,KAAK,QAAQ,GAAG,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,qBAAqB;;gBAcb,OAAO,EAAE,4BAA4B;IAKxD,IAAW,QAAQ,IAAI,mBAAmB,CAEzC;IAED,uEAAuE;IAChE,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI;IAQhD,kEAAkE;IAC3D,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAiD9C,UAAU,IAAI,IAAI;IAKzB;;;;;;;OAOG;IACI,OAAO,IAAI,IAAI;IAgBf,OAAO,IAAI,IAAI;CA8FvB"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/browser/controller.ts"],"names":[],"mappings":"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"}