@tineon/t9n 0.1.2

package/README.md

@@ -0,0 +1,87 @@
+# `@tineon/t9n`
+
+Framework-agnostic checkout SDK for Tineon (T9N). Works in React, Vue, Angular, and plain JavaScript apps.
+
+## Modal strategy
+
+- Uses `Shadow DOM` (not iframe) for integration flexibility.
+- Uses max overlay z-index (`2147483647`) to stay above host app UI.
+
+## Features
+
+- Button trigger (`createButton` / `mountButton`)
+- Non-button trigger support (`bindTrigger`)
+- Button style overrides (`text`, `theme`, `className`, inline `style`)
+- 15-minute checkout session flow
+- Native-currency-only checkout enforcement
+- Address generation + QR + confirmation flow
+- Lifecycle hooks (`onOpen`, `onStatusChange`, `onSuccess`, `onFail`, etc.)
+
+## Install
+
+```bash
+npm i @tineon/t9n
+```
+
+## Quickstart
+
+```ts
+import { initializeT9n } from "@tineon/t9n";
+
+const checkout = initializeT9n({
+  publicKey: "pk_live_xxx",
+  amountNgn: 50000,
+  currencies: ["BTC", "ETH", "TRX"],
+  customer: { email: "buyer@example.com", name: "Ada", reference: "order-123" },
+  metadata: { orderId: "order-123" },
+  callbackUrl: "https://merchant.example.com/payment/success",
+  hooks: {
+    onSuccess: ({ sessionId }) => console.log("paid", sessionId),
+    onFail: ({ error }) => console.error("checkout error", error),
+  },
+});
+
+checkout.mountButton("#pay-btn-slot", {
+  text: "Pay with Crypto",
+  theme: "solid",
+});
+```
+
+## Triggers
+
+```ts
+checkout.open();
+
+const detach = checkout.bindTrigger("#custom-card-pay", "click");
+// later: detach()
+```
+
+## Runtime config
+
+```ts
+type CheckoutConfig = {
+  publicKey: string; // required, pk_live_*
+  amountNgn: number;
+  currencies: NativeCurrency[]; // required, native only, no duplicates
+  customer: { email: string; name?: string; reference?: string }; // email is required
+  metadata?: Record<string, unknown>;
+  callbackUrl?: string;
+  requestTimeoutMs?: number;
+  pollIntervalMs?: number;
+  hooks?: {
+    onOpen?: () => void;
+    onClose?: () => void;
+    onSessionCreated?: (session) => void;
+    onCurrencySelected?: (payload) => void;
+    onStatusChange?: (status) => void;
+    onSuccess?: (payload) => void;
+    onFail?: (payload) => void;
+  };
+  button?: {
+    text?: string;
+    className?: string;
+    theme?: "solid" | "light" | "outline";
+    style?: Record<string, string>;
+  };
+};
+```

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { type CheckoutConfig, type T9nButtonOptions } from "./types.js";
+export declare class T9nCheckout {
+    private cfg;
+    private currencies;
+    private modal?;
+    private sessionId;
+    private intervalId?;
+    private statusPollId?;
+    private expiresAt?;
+    private isOpen;
+    private lastResultFailed;
+    private hasAttemptedConfirm;
+    constructor(config: CheckoutConfig);
+    createButton(options?: T9nButtonOptions): HTMLButtonElement;
+    bindTrigger(target: string | HTMLElement, eventName?: keyof HTMLElementEventMap): () => void;
+    mountButton(target: string | HTMLElement, options?: T9nButtonOptions): HTMLButtonElement;
+    open(): Promise<void>;
+    close(): void;
+    private createSession;
+    private selectCurrency;
+    private confirmPayment;
+    private startTimer;
+    private startStatusPolling;
+    private defaultNetworkFor;
+    private fetchWithTimeout;
+    private assertSecureConfig;
+    private applyButtonStyle;
+    private applyButtonTheme;
+    private normalizeStatus;
+    private markFailed;
+    private markClosed;
+    private emitStatus;
+    private getApiBaseUrl;
+}
+export declare function initializeT9n(config: CheckoutConfig): T9nCheckout;

package/dist/index.js

