suioutkit 1.0.4 → 1.2.0

package/README.md

@@ -9,7 +9,7 @@
 
 Browser SDK for SuiOutKit checkout: create sessions, open a ready-made payment modal, or build a custom UI with helpers.
 
-Uses the **hosted SuiOutKit API** at `https://api.suioutkit.xyz` by default (all routes under `/v1/`). The SDK does not perform settlement, treasury checks, or provider calls itself.
+Defaults to the **hosted SuiOutKit API** at `https://api.suioutkit.xyz` (`mode: "live"`). Switch with `mode: "test"` or `mode: "local"` for development. All routes under `/v1/`. The SDK does not perform settlement, treasury checks, or provider calls itself.
 
 | Resource | Link |
 |----------|------|
@@ -47,7 +47,7 @@ import { SuiOutKit } from "suioutkit";
 
 const sdk = new SuiOutKit({
   merchantAddress: "0xYOUR_MERCHANT_SUI_ADDRESS",
-  // backendUrl optional - defaults to https://api.suioutkit.xyz
+  // mode optional - defaults to "live" (https://api.suioutkit.xyz, mainnet)
 });
 
 export function PayButton() {
@@ -86,14 +86,10 @@ For simple demos you can serve the built SDK bundle from any static host. Build
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `merchantAddress` | `string` | Yes | Sui address that receives settlement |
-| `backendUrl` | `string` | No | API origin (no trailing slash). Default: `https://api.suioutkit.xyz`. Use `http://localhost:5000` only for local development. |
+| `mode` | `"local" \| "test" \| "live"` | No | Default: `"live"`. `"local"` → `http://localhost:5000` (testnet), `"test"` → `https://api.staging.suioutkit.xyz` (testnet), `"live"` → `https://api.suioutkit.xyz` (mainnet). |
+| `backendUrl` | `string` | No | Override API origin (no trailing slash). Takes precedence over `mode`. |
 
-### Network (crypto flows)
-The modal reads `window.SuiOutKitNetwork` - set to `"mainnet"` or `"testnet"` before opening the modal if you need a specific network for wallet / outPay flows.
-
-```html
-<script>window.SuiOutKitNetwork = "testnet";</script>
-```
+The SDK automatically sets `window.SuiOutKitNetwork` to the correct Sui network based on `mode` - no manual `<script>` tag needed.
 
 ## API reference
 ### `initCheckout(options)`
@@ -103,6 +99,7 @@ Creates a checkout session on the backend.
 const session = await sdk.initCheckout({
   amount: 45000,       // integer in major units (e.g. 45000 NGN)
   currency: "NGN",     // e.g. "NGN"
+  coinType?: "0x2::sui::SUI",  // optional: override settlement coin
   metadata?: { orderId: "ORDER-123" },
 });
 ```
@@ -116,6 +113,7 @@ const session = await sdk.initCheckout({
 | `amount`, `currency` | Checkout totals |
 | `merchantAddress` | Normalized Sui address |
 | `coinType` | Settlement coin type (from backend config) |
+| `supportedCoins` | Array of `{ symbol, type, decimals }` for available settlement coins |
 | `estimatedRate` | FX preview (NGN → token) when applicable |
 | `packageId`, `cryptoRegistryId`, `cryptoRegistryName` | On-chain config for crypto paths |
 
@@ -123,17 +121,29 @@ Throws if the backend returns a non-OK response.
 
 ---
 
-### `openModal(session, onClose?)`
+### `openModal(session, options?)`
 Opens the built-in checkout modal (bank transfer, OPay, Stripe, Sui wallet, outPay).
 
 ```ts
-const modal = sdk.openModal(session, () => {
-  // Called when the user closes the overlay
+const modal = sdk.openModal(session, {
+  onClose: () => console.log("closed"),
+  onPaymentComplete: (result) => console.log(result.txDigest, result.walrusBlobId),
+  redirectUrl: "/thank-you",
+  autoCloseOnSuccess: true,
 });
 ```
 
 **Returns** `SuiOutKitModal` (internal handle). The modal loads styles from `{backendUrl}/style.css` automatically.
 
+Options (`SuiOutKitModalOptions`):
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `onClose` | `() => void` | Called when the user dismisses the overlay |
+| `onPaymentComplete` | `(result: PaymentResult) => void` | Called after on-chain settlement with `{ nonce, txDigest, walrusBlobId }` |
+| `redirectUrl` | `string` | Redirect browser here after successful payment |
+| `autoCloseOnSuccess` | `boolean` | Auto-close the modal after settlement instead of showing success panel |
+
 > **Note:** Theme, logo, and `allowedMethods` customization are not exposed on `openModal` today. Use [custom UI](#custom-ui-no-modal) or extend the modal in source if you need that.
 
 ---
@@ -146,6 +156,7 @@ Binds checkout to a DOM button.
 | `selector` | `string` | CSS selector (e.g. `"#pay-btn"`) |
 | `options.amount` | `number` | Checkout amount |
 | `options.currency` | `string` | e.g. `"NGN"` |
+| `options.coinType` | `string` | Optional settlement coin type override |
 | `options.metadata` | `object` | Optional passthrough to `initCheckout` |
 
 ---
@@ -258,7 +269,7 @@ Webhooks (`/v1/checkout/webhook`, `/v1/checkout/stripe-webhook`) are server-to-p
 | `409 Treasury insufficient` | Operator vault underfunded for FX settlement amount |
 | Modal stuck on “waiting for settlement” | Webhook not reaching backend (Flutterwave hash, Stripe CLI, or ngrok) |
 | Stripe card errors on small NGN amounts | Backend enforces ~$0.50 USD equivalent minimum |
-| Crypto connect fails | Wrong `window.SuiOutKitNetwork` or registry env on backend |
+| Crypto connect fails | Wrong `mode` or registry env on backend |
 | Styles missing | Backend not serving `/style.css` or wrong `backendUrl` |
 
 See also [Developer Guide - Troubleshooting](/docs/developer-guide.md#troubleshooting).
@@ -266,9 +277,9 @@ See also [Developer Guide - Troubleshooting](/docs/developer-guide.md#troublesho
 
 
 ## Security
-- Only `merchantAddress` and `backendUrl` belong in browser code.
+- Only `merchantAddress`, `mode`, and `backendUrl` belong in browser code.
 - Never embed operator keys, Flutterwave secrets, or Stripe secret keys in the client.
-- Use **HTTPS** for `backendUrl` in production.
+- Use **HTTPS** for the API endpoint in production (default when `mode: "live"`).
 
 Report vulnerabilities through your project’s private security channel (do not file public issues with key material).
 

package/dist/config/api.d.ts

@@ -1,5 +1,5 @@
-/** Production SuiOutKit API origin (versioned paths under /v1/). */
-export declare const DEFAULT_API_ORIGIN = "http://localhost:5000";
+/** Production SuiOutKit API origin (versioned paths under /v1/). Use `mode` config to switch between local/test/live. */
+export declare const DEFAULT_API_ORIGIN = "https://api.suioutkit.xyz";
 /** API version prefix - all checkout and payment routes live under this path. */
 export declare const API_V1_PREFIX = "/v1";
 export declare function joinApiPath(origin: string, ...segments: string[]): string;

package/dist/config/modes.d.ts

@@ -0,0 +1,6 @@
+export type SuiOutKitMode = "local" | "test" | "live";
+export interface ModeConfig {
+    backendUrl: string;
+    suiNetwork: "mainnet" | "testnet";
+}
+export declare const MODE_MAP: Record<SuiOutKitMode, ModeConfig>;

package/dist/index.d.ts

@@ -1,13 +1,10 @@
-import { CheckoutSession, CheckoutSessionOptions, CryptoConfirmResponse, SuiOutKitModalOptions } from "./types/index.js";
+import { CheckoutSession, CheckoutSessionOptions, CryptoConfirmResponse, SuiOutKitModalOptions, SuiOutKitConfig } from "./types/index.js";
 import { SuiOutKitModal } from "./components/modal.js";
 export { DEFAULT_API_ORIGIN, API_V1_PREFIX } from "./config/api.js";
 export declare class SuiOutKit {
     private backendUrl;
     private merchantAddress;
-    constructor(config: {
-        merchantAddress: string;
-        backendUrl?: string;
-    });
+    constructor(config: SuiOutKitConfig);
     /**
      * Initializes a brand-new isolated checkout session from the backend.
      */
@@ -27,6 +24,7 @@ export declare class SuiOutKit {
     wrapButton(selector: string, options: {
         amount: number;
         currency: "NGN" | "SUI" | string;
+        coinType?: string;
         metadata?: Record<string, any>;
     }): void;
 }

package/dist/index.js

@@ -51981,7 +51981,7 @@ var loadStripe = function loadStripe2() {
 var import_react = __toESM(require_react());
 
 // src/config/api.ts
-var DEFAULT_API_ORIGIN = "http://localhost:5000";
+var DEFAULT_API_ORIGIN = "https://api.suioutkit.xyz";
 var API_V1_PREFIX = "/v1";
 function joinApiPath(origin, ...segments) {
   const base = origin.replace(/\/+$/, "");
@@ -52401,13 +52401,20 @@ var SuiOutKitModal = class {
   async handleCryptoPaymentPanel() {
     const container = this.overlay?.querySelector("#sok-content-panel");
     if (!container) return;
+    const coins = this.session.supportedCoins || [];
+    const currentCoin = this.session.coinType || "0x2::sui::SUI";
+    const currentSymbol = coins.find((c4) => c4.type === currentCoin)?.symbol || "SUI";
+    const coinChips = coins.length > 1 ? `<div class="sok-coin-selector">${coins.map(
+      (c4) => `<button class="sok-coin-chip${c4.type === currentCoin ? " active" : ""}" data-coin-type="${c4.type}">${c4.symbol}</button>`
+    ).join("")}</div>` : `<div class="sok-coin-badge">${currentSymbol}</div>`;
     container.innerHTML = `
       <button class="suioutkit-back" id="sok-back-btn">\u2190 Back to methods</button>
       <div class="suioutkit-header">
         <h2 class="suioutkit-title">Pay with Sui Wallet</h2>
-        <p class="suioutkit-subtitle">Choose SUI payment channel</p>
+        <p class="suioutkit-subtitle">Choose settlement token and payment channel</p>
       </div>
       <div class="suioutkit-panel">
+        ${coinChips}
         <p class="sok-status-text" style="margin-bottom: 12px;">
           Choose whether to pay via a desktop extension wallet or scan a dynamic QR Code with your mobile wallet.
         </p>
@@ -52419,6 +52426,17 @@ var SuiOutKitModal = class {
         </button>
       </div>
     `;
+    if (coins.length > 1) {
+      container.querySelectorAll(".sok-coin-chip").forEach((chip) => {
+        chip.addEventListener("click", () => {
+          const coinType = chip.dataset.coinType || "";
+          if (coinType && coinType !== this.session.coinType) {
+            this.session.coinType = coinType;
+            void this.handleCryptoPaymentPanel();
+          }
+        });
+      });
+    }
     container.querySelector("#sok-back-btn")?.addEventListener("click", () => this.renderSelectionPanel());
     container.querySelector("#sok-connect-extension-btn")?.addEventListener("click", async () => {
       this.renderLoadingPanel("Preparing crypto payment...");
@@ -52766,13 +52784,17 @@ var SuiOutKitModal = class {
     });
   }
   async loadCryptoIntent(method) {
+    const body = {
+      token: this.session.token,
+      method
+    };
+    if (this.session.coinType) {
+      body.coinType = this.session.coinType;
+    }
     const response = await fetch(joinApiPath(this.backendUrl, "checkout", "crypto", "intent"), {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        token: this.session.token,
-        method
-      })
+      body: JSON.stringify(body)
     });
     const result = await response.json();
     if (!response.ok) {
@@ -52890,6 +52912,13 @@ var SuiOutKitModal = class {
   }
 };
 
+// src/config/modes.ts
+var MODE_MAP = {
+  local: { backendUrl: "http://localhost:5000", suiNetwork: "testnet" },
+  test: { backendUrl: "https://api.staging.suioutkit.xyz", suiNetwork: "testnet" },
+  live: { backendUrl: "https://api.suioutkit.xyz", suiNetwork: "mainnet" }
+};
+
 // src/utils/http.ts
 var HttpError = class extends Error {
   constructor(message, status = null, body = null) {
@@ -52990,8 +53019,11 @@ var SuiOutKit = class {
     if (!config.merchantAddress) {
       throw new Error("SuiOutKit Error: merchantAddress is required.");
     }
-    this.backendUrl = (config.backendUrl || DEFAULT_API_ORIGIN).replace(/\/+$/, "");
+    const mode = config.mode || "live";
+    const modeCfg = MODE_MAP[mode];
+    this.backendUrl = (config.backendUrl || modeCfg.backendUrl).replace(/\/+$/, "");
     this.merchantAddress = config.merchantAddress;
+    window.SuiOutKitNetwork = modeCfg.suiNetwork;
   }
   /**
    * Initializes a brand-new isolated checkout session from the backend.
@@ -53005,6 +53037,7 @@ var SuiOutKit = class {
           amount: options.amount,
           currency: options.currency,
           merchantAddress: this.merchantAddress,
+          coinType: options.coinType,
           metadata: options.metadata || {}
         })
       });

package/dist/types/index.d.ts

@@ -1,8 +1,19 @@
-export type SomeType = any;
+export type SuiOutKitMode = "local" | "test" | "live";
+export interface SuiOutKitConfig {
+    merchantAddress: string;
+    mode?: SuiOutKitMode;
+    backendUrl?: string;
+}
+export interface SupportedCoin {
+    symbol: string;
+    type: string;
+    decimals: number;
+}
 export interface CheckoutSessionOptions {
     amount: number;
     currency: "NGN" | "SUI" | string;
     merchantAddress: string;
+    coinType?: string;
     metadata?: Record<string, any>;
 }
 export interface CheckoutSession {
@@ -17,6 +28,7 @@ export interface CheckoutSession {
     cryptoRegistryName?: string;
     coinType?: string;
     estimatedRate?: number;
+    supportedCoins?: SupportedCoin[];
 }
 export type ChargeMethod = "bank_transfer" | "opay" | "crypto" | "sui_wallet" | "outpay" | "stripe";
 export interface VirtualAccount {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suioutkit",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "Premium Universal Payment Gateway SDK for instant settlement on Sui",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/components/modal.ts

@@ -420,13 +420,27 @@ export class SuiOutKitModal {
     const container = this.overlay?.querySelector("#sok-content-panel");
     if (!container) return;
 
+    const coins = this.session.supportedCoins || [];
+    const currentCoin = this.session.coinType || "0x2::sui::SUI";
+    const currentSymbol = coins.find((c) => c.type === currentCoin)?.symbol || "SUI";
+
+    const coinChips = coins.length > 1
+      ? `<div class="sok-coin-selector">${coins
+          .map(
+            (c) =>
+              `<button class="sok-coin-chip${c.type === currentCoin ? " active" : ""}" data-coin-type="${c.type}">${c.symbol}</button>`
+          )
+          .join("")}</div>`
+      : `<div class="sok-coin-badge">${currentSymbol}</div>`;
+
     container.innerHTML = `
       <button class="suioutkit-back" id="sok-back-btn">← Back to methods</button>
       <div class="suioutkit-header">
         <h2 class="suioutkit-title">Pay with Sui Wallet</h2>
-        <p class="suioutkit-subtitle">Choose SUI payment channel</p>
+        <p class="suioutkit-subtitle">Choose settlement token and payment channel</p>
       </div>
       <div class="suioutkit-panel">
+        ${coinChips}
         <p class="sok-status-text" style="margin-bottom: 12px;">
           Choose whether to pay via a desktop extension wallet or scan a dynamic QR Code with your mobile wallet.
         </p>
@@ -439,6 +453,18 @@ export class SuiOutKitModal {
       </div>
     `;
 
+    if (coins.length > 1) {
+      container.querySelectorAll(".sok-coin-chip").forEach((chip) => {
+        chip.addEventListener("click", () => {
+          const coinType = (chip as HTMLElement).dataset.coinType || "";
+          if (coinType && coinType !== this.session.coinType) {
+            this.session.coinType = coinType;
+            void this.handleCryptoPaymentPanel();
+          }
+        });
+      });
+    }
+
     container.querySelector("#sok-back-btn")?.addEventListener("click", () => this.renderSelectionPanel());
 
     container.querySelector("#sok-connect-extension-btn")?.addEventListener("click", async () => {
@@ -858,13 +884,17 @@ export class SuiOutKitModal {
   }
 
   private async loadCryptoIntent(method: "sui_wallet" | "outpay"): Promise<CryptoIntentResponse> {
+    const body: Record<string, any> = {
+      token: this.session.token,
+      method
+    };
+    if (this.session.coinType) {
+      body.coinType = this.session.coinType;
+    }
     const response = await fetch(joinApiPath(this.backendUrl, "checkout", "crypto", "intent"), {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        token: this.session.token,
-        method
-      })
+      body: JSON.stringify(body)
     });
 
     const result: any = await response.json();

package/src/components/style.css

@@ -478,6 +478,48 @@
   100% { top: 0; }
 }
 
+.sok-coin-selector {
+  display: flex;
+  gap: 8px;
+  justify-content: center;
+  margin-bottom: 14px;
+  flex-wrap: wrap;
+}
+
+.sok-coin-chip {
+  background: var(--sok-card-bg);
+  border: 2px solid var(--sok-border);
+  border-radius: 20px;
+  padding: 6px 18px;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  color: var(--sok-text);
+}
+
+.sok-coin-chip:hover {
+  border-color: var(--sok-accent);
+  color: var(--sok-accent);
+}
+
+.sok-coin-chip.active {
+  border-color: var(--sok-accent);
+  background: var(--sok-accent);
+  color: #ffffff;
+}
+
+.sok-coin-badge {
+  display: inline-block;
+  background: var(--sok-accent);
+  color: #ffffff;
+  border-radius: 20px;
+  padding: 4px 16px;
+  font-size: 13px;
+  font-weight: 600;
+  margin-bottom: 14px;
+}
+
 .suioutkit-wallet-list {
   display: flex;
   flex-direction: column;

package/src/config/api.ts

@@ -2,9 +2,8 @@
 // Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
 // Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
 
-/** Production SuiOutKit API origin (versioned paths under /v1/). */
-//export const DEFAULT_API_ORIGIN = "https://api.suioutkit.xyz";
-export const DEFAULT_API_ORIGIN = "http://localhost:5000";
+/** Production SuiOutKit API origin (versioned paths under /v1/). Use `mode` config to switch between local/test/live. */
+export const DEFAULT_API_ORIGIN = "https://api.suioutkit.xyz";
 
 /** API version prefix - all checkout and payment routes live under this path. */
 export const API_V1_PREFIX = "/v1";

package/src/config/modes.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: GPL-3.0
+// Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
+// Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
+
+export type SuiOutKitMode = "local" | "test" | "live";
+
+export interface ModeConfig {
+  backendUrl: string;
+  suiNetwork: "mainnet" | "testnet";
+}
+
+export const MODE_MAP: Record<SuiOutKitMode, ModeConfig> = {
+  local: { backendUrl: "http://localhost:5000", suiNetwork: "testnet" },
+  test:  { backendUrl: "https://api.staging.suioutkit.xyz", suiNetwork: "testnet" },
+  live:  { backendUrl: "https://api.suioutkit.xyz", suiNetwork: "mainnet" },
+};

package/src/index.ts

@@ -2,9 +2,10 @@
 // Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
 // Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
 
-import { CheckoutSession, CheckoutSessionOptions, CryptoConfirmResponse, SuiOutKitModalOptions } from "./types/index.js";
+import { CheckoutSession, CheckoutSessionOptions, CryptoConfirmResponse, SuiOutKitModalOptions, SuiOutKitConfig, SuiOutKitMode } from "./types/index.js";
 import { SuiOutKitModal } from "./components/modal.js";
-import { DEFAULT_API_ORIGIN, joinApiPath } from "./config/api.js";
+import { joinApiPath, DEFAULT_API_ORIGIN } from "./config/api.js";
+import { MODE_MAP } from "./config/modes.js";
 
 export { DEFAULT_API_ORIGIN, API_V1_PREFIX } from "./config/api.js";
 
@@ -12,13 +13,15 @@ export class SuiOutKit {
   private backendUrl: string;
   private merchantAddress: string;
 
-  constructor(config: { merchantAddress: string; backendUrl?: string }) {
+  constructor(config: SuiOutKitConfig) {
     if (!config.merchantAddress) {
       throw new Error("SuiOutKit Error: merchantAddress is required.");
     }
-    // Strip trailing slashes and provide default fallback
-    this.backendUrl = (config.backendUrl || DEFAULT_API_ORIGIN).replace(/\/+$/, "");
+    const mode: SuiOutKitMode = config.mode || "live";
+    const modeCfg = MODE_MAP[mode];
+    this.backendUrl = (config.backendUrl || modeCfg.backendUrl).replace(/\/+$/, "");
     this.merchantAddress = config.merchantAddress;
+    (window as any).SuiOutKitNetwork = modeCfg.suiNetwork;
   }
 
   /**
@@ -33,6 +36,7 @@ export class SuiOutKit {
           amount: options.amount,
           currency: options.currency,
           merchantAddress: this.merchantAddress,
+          coinType: options.coinType,
           metadata: options.metadata || {}
         })
       });
@@ -86,7 +90,7 @@ export class SuiOutKit {
    */
   public wrapButton(
     selector: string,
-    options: { amount: number; currency: "NGN" | "SUI" | string; metadata?: Record<string, any> }
+    options: { amount: number; currency: "NGN" | "SUI" | string; coinType?: string; metadata?: Record<string, any> }
   ): void {
     const btn = document.querySelector(selector) as HTMLButtonElement;
     if (!btn) {

package/src/types/index.ts

@@ -2,12 +2,25 @@
 // Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
 // Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
 
-export type SomeType = any;
+export type SuiOutKitMode = "local" | "test" | "live";
+
+export interface SuiOutKitConfig {
+  merchantAddress: string;
+  mode?: SuiOutKitMode;
+  backendUrl?: string;
+}
+
+export interface SupportedCoin {
+  symbol: string;
+  type: string;
+  decimals: number;
+}
 
 export interface CheckoutSessionOptions {
   amount: number;
   currency: "NGN" | "SUI" | string;
   merchantAddress: string;
+  coinType?: string;
   metadata?: Record<string, any>;
 }
 
@@ -23,6 +36,7 @@ export interface CheckoutSession {
   cryptoRegistryName?: string;
   coinType?: string;
   estimatedRate?: number;
+  supportedCoins?: SupportedCoin[];
 }
 
 export type ChargeMethod = "bank_transfer" | "opay" | "crypto" | "sui_wallet" | "outpay" | "stripe";