@pulsebyshiga/collect-js 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shiga Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @pulsebyshiga/collect-js
+
+Web loader for Pulse Collect's embedded payment components. Mounts a Pulse-controlled
+iframe into your page and gives you a typed event surface around it — the payment surface,
+session token, and order data never enter your DOM. You own the layout, chrome, and brand.
+
+> **Status: pre-release (0.1.0).** Published API may change until the Pulse contract is
+> reconciled.
+
+## Requirements
+
+- Any framework or none — the loader is dependency-free
+- ESM (`import`) for the npm package; a script-tag IIFE build is also shipped
+- A session token (`cs_*`) minted by your backend with [`@pulsebyshiga/node`](../node-sdk) —
+  secret keys never reach the browser
+
+## Installation
+
+```sh
+npm install @pulsebyshiga/collect-js
+```
+
+Or without a bundler:
+
+```html
+<script src="https://embed.pulse.shiga.io/v1/collect.iife.js"></script>
+<script>
+  window.PulseCollect.mount(target, { sessionToken });
+</script>
+```
+
+## Usage
+
+```ts
+import { PulseCollect } from '@pulsebyshiga/collect-js';
+
+const handle = PulseCollect.mount(document.getElementById('pay'), {
+  sessionToken, // cs_* from your backend
+  theme: { primaryColor: '#083a9a', fontFamily: 'YourFont, sans-serif' },
+  strings: { title: 'Add {target} to your safe' },
+  onSuccess: (orderId) => showFunded(orderId), // UX only — credit off the webhook
+  onError: (code, message) => report(code, message),
+});
+
+// later
+handle.unmount();
+```
+
+By default the component walks the user through **Select asset → Choose network → Pay**;
+the selection re-targets the order (new address, QR, re-locked quote) before payment.
+Pass `flow: "direct"` to pin the asset/network chosen at session creation and render the
+single payment view.
+
+## API
+
+### `PulseCollect.mount(target, options) → EmbedHandle`
+
+Creates the iframe inside `target` and wires the message bridge. Returns
+`{ iframe, unmount() }`. Throws if `sessionToken` is missing or not a `cs_*` token.
+
+### Options
+
+| Option           | Type                               | Default          | Description                                                                                                                    |
+| ---------------- | ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `sessionToken`   | `string`                           | — (required)     | Single-order session token from your backend.                                                                                  |
+| `component`      | `"payment" \| "quote" \| "status"` | `"payment"`      | Full flow, live locked quote only, or progress/status only.                                                                    |
+| `flow`           | `"select" \| "direct"`             | `"select"`       | In-embed asset/network selection, or pinned to the session's values.                                                           |
+| `networks`       | `string[]`                         | all enabled      | Narrow the selectable networks for this mount. Intersected with your dashboard configuration — narrowing only, never widening. |
+| `assets`         | `string[]`                         | all enabled      | Narrow the payable assets; same rules as `networks`.                                                                           |
+| `theme`          | `EmbedTheme`                       | design defaults  | Visual tokens — see [Theming](#theming).                                                                                       |
+| `strings`        | `EmbedStrings`                     | built-in copy    | Copy overrides — see [Copy](#copy).                                                                                            |
+| `readyTimeoutMs` | `number`                           | `15000`          | Ms to wait for the embed's ready signal before `onError("embed_load_timeout")`.                                                |
+| `embedUrl`       | `string`                           | production embed | Embed origin override (local development, partner-subdomain deployment).                                                       |
+| `apiUrl`         | `string`                           | embed default    | API base the embed calls with the session token.                                                                               |
+
+### Events
+
+| Callback           | Signature           | Notes                                                                                              |
+| ------------------ | ------------------- | -------------------------------------------------------------------------------------------------- |
+| `onReady`          | `()`                | Embed rendered and polling.                                                                        |
+| `onStatusChange`   | `(status, orderId)` | Every lifecycle transition — see status values below.                                              |
+| `onSuccess`        | `(orderId)`         | Order settled. **UX signal only** — credit users from the signed `disbursement.completed` webhook. |
+| `onQuoteExpired`   | `()`                | Locked quote lapsed; the embed offers recovery itself.                                             |
+| `onQuoteRefreshed` | `(lockedUntil)`     | A new quote window was locked.                                                                     |
+| `onError`          | `(code, message)`   | Load, session, or action failures (e.g. `embed_load_timeout`, `session_load_failed`).              |
+
+Status values: `loading`, `awaiting_payment`, `deposit_detected`, `deposit_confirmed`,
+`converting`, `completed`, `underpaid`, `overpaid`, `wrong_chain`, `expired`, `failed`.
+
+## Theming
+
+All tokens are optional; unset tokens fall back to your dashboard configuration, then to
+the design defaults.
+
+| Token                          | Applies to                                                                           |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| `primaryColor`                 | Buttons and accents — your brand color.                                              |
+| `buttonTextColor`              | Text on primary buttons.                                                             |
+| `mode`                         | `"light"` (default) or `"dark"` palette.                                             |
+| `fontFamily`                   | Whole component.                                                                     |
+| `inkColor` / `mutedColor`      | Primary / secondary text.                                                            |
+| `backgroundColor`              | Panel background.                                                                    |
+| `lineColor`                    | Borders, dividers, inactive step markers.                                            |
+| `successColor` / `dangerColor` | Positive states / failures and final-minute countdown.                               |
+| `borderRadius`                 | Control rounding, e.g. `"8px"`.                                                      |
+| `pageBackgroundColor`          | Full-page (Tier B) backdrop.                                                         |
+| `density`                      | `"compact"` (default) or `"comfortable"`.                                            |
+| `attribution`                  | `"subtle"` (default) or `"none"` — the "Powered by Pulse" footer is never mandatory. |
+
+## Copy
+
+Override any user-facing string via `strings`: `title`, `subtitle`, `heroLabel`,
+`successTitle`, `successSubtitle`, `expiredTitle`, `expiredSubtitle`, `refreshButton`,
+`copyButton`, `copiedButton`. Values may use the placeholders `{target}` (formatted fiat),
+`{assetAmount}`, `{asset}`, `{network}`, and `{settlementRef}`.
+
+## Server-driven configuration
+
+Networks, assets, theme, copy, attribution, and default flow can also be set once in the
+Pulse dashboard (`partner_config`); the embed applies them with no code change. Precedence
+is _defaults ← dashboard ← mount options_, except the network/asset lists, which only ever
+narrow: a mount cannot re-enable what the dashboard disabled, and the server rejects
+disabled values at session creation and re-selection.
+
+## Security model
+
+- The session token travels in the URL **fragment** — it is never sent to any server in a
+  request line or stored in logs.
+- Messages are accepted only from the embed's origin and window; everything else is ignored.
+- The iframe runs with a least-privilege `sandbox` (no top navigation, no downloads).
+- Keep your `sk_*` key and any user PII on your backend; this package needs neither.
+
+## Advanced
+
+- **`buildEmbedSrc(options)`** — returns the embed URL + origin without mounting; used by
+  the React Native wrapper and useful for Tier B (full-page, `layout=page`) links.
+- **`formatFiat(amount, currency)` / `formatAsset(amount)`** — the embed's own formatters,
+  exported so surrounding partner UI renders amounts identically.
+
+## Related packages
+
+React bindings: [`@pulsebyshiga/collect-react`](../collect-react) ·
+React Native: [`@pulsebyshiga/collect-react-native`](../collect-react-native) ·
+Backend: [`@pulsebyshiga/node`](../node-sdk)
+
+## License
+
+[MIT](../../LICENSE) © Shiga Digital

package/dist/collect.iife.js

@@ -0,0 +1 @@
+"use strict";var PulseCollect=(()=>{var h=Object.defineProperty;var H=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var _=Object.prototype.hasOwnProperty;var A=(t,e)=>{for(var s in e)h(t,s,{get:e[s],enumerable:!0})},L=(t,e,s,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of N(e))!_.call(t,r)&&r!==s&&h(t,r,{get:()=>e[r],enumerable:!(i=H(e,r))||i.enumerable});return t};var U=t=>L(h({},"__esModule",{value:!0}),t);var $={};A($,{CHANNEL:()=>l,PulseCollect:()=>M,buildEmbedSrc:()=>k,default:()=>F,formatAsset:()=>C,formatFiat:()=>w,isEmbedToHostMessage:()=>b,mount:()=>S,useSession:()=>v});var l="pulse-collect";function b(t){return typeof t=="object"&&t!==null&&"channel"in t&&t.channel===l&&"type"in t}function w(t,e){let s=Number(t);if(!Number.isFinite(s))return`${t} ${e}`;let i=s.toLocaleString("en-US",{minimumFractionDigits:2,maximumFractionDigits:2});return e==="NGN"?`\u20A6${i}`:e==="USD"?`$${i}`:`${i} ${e}`}function C(t){let e=Number(t);return Number.isFinite(e)?e.toLocaleString("en-US",{minimumFractionDigits:2,maximumFractionDigits:6}):t}function v(t){return{mode:"session",sessionToken:t}}var P="https://embed.pulse.shiga.io/v1/",I=420,x=15e3,O=["primaryColor","borderRadius","mode","fontFamily","inkColor","mutedColor","backgroundColor","buttonTextColor","lineColor","successColor","dangerColor","pageBackgroundColor","density","attribution"],R=["title","subtitle","heroLabel","successTitle","successSubtitle","expiredTitle","expiredSubtitle","refreshButton","copyButton","copiedButton"];function k(t){var m,c,g,u,n,o;let e=(c=(m=t.auth)==null?void 0:m.sessionToken)!=null?c:t.sessionToken;if(e===void 0||e===""||!e.startsWith("cs_"))throw new Error("@pulsebyshiga/collect-js: a session token (cs_*) is required");let s=(g=t.embedUrl)!=null?g:P,i=new URL(s).origin,r=new URL(s);r.searchParams.set("component",(u=t.component)!=null?u:"payment"),t.parentOrigin!==void 0?r.searchParams.set("parentOrigin",t.parentOrigin):typeof window!="undefined"&&typeof window.location!="undefined"&&r.searchParams.set("parentOrigin",window.location.origin),t.apiUrl!==void 0&&r.searchParams.set("apiUrl",t.apiUrl),t.flow!==void 0&&r.searchParams.set("flow",t.flow),t.networks!==void 0&&t.networks.length>0&&r.searchParams.set("networks",t.networks.join(",")),t.assets!==void 0&&t.assets.length>0&&r.searchParams.set("assets",t.assets.join(","));for(let a of O){let d=(n=t.theme)==null?void 0:n[a];d!==void 0&&r.searchParams.set(a,d)}for(let a of R){let d=(o=t.strings)==null?void 0:o[a];d!==void 0&&r.searchParams.set(`str_${a}`,d)}return r.hash=`token=${encodeURIComponent(e)}`,{src:r.toString(),embedOrigin:i}}function S(t,e){var u;let{src:s,embedOrigin:i}=k(e),r=document.createElement("iframe");r.src=s,r.title="Payment",r.allow="clipboard-write",r.setAttribute("sandbox","allow-scripts allow-same-origin allow-forms allow-popups"),r.style.width="100%",r.style.border="0",r.style.display="block",r.style.height=`${I}px`;let m=n=>{n.origin===i&&n.source===r.contentWindow&&b(n.data)&&g(n.data)},c=window.setTimeout(()=>{var n,o;(o=e.onError)==null||o.call(e,"embed_load_timeout",`The payment component did not become ready within ${(n=e.readyTimeoutMs)!=null?n:x}ms`)},(u=e.readyTimeoutMs)!=null?u:x),g=n=>{var o,a,d,p,y,E,T;switch(n.type){case"ready":{if(window.clearTimeout(c),e.theme!==void 0||e.strings!==void 0){let f={channel:l,type:"configure"};e.theme!==void 0&&(f.theme=e.theme),e.strings!==void 0&&(f.strings=e.strings),(o=r.contentWindow)==null||o.postMessage(f,i)}(a=e.onReady)==null||a.call(e);break}case"resize":r.style.height=`${Math.max(n.height,0)}px`;break;case"status_change":(d=e.onStatusChange)==null||d.call(e,n.status,n.orderId);break;case"quote_expired":(p=e.onQuoteExpired)==null||p.call(e);break;case"quote_refreshed":(y=e.onQuoteRefreshed)==null||y.call(e,n.lockedUntil);break;case"success":(E=e.onSuccess)==null||E.call(e,n.orderId);break;case"error":(T=e.onError)==null||T.call(e,n.code,n.message);break}};return window.addEventListener("message",m),t.appendChild(r),{iframe:r,unmount:()=>{window.clearTimeout(c),window.removeEventListener("message",m),r.remove()}}}var M={mount:S},F=M;return U($);})();

package/dist/format.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Amount display helpers shared by the embed and offered to partners so their
+ * own screens format amounts identically to the payment component.
+ */
+/** "1000000.00" + "NGN" → "₦1,000,000.00"; unknown currencies fall back to a suffix. */
+export declare function formatFiat(amount: string, currency: string): string;
+/** "6000.00" → "6,000.00" (up to 6dp for small stablecoin amounts). */
+export declare function formatAsset(amount: string): string;

package/dist/format.js

@@ -0,0 +1,29 @@
+/**
+ * Amount display helpers shared by the embed and offered to partners so their
+ * own screens format amounts identically to the payment component.
+ */
+/** "1000000.00" + "NGN" → "₦1,000,000.00"; unknown currencies fall back to a suffix. */
+export function formatFiat(amount, currency) {
+    const value = Number(amount);
+    if (!Number.isFinite(value))
+        return `${amount} ${currency}`;
+    const formatted = value.toLocaleString('en-US', {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+    });
+    if (currency === 'NGN')
+        return `₦${formatted}`;
+    if (currency === 'USD')
+        return `$${formatted}`;
+    return `${formatted} ${currency}`;
+}
+/** "6000.00" → "6,000.00" (up to 6dp for small stablecoin amounts). */
+export function formatAsset(amount) {
+    const value = Number(amount);
+    if (!Number.isFinite(value))
+        return amount;
+    return value.toLocaleString('en-US', {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 6,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { type EmbedComponent, type EmbedStatus, type EmbedStrings, type EmbedTheme } from './protocol.js';
+/**
+ * The browser-safe credential. Only a session token (`cs_*`) is ever accepted
+ * client-side — an API key must never ship to a browser. `useSession` is the
+ * client mirror of the backend's useSession; there is deliberately no
+ * `useApiKey` here.
+ */
+export type ClientAuth = {
+    readonly mode: 'session';
+    readonly sessionToken: string;
+};
+/** Wrap a single-order session token for `mount`/`<PulseCollectPayment>`. */
+export declare function useSession(sessionToken: string): ClientAuth;
+export type MountOptions = {
+    /**
+     * The browser-safe credential: a single-order session token (`cs_*`) from
+     * the partner backend (collectionSessions.create). Pass it directly, or as
+     * `auth: useSession(cs_…)`.
+     */
+    sessionToken?: string;
+    /** Alternative to `sessionToken` — the result of `useSession(cs_…)`. */
+    auth?: ClientAuth;
+    /** Embed origin override — local dev or a partner-subdomain deployment. */
+    embedUrl?: string;
+    /** API base the embed calls with the session token (dev: the local Pulse stand-in). */
+    apiUrl?: string;
+    /** Which piece to render: full "payment" flow (default), live "quote" only, or "status" only. */
+    component?: EmbedComponent;
+    /**
+     * "select" (default): the user picks asset + network inside the embed
+     * (Select asset → Choose network → Pay). "direct": skip selection — the
+     * values pinned at session creation are used (R5.3 partner pinning).
+     */
+    flow?: 'select' | 'direct';
+    /**
+     * Narrow the networks selectable in this mount. Intersected with the
+     * partner's dashboard config (`partner_config.enabled_networks`) — a mount
+     * can only narrow further, never re-enable a network the config removed.
+     * Omit for every network the partner has enabled.
+     */
+    networks?: string[];
+    /** Narrow the payable assets in this mount. Same narrowing rules as `networks`. */
+    assets?: string[];
+    theme?: EmbedTheme;
+    strings?: EmbedStrings;
+    /** Ms to wait for the embed's ready signal before onError("embed_load_timeout"). Default 15000. */
+    readyTimeoutMs?: number;
+    onReady?: () => void;
+    onStatusChange?: (status: EmbedStatus, orderId: string) => void;
+    onSuccess?: (orderId: string) => void;
+    onQuoteExpired?: () => void;
+    onQuoteRefreshed?: (lockedUntil: string) => void;
+    onError?: (code: string, message: string) => void;
+};
+export type EmbedHandle = {
+    iframe: HTMLIFrameElement;
+    unmount: () => void;
+};
+export type EmbedTarget = {
+    src: string;
+    embedOrigin: string;
+};
+export type BuildEmbedSrcOptions = Pick<MountOptions, 'sessionToken' | 'auth' | 'embedUrl' | 'apiUrl' | 'component' | 'flow' | 'networks' | 'assets' | 'theme' | 'strings'> & {
+    /** Origin of the page hosting the embed. Defaults to window.location.origin. */
+    parentOrigin?: string;
+};
+/**
+ * Build the embed URL. Theme and copy travel as query params so the first
+ * paint is already branded; the token travels in the fragment so it is never
+ * sent to any server in a URL or request log. Shared by the web loader and
+ * the React Native WebView wrapper.
+ */
+export declare function buildEmbedSrc(options: BuildEmbedSrcOptions): EmbedTarget;
+/**
+ * Mount a Pulse Collect component into the partner's page. The component
+ * renders inside a Pulse-controlled iframe: the session token, order data and
+ * payment surface never enter the partner DOM. The partner owns everything
+ * around it — layout, chrome, branding (theme + strings).
+ */
+export declare function mount(target: HTMLElement, options: MountOptions): EmbedHandle;
+export declare const PulseCollect: {
+    mount: typeof mount;
+};
+export default PulseCollect;
+export { CHANNEL, isEmbedToHostMessage, type EmbedComponent, type EmbedStatus, type EmbedStrings, type EmbedTheme, type EmbedToHostMessage, type HostToEmbedMessage, } from './protocol.js';
+export { formatAsset, formatFiat } from './format.js';

package/dist/index.js

@@ -0,0 +1,162 @@
+import { CHANNEL, isEmbedToHostMessage, } from './protocol.js';
+/** Wrap a single-order session token for `mount`/`<PulseCollectPayment>`. */
+export function useSession(sessionToken) {
+    return { mode: 'session', sessionToken };
+}
+const DEFAULT_EMBED_URL = 'https://embed.pulse.shiga.io/v1/';
+const INITIAL_HEIGHT_PX = 420;
+const DEFAULT_READY_TIMEOUT_MS = 15_000;
+const THEME_PARAM_KEYS = [
+    'primaryColor',
+    'borderRadius',
+    'mode',
+    'fontFamily',
+    'inkColor',
+    'mutedColor',
+    'backgroundColor',
+    'buttonTextColor',
+    'lineColor',
+    'successColor',
+    'dangerColor',
+    'pageBackgroundColor',
+    'density',
+    'attribution',
+];
+const STRING_PARAM_KEYS = [
+    'title',
+    'subtitle',
+    'heroLabel',
+    'successTitle',
+    'successSubtitle',
+    'expiredTitle',
+    'expiredSubtitle',
+    'refreshButton',
+    'copyButton',
+    'copiedButton',
+];
+/**
+ * Build the embed URL. Theme and copy travel as query params so the first
+ * paint is already branded; the token travels in the fragment so it is never
+ * sent to any server in a URL or request log. Shared by the web loader and
+ * the React Native WebView wrapper.
+ */
+export function buildEmbedSrc(options) {
+    const sessionToken = options.auth?.sessionToken ?? options.sessionToken;
+    if (sessionToken === undefined || sessionToken === '' || !sessionToken.startsWith('cs_')) {
+        throw new Error('@pulsebyshiga/collect-js: a session token (cs_*) is required');
+    }
+    const embedUrl = options.embedUrl ?? DEFAULT_EMBED_URL;
+    const embedOrigin = new URL(embedUrl).origin;
+    const src = new URL(embedUrl);
+    src.searchParams.set('component', options.component ?? 'payment');
+    if (options.parentOrigin !== undefined) {
+        src.searchParams.set('parentOrigin', options.parentOrigin);
+    }
+    else if (typeof window !== 'undefined' && typeof window.location !== 'undefined') {
+        // Absent in React Native (the WebView bridge needs no origin) — browser only.
+        src.searchParams.set('parentOrigin', window.location.origin);
+    }
+    if (options.apiUrl !== undefined)
+        src.searchParams.set('apiUrl', options.apiUrl);
+    if (options.flow !== undefined)
+        src.searchParams.set('flow', options.flow);
+    if (options.networks !== undefined && options.networks.length > 0) {
+        src.searchParams.set('networks', options.networks.join(','));
+    }
+    if (options.assets !== undefined && options.assets.length > 0) {
+        src.searchParams.set('assets', options.assets.join(','));
+    }
+    for (const key of THEME_PARAM_KEYS) {
+        const value = options.theme?.[key];
+        if (value !== undefined)
+            src.searchParams.set(key, value);
+    }
+    for (const key of STRING_PARAM_KEYS) {
+        const value = options.strings?.[key];
+        if (value !== undefined)
+            src.searchParams.set(`str_${key}`, value);
+    }
+    src.hash = `token=${encodeURIComponent(sessionToken)}`;
+    return { src: src.toString(), embedOrigin };
+}
+/**
+ * Mount a Pulse Collect component into the partner's page. The component
+ * renders inside a Pulse-controlled iframe: the session token, order data and
+ * payment surface never enter the partner DOM. The partner owns everything
+ * around it — layout, chrome, branding (theme + strings).
+ */
+export function mount(target, options) {
+    const { src, embedOrigin } = buildEmbedSrc(options);
+    const iframe = document.createElement('iframe');
+    iframe.src = src;
+    iframe.title = 'Payment';
+    iframe.allow = 'clipboard-write';
+    // Least privilege: scripts + own-origin fetch; no top-navigation, no downloads.
+    iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms allow-popups');
+    iframe.style.width = '100%';
+    iframe.style.border = '0';
+    iframe.style.display = 'block';
+    iframe.style.height = `${INITIAL_HEIGHT_PX}px`;
+    const onMessage = (event) => {
+        if (event.origin !== embedOrigin)
+            return;
+        if (event.source !== iframe.contentWindow)
+            return;
+        if (!isEmbedToHostMessage(event.data))
+            return;
+        handleMessage(event.data);
+    };
+    // A dead embed (network failure, bad deploy) must surface, not hang silently.
+    const readyTimer = window.setTimeout(() => {
+        options.onError?.('embed_load_timeout', `The payment component did not become ready within ${options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS}ms`);
+    }, options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+    const handleMessage = (message) => {
+        switch (message.type) {
+            case 'ready': {
+                window.clearTimeout(readyTimer);
+                if (options.theme !== undefined || options.strings !== undefined) {
+                    const configure = { channel: CHANNEL, type: 'configure' };
+                    if (options.theme !== undefined)
+                        configure.theme = options.theme;
+                    if (options.strings !== undefined)
+                        configure.strings = options.strings;
+                    iframe.contentWindow?.postMessage(configure, embedOrigin);
+                }
+                options.onReady?.();
+                break;
+            }
+            case 'resize':
+                iframe.style.height = `${Math.max(message.height, 0)}px`;
+                break;
+            case 'status_change':
+                options.onStatusChange?.(message.status, message.orderId);
+                break;
+            case 'quote_expired':
+                options.onQuoteExpired?.();
+                break;
+            case 'quote_refreshed':
+                options.onQuoteRefreshed?.(message.lockedUntil);
+                break;
+            case 'success':
+                options.onSuccess?.(message.orderId);
+                break;
+            case 'error':
+                options.onError?.(message.code, message.message);
+                break;
+        }
+    };
+    window.addEventListener('message', onMessage);
+    target.appendChild(iframe);
+    return {
+        iframe,
+        unmount: () => {
+            window.clearTimeout(readyTimer);
+            window.removeEventListener('message', onMessage);
+            iframe.remove();
+        },
+    };
+}
+export const PulseCollect = { mount };
+export default PulseCollect;
+export { CHANNEL, isEmbedToHostMessage, } from './protocol.js';
+export { formatAsset, formatFiat } from './format.js';

package/dist/protocol.d.ts

@@ -0,0 +1,94 @@
+/**
+ * postMessage protocol between the partner page (host) and the Pulse-controlled
+ * iframe (embed). Every message carries channel: "pulse-collect" so the bridge
+ * can ignore unrelated traffic on the same window.
+ */
+export declare const CHANNEL: "pulse-collect";
+export type EmbedStatus = 'loading' | 'awaiting_payment' | 'deposit_detected' | 'deposit_confirmed' | 'converting' | 'completed' | 'underpaid' | 'overpaid' | 'wrong_chain' | 'expired' | 'failed';
+export type EmbedComponent = 'payment' | 'quote' | 'status';
+export type EmbedTheme = {
+    /** CSS color for buttons/accents — the partner's brand color. */
+    primaryColor?: string;
+    /** CSS length for control rounding, e.g. "8px". */
+    borderRadius?: string;
+    mode?: 'light' | 'dark';
+    /** CSS font-family stack applied to the whole component. */
+    fontFamily?: string;
+    /** Primary text color. */
+    inkColor?: string;
+    /** Secondary text color. */
+    mutedColor?: string;
+    /** Panel background color. */
+    backgroundColor?: string;
+    /** Text color on primary buttons. */
+    buttonTextColor?: string;
+    /** Borders, dividers, and inactive step markers. */
+    lineColor?: string;
+    /** Success-state text (e.g. "Payment complete"). */
+    successColor?: string;
+    /** Failure/urgency accents (failed title, final-minute countdown). */
+    dangerColor?: string;
+    /** Tier B page-shell backdrop. */
+    pageBackgroundColor?: string;
+    /** "compact" (default for now) tightens padding and shrinks the QR; "comfortable" widens. */
+    density?: 'comfortable' | 'compact';
+    /**
+     * Greyed-out "Powered by Shiga Digital" at the foot of the component.
+     * Defaults to "subtle"; set "none" to remove (R3.4 — never mandatory).
+     */
+    attribution?: 'subtle' | 'none';
+};
+/**
+ * Copy overrides for the money-moment states. Values may use placeholders:
+ * {target} — formatted fiat target ("$6,000.00"), {assetAmount}, {asset},
+ * {network}, {settlementRef}.
+ */
+export type EmbedStrings = {
+    title?: string;
+    subtitle?: string;
+    /** Uppercase label above the fiat hero amount ("You're paying"). */
+    heroLabel?: string;
+    successTitle?: string;
+    successSubtitle?: string;
+    expiredTitle?: string;
+    expiredSubtitle?: string;
+    refreshButton?: string;
+    copyButton?: string;
+    copiedButton?: string;
+};
+export type EmbedToHostMessage = {
+    channel: typeof CHANNEL;
+    type: 'ready';
+} | {
+    channel: typeof CHANNEL;
+    type: 'resize';
+    height: number;
+} | {
+    channel: typeof CHANNEL;
+    type: 'status_change';
+    status: EmbedStatus;
+    orderId: string;
+} | {
+    channel: typeof CHANNEL;
+    type: 'quote_expired';
+} | {
+    channel: typeof CHANNEL;
+    type: 'quote_refreshed';
+    lockedUntil: string;
+} | {
+    channel: typeof CHANNEL;
+    type: 'success';
+    orderId: string;
+} | {
+    channel: typeof CHANNEL;
+    type: 'error';
+    code: string;
+    message: string;
+};
+export type HostToEmbedMessage = {
+    channel: typeof CHANNEL;
+    type: 'configure';
+    theme?: EmbedTheme;
+    strings?: EmbedStrings;
+};
+export declare function isEmbedToHostMessage(data: unknown): data is EmbedToHostMessage;

package/dist/protocol.js

@@ -0,0 +1,13 @@
+/**
+ * postMessage protocol between the partner page (host) and the Pulse-controlled
+ * iframe (embed). Every message carries channel: "pulse-collect" so the bridge
+ * can ignore unrelated traffic on the same window.
+ */
+export const CHANNEL = 'pulse-collect';
+export function isEmbedToHostMessage(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        'channel' in data &&
+        data.channel === CHANNEL &&
+        'type' in data);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@pulsebyshiga/collect-js",
+  "version": "0.2.0",
+  "description": "Tier A embed loader — mounts Pulse Collect payment components into a partner page via a sandboxed iframe and a typed postMessage bridge",
+  "license": "MIT",
+  "author": "Shiga Digital",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pulse-Digital/pulse-collect.git",
+    "directory": "packages/collect-js"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.24.2",
+    "jsdom": "^25.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && pnpm run build:iife",
+    "build:iife": "esbuild src/index.ts --bundle --format=iife --global-name=PulseCollect --outfile=dist/collect.iife.js --minify --target=es2019",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}