suioutkit 1.1.1 → 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 |
 
@@ -158,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` |
 
 ---
@@ -270,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).
@@ -278,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.
      */

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(/\/+$/, "");
@@ -52912,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) {
@@ -53012,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.

package/dist/types/index.d.ts

@@ -1,4 +1,9 @@
-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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suioutkit",
-  "version": "1.1.1",
+  "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/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;
   }
 
   /**

package/src/types/index.ts

@@ -2,7 +2,13 @@
 // 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;