@andco/sdk 0.0.1

package/dist/browser/controller.js

@@ -0,0 +1,215 @@
+import { ANDCO_ERROR_CODES as ANDCO_PROTOCOL_ERROR_CODES, ANDCO_RELEASE, callbackStateCreate } from "@andco/protocol";
+import { ANDCO_ERROR_CODES, AndcoError } from "../errors.js";
+import { AndcoButtonBridge } from "./frame.js";
+/**
+ * Coordinates one hosted Andco iframe without owning how a framework renders it.
+ *
+ * The iframe is Andco-deployed and cross-origin, which is what the Hosted Intent Button buys: the
+ * visible control's DOM and code are not the Project's, and the popup handle never enters Project
+ * JavaScript. It is not an authorization boundary and does not protect Project tokens.
+ *
+ * Render `snapshot.iframeURL` in your platform's own iframe element, then hand that element to
+ * `connect()` once it mounts.
+ *
+ * @example
+ * ```ts
+ * const controller = new AndcoButtonController({ client: andco, onComplete: reload });
+ * const stop = controller.subscribe((snapshot) => setState(snapshot));
+ * const disconnect = controller.connect(iframeElement);
+ * ```
+ */
+export class AndcoButtonController {
+    #options;
+    #listeners = new Set();
+    #bridge;
+    #iframe;
+    #snapshot;
+    #pending;
+    #presentationId;
+    #generation = 0;
+    /** One automatic reconnect per `connect()` call, so a single slow network blip self-heals without
+     * bothering the app — but a persistently broken endpoint still surfaces as a visible `"error"`
+     * rather than retrying forever and hiding a real misconfiguration. */
+    #timedOutOnce = false;
+    constructor(options) {
+        this.#options = options;
+        this.#snapshot = { status: "idle", iframeURL: this.#iframeURL(), ready: false, error: null };
+    }
+    get snapshot() {
+        return this.#snapshot;
+    }
+    /** Observes lifecycle changes. The return value is the unsubscribe. */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        listener(this.#snapshot);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** Attaches a mounted iframe. The return value disconnects it. */
+    connect(iframe) {
+        this.disconnect();
+        this.#iframe = iframe;
+        console.debug("[AndcoButtonController] connecting: %o", { iframeURL: this.#snapshot.iframeURL });
+        this.#publish({ status: "connecting", ready: false, error: null });
+        try {
+            this.#bridge = new AndcoButtonBridge(iframe, {
+                endpointButton: this.#iframeURL(),
+                onReady: (event) => {
+                    this.#publish({ status: "ready", ready: true });
+                    this.#options.onReady?.(event);
+                },
+                onActivate: (event) => {
+                    this.#presentationId = event.presentationId;
+                    this.#options.onActivate?.(event);
+                    void this.#authorize();
+                },
+                onComplete: (event) => void this.#settle(event),
+                onDismiss: () => {
+                    this.#publish({ status: "dismissed" });
+                    this.#options.onDismiss?.();
+                },
+                onAuthorizationError: (event) => this.#fail(new AndcoError(event.error.code, {
+                    message: event.error.description,
+                })),
+                onError: (event) => {
+                    // A single automatic reconnect on a timed-out handshake, and only that one code: it is the
+                    // one transient failure the bridge itself cannot retry past (it deliberately settles
+                    // permanently once it gives up, see `AndcoButtonBridge`). Everything else — a rejected
+                    // iframe, an untrusted origin — is not a timing fluke and retrying it would just repeat it.
+                    const timedOut = event.error.code === ANDCO_PROTOCOL_ERROR_CODES.HANDSHAKE_TIMEOUT;
+                    if (timedOut && !this.#timedOutOnce && this.#iframe) {
+                        this.#timedOutOnce = true;
+                        console.debug("[AndcoButtonController] handshake timed out", { action: "reconnect", retry: 1 });
+                        this.connect(this.#iframe);
+                        return;
+                    }
+                    this.#fail(new AndcoError(event.error.code), event);
+                },
+            });
+        }
+        catch (cause) {
+            this.#fail(AndcoError.from(cause, ANDCO_ERROR_CODES.INVALID_IFRAME));
+        }
+        return () => this.disconnect();
+    }
+    disconnect() {
+        this.#bridge?.destroy();
+        this.#bridge = undefined;
+    }
+    /**
+     * Returns the surface to its ready state so it can be activated again.
+     *
+     * A bridge that ended in `"error"` — a timed-out or failed handshake — has already settled
+     * permanently and silently ignores every message after that, including a late `"ready"`. Resetting
+     * the status without rebuilding it would show a working button over a bridge that can never
+     * recover, so this reconnects against the last-connected iframe instead.
+     */
+    restart() {
+        this.#generation += 1;
+        this.#pending = undefined;
+        if (this.#snapshot.status === "error" && this.#iframe) {
+            // A deliberate retry (the app calling this after showing the error) earns its own one-shot
+            // auto-reconnect on a future timeout, same as the very first connect did.
+            this.#timedOutOnce = false;
+            console.debug("[AndcoButtonController] restarting after an error, reconnecting: %o", {
+                code: this.#snapshot.error?.code,
+            });
+            this.connect(this.#iframe);
+            return;
+        }
+        this.#publish({ status: this.#bridge ? "ready" : "idle", error: null });
+    }
+    destroy() {
+        this.disconnect();
+        this.#iframe = undefined;
+        this.#listeners.clear();
+    }
+    /**
+     * Prepares an authorization once the user has activated the hosted control.
+     *
+     * Deferred on purpose: the iframe holds the user activation and opens the popup synchronously,
+     * then asks for the URL. Preparing it earlier would waste a transaction on every render and,
+     * for an Intent, create one before anyone asked for it.
+     */
+    async #authorize() {
+        const generation = ++this.#generation;
+        this.#publish({ status: "authorizing", error: null });
+        // The hosted surface opens the popup, so the callback has to know to deliver its result there.
+        // Encoding that in the state is the protocol's own mechanism and the only one available: the
+        // callback document cannot read a cross-origin opener's location.
+        const prepared = await this.#options.client.oauth.createAuthorizationRequest({
+            ...(this.#options.authorization ?? {}),
+            state: callbackStateCreate(this.#options.client.config.endpoints.widget.origin, this.#presentationId),
+        });
+        if (generation !== this.#generation)
+            return;
+        if (prepared.error)
+            return this.#fail(prepared.error);
+        this.#pending = prepared.data;
+        this.#bridge?.resolveAuthorization(this.#presentationId, prepared.data.authorizationUrl.href);
+    }
+    async #settle(event) {
+        const generation = this.#generation;
+        const request = this.#pending;
+        this.#pending = undefined;
+        // A public PKCE completion carries a one-time code the opener must exchange; a host-managed or
+        // Intent completion carries only a lifecycle outcome, and the authenticated read is authoritative.
+        if (event.type === "oauth.authorization_code" && request) {
+            const callbackUrl = new URL(request.redirectTo);
+            callbackUrl.searchParams.set("code", event.authorizationCode);
+            callbackUrl.searchParams.set("state", request.state);
+            const exchanged = await this.#options.client.oauth.exchangeCallback({ callbackUrl, request });
+            if (generation !== this.#generation)
+                return;
+            if (exchanged.error)
+                return this.#fail(exchanged.error);
+            const written = await this.#options.client.session.set(exchanged.data);
+            if (written.error)
+                return this.#fail(written.error);
+        }
+        if (generation !== this.#generation)
+            return;
+        this.#publish({ status: "complete", error: null });
+        this.#options.onComplete?.();
+    }
+    #fail(error, event) {
+        // An app that never wired `onError` must not lose the failure entirely — a button that just sits
+        // there disabled, with nothing in the console, is what made the last one of these hard to find.
+        console.error("[AndcoButtonController] %s: %o", error.code, { message: error.message, details: error.details });
+        this.#publish({ status: "error", error });
+        this.#options.onError?.(error, event);
+    }
+    #iframeURL() {
+        const config = this.#options.client.config;
+        const url = config.widgetURL(this.#options.release ?? ANDCO_RELEASE);
+        url.searchParams.set("themeMode", this.#options.themeMode ?? config.themeMode);
+        url.searchParams.set("locale", this.#options.locale ?? config.locale);
+        url.searchParams.set("theme", config.theme);
+        url.searchParams.set("flow", this.#options.flow ?? "authorization");
+        url.searchParams.set("presentation", this.#options.presentation ?? "popup");
+        // The hosted surface renders its own authorization affordances, so it has to reach the same
+        // Authorization Server as the instance. Omitting this let it fall back to the production
+        // origin, which is invisible in development until nothing works.
+        url.searchParams.set("endpointAuth", config.endpoints.auth.href);
+        // The hosted contract needs the client it represents and the callback it will return to: it
+        // derives its trusted parent origin from the callback during local development, and refuses to
+        // enable itself without both. Both come from the instance, never from a component prop — the
+        // rule is that a *component* does not accept endpoints, not that the hosted contract can go
+        // without them.
+        url.searchParams.set("clientId", config.clientId);
+        if (config.redirectTo)
+            url.searchParams.set("redirectTo", config.redirectTo.href);
+        // The hosted contract spells booleans out; "1" is rejected by its parameter schema.
+        if (this.#options.disabled !== undefined)
+            url.searchParams.set("disabled", String(this.#options.disabled));
+        if (this.#options.busy !== undefined)
+            url.searchParams.set("busy", String(this.#options.busy));
+        return url.href;
+    }
+    #publish(patch) {
+        this.#snapshot = { ...this.#snapshot, ...patch, iframeURL: this.#iframeURL() };
+        for (const listener of [...this.#listeners])
+            listener(this.#snapshot);
+    }
+}

package/dist/browser/frame.d.ts

@@ -0,0 +1,65 @@
+import { type AndCoClickEvent, type AndCoErrorEvent, type AndCoIntentCompleteEvent, type AndCoIntentDismissEvent, type AndCoOAuthAuthorizationCodeEvent, type AndCoOAuthCompleteEvent, type AndCoOAuthDismissEvent, type AndCoOAuthErrorEvent, type AndCoPopupResult, type AndCoReadyEvent, type AndCoSetPreferencesMessage } from "@andco/protocol";
+/** Callbacks and endpoint required by a secure-button bridge. */
+export type AndcoFrameOptions = {
+    endpointButton: string;
+    onReady?: (event: AndCoReadyEvent) => void;
+    onError?: (event: AndCoErrorEvent) => void;
+    onComplete?: (event: AndCoOAuthAuthorizationCodeEvent | AndCoOAuthCompleteEvent | AndCoIntentCompleteEvent) => void;
+    onDismiss?: (event: AndCoOAuthDismissEvent | AndCoIntentDismissEvent) => void;
+    onAuthorizationError?: (event: AndCoOAuthErrorEvent) => void;
+    onActivate?: (event: AndCoClickEvent) => void;
+};
+/** Manages the protocol connection to a secure-button iframe.
+ *
+ * @example
+ * ```ts
+ * const bridge = new AndcoButtonBridge(iframe, { endpointButton });
+ * // When unmounting the iframe:
+ * bridge.destroy();
+ * ```
+ */
+export declare class AndcoButtonBridge {
+    private readonly iframe;
+    private readonly options;
+    private readonly url;
+    private settled;
+    private transport;
+    private port;
+    private handshakeTimer;
+    private handshakeTimeout;
+    private handshakeAttempts;
+    private handshakeStartedAt;
+    private destroyed;
+    constructor(iframe: HTMLIFrameElement, options: AndcoFrameOptions);
+    private stopHandshake;
+    private closePort;
+    private receive;
+    private readonly receiveWindow;
+    private readonly initialize;
+    private readonly startHandshake;
+    /** Sends a validated protocol message to the hosted iframe. */
+    private post;
+    /**
+     * Resolves a deferred authorization request from the hosted button.
+     * Omit the URL to close the pending popup after resolution fails.
+     *
+     * @example
+     * ```ts
+     * bridge.resolveAuthorization(presentationId, "https://app.example.com/oauth/start");
+     * ```
+     */
+    resolveAuthorization(presentationId: string, authorizationUrl?: string | URL): void;
+    /**
+     * Forwards a validated same-origin host callback to the iframe that owns the popup.
+     *
+     * This method is intended for SDK adapters that relay a callback through an
+     * established button bridge; application code normally uses `onComplete` or
+     * `onDismiss` instead.
+     */
+    forwardAuthorizationResult(message: AndCoPopupResult): void;
+    /** Updates locale or color scheme without recreating the iframe. */
+    setPreferences(preferences: Pick<AndCoSetPreferencesMessage, "locale" | "themeMode">): void;
+    /** Stops the handshake and releases listeners and the message channel. */
+    destroy(): void;
+}
+//# sourceMappingURL=frame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/browser/frame.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,eAAe,EAEpB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,EACrC,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAEhC,MAAM,iBAAiB,CAAC;AAGzB,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAC3C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gCAAgC,GAAG,uBAAuB,GAAG,wBAAwB,KAAK,IAAI,CAAC;IACpH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,GAAG,uBAAuB,KAAK,IAAI,CAAC;IAC9E,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC7D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC/C,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAY1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZ1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,SAAS,CAAS;gBAGP,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,iBAAiB;IAkB7C,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,OAAO;IAkDf,OAAO,CAAC,QAAQ,CAAC,aAAa,CAM5B;IAEF,OAAO,CAAC,QAAQ,CAAC,UAAU,CA8BzB;IAEF,OAAO,CAAC,QAAQ,CAAC,cAAc,CA0B7B;IAEF,+DAA+D;IAC/D,OAAO,CAAC,IAAI;IASZ;;;;;;;;OAQG;IACI,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,GAAG;IAWnF;;;;;;OAMG;IACI,0BAA0B,CAAC,OAAO,EAAE,gBAAgB;IAI3D,oEAAoE;IAC7D,cAAc,CAAC,WAAW,EAAE,IAAI,CAAC,0BAA0B,EAAE,QAAQ,GAAG,WAAW,CAAC;IAU3F,0EAA0E;IACnE,OAAO;CASf"}

package/dist/browser/frame.js

@@ -0,0 +1,237 @@
+import { ANDCO_ERROR_CODES as ANDCO_PROTOCOL_ERROR_CODES, ANDCO_PROTOCOL_VERSION, ANDCO_SDK_PROTOCOL, isAndCoBridgeMessage, } from "@andco/protocol";
+import { ANDCO_ERROR_CODES, AndcoError } from "../errors.js";
+/** Manages the protocol connection to a secure-button iframe.
+ *
+ * @example
+ * ```ts
+ * const bridge = new AndcoButtonBridge(iframe, { endpointButton });
+ * // When unmounting the iframe:
+ * bridge.destroy();
+ * ```
+ */
+export class AndcoButtonBridge {
+    iframe;
+    options;
+    url;
+    settled = false;
+    transport = "pending";
+    port;
+    handshakeTimer;
+    handshakeTimeout;
+    handshakeAttempts = 0;
+    handshakeStartedAt = 0;
+    destroyed = false;
+    constructor(iframe, options) {
+        this.iframe = iframe;
+        this.options = options;
+        if (typeof window === "undefined" || typeof document === "undefined") {
+            throw new AndcoError(ANDCO_ERROR_CODES.BROWSER_UNAVAILABLE);
+        }
+        else if (!(iframe instanceof HTMLIFrameElement)) {
+            throw new AndcoError(ANDCO_ERROR_CODES.INVALID_IFRAME, { details: { iframe } });
+        }
+        this.url = new URL(options.endpointButton);
+        if (this.url.origin === window.location.origin) {
+            throw new AndcoError(ANDCO_ERROR_CODES.SAME_ORIGIN_ENDPOINT, { details: { endpointButton: this.url.href } });
+        }
+        console.debug("[AndcoButtonBridge] created: %o", { endpointButton: this.url.href });
+        iframe.addEventListener("load", this.startHandshake);
+        this.startHandshake();
+    }
+    stopHandshake() {
+        if (this.handshakeTimer !== undefined) {
+            window.clearInterval(this.handshakeTimer);
+        }
+        if (this.handshakeTimeout !== undefined) {
+            window.clearTimeout(this.handshakeTimeout);
+        }
+        this.handshakeTimer = undefined;
+        this.handshakeTimeout = undefined;
+    }
+    closePort() {
+        this.port?.close();
+        this.port = undefined;
+    }
+    receive(message) {
+        if (!isAndCoBridgeMessage(message)) {
+            return;
+        }
+        switch (message["type"]) {
+            case "ready": {
+                if (this.settled)
+                    return;
+                this.settled = true;
+                this.stopHandshake();
+                console.debug("[AndcoButtonBridge] handshake settled: %o", {
+                    attempts: this.handshakeAttempts,
+                    transport: this.transport,
+                    elapsedMs: Date.now() - this.handshakeStartedAt,
+                });
+                this.options.onReady?.(message);
+                return;
+            }
+            case "error": {
+                if (!this.settled) {
+                    this.settled = true;
+                    this.stopHandshake();
+                }
+                console.warn("[AndcoButtonBridge] hosted surface reported an error: %o", message.error);
+                this.options.onError?.(message);
+                return;
+            }
+            case "oauth.authorization_code":
+            case "oauth.complete":
+            case "intent.complete": {
+                if (!this.settled)
+                    return;
+                this.options.onComplete?.(message);
+                return;
+            }
+            case "oauth.dismiss":
+            case "intent.dismiss": {
+                if (this.settled)
+                    this.options.onDismiss?.(message);
+                return;
+            }
+            case "oauth.error": {
+                // An Authorization Server error is not a decision, so it never becomes a dismissal.
+                if (this.settled)
+                    this.options.onAuthorizationError?.(message);
+                return;
+            }
+            case "click": {
+                if (this.settled)
+                    this.options.onActivate?.(message);
+                return;
+            }
+        }
+    }
+    receiveWindow = (event) => {
+        if (this.transport === "port" || event.origin !== this.url.origin || event.source !== this.iframe.contentWindow) {
+            return;
+        }
+        this.transport = "window";
+        this.receive(event.data);
+    };
+    initialize = () => {
+        const target = this.iframe.contentWindow;
+        if (!target)
+            return;
+        this.handshakeAttempts += 1;
+        this.closePort();
+        const channel = new MessageChannel();
+        this.port = channel.port1;
+        this.port.onmessage = (event) => {
+            if (this.transport === "window")
+                return;
+            this.transport = "port";
+            window.removeEventListener("message", this.receiveWindow);
+            this.receive(event.data);
+        };
+        const message = {
+            protocol: ANDCO_SDK_PROTOCOL,
+            version: ANDCO_PROTOCOL_VERSION,
+            type: "init",
+        };
+        try {
+            target.postMessage(message, this.url.origin, [channel.port2]);
+        }
+        catch (cause) {
+            // The iframe can still be on `about:blank` (inheriting this window's origin) the instant this
+            // runs, since `startHandshake` calls `initialize` once before the retry interval exists. That
+            // makes the very first attempt throw a targetOrigin mismatch; the 250ms retry loop recovers
+            // once the iframe has actually navigated, so a transient failure here is not fatal — but it is
+            // worth a log line, since a run that never recovers looks identical to this from the outside.
+            console.debug("[AndcoButtonBridge] init attempt %d could not post yet, retrying: %o", this.handshakeAttempts, {
+                cause,
+            });
+        }
+    };
+    startHandshake = () => {
+        this.stopHandshake();
+        this.settled = false;
+        this.transport = "pending";
+        this.handshakeAttempts = 0;
+        this.handshakeStartedAt = Date.now();
+        window.addEventListener("message", this.receiveWindow);
+        this.initialize();
+        this.handshakeTimer = window.setInterval(this.initialize, 250);
+        this.handshakeTimeout = window.setTimeout(() => {
+            this.settled = true;
+            this.stopHandshake();
+            this.closePort();
+            console.error("[AndcoButtonBridge] handshake timed out: %o", {
+                attempts: this.handshakeAttempts,
+                endpointButton: this.url.href,
+            });
+            const message = {
+                protocol: ANDCO_SDK_PROTOCOL,
+                version: ANDCO_PROTOCOL_VERSION,
+                type: "error",
+                // The wire protocol owns its own code vocabulary; SDK-raised codes are a separate set.
+                error: { code: ANDCO_PROTOCOL_ERROR_CODES.HANDSHAKE_TIMEOUT },
+            };
+            this.options.onError?.(message);
+        }, 10_000);
+    };
+    /** Sends a validated protocol message to the hosted iframe. */
+    post(message) {
+        if (this.destroyed || !this.settled)
+            return;
+        if (this.transport === "port" && this.port) {
+            this.port.postMessage(message);
+            return;
+        }
+        this.iframe.contentWindow?.postMessage(message, this.url.origin);
+    }
+    /**
+     * Resolves a deferred authorization request from the hosted button.
+     * Omit the URL to close the pending popup after resolution fails.
+     *
+     * @example
+     * ```ts
+     * bridge.resolveAuthorization(presentationId, "https://app.example.com/oauth/start");
+     * ```
+     */
+    resolveAuthorization(presentationId, authorizationUrl) {
+        const message = {
+            protocol: ANDCO_SDK_PROTOCOL,
+            version: ANDCO_PROTOCOL_VERSION,
+            type: "authorization-response",
+            presentationId,
+            authorizationUrl: authorizationUrl?.toString(),
+        };
+        this.post(message);
+    }
+    /**
+     * Forwards a validated same-origin host callback to the iframe that owns the popup.
+     *
+     * This method is intended for SDK adapters that relay a callback through an
+     * established button bridge; application code normally uses `onComplete` or
+     * `onDismiss` instead.
+     */
+    forwardAuthorizationResult(message) {
+        this.post(message);
+    }
+    /** Updates locale or color scheme without recreating the iframe. */
+    setPreferences(preferences) {
+        const message = {
+            protocol: ANDCO_SDK_PROTOCOL,
+            version: ANDCO_PROTOCOL_VERSION,
+            type: "set-preferences",
+            ...preferences,
+        };
+        this.post(message);
+    }
+    /** Stops the handshake and releases listeners and the message channel. */
+    destroy() {
+        if (this.destroyed)
+            return;
+        console.debug("[AndcoButtonBridge] destroyed: %o", { settled: this.settled, attempts: this.handshakeAttempts });
+        this.destroyed = true;
+        window.removeEventListener("message", this.receiveWindow);
+        this.iframe.removeEventListener("load", this.startHandshake);
+        this.stopHandshake();
+        this.closePort();
+    }
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,52 @@
+import { AndcoClient, type AndcoClientOptions } from "../client.js";
+import type { AndcoAuthorizationRequest } from "../oauth.js";
+import type { AndcoPresenter } from "../presenter.js";
+export { AndcoButtonController, type AndcoButtonControllerOptions, type AndcoButtonFlow, type AndcoButtonSnapshot, type AndcoButtonStatus, } from "./controller.js";
+export { AndcoButtonBridge, type AndcoFrameOptions } from "./frame.js";
+export { type AndcoPopupMessage, type AndcoPopupWindow, type AndcoRelayOutcome, andcoPopupPresentationId, isAndcoNativeHost, openAndcoPopup, openAndcoPopupWindow, relayAndcoPopupCallback, } from "./popup.js";
+/**
+ * Presents an authorization in a browser.
+ *
+ * It detects the first-party Andco Host and routes over the native bridge instead of opening a
+ * window, so a Miniapp runs the same build in a browser tab and inside the Host without branching
+ * on the platform. That is why there is no mobile presenter and no mobile builder.
+ */
+export declare function browserPresenter(): AndcoPresenter;
+export type AndcoBrowserOptions = Omit<AndcoClientOptions, "presenter" | "source" | "clientSecret"> & {
+    /** Rejected by type: a confidential credential must never reach a browser. */
+    clientSecret?: never;
+    presenter?: AndcoPresenter;
+    /** Whether an authorization code in the URL is exchanged during the load. Defaults to `true`. */
+    detectSessionInUrl?: boolean;
+    /** Whether this document relays a callback to its opener when it is an Andco popup. Default `true`. */
+    relayPopupCallback?: boolean;
+    /** Replaces the URL after consumption. Defaults to the History API. */
+    replaceUrl?: (url: URL) => void;
+    /** Recovers the transaction started before the redirect. Supplied by the SDK's own storage. */
+    transactionStorage?: Storage;
+};
+/**
+ * Creates an Andco Instance for a browser.
+ *
+ * Construction is synchronous and performs no I/O. The one effect it does perform is the popup
+ * relay, and only when five conditions hold: this document has an opener, its `window.name` carries
+ * a valid Presentation ID, the URL carries callback parameters, the state parses, and the opener
+ * origin is allowed. A normal page fails the first two and the call is inert.
+ *
+ * Exchanging an authorization code is *not* done here. That is a credential write, the code is
+ * single-use, and a construction a framework discards must not burn it — so it happens lazily, on
+ * the store's first read.
+ *
+ * @example
+ * ```ts
+ * const andco = createAndcoInstanceForBrowser({
+ *   clientId: "your-public-oauth-client-id",
+ *   redirectTo: "https://app.example.com/auth/callback",
+ *   initialScopes: ["openid", "email", "profile"],
+ * });
+ * ```
+ */
+export declare function createAndcoInstanceForBrowser(options: AndcoBrowserOptions): AndcoClient;
+/** Persists a transaction across a full-page redirect. Used by the redirect presentation. */
+export declare function storeAndcoTransaction(clientId: string, request: AndcoAuthorizationRequest, storage?: Storage): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIpE,OAAO,KAAK,EAAE,yBAAyB,EAAc,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAItD,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAyBjD;AAED,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,QAAQ,GAAG,cAAc,CAAC,GAAG;IACpG,8EAA8E;IAC9E,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,iGAAiG;IACjG,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,uGAAuG;IACvG,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,uEAAuE;IACvE,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;IAChC,+FAA+F;IAC/F,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,mBAAmB,GAAG,WAAW,CAmBvF;AA0CD,6FAA6F;AAC7F,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAMnH"}