@fiatden/openpay 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,270 @@
-# Temporary Holding Version
+# @openpay/sdk
 
-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.
+Official TypeScript SDK for **OpenPay** — the Stripe-alternative payment orchestrator. One integration, multiple African payment providers (Paystack, Flutterwave, Korapay, Hyperswitch), multi-app workspaces, subscriptions, coupons, metering, payouts, and full platform analytics.
+
+- **TypeScript-first** — full type definitions for every request and response
+- **23 resources** — charges, checkout, subscriptions, coupons, customers, apps, payouts, analytics, and more
+- **Node 18+** — uses the global `fetch`, zero runtime dependencies
+
+## Install
+
+```bash
+npm install @openpay/sdk
+```
+
+## Quick start
+
+```ts
+import { OpenPayApi, OpenPayError } from '@openpay/sdk';
+
+const openpay = new OpenPayApi('pk_your_api_key', {
+  baseUrl: 'https://api.your-domain.com', // default: http://localhost:3000
+  platformName: 'Open Pay',               // shown in emails/receipts (optional)
+});
+
+try {
+  const charge = await openpay.charges.create({
+    amount: 500000,                 // ₦5,000 in kobo
+    email: 'customer@gmail.com',
+    merchant_id: 'merchant-uuid',
+  });
+  console.log(charge.authorization_url); // redirect the customer here
+} catch (err) {
+  if (err instanceof OpenPayError) {
+    console.error(`${err.status} ${err.code}: ${err.message}`);
+  }
+}
+```
+
+## Authentication
+
+Pass any valid API key. Keys created with `openpay.apiKeys.create()` are returned **once** — store the secret immediately. Two capabilities are worth knowing:
+
+- **Scopes** — keys carry `v1:read` / `v1:write` scopes; write operations require a key with `v1:write`.
+- **Workspace binding** — a key can be bound to one app (workspace). Calls made with a bound key are automatically scoped to that workspace for app-aware resources (charges, checkout, coupons, plans, payouts). You never need to repeat `app_id` on every call, but an explicit `app_id` parameter always wins.
+
+```ts
+const { api_key, note } = await openpay.apiKeys.create({
+  name: 'Production server key',
+  scopes: ['v1:read', 'v1:write'],
+  // app_id: 'app-uuid', // optional: bind this key to one workspace
+});
+```
+
+## Workspaces (apps)
+
+Apps are the platform's **workspaces**: each one partitions API keys, webhook endpoints, hosted-checkout branding, transactions, subscription plans, subscriptions, coupons, disputes, and provider credentials. Use them to run a marketplace, a SaaS product, and a newsletter business on one merchant account with full isolation.
+
+```ts
+// 1. Create a workspace (one-time secret pair — save it immediately)
+const app = await openpay.apps.create({ name: 'Marketplace', slug: 'marketplace' });
+console.log(app.publishable_key, app.secret_key); // shown once
+
+// 2. Every app-scoped resource accepts an explicit app_id
+await openpay.coupons.create({
+  code: 'WELCOME10',
+  discount_type: 'percentage',
+  discount_value: 1000, // 10% (basis points)
+  app_id: app.id,       // scoped to this workspace only
+});
+await openpay.subscriptions.createPlan({
+  merchant_id: 'merchant-uuid',
+  name: 'Pro monthly',
+  amount: 2500000,
+  currency: 'NGN',
+  interval_unit: 'month',
+  interval_count: 1,
+  app_id: app.id,
+});
+
+// 3. Omit app_id → merchant-wide (usable by every workspace)
+await openpay.coupons.create({ code: 'SITEWIDE10', /* … */ });
+
+// 4. Workspace rollups
+const stats = await openpay.apps.get(app.id);          // volume, subs, disputes
+const analytics = await openpay.apps.analytics(app.id, '30d');
+
+// 5. Lost secret? Rotate it (old secret is revoked immediately)
+const rotated = await openpay.apps.rotateSecret(app.id);
+```
+
+**Coupon scoping rules** (enforced server-side): a coupon with `app_id` set is redeemable only in that workspace; a coupon with `app_id: null` is redeemable everywhere for that merchant. The same code may exist once merchant-wide and once per workspace.
+
+## Resources
+
+| Resource | Methods |
+|---|---|
+| `openpay.charges` | `create`, `retrieve`, `refund`, `tokenize`, `invoice`, `sendInvoice` |
+| `openpay.checkout` | `create`, `get` |
+| `openpay.subscriptions` | `createPlan`, `listPlans`, `create`, `list`, `resume`, `cancel` |
+| `openpay.coupons` | `create`, `list`, `get`, `update`, `deactivate`, `validate` |
+| `openpay.customers` | `get`, `paymentMethods`, `transactions`, `subscriptions`, `disputes`, `recomputeRisk`, `update`, `exportData`, `erase` |
+| `openpay.apps` | `create`, `list`, `get`, `update`, `rotateSecret`, `archive`, `analytics` |
+| `openpay.payouts` | `create`, `retrieve`, `list`, `listScheduled`, `createBulk` |
+| `openpay.disputes` | `list`, `get`, `listEvidenceSubmissions`, `markSubmitted` |
+| `openpay.apiKeys` | `create`, `list`, `rotate`, `revoke`, `update` |
+| `openpay.webhooks` | `list`, `retrieve`, `update`, `delete`, `deliveries`, `test` |
+| `openpay.metering` | `record`, `report`, `history`, `createMeter`, `listMeters`, `deactivateMeter` |
+| `openpay.reconciliation` | `upload`, `listReports`, `getReport`, `listUnreconciled`, `clearOperatorHold` |
+| `openpay.fx` | `list`, `set` |
+| `openpay.currencies` | `list`, `upsert`, `update`, `deactivate` |
+| `openpay.analytics` | `getOverview`, `getMerchantAnalytics`, `getPnl`, `getTrialBalance`, `getCircuitStatus`, `listFxRates`, `getFraudAnalytics`, `getChargebackRatios` |
+| `openpay.providers` | `listConfigs`, `deleteConfig`, `getFees` |
+| `openpay.customers` (CRM) | see `exportData` / `erase` for GDPR flows |
+| `openpay.paymentLinks` | `create`, `list`, `get`, `deactivate` |
+| `openpay.referrals` | `myReferral`, `commissions` |
+| `openpay.riskReview` | `list`, `get`, `approve`, `decline`, `stats` |
+| `openpay.emailTemplates` | `get`, `create`, `update`, `delete`, `preview` |
+| `openpay.totp` | `setup`, `verify`, `disable`, `status`, `submitChallenge` |
+| `openpay.auth` | `register`, `login`, `me`, `refresh`, `logout`, `verifyEmail`, `resendVerification`, `changePassword`, `forgotPassword`, `resetPassword`, `deleteAccount` |
+
+## Payments
+
+```ts
+// Direct charge (provider is auto-routed by currency and availability)
+const charge = await openpay.charges.create({
+  amount: 500000,
+  email: 'customer@gmail.com',
+  merchant_id: 'merchant-uuid',
+  currency: 'NGN',
+  // app_id: 'app-uuid',        // optional workspace attribution
+  // coupon_code: 'WELCOME10',  // app-scoped coupons are honored here
+  // metadata: { order_id: '123' },
+});
+
+// Hosted checkout (branded per workspace via the app's colors/logo)
+const session = await openpay.checkout.create({
+  amount: 1000000,
+  email: 'customer@gmail.com',
+  success_url: 'https://yourapp.com/thanks',
+  cancel_url: 'https://yourapp.com/cancel',
+});
+window.open(session.checkout_url);
+
+// Verify, refund
+const c = await openpay.charges.retrieve(charge.reference);
+await openpay.charges.refund(charge.reference, { amount: 100000 }); // partial
+
+// Recurring: charge a saved authorization (from a prior payment)
+await openpay.charges.tokenize({
+  amount: 2500000,
+  email: 'customer@gmail.com',
+  auth_token: 'AUTH_xxx',
+  reference: 'order-42-renewal',
+  currency: 'NGN',
+});
+```
+
+## Subscriptions
+
+```ts
+const plan = await openpay.subscriptions.createPlan({
+  merchant_id: 'merchant-uuid',
+  name: 'Pro monthly',
+  amount: 2500000,
+  currency: 'NGN',
+  interval_unit: 'month',   // day | week | month | quarter | year
+  interval_count: 1,
+  trial_days: 14,           // optional
+  // app_id: 'app-uuid',
+});
+
+const sub = await openpay.subscriptions.create({
+  plan_id: plan.id,
+  customer_id: 'customer-uuid',
+  payment_method_id: 'pm-uuid',   // a reusable card from a prior charge
+});
+
+await openpay.subscriptions.cancel(sub.id);   // ends at period end
+await openpay.subscriptions.resume(sub.id);
+```
+
+Billing runs server-side: the platform's durable billing-attempt ledger reserves wallet credit, charges only the uncovered remainder through the provider, and idempotently finalizes from provider webhooks — plan changes mid-cycle bank a proration credit instead of double-charging.
+
+## Webhooks
+
+```ts
+const hooks = await openpay.webhooks.list();
+await openpay.webhooks.update(hooks.data[0].id, {
+  url: 'https://yourapp.com/api/webhooks',
+  events: ['charge.success', 'charge.failed'],
+});
+const deliveries = await openpay.webhooks.deliveries(hooks.data[0].id);
+await openpay.webhooks.test(hooks.data[0].id); // sends a test event
+```
+
+Inbound provider webhooks (Paystack/Korapay/Flutterwave/Hyperswitch → `POST /v1/webhooks/<provider>`) are verified with HMAC over the **raw request body** before any processing.
+
+## Metering & usage-based billing
+
+```ts
+await openpay.metering.record('api_calls', 1, sub.id);
+const report = await openpay.metering.report('api_calls', 'day');
+```
+
+## Analytics & finance
+
+```ts
+await openpay.analytics.getOverview();
+await openpay.analytics.getPnl({ period_start: '2024-01-01', period_end: '2024-01-31' });
+await openpay.analytics.getTrialBalance();   // double-entry integrity check
+await openpay.analytics.getCircuitStatus();  // provider health
+```
+
+## Error handling
+
+All errors throw `OpenPayError`:
+
+```ts
+import { OpenPayError } from '@openpay/sdk';
+
+try {
+  await openpay.charges.create({ /* … */ });
+} catch (err) {
+  if (err instanceof OpenPayError) {
+    switch (err.status) {
+      case 400: // validation_error — err.code carries the field detail
+        break;
+      case 401: // authentication_error — check the API key
+        break;
+      case 403: // authorization_error — scope or tenant violation
+        break;
+      case 409: // conflict — duplicate reference, etc.
+        break;
+      case 429: // rate_limit_error — back off and retry
+        break;
+    }
+  }
+}
+```
+
+| Status | Type | Meaning |
+|---|---|---|
+| 400 | `validation_error` | Invalid parameters; `err.code` has the zod detail |
+| 401 | `authentication_error` | Missing/invalid API key or session |
+| 403 | `authorization_error` | Scope missing, wrong tenant, or CSRF failure |
+| 404 | `not_found` | Resource doesn't exist or belongs to another tenant |
+| 409 | `conflict` | Duplicate (e.g. reference or code already used) |
+| 429 | `rate_limit_error` | Too many requests |
+| 500 | `api_error` | Server-side failure — safe to retry with the same idempotency key |
+
+## Idempotency & safety notes
+
+- Payouts accept `idempotency_key` — retries return the original payout instead of double-paying.
+- Charge references are unique per merchant; retrying with the same reference is safe.
+- Secrets (`secret_key`, API keys) are returned exactly once at creation/rotation.
+- Platform provider credentials (env keys) are **test-only**: production merchant traffic must use merchant-configured provider credentials.
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest
+npm run build       # emit dist/
+npm publish         # runs prepublishOnly: typecheck → test → build
+```
+
+## License
+
+MIT

package/dist/analytics.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=analytics.test.d.ts.map

package/dist/analytics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.test.d.ts","sourceRoot":"","sources":["../src/analytics.test.ts"],"names":[],"mappings":""}

package/dist/analytics.test.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const analytics_1 = require("./resources/analytics");
+// Mock global fetch
+const mockFetch = vitest_1.vi.fn();
+global.fetch = mockFetch;
+function createMockClient(responseData, status = 200) {
+    mockFetch.mockResolvedValueOnce({
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => responseData,
+    });
+    const apiKey = 'pk_test_123';
+    // Inline a minimal HttpClient since we can't easily import it without
+    // triggering the actual fetch implementation
+    const client = {
+        request: async (path, options) => {
+            const { method = 'GET', body, params } = options || {};
+            let url = `http://localhost:3000${path}`;
+            if (params) {
+                const qs = Object.entries(params)
+                    .filter(([, v]) => v !== undefined)
+                    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+                    .join('&');
+                if (qs)
+                    url += `?${qs}`;
+            }
+            const response = await fetch(url, {
+                method,
+                headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
+                body: body ? JSON.stringify(body) : undefined,
+            });
+            const data = await response.json();
+            if (!response.ok)
+                throw new Error(data.message || `HTTP ${response.status}`);
+            return data;
+        },
+    };
+    return { client };
+}
+(0, vitest_1.describe)('AnalyticsResource', () => {
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.clearAllMocks();
+    });
+    (0, vitest_1.it)('getOverview returns platform overview metrics', async () => {
+        const overview = {
+            total_transactions: 1500,
+            total_volume: 750000000,
+            active_merchants: 42,
+            active_subscriptions: 88,
+            platform_revenue: 18750000,
+        };
+        const { client } = createMockClient(overview);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getOverview();
+        (0, vitest_1.expect)(result).toEqual(overview);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/overview', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('getMerchantAnalytics fetches per-merchant data', async () => {
+        const merchantData = { merchant_id: 'uuid-123', total_volume: 500000 };
+        const { client } = createMockClient(merchantData);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getMerchantAnalytics('uuid-123');
+        (0, vitest_1.expect)(result).toEqual(merchantData);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/merchant/uuid-123', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('getPnl returns P&L statement with date range', async () => {
+        const pnl = {
+            period: { start: '2024-01-01T00:00:00Z', end: '2024-01-31T23:59:59Z' },
+            income: { platform_commissions: 500000, fx_revenue: 12000, total_revenue: 512000 },
+            expenses: { provider_fees: 80000, coupon_discounts: 25000, referral_commissions: 15000, total_expenses: 120000 },
+            net_profit: 392000,
+            metrics: { gross_volume: 20000000, transaction_count: 400, take_rate_pct: 2.5, profit_margin_pct: 76.56 },
+            currency: 'NGN',
+        };
+        const { client } = createMockClient(pnl);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getPnl({ period_start: '2024-01-01', period_end: '2024-01-31' });
+        (0, vitest_1.expect)(result).toEqual(pnl);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/pnl?period_start=2024-01-01&period_end=2024-01-31', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('getPnl works without params', async () => {
+        const pnl = { period: {}, net_profit: 0, currency: 'NGN' };
+        const { client } = createMockClient(pnl);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getPnl();
+        (0, vitest_1.expect)(result).toEqual(pnl);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/pnl', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('getTrialBalance returns balanced trial balance', async () => {
+        const tb = {
+            as_of: '2024-01-15T00:00:00Z',
+            credits: [{ category: 'Payment Revenue', total: 1000000 }],
+            debits: [{ category: 'Merchant Settlements', total: 1000000 }],
+            summary: { total_credits: 1000000, total_debits: 1000000, net: 0, balanced: true },
+            wallet_liabilities: { available_balance: 500000, pending_balance: 100000, locked_balance: 0, total: 600000 },
+            currency: 'NGN',
+        };
+        const { client } = createMockClient(tb);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getTrialBalance('2024-01-15');
+        (0, vitest_1.expect)(result).toEqual(tb);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/trial-balance?as_of=2024-01-15', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('getTrialBalance works without date', async () => {
+        const tb = { summary: { balanced: true } };
+        const { client } = createMockClient(tb);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getTrialBalance();
+        (0, vitest_1.expect)(result).toEqual(tb);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/trial-balance', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('getCircuitStatus returns provider states', async () => {
+        const circuits = {
+            data: [
+                { provider: 'paystack', circuit: 'closed', open_until: null, failure_count: 0, last_failure_at: null },
+                { provider: 'flutterwave', circuit: 'open', open_until: '2024-01-01T00:00:00Z', failure_count: 7, last_failure_at: '2023-12-31T23:59:00Z' },
+            ],
+        };
+        const { client } = createMockClient(circuits);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getCircuitStatus();
+        (0, vitest_1.expect)(result).toEqual(circuits);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/circuits', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('listFxRates returns active rates', async () => {
+        const rates = {
+            data: [
+                { base: 'USD', target: 'NGN', rate: 1550.25, source: 'manual', spread: 0.5 },
+                { base: 'NGN', target: 'GHS', rate: 0.0083, source: 'auto', spread: 1.0 },
+            ],
+        };
+        const { client } = createMockClient(rates);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.listFxRates();
+        (0, vitest_1.expect)(result).toEqual(rates);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/fx-rates', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('setFxRate creates a new rate', async () => {
+        const newRate = { base: 'USD', target: 'NGN', rate: 1600, source: 'manual', spread: 0.5 };
+        const { client } = createMockClient(newRate, 201);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.setFxRate({
+            base_currency: 'USD',
+            target_currency: 'NGN',
+            rate: 1600,
+            source: 'manual',
+        });
+        (0, vitest_1.expect)(result).toEqual(newRate);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/analytics/fx-rates', vitest_1.expect.objectContaining({
+            method: 'POST',
+            body: JSON.stringify({ base_currency: 'USD', target_currency: 'NGN', rate: 1600, source: 'manual' }),
+        }));
+    });
+    (0, vitest_1.it)('getAuditLogs fetches with filters', async () => {
+        const logs = { data: [{ id: '1', action: 'charge.success' }], total: 1, has_more: false };
+        const { client } = createMockClient(logs);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getAuditLogs({ action: 'charge.success', limit: 10 });
+        (0, vitest_1.expect)(result).toEqual(logs);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/audit-logs?action=charge.success&limit=10', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('getAuditLogs works without params', async () => {
+        const logs = { data: [], total: 0, has_more: false };
+        const { client } = createMockClient(logs);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        const result = await analytics.getAuditLogs();
+        (0, vitest_1.expect)(result).toEqual(logs);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/audit-logs', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('skips undefined params in query string', async () => {
+        const logs = { data: [], total: 0, has_more: false };
+        const { client } = createMockClient(logs);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        await analytics.getAuditLogs({ action: 'charge.success', resource_type: undefined, limit: 20 });
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/audit-logs?action=charge.success&limit=20', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('propagates API errors', async () => {
+        const { client } = createMockClient({ message: 'Not found' }, 404);
+        const analytics = new analytics_1.AnalyticsResource(client);
+        await (0, vitest_1.expect)(analytics.getOverview()).rejects.toThrow('Not found');
+    });
+});

