@atom-circuit/embed-sdk 1.2.1

package/dist/react.d.ts

@@ -0,0 +1,337 @@
+import { CSSProperties, ReactElement } from 'react';
+
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * React wrapper. Imports are kept narrow so the bundle stays small when only
+ * the `./react` subpath is consumed.
+ *
+ * SSR-safe: renders nothing on the server (returns null until the effect
+ * runs in the browser). The host should still wrap this in a `dynamic`
+ * import with `ssr: false` when using Next.js App Router to avoid pulling
+ * iframe-only code into the server bundle.
+ */
+
+interface AtomCircuitSwapProps {
+    /**
+     * Validator-supplied affiliate identifier. Optional - defaults to
+     * `'general'` when omitted. See {@link MountOptions.referralId}.
+     */
+    referralId?: string;
+    /**
+     * Override the widget origin. Defaults to `https://atomcircuit.net`.
+     */
+    origin?: string;
+    /**
+     * Override the widget path. Defaults to `/embed/swap`.
+     */
+    path?: string;
+    /**
+     * Minimum iframe height; default `480px`.
+     */
+    minHeight?: string;
+    /**
+     * CSS class applied to the wrapping `<div>`.
+     */
+    className?: string;
+    /**
+     * Inline style applied to the wrapping `<div>`.
+     */
+    style?: CSSProperties;
+    /** Fires once the handshake completes. */
+    onReady?: (payload: ReadyPayload) => void;
+    /** Fires on every measured content-height change. */
+    onResize?: (info: {
+        height: number;
+    }) => void;
+    /** Fires when a user submits a swap. */
+    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 (handshake timeout, iframe load failure, origin mismatch). */
+    onError?: (error: MountError) => void;
+    /**
+     * Optional theme. Forwarded to the iframe URL as a validated, base64-encoded
+     * payload. Validation failures silently drop the theme; the iframe falls
+     * back to its defaults. See {@link ThemeOptions}.
+     */
+    theme?: ThemeOptions;
+    /**
+     * Optional chrome toggles. Each flag hides the corresponding embed surface
+     * (logo, wallet button, validator badge, footer) when false. Defaults are
+     * all-on so an embed dropped in with no chrome configuration retains the
+     * full surface. See {@link ChromeOptions}.
+     */
+    chrome?: ChromeOptions;
+    /** CSS width for the iframe. Default `'100%'`. */
+    width?: string;
+    /** CSS max-width for the iframe. Default unset. */
+    maxWidth?: string;
+    /**
+     * CSS padding applied to the wrapping div around the iframe (NOT the
+     * iframe element itself). Default `'0'`.
+     */
+    padding?: string;
+}
+/**
+ * React component wrapping `mount()`. Mounts on first effect tick, unmounts
+ * on cleanup. Callbacks are captured via a ref so updating them between
+ * renders does not re-mount the iframe.
+ */
+declare function AtomCircuitSwap(props: AtomCircuitSwapProps): ReactElement | null;
+
+export { AtomCircuitSwap, type AtomCircuitSwapProps, type ChromeOptions, type MountError, type MountErrorCode, type MountResult, type ReadyPayload, type SwapErrorPayload, type SwapRouteSummary, type SwapSubmittedPayload, type SwapSuccessPayload, type ThemeOptions };