@atom-circuit/embed-sdk 1.2.1

package/dist/index.d.ts

@@ -0,0 +1,391 @@
+/**
+ * Atom Circuit Embed SDK - wire protocol contracts.
+ *
+ * Every message passed between host page and iframe must match one of the
+ * discriminated unions exported here. Strict origin and shape checks rely on
+ * these types both at compile time and at runtime (see assertion helpers).
+ */
+/**
+ * Wire-protocol major. SDK sends this in the URL (`?v=`) and during the
+ * handshake. The iframe must honor at least the last 2 majors or 18 months
+ * of SDK versions, whichever is longer. Bumped on every
+ * breaking wire change; independent of the npm package version.
+ */
+declare const PROTOCOL_VERSION = "1.0.0";
+/**
+ * Capabilities advertised in the handshake. Names are stable strings; new
+ * capabilities may be added without breaking older SDKs (they simply ignore
+ * unknown entries).
+ */
+type Capability = 'swap.submit' | 'swap.status' | 'resize.report' | 'events.stream';
+type Capabilities = ReadonlyArray<Capability | string>;
+/**
+ * Handshake payload exchanged once on connect. The iframe is expected to
+ * reply with its own handshake describing its protocol version + capability
+ * set; the SDK warns (does not throw) when the major versions diverge.
+ */
+interface HandshakeMessage {
+    readonly type: 'handshake';
+    readonly protocolVersion: string;
+    readonly capabilities: Capabilities;
+}
+interface ReadyPayload {
+    readonly protocolVersion: string;
+}
+interface SwapSubmittedPayload {
+    readonly txHash: string;
+    readonly route?: SwapRouteSummary;
+}
+interface SwapSuccessPayload {
+    readonly txHash: string;
+}
+interface SwapErrorPayload {
+    readonly code: string;
+    readonly message: string;
+}
+interface SwapRouteSummary {
+    readonly sourceChainId: string;
+    readonly destChainId: string;
+    readonly sourceDenom: string;
+    readonly destDenom: string;
+    readonly amountIn: string;
+    readonly amountOut?: string;
+}
+/**
+ * Discriminated union of all valid widget events. Use this when typing event
+ * subscribers on the host side.
+ */
+type WidgetEvent = {
+    readonly name: 'ready';
+    readonly payload: ReadyPayload;
+} | {
+    readonly name: 'swap:submitted';
+    readonly payload: SwapSubmittedPayload;
+} | {
+    readonly name: 'swap:success';
+    readonly payload: SwapSuccessPayload;
+} | {
+    readonly name: 'swap:error';
+    readonly payload: SwapErrorPayload;
+};
+/**
+ * Optional theming contract passed from host to iframe via the `?theme=` URL
+ * parameter (base64-encoded compact JSON of this object).
+ *
+ * Contract:
+ * - The SDK validates every field against the rules documented per-field. If
+ *   ANY field fails validation, the entire theme is dropped and the iframe
+ *   falls back to its default appearance. Validation is intentionally strict
+ *   so a malformed theme cannot break the embed or be used as an injection
+ *   vector against the iframe's CSS surface.
+ * - Fields are optional; the iframe must accept partial themes and apply only
+ *   the keys present.
+ * - Color values are CSS hex strings (`#RGB` or `#RRGGBB`). Other CSS color
+ *   notations (rgb(), named colors) are rejected to keep the wire surface
+ *   trivial to validate and to avoid CSS-injection footguns via string
+ *   interpolation on the iframe side.
+ * - `radius` and `fontSize` are plain pixel numbers in tight bounds.
+ * - `fontFamily` is a CSS-safe subset: letters, digits, spaces, hyphens,
+ *   commas, single/double quotes, dots. Anything containing `<`, `>`, `;`,
+ *   `{`, `}`, `=`, `(`, `)`, newlines, or tabs is rejected. Max 200 chars.
+ * - The iframe applies these as CSS custom properties on its embed root;
+ *   see the dapp side for the variable mapping.
+ *
+ * Omitting the `theme` field on MountOptions omits the `?theme=` param
+ * from the iframe URL entirely.
+ */
+interface ThemeOptions {
+    /** Light/dark/auto mode hint. Auto follows the host system preference. */
+    readonly mode?: 'light' | 'dark' | 'auto';
+    /** Brand accent color used for primary buttons and highlights. Hex only. */
+    readonly accentColor?: string;
+    /** Page background color. Hex only. */
+    readonly background?: string;
+    /** Primary text/foreground color. Hex only. */
+    readonly foreground?: string;
+    /** Border color for inputs, cards, dividers. Hex only. */
+    readonly border?: string;
+    /** Corner radius in pixels. Range: 0-64 inclusive. */
+    readonly radius?: number;
+    /** Base font size in pixels. Range: 8-32 inclusive. */
+    readonly fontSize?: number;
+    /** CSS font-family value. CSS-safe subset only; see ThemeOptions doc. */
+    readonly fontFamily?: string;
+}
+/**
+ * Toggles for the visual chrome surfaces rendered by the embed page. Each
+ * surface defaults to ON (true) so an embed dropped in with no chrome
+ * option shows the full chrome. Setting a flag to false hides the
+ * corresponding surface.
+ *
+ * Encoded into the iframe URL as part of the `?theme=` base64-JSON
+ * payload under the `chrome` key. Validation is strict: each present field
+ * must be a boolean, otherwise the entire chrome bundle is rejected.
+ *
+ * Omitting the `chrome` field, or omitting individual flags, leaves the
+ * default-on behaviour in place.
+ */
+interface ChromeOptions {
+    /** Show the Atom Circuit logo in the top bar. Default true. */
+    readonly logo?: boolean;
+    /** Show the wallet connect / disconnect button in the top bar. Default true. */
+    readonly wallet?: boolean;
+    /** Show the "Fees stake with <moniker>" validator badge. Default true. */
+    readonly validator?: boolean;
+    /** Show the "Powered by Atom Circuit" footer. Default true. */
+    readonly footer?: boolean;
+}
+/**
+ * Stable error codes surfaced via the `onError` callback. Consumers should
+ * treat unknown codes as opaque diagnostics rather than control-flow
+ * signals.
+ */
+type MountErrorCode = 'handshake_failed' | 'iframe_load_failed' | 'origin_mismatch' | 'protocol_incompatible' | 'unknown';
+/**
+ * Shape of the error passed to `onError`. `cause` carries the original error
+ * (if any) for diagnostic logging; it is typed as `unknown` so consumers
+ * narrow it explicitly before use.
+ */
+interface MountError {
+    readonly code: MountErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+/**
+ * Options accepted by both `mount(...)` (vanilla) and `<AtomCircuitSwap />`
+ * (React). Required fields are kept to the absolute minimum so the embed
+ * stays a one-liner for the validator.
+ */
+interface MountOptions {
+    /**
+     * Validator-supplied affiliate identifier. Forwarded to the widget via the
+     * iframe URL so fees route correctly.
+     */
+    /**
+     * Validator referralId. Optional. When omitted (or empty / whitespace),
+     * the SDK defaults to the literal string `'general'`, which fans the
+     * affiliate fee across all participating Atom Circuit validators at
+     * sweep time. Hosts that want fees to stake to a specific validator
+     * pass that validator's 8-character hex referralId (or a registered
+     * vanity slug).
+     */
+    referralId?: string;
+    /**
+     * Override the widget origin. Default `https://atomcircuit.net`. Used by
+     * the test suite and local development only.
+     */
+    origin?: string;
+    /**
+     * Override the widget path. Default `/embed/swap`.
+     */
+    path?: string;
+    /**
+     * Minimum height applied to the iframe before any resize messages arrive.
+     * Default `480px`.
+     */
+    minHeight?: string;
+    /**
+     * Optional additional CSS class applied to the iframe element.
+     */
+    className?: string;
+    /**
+     * Optional inline style merge. `height` and `width` are managed by the SDK
+     * and ignored if supplied.
+     */
+    style?: Partial<CSSStyleDeclaration>;
+    /**
+     * Fires once the iframe has loaded and the handshake completes.
+     */
+    onReady?: (payload: ReadyPayload) => void;
+    /**
+     * Fires on every measured content-height change.
+     */
+    onResize?: (info: {
+        height: number;
+    }) => void;
+    /**
+     * Fires when the user submits a swap (tx broadcast).
+     */
+    onSwapSubmitted?: (payload: SwapSubmittedPayload) => void;
+    /**
+     * Fires when a submitted swap confirms on chain.
+     */
+    onSwapSuccess?: (payload: SwapSuccessPayload) => void;
+    /**
+     * Fires when a swap fails or is rejected by the wallet.
+     */
+    onSwapError?: (payload: SwapErrorPayload) => void;
+    /**
+     * Fires on SDK-level failures (iframe load failure, handshake timeout,
+     * origin mismatch, etc). When not supplied the SDK emits a single warning
+     * via the injected warn sink and returns. This is distinct from
+     * `onSwapError`, which reports widget-level (in-iframe) swap failures.
+     */
+    onError?: (error: MountError) => void;
+    /**
+     * Optional theme. See {@link ThemeOptions} for the validated contract.
+     * Validation failure silently drops the theme; the iframe falls back to
+     * defaults.
+     */
+    readonly theme?: ThemeOptions;
+    /**
+     * Optional chrome toggles. See {@link ChromeOptions} for the validated
+     * contract. Validation failure silently drops the chrome bundle; the
+     * iframe falls back to all-chrome-on defaults. Encoded alongside `theme`
+     * in the iframe URL.
+     */
+    readonly chrome?: ChromeOptions;
+    /**
+     * CSS `width` applied to the iframe. Default `'100%'` when omitted.
+     */
+    readonly width?: string;
+    /**
+     * CSS `max-width` applied to the iframe. Default unset (no cap) when
+     * omitted.
+     */
+    readonly maxWidth?: string;
+    /**
+     * CSS `padding` applied to the wrapper element around the iframe (NOT to
+     * the iframe element itself, since padding on iframes does not behave
+     * intuitively across browsers). Default `'0'` when omitted.
+     */
+    readonly padding?: string;
+}
+
+/**
+ * Host-side client that wraps Penpal v7 for typed RPC plus a custom
+ * event emitter for streamed widget events (resize, ready, swap:*).
+ *
+ * Strict origin validation is enforced two ways:
+ *   1. Penpal's `WindowMessenger({ allowedOrigins })` filters at the messenger layer.
+ *   2. A second `MessageEvent` listener double-checks `event.origin` before
+ *      acknowledging stream events. Two-tier check is intentional: it ensures
+ *      we never trust a payload coming through a future Penpal change that
+ *      relaxes origin handling.
+ */
+
+/**
+ * Per-event handler signatures. Keeps the public surface free of `any`.
+ */
+interface EventHandlers {
+    ready: (payload: ReadyPayload) => void;
+    resize: (info: {
+        height: number;
+    }) => void;
+    'swap:submitted': (payload: SwapSubmittedPayload) => void;
+    'swap:success': (payload: SwapSuccessPayload) => void;
+    'swap:error': (payload: SwapErrorPayload) => void;
+}
+type EventName = keyof EventHandlers;
+interface IframeClientOptions {
+    /**
+     * The iframe element. Must already be appended to the DOM and have its
+     * `src` set so `iframe.contentWindow` is non-null by the time `init()`
+     * resolves.
+     */
+    iframe: HTMLIFrameElement;
+    /**
+     * Origin to trust for postMessage. Defaults to {@link WIDGET_ORIGIN}.
+     */
+    allowedOrigin?: string;
+    /**
+     * Connection timeout in milliseconds. Default 15000.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional warning sink. Defaults to a no-op (the SDK refuses to write to
+     * console.log per project policy).
+     */
+    warn?: (message: string) => void;
+}
+/**
+ * Typed Penpal RPC client + stream-event hub. One instance per iframe.
+ */
+declare class IframeClient {
+    private readonly iframe;
+    private readonly allowedOrigin;
+    private readonly timeoutMs;
+    private readonly warn;
+    private connection;
+    private rawListener;
+    private destroyed;
+    private handshakeReceived;
+    private handshakeResolvers;
+    private readonly handlers;
+    constructor(opts: IframeClientOptions);
+    /**
+     * Opens the Penpal connection and starts listening for stream events.
+     * Resolves once the remote handshake has been received.
+     */
+    init(): Promise<HandshakeMessage>;
+    /**
+     * Subscribe to a named stream event. Returns an unsubscribe function.
+     */
+    on<K extends EventName>(name: K, handler: EventHandlers[K]): () => void;
+    /**
+     * Remove a registered handler.
+     */
+    off<K extends EventName>(name: K, handler: EventHandlers[K]): void;
+    /**
+     * Tears down the Penpal connection, removes the raw listener, and clears
+     * every event subscriber. Safe to call multiple times.
+     */
+    destroy(): void;
+    /**
+     * Returns the handshake payload received from the iframe, or null if no
+     * handshake has been observed yet.
+     */
+    getHandshake(): HandshakeMessage | null;
+    /**
+     * Returns true if the iframe advertised the given capability in its
+     * handshake. Returns false when no handshake has been received yet or
+     * when the capability is not present.
+     *
+     * Callers wrapping a method that requires a capability should gate on
+     * `client.has('cap')` before invoking it. Calls to capabilities the
+     * iframe does not advertise are silent no-ops at the call-site (or
+     * resolve to `null`); the iframe is the source of truth for what it
+     * implements.
+     */
+    has(capability: string): boolean;
+    /**
+     * Test-only seam. Allows unit tests to invoke the message handler without
+     * dispatching real `MessageEvent`s through the JSDOM bus.
+     */
+    _handleMessageForTest(event: MessageEvent): void;
+    private handleRawMessage;
+    private recordHandshake;
+    private waitForHandshake;
+    private emitResize;
+    private dispatchWidgetEvent;
+    private emitReady;
+    private emitTyped;
+}
+
+/**
+ * Vanilla mount factory. Builds the iframe element, applies sandbox attrs,
+ * wires up the IframeClient + resize handler, and returns a destroy handle.
+ */
+
+interface MountResult {
+    iframe: HTMLIFrameElement;
+    /**
+     * Wrapper div the iframe is appended to. Always present in v1.0.0 and
+     * later. Hosts that previously relied on `container > iframe` should use
+     * `container iframe` or `[data-atom-circuit-embed] iframe` instead. The
+     * wrapper carries a position:relative anchor so the pre-handshake
+     * loading overlay (the spinner) can absolutely-position over the iframe
+     * without leaking into surrounding host layout. Padding (when supplied)
+     * is applied to this wrapper, never to the iframe element itself.
+     */
+    wrapper: HTMLDivElement;
+    client: IframeClient;
+    destroy(): void;
+}
+/**
+ * Creates an iframe, appends it to the container, and connects to the widget.
+ * Returns a handle for cleanup.
+ */
+declare function mount(container: HTMLElement, opts?: MountOptions): MountResult;
+
+export { type ChromeOptions, type MountError, type MountErrorCode, type MountOptions, type MountResult, PROTOCOL_VERSION, type ReadyPayload, type SwapErrorPayload, type SwapRouteSummary, type SwapSubmittedPayload, type SwapSuccessPayload, type ThemeOptions, type WidgetEvent, mount };