justgold_sdk 1.0.0

JustGold Connect SDK for Flutter — embeddable gold & silver trading UI for partner apps.

justgold_sdk (Flutter)

Flutter wrapper — embeds the JustGold trading UI in JustGoldConnect via flutter_inappwebview. Bridge parity with @justgold/rn-sdk.

Registry	pub.dev
Version	1.0.0
Publish	Manual — GitHub Actions
Partner docs	Quickstart · Flutter guide
Reference app	apps/flutter-b2b — Pattern A & B payment demos
Requires	@justgold/partner-sdk on your backend
UI source	@justgold/mobile-sdk (internal, not published)

---

Requirements

• Flutter 3.10+, Dart 3.0+
• flutter_inappwebview ^6.1.5

---

Installation

dependencies:
  justgold_sdk: ^1.0.0

flutter pub get

---

Usage

import 'package:justgold_sdk/justgold_sdk.dart';

JustGoldConnect(
  token: token,
  refreshToken: refreshToken,
  sandbox: false,
  locale: 'en',
  theme: const SdkTheme(mode: SdkThemeMode.light, primaryColor: '#2563eb'),
  onClose: () => Navigator.of(context).pop(),
  onSessionExpired: () => refreshSession(),
  onTokensRefreshed: (payload) => persistTokens(payload),
  onPaymentRequired: (payload, _resume) {
    Navigator.of(context).push(
      MaterialPageRoute(builder: (_) => PartnerPaymentPage(payload: payload)),
    );
  },
)

Constructor parameters

Parameter	Type	Description
token	String	Required. JWT session token
refreshToken	String?	Refresh token for silent renew (~60s before JWT expiry)
sandbox	bool	true → sandbox API; default production
locale	String?	'en' or 'ar'
theme	SdkTheme?	Light/dark + brand colors
onClose	VoidCallback?	User closed the flow
onSessionExpired	VoidCallback?	Token expired — re-issue session
onTokensRefreshed	callback	SDK renewed tokens — persist refresh token
onSuccess	callback	TRANSACTION_COMPLETE
onError	callback	SDK error
onPaymentRequired	callback	(payload, resume?) — open payment, PATCH txn, close (see below)

Full-page payment

1. Open payment UI on PAYMENT_REQUIRED
2. PATCH /v1/transactions/:id (HMAC)
3. Close payment UI — SDK polls and shows result

Pattern A (recommended): keep JustGoldConnect mounted; push payment route on top.
Pattern B: unmount JustGoldConnect during payment; remount with same tokens — wrapper restores route via session cache.

resume(transactionId) is optional. Test both patterns in apps/flutter-b2b.

Production: issue tokens from your backend — never ship clientSecret in the app.

---

Monorepo development

yarn build:sdk          # syncs assets/webview/
yarn verify:flutter     # analyze + test

---

Publishing (maintainers)

1. Bump version in pubspec.yaml (align with npm SDK versions)
2. yarn build:sdk
3. Actions → SDK: Publish (manual) → enable Publish justgold_sdk

Requires PUB_TOKEN in GitHub secrets (pub.dev upload credentials).

Local dry run:

cd packages/flutter-sdk
dart pub publish --dry-run

---

Quality checks

Command	Description
yarn verify:flutter	format + analyze + test
yarn analyze:flutter	flutter analyze

---

SDK UI loading (internal)

The bundled UI is a Vite ES module bundle — it needs a non-file:// origin. JustGoldConnect serves the HTML from package assets via a custom URL scheme (justgold-sdk://webview/index.html) using flutter_inappwebview’s onLoadResourceWithCustomScheme.

Partners do not configure this — no localhost server, cleartext traffic, or ATS exceptions are required on iOS or Android.

Notes

• UI bundle: assets/webview/ (generated by yarn build:sdk, not committed)
• JWT held in memory only inside the SDK
• Session cache (Pattern B) survives SDK unmount within the same app session