@justgold/web-sdk

Embeddable JustGold trading UI for partner web applications — React iframe host (JustGoldEmbed) and vanilla JS helper (createJustGoldHost).

| | | | ----------------- | ------------------------------------------------------------------------------------------------------------ | | Registry | npm | | Version | 1.1.13 — see CHANGELOG | | Publish | Manual — GitHub Actions | | Partner docs | Quickstart · Web guide | | Requires | @justgold/partner-sdk on your backend | | Reference app | apps/web-b2b — iframe + payment overlay demo |

Installation

yarn add @justgold/web-sdk
npm install @justgold/web-sdk

Peer dependencies (React entry only): react >= 18, react-dom >= 18

Host the UI bundle (recommended)

The trading UI ships inside this package at assets/webview/index.html. Copy it to your static assets after install / upgrade:

cp -r node_modules/@justgold/web-sdk/assets/webview public/justgold-sdk

Use sdkUrl="/justgold-sdk/index.html". Same-origin hosting is the recommended web integration — mobile SDKs use JustGold CDN instead.

Node-only helper (build scripts):

import { getBundledWebviewDir } from '@justgold/web-sdk/node';

React

import { JustGoldEmbed } from '@justgold/web-sdk';

<JustGoldEmbed
  sdkUrl="/justgold-sdk/index.html"
  session={{
    token: jwt,
    refreshToken,
    sandbox: false,
    locale: 'en',
  }}
  onClose={() => setOpen(false)}
  onAuthRequired={() => refreshToken()}
  onSessionExpired={() => refreshToken()}
  onTokensRefreshed={({ sessionToken, refreshToken }) => persist(refreshToken)}
  onSuccess={txn => console.log(txn)}
  onAnalytics={({ name, params }) => console.log(name, params)}
  onPaymentRequired={(payload, _resume) => openPaymentOverlay(payload)}
  onError={err => {
    if (err.fatal) {
      // SDK cannot load — show your UI or close
    } else {
      console.warn(err);
    }
  }}
/>;

Pass session.sandbox: true for the sandbox API — partners do not pass apiBaseUrl.

When sdkUrl is omitted, the wrapper can fetch a signed CDN URL from GET /v1/sdk/ui-url (same as mobile). For browser apps, prefer same-origin sdkUrl above.

Full-page payment (web)

Keep the iframe mounted. Show a full-screen payment overlay on top, PATCH Completed / Failed / Cancelled (Back) via HMAC, then close the overlay — the SDK polls: result or restore buy/sell. See apps/web-b2b.

resume(transactionId) via the second onPaymentRequired argument or host.sendPaymentResult(id) is optional.

If payment stays Pending for 10 minutes, JustGold marks it Stale. Do not PATCH Stale.

Session recovery (1.1.5+)

When auth fails, the embedded UI runs multi-phase recovery (retries + tab foreground auto-retry). Refresh session tokens in onAuthRequired / onSessionExpired — keep the iframe mounted. On visibilitychange back to visible, refresh again if the embed is still open.

Vanilla JS

import { createJustGoldHost } from '@justgold/web-sdk';

const host = createJustGoldHost({
  container: document.getElementById('justgold')!,
  sdkUrl: '/justgold-sdk/index.html',
  session: { token: jwt, sandbox: false },
  onClose: () => host.destroy(),
  onAnalytics: ({ name, params }) => console.log(name, params),
  onPaymentRequired: payload => {
    showPaymentOverlay(payload).then(() => hidePaymentOverlay());
    // SDK polls and shows result — resume() / host.sendPaymentResult() optional
  },
});

Environments

| Environment | Partner API | Web UI | session.sandbox | | ----------- | ---------------------------------------- | ------------------------- | ----------------- | | Sandbox | https://api.stage.partner.justgold.app | Same-origin copy from npm | true | | Production | https://api.partner.justgold.app | Same-origin copy from npm | false / omit |

Local development (monorepo)

yarn sync:postman-env
yarn dev:sdk:web

Open http://localhost:5180 — see apps/web-b2b.

Publishing (maintainers)

1. Bump version in package.json (keep aligned with @justgold/rn-sdk / UI bundle)
2. From repo root: yarn build:sdk (syncs assets/webview/)
3. Actions → SDK: Publish (manual) → select @justgold/web-sdk

Scripts

| Script | Description | | ----------------------------------------- | ------------------ | | yarn workspace @justgold/web-sdk build | Compile to dist/ | | yarn workspace @justgold/web-sdk verify | typecheck + lint |