suioutkit 1.0.1

package/src/config/api.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)
+
+/** 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";
+
+/** API version prefix - all checkout and payment routes live under this path. */
+export const API_V1_PREFIX = "/v1";
+
+export function joinApiPath(origin: string, ...segments: string[]): string {
+  const base = origin.replace(/\/+$/, "");
+  const path = [API_V1_PREFIX, ...segments].join("/").replace(/\/+/g, "/");
+  return `${base}${path}`;
+}

package/src/declarations.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/src/hooks/usePaymentStatus.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: GPL-3.0
+// Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
+// Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
+
+import { useEffect, useState } from "react";
+import { joinApiPath } from "../config/api.js";
+
+type PaymentUpdate = {
+  status?: "PENDING" | "PROCESSING" | "BANK_CONFIRMED" | "SETTLED" | "ERROR";
+  walrusBlobId?: string;
+  txDigest?: string;
+  error?: string;
+};
+
+/**
+ * Hook to listen to backend payment status via Server‑Sent Events.
+ * Usage: const update = usePaymentStatus(session.nonce);
+ */
+export function usePaymentStatus(backendUrl: string, nonce: string): PaymentUpdate {
+  const [state, setState] = useState<PaymentUpdate>({ status: "PENDING" });
+
+  useEffect(() => {
+    const source = new EventSource(joinApiPath(backendUrl, "payments", "stream", nonce));
+    source.onmessage = (e) => {
+      try {
+        const data = JSON.parse(e.data);
+        setState((prev) => ({ ...prev, ...data }));
+      } catch (_) { }
+    };
+    source.onerror = () => {
+      if (source.readyState === EventSource.CLOSED) {
+        setState((prev) => ({ ...prev, status: "ERROR", error: "Connection lost" }));
+        source.close();
+      }
+    };
+    return () => source.close();
+  }, [backendUrl, nonce]);
+
+  return state;
+}

package/src/hooks/usePolling.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: GPL-3.0
+// Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
+// Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
+/**
+ * Lightweight framework-agnostic polling utility.
+ * Usage:
+ * const poll = createPolling(async () => { await fetchStatus() }, 5000);
+ * poll.start();
+ * poll.stop();
+ */
+export function createPolling(fn: () => Promise<void> | void, intervalMs: number) {
+  let timer: number | null = null;
+  let running = false;
+
+  async function tick() {
+    try {
+      await fn();
+    } catch (e) {
+      // swallow errors — caller should handle inside fn
+      // but preserve running state
+    }
+    if (running) {
+      timer = (setTimeout(() => void tick(), intervalMs) as unknown) as number;
+    }
+  }
+
+  return {
+    start() {
+      if (running) return;
+      running = true;
+      tick();
+    },
+    stop() {
+      running = false;
+      if (timer) {
+        clearTimeout(timer as unknown as number);
+        timer = null;
+      }
+    },
+    isRunning() {
+      return running;
+    }
+  } as const;
+}
+
+export default createPolling;

