@synfin/widget 0.1.0

package/LICENSE

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

@@ -0,0 +1,145 @@
+# @synfin/widget
+
+An embeddable **quote-and-fee widget** for Canton, built on
+[`@synfin/client`](https://www.npmjs.com/package/@synfin/client). Drop it into
+any site to show a live best-execution quote across venues with your disclosed
+fees. Non-custodial: it holds no keys and signs nothing.
+
+- Docs: https://synfin.xyz/docs/sdk
+- Status: **v0**, the surface may evolve with design partners. Pin a version.
+
+## Install
+
+Two paths, pick one. Both register the same `<synfin-widget>` custom element.
+
+### 1. Script tag (no build step, no bundler)
+
+For any site (plain HTML, Vue, Svelte, Angular, Rails, WordPress). One `<script>`
+loads a **self-contained** bundle (`@synfin/client` is inlined, so there is no
+import map and nothing else to fetch) and registers the element:
+
+```html
+<script src="https://unpkg.com/@synfin/widget"></script>
+<synfin-widget
+  api-key="sk_live_..."
+  fee-bps="30"
+  fee-recipient="you::1220..."
+  from="CC" to="USDCx" amount="100"
+></synfin-widget>
+```
+
+Pin a version in production (the CDN caches it and the API stays stable):
+
+```html
+<script src="https://unpkg.com/@synfin/widget@0.1.0"></script>
+<!-- or jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@synfin/widget@0.1.0"></script>
+```
+
+The bare `unpkg.com/@synfin/widget` URL resolves to the IIFE bundle
+(`dist/synfin-widget.global.js`) through the package `unpkg`/`jsdelivr` fields,
+so you never spell the path. The bundle is browser-only and minified.
+
+### 2. npm (with a bundler: Vite, Next.js, Webpack)
+
+```sh
+npm install @synfin/widget
+```
+```ts
+import '@synfin/widget'; // registers <synfin-widget>
+```
+
+`@synfin/client` comes in as a normal dependency (the real range `^0.1.0`, not a
+workspace reference), so the package installs cleanly outside this repo.
+
+React:
+
+```tsx
+import { SynfinWidget } from '@synfin/widget/react';
+
+<SynfinWidget apiKey="sk_live_..." feeBps={30} feeRecipient="you::1220..."
+  onQuote={(e) => console.log(e.detail)} />
+```
+
+## What it does (v1)
+
+A live quote across Canton venues for your pair and amount, ranked best net
+receive first. We recommend the best, and mark it, but the user can select any
+available venue (a radio group: click, tap, or arrow keys); the receive figure,
+the fee breakdown, and the plan all follow their choice. The widget is shown to
+your END USER, so by default it shows only
+what they care about: what they pay, what they receive (net of all fees, read
+verbatim from the live quote and never recomputed in the browser), and a single
+neutral fee line for the total taken. The fee attribution (the Synfin service
+fee, your integrator fee, and the partner / Synfin split) is partner
+information, hidden from the end user by default; set `show-fee-breakdown` to
+reveal it for your own integration testing. Every state is designed: loading
+skeletons, an auto-refresh countdown, a venue shown honestly as unavailable
+(never breaking the widget), no-route, and errors.
+
+Creating a plan emits `synfin:plan` for **your** app to execute through the
+`WalletAdapter` it owns. In-widget wallet execution is deferred until a standard
+Canton browser wallet adapter exists (see docs/WIDGET.md); the widget never
+holds keys.
+
+## Configuration
+
+| attribute / prop | meaning |
+| --- | --- |
+| `api-key` / `apiKey` | your partner key (unlocks the fee breakdown) |
+| `fee-bps` / `feeBps` | your integrator fee, 0 to the cap (needs a recipient) |
+| `fee-recipient` / `feeRecipient` | the Canton party your fee settles to |
+| `from` `to` `amount` | default pair and amount |
+| `appearance` | `dark` (default) or `light` |
+| `base-url` / `baseUrl` | API origin (default `https://synfin.xyz`) |
+| `show-fee-breakdown` / `showFeeBreakdown` | show the full partner fee attribution (off by default; end users see the net and one neutral fee line) |
+| `show-attribution` / `showAttribution` | the subtle "Powered by Synfin" footer link (on by default; set off to white-label) |
+
+**On the API key:** in a browser widget the key is client-side visible by
+nature. Synfin keys are free, rate-limited, and non-custodial: a leaked key can
+only fetch quotes at that key's rate limit, and is revocable in one click. Use a
+dedicated widget key. A per-key origin allowlist is a roadmap item.
+
+## Theming
+
+Override any of these CSS custom properties (they pierce the Shadow DOM) to match
+your site; the Synfin cream/ember dark system is the default, `appearance="light"`
+a warm off-white:
+
+```css
+synfin-widget {
+  --synfin-accent: #6c5cff;
+  --synfin-bg: #0c0c14;
+  --synfin-surface: #17172a;
+  --synfin-ink: #eef;
+  --synfin-radius: 20px;
+  --synfin-font: 'Inter', sans-serif;
+}
+```
+
+## Events
+
+DOM `CustomEvent`s on the element (and `on*` props in the React wrapper):
+
+- `synfin:quote` - a fresh `QuoteResponse` loaded
+- `synfin:venue` - the user selected a venue (`{ venueId, net, isBest, pair }`)
+- `synfin:plan` - an `ExecutionPlan` created (execute it from your wallet)
+- `synfin:asset` - the pair changed
+- `synfin:error` - a `SynfinApiError` surfaced
+
+## Demo
+
+- `example/index.html`: the full embed against live production
+  (`https://synfin.xyz`) by default, with a control panel, the event log, and
+  theming. Add your API key to unlock the fee breakdown; keyless shows the venue
+  net only.
+- `example/cdn.html`: the script-tag path in isolation. It loads the
+  self-contained bundle with a plain `<script src>` (no import map), proving the
+  CDN embed a partner uses.
+
+The widget reads the public API cross-origin, so the API sends permissive CORS
+headers on `/api/*`; see the `/api/*` CORS middleware.
+
+## License
+
+MIT. Copyright Cayvox Labs.

package/dist/api.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The widget's own quote fetch. It talks to the same public /api/quote surface
+ * as @synfin/client, but unlike the client (which binds a key and always sends
+ * it) this attaches the x-api-key header ONLY when a real key is present. A
+ * keyless embed therefore sends a clean anonymous request, which the endpoint
+ * answers 200 with ranked venues and no clientFees (add a key to see fees). It
+ * reuses the client's exported error and quote types so the widget stays built
+ * on @synfin/client; planning still goes through the client, which needs a key.
+ */
+import { type FetchLike, type GetQuoteParams, type QuoteResponse } from '@synfin/client';
+export interface QuoteRequest {
+    readonly baseUrl: string;
+    /** The partner key, or null for a keyless (anonymous) request. */
+    readonly apiKey: string | null;
+    readonly fetch?: FetchLike;
+}
+/**
+ * Fetch a quote. Sends the x-api-key header only when {@link QuoteRequest.apiKey}
+ * is a non-empty string; a null/empty key produces a header-free anonymous
+ * request. Throws {@link SynfinApiError} on a non-2xx or non-JSON response.
+ */
+export declare function requestQuote(req: QuoteRequest, params: GetQuoteParams): Promise<QuoteResponse>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.js

@@ -0,0 +1,66 @@
+/**
+ * The widget's own quote fetch. It talks to the same public /api/quote surface
+ * as @synfin/client, but unlike the client (which binds a key and always sends
+ * it) this attaches the x-api-key header ONLY when a real key is present. A
+ * keyless embed therefore sends a clean anonymous request, which the endpoint
+ * answers 200 with ranked venues and no clientFees (add a key to see fees). It
+ * reuses the client's exported error and quote types so the widget stays built
+ * on @synfin/client; planning still goes through the client, which needs a key.
+ */
+import { SynfinApiError, } from '@synfin/client';
+/** Encode a flat param set, skipping undefined values. */
+function query(params) {
+    const parts = [];
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined)
+            continue;
+        parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    return parts.length > 0 ? `?${parts.join('&')}` : '';
+}
+function resolveFetch(injected) {
+    if (injected !== undefined)
+        return injected;
+    const g = globalThis.fetch;
+    if (g === undefined) {
+        throw new SynfinApiError(0, 'network', 'no fetch available in this runtime');
+    }
+    return g;
+}
+/**
+ * Fetch a quote. Sends the x-api-key header only when {@link QuoteRequest.apiKey}
+ * is a non-empty string; a null/empty key produces a header-free anonymous
+ * request. Throws {@link SynfinApiError} on a non-2xx or non-JSON response.
+ */
+export async function requestQuote(req, params) {
+    const qs = query({
+        from: params.from,
+        to: params.to,
+        amount: String(params.amount),
+        slippageBps: params.slippageBps,
+        feeBps: params.feeBps,
+        feeRecipient: params.feeRecipient,
+    });
+    const headers = {};
+    if (req.apiKey !== null && req.apiKey !== '') {
+        headers['x-api-key'] = req.apiKey;
+    }
+    const res = await resolveFetch(req.fetch)(`${req.baseUrl}/api/quote${qs}`, {
+        method: 'GET',
+        headers,
+    });
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        const text = await res.text().catch(() => '');
+        throw new SynfinApiError(res.status, 'bad_response', text.length > 0 ? text : 'non-JSON response from the Synfin API');
+    }
+    if (!res.ok) {
+        const e = body;
+        throw new SynfinApiError(res.status, e.code ?? 'error', e.error ?? `HTTP ${res.status}`);
+    }
+    return body;
+}
+//# sourceMappingURL=api.js.map