package/dist/apps.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=apps.test.d.ts.map

package/dist/apps.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.test.d.ts","sourceRoot":"","sources":["../src/apps.test.ts"],"names":[],"mappings":""}

package/dist/apps.test.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const apps_1 = require("./resources/apps");
+// Mock global fetch
+const mockFetch = vitest_1.vi.fn();
+global.fetch = mockFetch;
+function createMockClient(responseData, status = 200) {
+    mockFetch.mockResolvedValueOnce({
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => responseData,
+    });
+    const client = {
+        request: async (path, options) => {
+            const { method = 'GET', body } = options || {};
+            const response = await fetch(`http://localhost:3000${path}`, {
+                method,
+                headers: { 'Content-Type': 'application/json', 'x-api-key': 'pk_test_123' },
+                body: body ? JSON.stringify(body) : undefined,
+            });
+            const data = await response.json();
+            if (!response.ok)
+                throw new Error(data.message || `HTTP ${response.status}`);
+            return data;
+        },
+    };
+    return { client };
+}
+(0, vitest_1.describe)('AppsResource', () => {
+    (0, vitest_1.beforeEach)(() => {
+        vitest_1.vi.clearAllMocks();
+    });
+    (0, vitest_1.it)('create posts params and returns the one-time secret pair', async () => {
+        const created = {
+            id: 'app-1', name: 'Marketplace', slug: 'marketplace',
+            publishable_key: 'pk_app1_abc', secret_key: 'sk_app1_xyz',
+            warning: 'Save the secret_key now',
+        };
+        const { client } = createMockClient(created, 201);
+        const apps = new apps_1.AppsResource(client);
+        const result = await apps.create({ name: 'Marketplace', slug: 'marketplace' });
+        (0, vitest_1.expect)(result.secret_key).toBe('sk_app1_xyz');
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/apps', vitest_1.expect.objectContaining({ method: 'POST' }));
+    });
+    (0, vitest_1.it)('list appends status filter as query string', async () => {
+        const { client } = createMockClient({ data: [], has_more: false });
+        const apps = new apps_1.AppsResource(client);
+        await apps.list({ status: 'archived', limit: 10 });
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/apps?status=archived&limit=10', vitest_1.expect.objectContaining({ method: 'GET' }));
+    });
+    (0, vitest_1.it)('get fetches app detail with stats', async () => {
+        const { client } = createMockClient({ id: 'app-1', stats: { transaction_count: 5 } });
+        const apps = new apps_1.AppsResource(client);
+        const result = await apps.get('app-1');
+        (0, vitest_1.expect)(result.stats.transaction_count).toBe(5);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/apps/app-1', vitest_1.expect.anything());
+    });
+    (0, vitest_1.it)('update PATCHes partial fields', async () => {
+        const { client } = createMockClient({ id: 'app-1', name: 'Renamed' });
+        const apps = new apps_1.AppsResource(client);
+        const result = await apps.update('app-1', { name: 'Renamed' });
+        (0, vitest_1.expect)(result.name).toBe('Renamed');
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/apps/app-1', vitest_1.expect.objectContaining({ method: 'PATCH' }));
+    });
+    (0, vitest_1.it)('rotateSecret POSTs the rotate endpoint', async () => {
+        const { client } = createMockClient({ app_id: 'app-1', secret_key: 'sk_new', warning: 'save it' });
+        const apps = new apps_1.AppsResource(client);
+        const result = await apps.rotateSecret('app-1');
+        (0, vitest_1.expect)(result.secret_key).toBe('sk_new');
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/apps/app-1/rotate-secret', vitest_1.expect.objectContaining({ method: 'POST' }));
+    });
+    (0, vitest_1.it)('archive DELETEs the app', async () => {
+        const { client } = createMockClient({ id: 'app-1', is_active: false });
+        const apps = new apps_1.AppsResource(client);
+        const result = await apps.archive('app-1');
+        (0, vitest_1.expect)(result.is_active).toBe(false);
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/apps/app-1', vitest_1.expect.objectContaining({ method: 'DELETE' }));
+    });
+    (0, vitest_1.it)('analytics defaults to the 30d period', async () => {
+        const { client } = createMockClient({ app_id: 'app-1', period: '30d' });
+        const apps = new apps_1.AppsResource(client);
+        const result = await apps.analytics('app-1');
+        (0, vitest_1.expect)(result.period).toBe('30d');
+        (0, vitest_1.expect)(mockFetch).toHaveBeenCalledWith('http://localhost:3000/v1/apps/app-1/analytics?period=30d', vitest_1.expect.anything());
+    });
+    (0, vitest_1.it)('propagates API errors', async () => {
+        const { client } = createMockClient({ message: 'Validation failed: slug: Invalid' }, 400);
+        const apps = new apps_1.AppsResource(client);
+        await (0, vitest_1.expect)(apps.create({ name: 'X', slug: 'BAD' })).rejects.toThrow('Validation failed');
+    });
+});

