@opensylo/embed-sdk

Embed the OpenSylo funding application journey into your dashboard. The SDK creates a sandboxed iframe pointing at the hosted journey, passes a short-lived embed token via the URL fragment, and bridges lifecycle events over postMessage with strict origin checks. No redirect, no OpenSylo login.

Install

npm i @opensylo/embed-sdk

Or load the CDN bundle (exposes window.OpenSyloEmbed):

<script src="https://sdk.opensylo.com/v1/opensylo-embed.global.js"></script>

Usage

1. Backend — mint a short-lived embed token for the merchant: POST /api/v1/marketplace-api/merchants/{thirdPartyCustomerId}/embed-tokens (authenticated with your sk_live_/sk_test_ key). Pass the returned token to your frontend.

2. Frontend — render the journey:

import { loadOpenSyloEmbed } from "@opensylo/embed-sdk";

const embed = await loadOpenSyloEmbed();

const journey = embed.ApplicationJourney({
  token,                       // from your backend
  container: "#funding",       // selector or HTMLElement
  environment: "test",         // "test" | "live"
  theme: { primary: "#ff5500", logo: "https://…/logo.svg" },
  onReady: () => console.log("journey ready"),
  onStepChange: ({ step }) => console.log("step:", step),
  onCompleted: ({ merchantId }) => console.log("submitted", merchantId),
  onError: ({ code, message }) => console.error(code, message),
});

// later: journey.destroy();

Events (postMessage bridge)

The SDK only accepts messages from the embed host origin; the journey iframe only posts to the parent origin the SDK passed it.

| Event | Payload | When | |-------|---------|------| | ready | – | journey mounted with a valid token | | step-change | { step } | the merchant advances a step | | completed | { merchantId? } | the application is submitted | | error | { code?, message } | a fatal error (e.g. missing/expired token) | | resize | (internal) | iframe height auto-adjusts to content |

Options

ApplicationJourney({ token, container, environment?, host?, theme?, on* }). host defaults to https://embed.opensylo.com; override it for local dev (http://localhost:3024).

Build (maintainers)

pnpm build (tsup) produces dist/index.js (ESM), dist/index.cjs (CJS), dist/index.global.js (IIFE/CDN), and dist/index.d.ts.