@zapodotcash/widget 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zapo Labs
+
+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

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# zapo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Zapo deposit widget for web apps. Your users pay with the tokens they already hold, on the chain they are
+already on; the token you want arrives in the wallet you name.
+
+This package is the loader: it puts the widget's frame in your page, hands it your configuration and passes its
+events back to you. The widget itself is served by Zapo, so your page never holds a secret.
+
+## Install
+
+```bash
+npm install @zapodotcash/widget
+```
+
+You need a project key (it starts with `zpk_`) from the [Zapo dashboard](https://zapo.cash/app).
+
+## Use
+
+```ts
+import { mount } from '@zapodotcash/widget'
+
+const zapo = mount('#deposit', {
+  apiKey: 'zpk_live_your_key',
+  destinations: [{ chainId: 8453, tokens: ['USDC'], recipient: usersWallet }],
+}, {
+  onStatus: (deposit) => console.log(deposit.phase),
+  onClose: () => hideMyDialog(),
+})
+
+zapo.update(nextConfig) // for example when the user connects another wallet
+zapo.destroy()
+```
+
+### React
+
+```tsx
+import { ZapoDeposit } from '@zapodotcash/widget/react'
+
+<ZapoDeposit
+  apiKey="zpk_live_your_key"
+  destinations={[{ chainId: 8453, tokens: ['USDC'], recipient: wallet }]}
+  onStatus={(deposit) => console.log(deposit.phase)}
+/>
+```
+
+## Configuration
+
+| Field          | What it does                                                                                     |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| `apiKey`       | Required. Your project's publishable key.                                                        |
+| `destinations` | Required. What the user may fund: a chain id, the tokens you accept there, the wallet that receives. |
+| `from.chains`  | Chains the user may send from. Left out: every supported chain.                                  |
+| `refundTo`     | The user's own wallet per chain family (`evm`, `svm`), for refunds.                              |
+| `methods`      | `['address', 'wallet']` by default. Either can be left out.                                      |
+| `defaults`     | `fromChainId`, `toChainId`, `toToken`: choices to make for the user.                             |
+| `theme`        | `light`, `dark` or `auto` (the default).                                                         |
+| `appearance`   | Your look: an `accent`, `light`/`dark` colours, `radius`, `font`, `shadow`. Left out: the widget's own. |
+| `appName`      | Shown as "Deposit to ...". Left out: your project's name.                                        |
+| `logoUrl`      | An https image shown at the top left. Left out: your project's logo, else your account's.        |
+
+## Events
+
+| Handler    | When                                                                                                |
+| ---------- | --------------------------------------------------------------------------------------------------- |
+| `onReady`  | The widget has loaded.                                                                              |
+| `onStatus` | A deposit changed phase: `detected`, `confirming`, `routing`, `delivering`, `delivered`, `delayed`, `refunded`, `failed`. |
+| `onClose`  | The user pressed Done or Close.                                                                     |
+
+Events are for your interface. To credit a user, watch the chain: the delivery is an ordinary transfer to the wallet
+you named.
+
+Everything is typed; the full reference is in the [Zapo docs](https://zapo.cash/docs). To put your look together,
+use the [Theme builder](https://zapo.cash/docs/theme).
+
+## Licence
+
+MIT

package/dist/chunk-sqektmvr.js

@@ -0,0 +1,119 @@
+// src/core.ts
+var MAX_WIDTH = 496;
+var INITIAL_HEIGHT = 512;
+var MIN_HEIGHT = 240;
+var MAX_HEIGHT = 2400;
+function encodeConfig(config) {
+  const bytes = new TextEncoder().encode(JSON.stringify(config));
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function withoutKey(config) {
+  const { apiKey: _apiKey, ...rest } = config;
+  return JSON.parse(JSON.stringify(rest));
+}
+function frameUrl(origin, config) {
+  const key = typeof config.apiKey === "string" ? config.apiKey.trim() : "";
+  const query = key === "" ? "" : `?key=${encodeURIComponent(key)}`;
+  return `${origin.replace(/\/+$/, "")}/embed${query}#config=${encodeConfig(withoutKey(config))}`;
+}
+function clampHeight(height) {
+  return Math.max(MIN_HEIGHT, Math.min(Math.ceil(height), MAX_HEIGHT));
+}
+function isFrameMessage(data) {
+  if (typeof data !== "object" || data === null)
+    return false;
+  const message = data;
+  return message.source === "zapo" && typeof message.type === "string";
+}
+function toStatusEvent(data) {
+  if (typeof data !== "object" || data === null)
+    return null;
+  const message = data;
+  if (typeof message["id"] !== "string" || typeof message["phase"] !== "string")
+    return null;
+  const chain = (value) => typeof value === "number" ? value : null;
+  const text = (value) => typeof value === "string" ? value : null;
+  return {
+    id: message["id"],
+    phase: message["phase"],
+    originChainId: chain(message["originChainId"]),
+    destinationChainId: chain(message["destinationChainId"]),
+    amountOut: text(message["amountOut"]),
+    symbolOut: text(message["symbolOut"]),
+    txHashes: Array.isArray(message["txHashes"]) ? message["txHashes"].filter((hash) => typeof hash === "string") : []
+  };
+}
+function mountWidget(target, config, options, origin) {
+  const element = typeof target === "string" ? document.querySelector(target) : target;
+  if (element === null)
+    throw new Error("Zapo.mount: the target element was not found.");
+  const base = origin.replace(/\/+$/, "");
+  let latest = config;
+  let loaded = config;
+  let isAwaitingReady = true;
+  const makeFrame = (next) => {
+    const made = document.createElement("iframe");
+    made.src = frameUrl(base, next);
+    made.title = "Deposit";
+    made.allow = "clipboard-write";
+    made.style.cssText = `display:block;width:100%;max-width:${String(MAX_WIDTH)}px;height:${String(INITIAL_HEIGHT)}px;margin:0 auto;border:0;background:transparent;color-scheme:normal`;
+    return made;
+  };
+  let frame = makeFrame(config);
+  const post = (next) => {
+    frame.contentWindow?.postMessage({ type: "zapo:config", config: withoutKey(next) }, base);
+  };
+  const onMessage = (event) => {
+    if (event.source !== frame.contentWindow || event.origin !== base)
+      return;
+    const data = event.data;
+    if (!isFrameMessage(data))
+      return;
+    if (data.type === "resize" && typeof data.height === "number")
+      frame.style.height = `${String(clampHeight(data.height))}px`;
+    else if (data.type === "ready") {
+      isAwaitingReady = false;
+      if (latest !== loaded)
+        post(latest);
+      options.onReady?.();
+    } else if (data.type === "close")
+      options.onClose?.();
+    else if (data.type === "status") {
+      const status = toStatusEvent(data);
+      if (status !== null)
+        options.onStatus?.(status);
+    }
+  };
+  window.addEventListener("message", onMessage);
+  element.appendChild(frame);
+  return {
+    get frame() {
+      return frame;
+    },
+    update: (next) => {
+      const isOtherKey = next.apiKey !== loaded.apiKey;
+      latest = next;
+      if (isOtherKey) {
+        loaded = next;
+        isAwaitingReady = true;
+        const replacement = makeFrame(next);
+        replacement.style.cssText = frame.style.cssText;
+        frame.replaceWith(replacement);
+        frame = replacement;
+      } else if (!isAwaitingReady)
+        post(next);
+    },
+    destroy: () => {
+      window.removeEventListener("message", onMessage);
+      frame.remove();
+    }
+  };
+}
+
+// src/origin.ts
+var DEFAULT_ORIGIN = "https://zapo.cash";
+
+export { mountWidget, DEFAULT_ORIGIN };

package/dist/core.d.ts

@@ -0,0 +1,15 @@
+import type { ZapoConfig, ZapoHandle, ZapoOptions, ZapoStatusEvent } from './types.js';
+/** base64url of the UTF-8 JSON, carried in the frame URL's fragment - a fragment is never sent to any server. */
+export declare function encodeConfig(config: object): string;
+/**
+ * The configuration as the widget receives it: everything except the key, which travels in the frame's address.
+ * It goes through JSON, so what `update` sends is exactly what `mount` sent - a field set to `undefined` is left
+ * out rather than arriving as a key with no value, which the widget would refuse.
+ */
+export declare function withoutKey(config: ZapoConfig): Omit<ZapoConfig, 'apiKey'>;
+export declare function frameUrl(origin: string, config: ZapoConfig): string;
+/** The frame's height for a card of `height` pixels, kept within sane bounds whatever the frame reports. */
+export declare function clampHeight(height: number): number;
+/** A status message from the frame as the event handed to the page - fields read one by one, nothing passed through. */
+export declare function toStatusEvent(data: unknown): ZapoStatusEvent | null;
+export declare function mountWidget(target: string | Element, config: ZapoConfig, options: ZapoOptions, origin: string): ZapoHandle;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { ZapoConfig, ZapoHandle, ZapoOptions } from './types.js';
+export type { ZapoAppearance, ZapoColors, ZapoConfig, ZapoDestination, ZapoFont, ZapoHandle, ZapoHandlers, ZapoMethod, ZapoOptions, ZapoPhase, ZapoRadius, ZapoStatusEvent, ZapoTheme, } from './types.js';
+/**
+ * Put the Zapo deposit widget in the page.
+ *
+ * @param target An element, or a selector for one. The widget is appended to it.
+ * @param config Your key, and what your user may fund.
+ * @param options Handlers for the widget's events.
+ */
+export declare function mount(target: string | Element, config: ZapoConfig, options?: ZapoOptions): ZapoHandle;

package/dist/index.js

@@ -0,0 +1,12 @@
+import {
+  DEFAULT_ORIGIN,
+  mountWidget
+} from "./chunk-sqektmvr.js";
+
+// src/index.ts
+function mount(target, config, options = {}) {
+  return mountWidget(target, config, options, options.origin ?? DEFAULT_ORIGIN);
+}
+export {
+  mount
+};

package/dist/origin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Where Zapo's widget is served from. The placeholder below is replaced before the package is published - the
+ * release build refuses to run while it is still here - so a published package always carries the real address.
+ */
+export declare const DEFAULT_ORIGIN: string;
+export declare const PLACEHOLDER_ORIGIN: string;

package/dist/react.d.ts

@@ -0,0 +1,14 @@
+import type { ZapoConfig, ZapoHandlers } from './types.js';
+import type { CSSProperties, ReactElement } from 'react';
+export type { ZapoAppearance, ZapoColors, ZapoConfig, ZapoDestination, ZapoFont, ZapoHandlers, ZapoMethod, ZapoPhase, ZapoRadius, ZapoStatusEvent, ZapoTheme, } from './types.js';
+export interface ZapoDepositProps extends ZapoConfig, ZapoHandlers {
+    /** Where the widget is served from. Only needed to point at a deployment other than Zapo's own. */
+    origin?: string | undefined;
+    className?: string | undefined;
+    style?: CSSProperties | undefined;
+}
+/**
+ * The Zapo deposit widget as a React component. Pass your key and the destinations; the widget fills the width of
+ * its container up to 496px and sizes its own height.
+ */
+export declare function ZapoDeposit(props: ZapoDepositProps): ReactElement;

package/dist/react.js

@@ -0,0 +1,43 @@
+import {
+  DEFAULT_ORIGIN,
+  mountWidget
+} from "./chunk-sqektmvr.js";
+
+// src/react.ts
+import { createElement, useEffect, useRef, useState } from "react";
+function ZapoDeposit(props) {
+  const { origin, className, style, onReady, onStatus, onClose, ...config } = props;
+  const [element, setElement] = useState(null);
+  const handle = useRef(null);
+  const handlers = useRef({});
+  const serialised = JSON.stringify(config);
+  const latest = useRef(serialised);
+  const base = origin ?? DEFAULT_ORIGIN;
+  useEffect(() => {
+    handlers.current = { onReady, onStatus, onClose };
+  });
+  useEffect(() => {
+    if (element === null)
+      return;
+    const mounted = mountWidget(element, JSON.parse(latest.current), {
+      onReady: () => handlers.current.onReady?.(),
+      onStatus: (event) => handlers.current.onStatus?.(event),
+      onClose: () => handlers.current.onClose?.()
+    }, base);
+    handle.current = mounted;
+    return () => {
+      mounted.destroy();
+      handle.current = null;
+    };
+  }, [element, base, config.apiKey]);
+  useEffect(() => {
+    if (latest.current === serialised)
+      return;
+    latest.current = serialised;
+    handle.current?.update(JSON.parse(serialised));
+  }, [serialised]);
+  return createElement("div", { ref: setElement, className, style });
+}
+export {
+  ZapoDeposit
+};

package/dist/types.d.ts

@@ -0,0 +1,127 @@
+/** How a user can pay: to a deposit address (any wallet or exchange), or from a wallet connected in the browser. */
+export type ZapoMethod = 'address' | 'wallet';
+export type ZapoTheme = 'light' | 'dark' | 'auto';
+/** How round the corners are. `medium` is the widget's own. */
+export type ZapoRadius = 'none' | 'small' | 'medium' | 'large';
+/** `inter` (the default), or `system`: the font of the user's own device. */
+export type ZapoFont = 'inter' | 'system';
+/**
+ * Colours for one theme, as hex (`#f97316`). Every one is optional: whatever is left out keeps the widget's own.
+ * A colour that would make text hard to read on the card is ignored, with a warning in the browser console.
+ */
+export interface ZapoColors {
+    /** Buttons, the selected step, focus rings and highlights. */
+    accent?: string | undefined;
+    /** Text on the accent. Left out: black or white, whichever reads better on your accent. */
+    accentText?: string | undefined;
+    /** The card itself. */
+    background?: string | undefined;
+    /** Fields, menus and tiles inside the card. */
+    surface?: string | undefined;
+    /** Headings, amounts and addresses. */
+    text?: string | undefined;
+    /** Labels and secondary text. */
+    textMuted?: string | undefined;
+    /** Lines and outlines. */
+    border?: string | undefined;
+}
+/** Your look on the widget. Success, warning and error colours stay the widget's own: they carry meaning. */
+export interface ZapoAppearance {
+    /** One accent for both themes. A theme's own `accent` wins over it. */
+    accent?: string | undefined;
+    /** Colours in the light theme. */
+    light?: ZapoColors | undefined;
+    /** Colours in the dark theme. */
+    dark?: ZapoColors | undefined;
+    radius?: ZapoRadius | undefined;
+    font?: ZapoFont | undefined;
+    /** `false` takes off the card's drop shadow, and the room the frame keeps around the card for it. On by default. */
+    shadow?: boolean | undefined;
+}
+/** One thing a user may fund: a chain, the tokens you accept there, and the wallet that receives. */
+export interface ZapoDestination {
+    /** The chain to deliver on, by chain id (for example 8453 for Base, 792703809 for Solana). */
+    chainId: number;
+    /** Tokens you accept on that chain: symbols such as "USDC", or token addresses. */
+    tokens: string[];
+    /** The wallet that receives on that chain - your user's wallet. Funds are only ever sent to an address you name here. */
+    recipient: string;
+}
+export interface ZapoConfig {
+    /** Your project's publishable key, from the Zapo dashboard. It starts with `zpk_`. */
+    apiKey: string;
+    /** What the user may fund. With one entry it is selected for them; with several they choose. */
+    destinations: ZapoDestination[];
+    /** Chains the user may send from, by chain id. Left out: every chain Zapo supports. */
+    from?: {
+        chains?: number[] | undefined;
+    } | undefined;
+    /** The user's own wallet per chain family, for refunds when a deposit cannot be delivered. */
+    refundTo?: {
+        evm?: string | undefined;
+        svm?: string | undefined;
+    } | undefined;
+    /** Which ways to pay are offered. Default: both. */
+    methods?: ZapoMethod[] | undefined;
+    /** Choices to make for the user instead of asking. */
+    defaults?: {
+        fromChainId?: number | undefined;
+        toChainId?: number | undefined;
+        toToken?: string | undefined;
+    } | undefined;
+    /** `auto` (the default) follows the user's system setting. */
+    theme?: ZapoTheme | undefined;
+    /** Your colours, corners and font. See the Appearance docs. */
+    appearance?: ZapoAppearance | undefined;
+    /** Your app's name, shown as "Deposit to ...". Left out: your project's name from the dashboard. */
+    appName?: string | undefined;
+    /** Your logo, shown at the top left: the https address of an image. Left out: your project's logo, if it has one. */
+    logoUrl?: string | undefined;
+}
+/**
+ * Where a deposit is. `detected` to `delivering` are in flight, in order; `delivered`, `refunded` and `failed` are
+ * final; `delayed` means it is taking longer than usual and will still resolve.
+ */
+export type ZapoPhase = 'detected' | 'confirming' | 'routing' | 'delivering' | 'delivered' | 'delayed' | 'refunded' | 'failed';
+/** Sent each time a deposit changes phase. */
+export interface ZapoStatusEvent {
+    /** The deposit's id. The same deposit keeps its id across events. */
+    id: string;
+    phase: ZapoPhase;
+    originChainId: number | null;
+    destinationChainId: number | null;
+    /**
+     * The amount in the destination token's units, as a decimal string: what the route expects to deliver while the
+     * deposit is in flight, and what was delivered once `phase` is `delivered`. Null until it is known.
+     */
+    amountOut: string | null;
+    symbolOut: string | null;
+    /** Hashes of the delivery transactions on the destination chain - or, for a refund, of the refund on the source chain. */
+    txHashes: string[];
+}
+export interface ZapoHandlers {
+    /** The widget has loaded and is showing. */
+    onReady?: (() => void) | undefined;
+    /** A deposit changed phase. */
+    onStatus?: ((event: ZapoStatusEvent) => void) | undefined;
+    /** The user pressed Done or Close: hide whatever you showed the widget in. */
+    onClose?: (() => void) | undefined;
+}
+export interface ZapoOptions extends ZapoHandlers {
+    /** Where the widget is served from. Only needed to point at a deployment other than Zapo's own. */
+    origin?: string | undefined;
+}
+export interface ZapoHandle {
+    /**
+     * The frame the widget runs in. An update with a different key puts a new frame in its place, so read this again
+     * after one rather than keeping the element.
+     */
+    readonly frame: HTMLIFrameElement;
+    /**
+     * Replace the configuration - for example when the user connects a different wallet. Passing a different key
+     * reloads the widget for that key's project.
+     */
+    update: (config: ZapoConfig) => void;
+    /** Remove the widget and stop listening to it. */
+    destroy: () => void;
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@zapodotcash/widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Zapo deposit widget: your users pay with the tokens they have, on the chain they are on, and the token you want arrives in the wallet you name.",
+  "keywords": [
+    "crypto",
+    "deposit",
+    "widget",
+    "onramp",
+    "bridge",
+    "cross-chain",
+    "web3",
+    "ethereum",
+    "solana",
+    "usdc",
+    "react"
+  ],
+  "license": "MIT",
+  "author": "Zapo Labs",
+  "homepage": "https://zapo.cash/docs",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "react.js",
+    "react.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "prepublishOnly": "bun scripts/build.ts --release"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/react.d.ts

@@ -0,0 +1,2 @@
+// For tools that resolve '@zapodotcash/widget/react' as a file path instead of reading package.json "exports".
+export * from './dist/react.js'

package/react.js

@@ -0,0 +1,2 @@
+// For tools that resolve '@zapodotcash/widget/react' as a file path instead of reading package.json "exports".
+export * from './dist/react.js'