package/dist/http.d.ts

@@ -0,0 +1,22 @@
+type Params = Record<string, any>;
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    params?: Params;
+    /** Sent as the Stripe-compatible Idempotency-Key header for mutations. */
+    idempotencyKey?: string;
+}
+export declare class FTDNApiError extends Error {
+    status: number;
+    code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+export declare class HttpClient {
+    /** Exposed for resources that need raw fetch (CSV export, HTML invoice). */
+    baseUrl: string;
+    apiKey: string;
+    constructor(apiKey: string, baseUrl: string);
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+}
+export {};
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAGA,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAElC,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAUD,qBAAa,YAAa,SAAQ,KAAK;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;gBACF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAM3D;AAED,qBAAa,UAAU;IACrB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;gBAEH,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAKrC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;CAwCzE"}

package/dist/http.js

@@ -0,0 +1,56 @@
+"use strict";
+// ── HTTP Client ──────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = exports.FTDNApiError = void 0;
+class FTDNApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.name = 'FTDNApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.FTDNApiError = FTDNApiError;
+class HttpClient {
+    /** Exposed for resources that need raw fetch (CSV export, HTML invoice). */
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+    }
+    async request(path, options = {}) {
+        const { method = 'GET', body, params, idempotencyKey } = options;
+        const bodyIdempotencyKey = body && typeof body === 'object' && 'idempotency_key' in body
+            ? String(body.idempotency_key || '')
+            : undefined;
+        const effectiveIdempotencyKey = idempotencyKey || bodyIdempotencyKey || undefined;
+        let url = `${this.baseUrl}${path}`;
+        if (params) {
+            const qs = Object.entries(params)
+                .filter(([, v]) => v !== undefined)
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+                .join('&');
+            if (qs)
+                url += `?${qs}`;
+        }
+        const headers = {
+            'Content-Type': 'application/json',
+            'x-api-key': this.apiKey,
+            ...(effectiveIdempotencyKey ? { 'Idempotency-Key': effectiveIdempotencyKey } : {}),
+        };
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            throw new FTDNApiError(data.message || data.error || `HTTP ${response.status}`, response.status, data.code);
+        }
+        return data;
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/http.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=http.test.d.ts.map

package/dist/http.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.test.d.ts","sourceRoot":"","sources":["../src/http.test.ts"],"names":[],"mappings":""}