@wingspan/embedded-sdk

Embed Wingspan UI components in your application using iframes.

Note: This is an embedded SDK that provides a curated subset of Wingspan functionality designed specifically for embedding. It does not expose the full Wingspan application — only the components listed below are supported.

Installation

npm

npm install @wingspan/embedded-sdk

CDN

<script src="https://unpkg.com/@wingspan/embedded-sdk/dist/index.global.js"></script>
<script>
  const ws = Wingspan.init({ baseUrl: "https://app.wingspan.app", token: "…" });
</script>

The CDN bundle exposes the Wingspan class directly on window, so the same API surface (Wingspan.init({ … })) works in both ESM and script-tag contexts.

Quick Start

import { Wingspan } from "@wingspan/embedded-sdk";

const ws = Wingspan.init({
  baseUrl: "https://app.wingspan.app",
  token: "your-session-token",
  // Optional: route SDK telemetry into your observability pipeline.
  onError: (err) => myObservability.captureException(err),
});

// Create a composable onboarding flow
const onboarding = ws.createOnboarding({
  modules: [
    { type: "create_account", accountType: "payee" },
    { type: "certify_tax_payer_info" },
    { type: "payout_method" },
  ],
  onComplete: (data) => console.log("Done", data),
  onError: (err) => console.error(err.message),
});

// Mount into a DOM element …
onboarding.mount("#container");

// … or open as a modal
onboarding.openModal();

The onComplete / onError options are convenience sugar — they are exactly equivalent to calling onboarding.on("complete", …) / onboarding.on("error", …) immediately after construction. Use the on() form when you need an unsubscribe handle or want to register handlers dynamically.

Components

| Factory Method | Description | | ------------------------------- | -------------------------------------------------------------------------- | | createOnboarding(options) | Composable onboarding flow | | createDefaultPayoutMethod() | Read-only preview of the contractor's default payout method | | createManagePayoutMethod() | Add / change default payout method, switch standard vs. instant | | createDefaultPaymentMethod() | Read-only preview of the payer's default payment method | | createManagePaymentMethod() | Add / change default payment method (bank or card) used for autopay | | createPreviewFundingMethod() | Read-only preview of the payer's default payroll funding source | | createManageFundingMethod() | Add / change the payroll funding source (bank, wallet, or card) |

Lifecycle

Each component instance is single-mode: once you call mount() it can only be unmounted via destroy(); once you call openModal() it can only be closed via closeModal() (or by an iframe complete / error event). The component throws if you try to:

• mount the same instance to a second target
• call mount() while the modal is open (or vice versa)
• call mount() or openModal() after destroy()

Create a fresh component for the next flow.

Wildcard subscriptions and PII

onboarding.on("*", handler) forwards every iframe event to your handler — including events that may contain KYC / PII data (member ids, verification fields, error messages, etc.). Do not pipe on("*") output directly into Sentry, Datadog, or any third-party observability sink. Subscribe to specific events instead, and redact / filter payloads before forwarding them anywhere off-platform.

Observability

WingspanConfig.onError receives a discriminated EmbeddedSdkError union covering postMessage parse / version mismatches, origin mismatches, iframe load errors and timeouts, and uncaught errors thrown by your own event handlers. Wingspan never phones home — these errors are only delivered to the callback you provide.

Documentation

See DOCS.md for the full API reference.