@coinomad/checkout 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @coinomad/checkout
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server-side SDK for [Coinomad](https://coinomad.xyz)'s programmatic stablecoin checkout API.
+
+> Requires Node.js 18+ (uses global `fetch`).
+
+## Install
+
+```bash
+npm install @coinomad/checkout
+```
+
+## Create a checkout
+
+```ts
+import { CoinomadCheckout } from '@coinomad/checkout';
+
+const coinomad = new CoinomadCheckout({
+  apiKey: process.env.COINOMAD_WIDGET_KEY, // ck_test_… or ck_live_…
+});
+
+const checkout = await coinomad.checkouts.create({
+  amount: '50.00',
+  currency: 'USD',
+  name: 'Conference Ticket',
+  description: 'General admission',
+  metadata: { event_id: 'evt_123', ticket_id: 't_456' },
+  merchant_reference: 'order_789',
+});
+
+// Embed this in an iframe for the customer:
+console.log(checkout.checkout_url);
+```
+
+The `apiKey` is the widget's key from your Coinomad dashboard (Stablecoin Collections → Widget → Manage → API keys). `test_mode` checkouts are created automatically with a `ck_test_` key and never require real funds.
+
+## Simulate a payment (test mode)
+
+With a `ck_test_` key, drive a checkout to completion without moving real funds:
+
+```ts
+const result = await coinomad.checkouts.simulate(checkout.id);
+// result.checkout.status === 'paid'
+// result.webhook  — { delivered: true, url } — the signed callback that fired
+```
+
+`simulate` only works on test-mode checkouts — a live-key checkout rejects it.
+
+## Verify a webhook
+
+```ts
+import { verifyWebhook } from '@coinomad/checkout';
+
+// In your webhook handler — pass the RAW body string, not a re-parsed object:
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-coinomad-signature'];
+  const ok = verifyWebhook(req.body.toString('utf8'), signature, process.env.COINOMAD_WEBHOOK_SECRET);
+  if (!ok) return res.status(401).end();
+
+  const event = JSON.parse(req.body);
+  // event.event === 'checkout.payment.confirmed' — process the payment
+});
+```
+
+The `webhook signing secret` is the `whsec_…` value from the widget's dashboard (Stablecoin Collections → Widget → Manage → Integration).
+
+## API
+
+- `new CoinomadCheckout({ apiKey, baseUrl? })`
+- `coinomad.checkouts.create(params)` → `{ id, reference_code, checkout_url, test_mode, … }`
+- `coinomad.checkouts.simulate(id)` → `{ checkout, webhook }` (test mode only)
+- `verifyWebhook(rawBody, signature, secret)` → `boolean`
+
+## Errors
+
+Non-2xx responses throw a `CoinomadError` with `.status` and `.code`. 5xx and network errors are retried (2 retries by default); 4xx errors throw immediately.

package/dist/checkouts.d.ts

@@ -0,0 +1,3 @@
+import { type Checkout, type CreateCheckoutParams, type SimulateResult } from './types';
+export declare function createCheckout(apiKey: string, baseUrl: string, params: CreateCheckoutParams, retries?: number): Promise<Checkout>;
+export declare function simulateCheckout(apiKey: string, baseUrl: string, id: string): Promise<SimulateResult>;

package/dist/checkouts.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCheckout = createCheckout;
+exports.simulateCheckout = simulateCheckout;
+const types_1 = require("./types");
+async function createCheckout(apiKey, baseUrl, params, retries = 2) {
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const res = await fetch(`${baseUrl}/api/v1/checkouts`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
+                body: JSON.stringify(params),
+            });
+            const json = (await res.json().catch(() => ({})));
+            if (!res.ok) {
+                const err = new types_1.CoinomadError(res.status, json.error?.code ?? 'UNKNOWN', json.error?.message ?? `Request failed with status ${res.status}`);
+                if (res.status < 500)
+                    throw err;
+                lastErr = err;
+                continue;
+            }
+            if (!json.data)
+                throw new types_1.CoinomadError(200, 'MALFORMED_RESPONSE', 'Response was missing data');
+            return json.data;
+        }
+        catch (err) {
+            if (err instanceof types_1.CoinomadError && err.status < 500)
+                throw err;
+            lastErr = err;
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new types_1.CoinomadError(0, 'NETWORK_ERROR', 'Failed to reach the Coinomad API');
+}
+async function simulateCheckout(apiKey, baseUrl, id) {
+    const res = await fetch(`${baseUrl}/api/v1/checkouts/${id}/simulate`, {
+        method: 'POST',
+        headers: { 'x-api-key': apiKey },
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || !json.data) {
+        throw new types_1.CoinomadError(res.status, json.error?.code ?? 'UNKNOWN', json.error?.message ?? `Simulate failed with status ${res.status}`);
+    }
+    return json.data;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { CheckoutConfig, CreateCheckoutParams, Checkout, SimulateResult } from './types';
+export declare class CoinomadCheckout {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(config: CheckoutConfig);
+    get checkouts(): {
+        create: (params: CreateCheckoutParams) => Promise<Checkout>;
+        simulate: (id: string) => Promise<SimulateResult>;
+    };
+}
+export { verifyWebhook } from './webhooks';
+export { CoinomadError, type CheckoutConfig, type CreateCheckoutParams, type Checkout, type WebhookPayload, type SimulateResult, } from './types';

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoinomadError = exports.verifyWebhook = exports.CoinomadCheckout = void 0;
+const checkouts_1 = require("./checkouts");
+class CoinomadCheckout {
+    constructor(config) {
+        if (!config.apiKey || !config.apiKey.startsWith('ck_')) {
+            throw new Error("Invalid API key — expected a 'ck_test_' or 'ck_live_' key");
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl ?? 'https://api.coinomad.xyz').replace(/\/+$/, '');
+    }
+    get checkouts() {
+        return {
+            create: (params) => (0, checkouts_1.createCheckout)(this.apiKey, this.baseUrl, params),
+            simulate: (id) => (0, checkouts_1.simulateCheckout)(this.apiKey, this.baseUrl, id),
+        };
+    }
+}
+exports.CoinomadCheckout = CoinomadCheckout;
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhooks_1.verifyWebhook; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "CoinomadError", { enumerable: true, get: function () { return types_1.CoinomadError; } });

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export interface CheckoutConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface CreateCheckoutParams {
+    amount: string;
+    currency: string;
+    name?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    merchant_reference?: string;
+    callback_url?: string;
+    redirect_url?: string;
+}
+export interface Checkout {
+    id: string;
+    reference_code: string;
+    checkout_url: string;
+    status: 'active' | 'expired' | 'paid';
+    test_mode: boolean;
+    amount_type: 'fixed';
+    fixed_amount: string;
+    currency_base: string;
+    merchant_reference: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface WebhookPayload {
+    event: string;
+    checkout_id: string;
+    checkout_reference: string;
+    payment_reference: string | null;
+    merchant_reference: string | null;
+    amount: string;
+    asset: string;
+    network: string;
+    tx_hash: string;
+    sender: string;
+    test_mode: boolean;
+}
+export interface SimulateResult {
+    checkout: Checkout;
+    webhook: {
+        delivered: boolean;
+        url: string | null;
+    };
+}
+export declare class CoinomadError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoinomadError = void 0;
+class CoinomadError extends Error {
+    constructor(status, code, message) {
+        super(message);
+        this.name = 'CoinomadError';
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.CoinomadError = CoinomadError;

package/dist/webhooks.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Verify a Coinomad webhook signature.
+ *
+ * The signature is an HMAC-SHA256 of the raw JSON request body, hex-encoded and
+ * prefixed with `sha256=`, sent in the `x-coinomad-signature` header.
+ *
+ * IMPORTANT: pass the RAW request body string (not a re-serialised object).
+ * If your framework's JSON body parser consumes the body, configure a raw
+ * body capture on the webhook route (e.g. Express `express.raw({ type: 'application/json' })`).
+ */
+export declare function verifyWebhook(rawBody: string, signature: string | undefined | null, secret: string): boolean;

package/dist/webhooks.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhook = verifyWebhook;
+const crypto_1 = require("crypto");
+/**
+ * Verify a Coinomad webhook signature.
+ *
+ * The signature is an HMAC-SHA256 of the raw JSON request body, hex-encoded and
+ * prefixed with `sha256=`, sent in the `x-coinomad-signature` header.
+ *
+ * IMPORTANT: pass the RAW request body string (not a re-serialised object).
+ * If your framework's JSON body parser consumes the body, configure a raw
+ * body capture on the webhook route (e.g. Express `express.raw({ type: 'application/json' })`).
+ */
+function verifyWebhook(rawBody, signature, secret) {
+    if (!signature)
+        return false;
+    const expected = 'sha256=' + (0, crypto_1.createHmac)('sha256', secret).update(rawBody).digest('hex');
+    const a = Buffer.from(expected);
+    const b = Buffer.from(signature);
+    if (a.length !== b.length)
+        return false;
+    return (0, crypto_1.timingSafeEqual)(a, b);
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@coinomad/checkout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Server-side SDK for Coinomad's programmatic stablecoin checkout API.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "coinomad",
+    "checkout",
+    "stablecoin",
+    "payments",
+    "usdc",
+    "usdt"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  }
 }