@@ -0,0 +1,412 @@
+import { checkoutConfigSchema, T9N_DEFAULT_API_BASE_URL, } from "./types.js";
+import { CheckoutModal } from "./ui/modal.js";
+const DEFAULT_BUTTON_TEXT = "Pay with T9N";
+const DEFAULT_THEME = "solid";
+export class T9nCheckout {
+    constructor(config) {
+        this.sessionId = "";
+        this.isOpen = false;
+        this.lastResultFailed = false;
+        this.hasAttemptedConfirm = false;
+        this.cfg = checkoutConfigSchema.parse(config);
+        this.cfg.apiBaseUrl = this.cfg.apiBaseUrl || resolveDefaultApiBaseUrl();
+        this.currencies = this.cfg.currencies;
+        this.assertSecureConfig();
+    }
+    createButton(options) {
+        const btn = document.createElement("button");
+        btn.type = "button";
+        btn.textContent = options?.text || this.cfg.button?.text || DEFAULT_BUTTON_TEXT;
+        btn.className = options?.className || this.cfg.button?.className || "";
+        this.applyButtonTheme(btn, options?.theme || this.cfg.button?.theme || DEFAULT_THEME);
+        this.applyButtonStyle(btn, this.cfg.button?.style);
+        this.applyButtonStyle(btn, options?.style);
+        btn.onclick = async () => this.open();
+        return btn;
+    }
+    bindTrigger(target, eventName = "click") {
+        const element = typeof target === "string" ? document.querySelector(target) : target;
+        if (!element)
+            throw new Error("T9N: trigger target not found");
+        const handler = () => this.open();
+        element.addEventListener(eventName, handler);
+        return () => element.removeEventListener(eventName, handler);
+    }
+    mountButton(target, options) {
+        const container = typeof target === "string" ? document.querySelector(target) : target;
+        if (!container) {
+            throw new Error("T9N: target container not found for checkout button");
+        }
+        const btn = this.createButton(options);
+        container.appendChild(btn);
+        return btn;
+    }
+    async open() {
+        if (this.isOpen)
+            return;
+        this.isOpen = true;
+        this.lastResultFailed = false;
+        this.hasAttemptedConfirm = false;
+        try {
+            this.cfg.hooks?.onOpen?.();
+            const session = await this.createSession();
+            this.sessionId = session.sessionId;
+            this.expiresAt = new Date(session.expiresAt);
+            this.cfg.hooks?.onSessionCreated?.(session);
+            this.emitStatus("created");
+            this.modal = new CheckoutModal(this.currencies, {
+                onSelectCurrency: async (currency) => this.selectCurrency(currency),
+                onConfirmPayment: async () => this.confirmPayment(),
+                onClose: () => this.close(),
+            });
+            this.startTimer();
+            this.startStatusPolling();
+        }
+        catch (error) {
+            this.isOpen = false;
+            this.cfg.hooks?.onFail?.({ sessionId: this.sessionId || undefined, error: error?.message || "open failed" });
+            throw new Error(error?.message || "T9N: failed to open checkout");
+        }
+    }
+    close() {
+        if (this.intervalId)
+            window.clearInterval(this.intervalId);
+        if (this.statusPollId)
+            window.clearInterval(this.statusPollId);
+        if (this.lastResultFailed && this.sessionId) {
+            void this.markFailed();
+        }
+        else if (!this.hasAttemptedConfirm && this.sessionId) {
+            void this.markClosed();
+        }
+        this.modal?.close();
+        this.modal = undefined;
+        this.sessionId = "";
+        this.expiresAt = undefined;
+        this.isOpen = false;
+        this.emitStatus("closed");
+        this.cfg.hooks?.onClose?.();
+    }
+    async createSession() {
+        const res = await this.fetchWithTimeout(`${this.getApiBaseUrl()}/api/merchant/checkout/public/sessions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-public-key": this.cfg.publicKey,
+            },
+            body: JSON.stringify({
+                amountNgn: this.cfg.amountNgn,
+                supportedNativeCurrencies: this.cfg.currencies,
+                customer: this.cfg.customer,
+                metadata: this.cfg.metadata,
+            }),
+        });
+        if (!res.ok) {
+            let message = "T9N: failed to create checkout session";
+            try {
+                const data = await res.json();
+                if (data?.message)
+                    message = data.message;
+            }
+            catch (_) {
+                try {
+                    const text = await res.text();
+                    if (text)
+                        message = text;
+                }
+                catch (_) {
+                    // ignore
+                }
+            }
+            if (res.status === 429) {
+                throw new Error(`T9N_LIMIT_EXCEEDED: ${message}`);
+            }
+            if (res.status === 403) {
+                throw new Error(`T9N_FORBIDDEN: ${message}`);
+            }
+            throw new Error(`T9N_ERROR_${res.status}: ${message}`);
+        }
+        return (await res.json());
+    }
+    async selectCurrency(currency) {
+        const network = this.defaultNetworkFor(currency);
+        const res = await this.fetchWithTimeout(`${this.getApiBaseUrl()}/api/merchant/checkout/sessions/${this.sessionId}/select-currency`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-public-key": this.cfg.publicKey,
+            },
+            body: JSON.stringify({ currency, network }),
+        });
+        if (!res.ok) {
+            let message = "T9N: failed to select currency";
+            try {
+                const data = await res.json();
+                if (data?.message)
+                    message = data.message;
+            }
+            catch (_) {
+                try {
+                    const text = await res.text();
+                    if (text)
+                        message = text;
+                }
+                catch (_) {
+                    // ignore
+                }
+            }
+            throw new Error(`T9N_SELECT_ERROR_${res.status}: ${message}`);
+        }
+        const payload = (await res.json());
+        this.modal?.setAddress(payload.depositAddress);
+        this.modal?.setQrPayload(payload.depositAddress);
+        this.modal?.setDisclaimer(`Send exactly ${payload.expectedAmountCrypto} ${payload.currency} to the address below. Sending the wrong amount or asset can result in loss of funds.`);
+        this.cfg.hooks?.onCurrencySelected?.({
+            currency: payload.currency,
+            network,
+            depositAddress: payload.depositAddress,
+            expectedAmountCrypto: payload.expectedAmountCrypto,
+        });
+        this.emitStatus("awaiting_payment");
+    }
+    async confirmPayment() {
+        this.hasAttemptedConfirm = true;
+        this.modal?.setConfirmPending(true);
+        const res = await this.fetchWithTimeout(`${this.getApiBaseUrl()}/api/merchant/checkout/sessions/${this.sessionId}/confirm-payment`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-public-key": this.cfg.publicKey,
+            },
+            body: "{}",
+        });
+        if (!res.ok) {
+            this.modal?.setConfirmPending(false);
+            this.modal?.showResult("failed", "No payment detected yet. Please try again.");
+            this.lastResultFailed = true;
+            this.modal?.setConfirmLabel("Retry check");
+            this.emitStatus("pending_confirmation");
+            this.cfg.hooks?.onFail?.({ sessionId: this.sessionId || undefined, error: "confirm request failed" });
+            throw new Error("T9N: failed to confirm payment");
+        }
+        const payload = (await res.json());
+        this.modal?.setConfirmPending(false);
+        this.emitStatus(this.normalizeStatus(payload.status));
+        if (payload.status === "pending" || payload.status === "processing") {
+            this.modal?.showResult("failed", "No payment detected yet. Please try again.");
+            this.lastResultFailed = true;
+            this.modal?.setConfirmLabel("Retry check");
+            return;
+        }
+        this.modal?.setConfirmLabel("I have made the payment");
+        if (payload.status === "settled") {
+            this.modal?.showResult("success", "Payment received successfully.");
+            this.lastResultFailed = false;
+            this.cfg.hooks?.onSuccess?.({ sessionId: this.sessionId, status: payload.status });
+        }
+        if (payload.status === "expired") {
+            this.modal?.showResult("failed", "This session has expired.");
+            this.lastResultFailed = true;
+        }
+    }
+    startTimer() {
+        this.intervalId = window.setInterval(() => {
+            if (!this.expiresAt)
+                return;
+            const ms = this.expiresAt.getTime() - Date.now();
+            if (ms <= 0) {
+                this.modal?.setTimer("00:00");
+                this.modal?.setStatus("Session expired");
+                this.close();
+                return;
+            }
+            const minutes = Math.floor(ms / 60000)
+                .toString()
+                .padStart(2, "0");
+            const seconds = Math.floor((ms % 60000) / 1000)
+                .toString()
+                .padStart(2, "0");
+            this.modal?.setTimer(`${minutes}:${seconds}`);
+        }, 1000);
+    }
+    startStatusPolling() {
+        this.statusPollId = window.setInterval(async () => {
+            if (!this.sessionId)
+                return;
+            try {
+                const res = await this.fetchWithTimeout(`${this.getApiBaseUrl()}/api/merchant/checkout/sessions/${this.sessionId}`, {
+                    method: "GET",
+                    headers: { "x-public-key": this.cfg.publicKey },
+                });
+                if (!res.ok)
+                    return;
+                const payload = (await res.json());
+                if (payload.status) {
+                    const normalized = this.normalizeStatus(payload.status);
+                    this.emitStatus(normalized);
+                    if (normalized === "settled") {
+                        this.modal?.showResult("success", "Payment received successfully.");
+                        this.lastResultFailed = false;
+                        if (this.intervalId)
+                            window.clearInterval(this.intervalId);
+                        if (this.statusPollId)
+                            window.clearInterval(this.statusPollId);
+                        this.cfg.hooks?.onSuccess?.({ sessionId: this.sessionId, status: payload.status });
+                    }
+                    if (normalized === "failed") {
+                        if (this.hasAttemptedConfirm) {
+                            this.modal?.showResult("failed", "No payment detected yet. Please try again.");
+                            this.lastResultFailed = true;
+                            this.cfg.hooks?.onFail?.({ sessionId: this.sessionId, error: "checkout failed" });
+                        }
+                    }
+                }
+                if (payload.status === "expired") {
+                    this.modal?.showResult("failed", "This session has expired.");
+                    this.lastResultFailed = true;
+                    if (this.intervalId)
+                        window.clearInterval(this.intervalId);
+                    if (this.statusPollId)
+                        window.clearInterval(this.statusPollId);
+                }
+            }
+            catch (_) {
+                // keep modal alive even if one poll fails
+                this.cfg.hooks?.onFail?.({ sessionId: this.sessionId || undefined, error: "session status poll failed" });
+            }
+        }, this.cfg.pollIntervalMs);
+    }
+    defaultNetworkFor(currency) {
+        const map = {
+            BTC: "bitcoin",
+            ETH: "ethereum",
+            BNB: "bsc",
+            MATIC: "polygon",
+            AVAX: "avax",
+            SOL: "solana",
+            TRX: "tron",
+            LSK: "lisk",
+            FLOW: "flow",
+            RON: "ronin",
+            SEI: "sei",
+            FTM: "fantom",
+            HBAR: "hedera",
+        };
+        return map[currency] || "ethereum";
+    }
+    async fetchWithTimeout(input, init) {
+        const controller = new AbortController();
+        const timeout = window.setTimeout(() => controller.abort(), this.cfg.requestTimeoutMs);
+        try {
+            return await fetch(input, { ...init, signal: controller.signal });
+        }
+        finally {
+            window.clearTimeout(timeout);
+        }
+    }
+    assertSecureConfig() {
+        const apiURL = new URL(this.getApiBaseUrl());
+        const isLocalHost = apiURL.hostname === "localhost" || apiURL.hostname === "127.0.0.1";
+        if (!isLocalHost && apiURL.protocol !== "https:") {
+            throw new Error("T9N: apiBaseUrl must use HTTPS outside local development.");
+        }
+    }
+    applyButtonStyle(btn, style) {
+        if (!style)
+            return;
+        Object.entries(style).forEach(([key, value]) => {
+            btn.style.setProperty(key, value);
+        });
+    }
+    applyButtonTheme(btn, theme) {
+        btn.style.borderRadius = "10px";
+        btn.style.padding = "12px 18px";
+        btn.style.fontSize = "14px";
+        btn.style.fontWeight = "700";
+        btn.style.cursor = "pointer";
+        btn.style.transition = "all .18s ease";
+        switch (theme) {
+            case "light":
+                btn.style.border = "1px solid #dbe4f0";
+                btn.style.background = "#ffffff";
+                btn.style.color = "#0f172a";
+                break;
+            case "outline":
+                btn.style.border = "1px solid #0f172a";
+                btn.style.background = "transparent";
+                btn.style.color = "#0f172a";
+                break;
+            default:
+                btn.style.border = "1px solid #0f172a";
+                btn.style.background = "#0f172a";
+                btn.style.color = "#ffffff";
+                break;
+        }
+    }
+    normalizeStatus(value) {
+        switch (value) {
+            case "created":
+            case "address_generated":
+                return "awaiting_payment";
+            case "awaiting_payment":
+            case "pending_confirmation":
+            case "closed":
+            case "expired":
+            case "settled":
+            case "failed":
+                return value;
+            default:
+                return "failed";
+        }
+    }
+    async markFailed() {
+        try {
+            await this.fetchWithTimeout(`${this.getApiBaseUrl()}/api/merchant/checkout/sessions/${this.sessionId}/fail`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-public-key": this.cfg.publicKey,
+                },
+                body: "{}",
+            });
+        }
+        catch (_) {
+            // ignore best-effort failure mark
+        }
+    }
+    async markClosed() {
+        try {
+            await this.fetchWithTimeout(`${this.getApiBaseUrl()}/api/merchant/checkout/sessions/${this.sessionId}/close`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-public-key": this.cfg.publicKey,
+                },
+                body: "{}",
+            });
+        }
+        catch (_) {
+            // ignore best-effort close mark
+        }
+    }
+    emitStatus(status) {
+        this.cfg.hooks?.onStatusChange?.(status);
+    }
+    getApiBaseUrl() {
+        return this.cfg.apiBaseUrl || resolveDefaultApiBaseUrl();
+    }
+}
+function resolveDefaultApiBaseUrl() {
+    if (typeof window === "undefined") {
+        return T9N_DEFAULT_API_BASE_URL;
+    }
+    const host = window.location.hostname.toLowerCase();
+    const isLocal = host === "localhost" || host === "127.0.0.1" || host === "::1";
+    if (isLocal) {
+        return "http://localhost:8090";
+    }
+    return T9N_DEFAULT_API_BASE_URL;
+}
+export function initializeT9n(config) {
+    return new T9nCheckout(config);
+}

package/dist/security/integrity.d.ts

@@ -0,0 +1 @@
+export declare function sha256Hex(input: string): Promise<string>;

package/dist/security/integrity.js

@@ -0,0 +1,8 @@
+export async function sha256Hex(input) {
+    const enc = new TextEncoder();
+    const data = enc.encode(input);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(hash))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}