package/dist/assets.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The Canton asset catalog the selector offers. UI metadata only (symbol, name,
+ * decimals for display); the quote and its fees are the API's, never ours. Kept
+ * in sync with the tokens the hosted /api/quote resolves.
+ */
+export interface WidgetAsset {
+    readonly symbol: string;
+    readonly name: string;
+    readonly instrumentId: string;
+    readonly decimals: number;
+}
+export declare const ASSETS: readonly WidgetAsset[];
+export declare function findAsset(symbol: string): WidgetAsset | undefined;
+/**
+ * Map a name from the API (which may be the internal canonical instrumentId,
+ * e.g. "Amulet") to the user-facing ticker (e.g. "CC"). The canonical name must
+ * never surface in user-facing text; the user only ever sees the ticker they
+ * chose. Unknown names pass through unchanged (honest, never a wrong label).
+ */
+export declare function displaySymbol(nameOrId: string): string;
+/** A crisp, self-contained SVG monogram for a token (no remote image, no
+ *  possibly-wrong logo). Deterministic per ticker, on-brand, theme-agnostic. */
+export declare function assetIcon(symbol: string): string;
+export declare function searchAssets(query: string): readonly WidgetAsset[];
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.js

@@ -0,0 +1,64 @@
+export const ASSETS = [
+    { symbol: 'CC', name: 'Canton Coin', instrumentId: 'Amulet', decimals: 10 },
+    {
+        symbol: 'USDCx',
+        name: 'USDC (interchain)',
+        instrumentId: 'USDCx',
+        decimals: 6,
+    },
+    { symbol: 'CBTC', name: 'Canton BTC', instrumentId: 'CBTC', decimals: 8 },
+];
+export function findAsset(symbol) {
+    const s = symbol.trim().toLowerCase();
+    return ASSETS.find((a) => a.symbol.toLowerCase() === s);
+}
+/**
+ * Map a name from the API (which may be the internal canonical instrumentId,
+ * e.g. "Amulet") to the user-facing ticker (e.g. "CC"). The canonical name must
+ * never surface in user-facing text; the user only ever sees the ticker they
+ * chose. Unknown names pass through unchanged (honest, never a wrong label).
+ */
+export function displaySymbol(nameOrId) {
+    const s = nameOrId.trim();
+    const l = s.toLowerCase();
+    const byId = ASSETS.find((a) => a.instrumentId.toLowerCase() === l);
+    if (byId)
+        return byId.symbol;
+    const bySym = ASSETS.find((a) => a.symbol.toLowerCase() === l);
+    return bySym ? bySym.symbol : s;
+}
+// Curated per-token monogram (label + hue) for the crisp fallback icon. Real
+// Canton token logos are an OPTIONAL field on the CIP-0056 off-ledger token
+// metadata API and are not reliably published for these tokens, so the widget
+// ships a deterministic on-brand monogram rather than a possibly-wrong logo.
+const ICON = {
+    CC: { label: 'CC', hue: 20 },
+    AMULET: { label: 'CC', hue: 20 },
+    USDCX: { label: 'USDC', hue: 212 },
+    CBTC: { label: 'BTC', hue: 33 },
+    CETH: { label: 'ETH', hue: 250 },
+    CUSD: { label: 'USD', hue: 150 },
+};
+function hashHue(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = (h * 31 + s.charCodeAt(i)) >>> 0;
+    return h % 360;
+}
+/** A crisp, self-contained SVG monogram for a token (no remote image, no
+ *  possibly-wrong logo). Deterministic per ticker, on-brand, theme-agnostic. */
+export function assetIcon(symbol) {
+    const key = displaySymbol(symbol).toUpperCase();
+    const c = ICON[key] ?? { label: key.slice(0, 3), hue: hashHue(key) };
+    const h2 = (c.hue + 24) % 360;
+    const id = `sfic${c.hue}`;
+    const fs = c.label.length >= 4 ? 6.5 : c.label.length === 3 ? 8 : 9.5;
+    return `<svg class="asset__icon" viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" focusable="false"><defs><linearGradient id="${id}" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="hsl(${c.hue} 78% 58%)"></stop><stop offset="1" stop-color="hsl(${h2} 72% 44%)"></stop></linearGradient></defs><circle cx="12" cy="12" r="11" fill="url(#${id})"></circle><text x="12" y="12" dy="0.35em" text-anchor="middle" font-size="${fs}" font-weight="700" fill="#fff">${c.label}</text></svg>`;
+}
+export function searchAssets(query) {
+    const q = query.trim().toLowerCase();
+    if (q === '')
+        return ASSETS;
+    return ASSETS.filter((a) => a.symbol.toLowerCase().includes(q) || a.name.toLowerCase().includes(q));
+}
+//# sourceMappingURL=assets.js.map