package/src/index.ts

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: GPL-3.0
+// Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
+// Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
+
+import { CheckoutSession, CheckoutSessionOptions, CryptoConfirmResponse } from "./types/index.js";
+import { SuiOutKitModal } from "./components/modal.js";
+import { DEFAULT_API_ORIGIN, joinApiPath } from "./config/api.js";
+
+export { DEFAULT_API_ORIGIN, API_V1_PREFIX } from "./config/api.js";
+
+export class SuiOutKit {
+  private backendUrl: string;
+  private merchantAddress: string;
+
+  constructor(config: { merchantAddress: string; backendUrl?: string }) {
+    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(/\/+$/, "");
+    this.merchantAddress = config.merchantAddress;
+  }
+
+  /**
+   * Initializes a brand-new isolated checkout session from the backend.
+   */
+  public async initCheckout(options: Omit<CheckoutSessionOptions, "merchantAddress">): Promise<CheckoutSession> {
+    try {
+      const response = await fetch(joinApiPath(this.backendUrl, "checkout", "session"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          amount: options.amount,
+          currency: options.currency,
+          merchantAddress: this.merchantAddress,
+          metadata: options.metadata || {}
+        })
+      });
+
+      if (!response.ok) {
+        throw new Error(`Server returned status ${response.status}`);
+      }
+
+      return await response.json();
+    } catch (err) {
+      console.error("SuiOutKit SDK Init Error:", err);
+      throw new Error("SuiOutKit: Failed to initialize checkout session.");
+    }
+  }
+
+  /**
+   * Spawns the interactive RainbowKit-style checkout modal.
+   */
+  public openModal(session: CheckoutSession, onClose?: () => void): SuiOutKitModal {
+    return new SuiOutKitModal(session, this.backendUrl, () => {
+      if (onClose) onClose();
+    });
+  }
+
+  /**
+   * Confirms a crypto payment after wallet execution by submitting the tx digest.
+   */
+  public async confirmCryptoPayment(
+    nonce: string,
+    txDigest: string,
+    method: "sui_wallet" | "outpay" = "sui_wallet"
+  ): Promise<CryptoConfirmResponse> {
+    const response = await fetch(joinApiPath(this.backendUrl, "checkout", "crypto", "confirm"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ nonce, txDigest, method })
+    });
+
+    const result: CryptoConfirmResponse = await response.json();
+    if (!response.ok) {
+      return {
+        status: "error",
+        error: result.error || "Crypto confirmation failed."
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * Integrates dynamically with a targeted button on the merchant's landing page.
+   * Brands the button and isolates a unique checkout session per click.
+   */
+  public wrapButton(
+    selector: string,
+    options: { amount: number; currency: "NGN" | "SUI" | string; metadata?: Record<string, any> }
+  ): void {
+    const btn = document.querySelector(selector) as HTMLButtonElement;
+    if (!btn) {
+      console.warn(`SuiOutKit: Element with selector "${selector}" was not found.`);
+      return;
+    }
+
+    // Format display currency symbol
+    const currencySymbol = options.currency === "NGN" ? "₦" : "";
+    const formattedAmount = `${currencySymbol}${options.amount.toLocaleString()}`;
+    const originalText = btn.textContent || "Pay Now";
+
+    // Set premium branded text
+    btn.textContent = `Pay ${formattedAmount}`;
+
+    // Add pointer cursor and smooth styling transitions
+    btn.style.cursor = "pointer";
+    btn.style.transition = "opacity 0.2s ease";
+
+    btn.addEventListener("click", async () => {
+      const tempText = btn.textContent;
+      btn.disabled = true;
+      btn.textContent = "Loading Checkout...";
+      btn.style.opacity = "0.7";
+
+      try {
+        const session = await this.initCheckout(options);
+        this.openModal(session, () => {
+          // Restore button when modal is closed
+          btn.disabled = false;
+          btn.textContent = `Pay ${formattedAmount}`;
+          btn.style.opacity = "1";
+        });
+      } catch (err) {
+        alert("SuiOutKit Error: Unable to open secure payment session.");
+        btn.disabled = false;
+        btn.textContent = originalText;
+        btn.style.opacity = "1";
+      }
+    });
+  }
+}
+
+// Re-export small helpers
+export { default as request } from "./utils/http.js";
+export * from "./utils/format.js";
+export { default as createPolling } from "./hooks/usePolling.js";
+

package/src/types/index.ts

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: GPL-3.0
+// Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
+// Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
+
+export type SomeType = any;
+
+export interface CheckoutSessionOptions {
+  amount: number;
+  currency: "NGN" | "SUI" | string;
+  merchantAddress: string;
+  metadata?: Record<string, any>;
+}
+
+export interface CheckoutSession {
+  token: string;
+  nonce: string;
+  amount: number;
+  currency: string;
+  merchantAddress: string;
+  walrusBlobId?: string;
+  packageId?: string;
+  cryptoRegistryId?: string;
+  cryptoRegistryName?: string;
+  coinType?: string;
+  estimatedRate?: number;
+}
+
+export type ChargeMethod = "bank_transfer" | "opay" | "crypto" | "sui_wallet" | "outpay" | "stripe";
+
+export interface VirtualAccount {
+  accountNumber: string;
+  bankName: string;
+  amount: number;
+  expirySeconds: number;
+}
+
+export interface ChargeResponse {
+  status: "success" | "pending" | "error";
+  virtualAccount?: VirtualAccount;
+  opayPrompt?: string;
+  clientSecret?: string;
+  stripePublicKey?: string;
+  message?: string;
+}
+
+export interface CryptoIntentResponse {
+  nonce: string;
+  receiverAddress: string;
+  amountBaseUnits: number;
+  coinType: string;
+  packageId?: string;
+  registryName?: string;
+  walrusBlobId?: string;
+  rate?: number;
+}
+
+export interface CryptoConfirmResponse {
+  status: "success" | "error";
+  txDigest?: string;
+  walrusBlobId?: string;
+  error?: string;
+}
+
+export interface CheckoutStatusResponse {
+  status: "PENDING" | "PROCESSING" | "SETTLED" | "EXPIRED";
+  txDigest?: string;
+  walrusBlobId?: string;
+  error?: string;
+}

package/src/utils/format.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: GPL-3.0
+// Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
+// Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
+
+/** Format a Naira amount with currency symbol and grouping. */
+export function formatNgn(amount: number): string {
+  try {
+    return new Intl.NumberFormat("en-NG", { style: "currency", currency: "NGN", maximumFractionDigits: 0 }).format(amount);
+  } catch (_) {
+    // Fallback
+    return `₦${Math.round(amount).toLocaleString()}`;
+  }
+}
+
+/** Convert base integer units into token float given decimals. */
+export function toTokenUnits(baseUnits: number, decimals = 9): number {
+  return baseUnits / Math.pow(10, decimals);
+}
+
+/** Format token amounts with fixed decimals and trimming. */
+export function formatToken(amount: number, decimals = 9, digits = 6): string {
+  const value = Number(amount);
+  if (!isFinite(value)) return "0";
+  return value.toFixed(digits).replace(/(?:\.0+|(?<=\.[0-9]*?)0+)$/, "");
+}
+
+export default { formatNgn, toTokenUnits, formatToken };

package/src/utils/http.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: GPL-3.0
+// Copyright (c) 2026 The3rdWebLabs (https://github.com/the3rdweblabs)
+// Author: @CYBWithFlourish (https://github.com/CYBWithFlourish)
+
+export type RequestOptions = RequestInit & {
+  timeout?: number; // ms
+  retries?: number; // simple retry count for idempotent GETs
+};
+
+export class HttpError extends Error {
+  status: number | null;
+  body: any | null;
+  constructor(message: string, status: number | null = null, body: any | null = null) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "HttpError";
+  }
+}
+
+export async function request<T = any>(input: string, opts: RequestOptions = {}): Promise<T> {
+  const { timeout = 10000, retries = 0, ...fetchOpts } = opts;
+
+  const controller = new AbortController();
+  const id = setTimeout(() => controller.abort(), timeout);
+  let lastErr: any = null;
+
+  try {
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const res = await fetch(input, { signal: controller.signal, ...fetchOpts } as RequestInit);
+        clearTimeout(id);
+
+        const contentType = res.headers.get("content-type") || "";
+        let body: any = null;
+        if (contentType.includes("application/json")) {
+          body = await res.json();
+        } else {
+          body = await res.text();
+        }
+
+        if (!res.ok) {
+          throw new HttpError(`HTTP ${res.status}: ${res.statusText}`, res.status, body);
+        }
+
+        return body as T;
+      } catch (err: any) {
+        lastErr = err;
+        // If aborted or unrecoverable, break early
+        if (err.name === "AbortError") throw new HttpError("Request timed out", null, null);
+        // For non-GET methods, don't retry
+        const method = (fetchOpts.method || "GET").toUpperCase();
+        if (method !== "GET") throw err;
+        // Otherwise loop to retry
+      }
+    }
+
+    throw lastErr || new Error("Unknown fetch error");
+  } finally {
+    clearTimeout(id);
+  }
+}
+
+export default request;

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "lib": ["DOM", "ES2020"],
+    "rootDir": "./src",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedSideEffectImports": true,
+  },
+
+  "include": ["src/**/*"]
+}