package/dist/config.d.ts

@@ -0,0 +1,43 @@
+export interface WidgetConfig {
+    apiKey?: string;
+    feeBps?: number;
+    feeRecipient?: string;
+    from?: string;
+    to?: string;
+    amount?: string;
+    appearance?: 'dark' | 'light';
+    baseUrl?: string;
+    refreshMs?: number;
+    /** Partner-facing detail mode: show the full fee attribution (Synfin service,
+     *  integrator fee, partner/Synfin split). OFF by default; the end-user default
+     *  shows only the net receive and a single neutral total fee. */
+    showFeeBreakdown?: boolean;
+    /** The subtle "Powered by Synfin" footer link (a growth surface, LI.FI-style).
+     *  ON by default; a white-label enterprise partner sets it off. */
+    showAttribution?: boolean;
+}
+export interface NormalizedConfig {
+    apiKey: string | null;
+    feeBps: number | null;
+    feeRecipient: string | null;
+    from: string;
+    to: string;
+    amount: string;
+    appearance: 'dark' | 'light';
+    baseUrl: string;
+    refreshMs: number;
+    showFeeBreakdown: boolean;
+    showAttribution: boolean;
+}
+export interface ConfigIssue {
+    field: string;
+    message: string;
+}
+/** The integrator fee cap for input validation (BUSINESS.md; the server is
+ *  authoritative and re-checks against the applied schema). */
+export declare const FEE_CAP_BPS = 100;
+export declare function normalizeConfig(raw: WidgetConfig): {
+    config: NormalizedConfig;
+    issues: ConfigIssue[];
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,80 @@
+/**
+ * Widget configuration: the partner passes their key, their integrator fee,
+ * default pair/amount, theme, and API origin. Normalization applies defaults
+ * and collects honest issues (shown, never thrown), so a misconfigured embed
+ * degrades to a clear message instead of a blank box.
+ */
+import { findAsset } from './assets.js';
+/** The integrator fee cap for input validation (BUSINESS.md; the server is
+ *  authoritative and re-checks against the applied schema). */
+export const FEE_CAP_BPS = 100;
+const DEFAULT_REFRESH_MS = 15_000;
+export function normalizeConfig(raw) {
+    const issues = [];
+    const from = (raw.from ?? 'CC').trim();
+    const to = (raw.to ?? 'USDCx').trim();
+    if (findAsset(from) === undefined)
+        issues.push({ field: 'from', message: `unknown asset "${from}"` });
+    if (findAsset(to) === undefined)
+        issues.push({ field: 'to', message: `unknown asset "${to}"` });
+    if (from.toLowerCase() === to.toLowerCase())
+        issues.push({ field: 'to', message: 'from and to must differ' });
+    const amount = (raw.amount ?? '100').trim();
+    if (!/^\d+(\.\d+)?$/.test(amount) || Number(amount) <= 0)
+        issues.push({
+            field: 'amount',
+            message: 'amount must be a positive number',
+        });
+    let feeBps = null;
+    let feeRecipient = null;
+    const hasFee = raw.feeBps !== undefined || raw.feeRecipient !== undefined;
+    if (hasFee) {
+        if (raw.feeBps === undefined || raw.feeRecipient === undefined) {
+            issues.push({
+                field: 'fee',
+                message: 'feeBps and feeRecipient must be set together',
+            });
+        }
+        else {
+            const n = Number(raw.feeBps);
+            if (!Number.isInteger(n) || n < 0 || n > FEE_CAP_BPS)
+                issues.push({
+                    field: 'feeBps',
+                    message: `feeBps must be an integer 0 to ${FEE_CAP_BPS}`,
+                });
+            else
+                feeBps = n;
+            const r = String(raw.feeRecipient).trim();
+            if (r === '')
+                issues.push({
+                    field: 'feeRecipient',
+                    message: 'feeRecipient required',
+                });
+            else
+                feeRecipient = r;
+        }
+    }
+    const appearance = raw.appearance === 'light' ? 'light' : 'dark';
+    const baseUrl = (raw.baseUrl ?? 'https://synfin.xyz').replace(/\/+$/, '');
+    const refreshMs = typeof raw.refreshMs === 'number' && raw.refreshMs >= 3000
+        ? raw.refreshMs
+        : DEFAULT_REFRESH_MS;
+    const apiKeyTrimmed = (raw.apiKey ?? '').trim();
+    return {
+        config: {
+            apiKey: apiKeyTrimmed === '' ? null : apiKeyTrimmed,
+            feeBps,
+            feeRecipient,
+            from,
+            to,
+            amount,
+            appearance,
+            baseUrl,
+            refreshMs,
+            showFeeBreakdown: raw.showFeeBreakdown === true,
+            showAttribution: raw.showAttribution !== false,
+        },
+        issues,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/element.d.ts

@@ -0,0 +1,65 @@
+/**
+ * <synfin-widget>: the custom element. Owns the persistent chrome (pair + amount
+ * fields, the asset selector popover, the refresh countdown) and drives the
+ * quote lifecycle through @synfin/client, swapping only the result region per
+ * quote. Non-custodial: it holds no keys and signs nothing; creating a plan
+ * emits synfin:plan for the host to execute. Shadow DOM isolates styles so it is
+ * robust inside any host page.
+ */
+import { type FetchLike } from '@synfin/client';
+export declare class SynfinWidgetElement extends HTMLElement {
+    static get observedAttributes(): readonly string[];
+    /** Injectable fetch (tests and advanced hosts); defaults to global fetch. */
+    fetchImpl?: FetchLike;
+    private cfg;
+    private client;
+    private view;
+    private debounce;
+    private ticker;
+    private countdown;
+    private reqSeq;
+    private selectorOpen;
+    private built;
+    private syncing;
+    /** The venue the user has chosen (defaults to best); persists across refreshes
+     *  while it stays available. */
+    private selectedVenue;
+    /** Transient Create-a-plan feedback, cleared on a fresh quote. */
+    private plan;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** Set config programmatically (React wrapper / advanced hosts). */
+    configure(partial: Record<string, string | number | boolean | undefined | null>): void;
+    private reconfigure;
+    private root;
+    private $;
+    private build;
+    private assetBtn;
+    private paintChrome;
+    private onAmount;
+    /** Change the pair from an INTERNAL action (swap/select): update live state
+     *  and re-quote directly, never through observed attributes (which would
+     *  reset the typed amount and re-enter reconfigure). */
+    private setPair;
+    private swap;
+    private setView;
+    /** Re-render the result region from the current view, selected venue, and plan
+     *  feedback. Called on a new quote and on any selection / plan change. */
+    private paintResult;
+    /** The "You receive" chrome follows the SELECTED venue, same formatting as the
+     *  summary line so the two never disagree. */
+    private paintReceive;
+    /** Select a venue (click or keyboard). Repaints so the receive figure, fees,
+     *  and plan all follow the choice, and emits synfin:venue for the host. */
+    private selectVenue;
+    private venueKeys;
+    private quote;
+    private startCountdown;
+    private stopCountdown;
+    private createPlan;
+    private openSelector;
+    private selectorKeys;
+    private closeSelector;
+}
+//# sourceMappingURL=element.d.ts.map