@zendfi/sdk 0.1.1 → 0.2.0

package/README.md

@@ -7,20 +7,17 @@
 
 ## Features
 
-- **Zero Configuration** - Works out of the box, auto-detects environment
-- **Type-Safe** - Full TypeScript support with complete type definitions
-- **Auto-Retry** - Built-in retry logic with exponential backoff
-- **Idempotency** - Automatic idempotency key generation
-- **Environment Detection** - Automatically switches between test/production
-- **Smart Defaults** - Sensible defaults for all options
+- **Zero Configuration** — Auto-detects environment and works with sensible defaults
+- **Type-Safe** — Full TypeScript types for payments, payment links, subscriptions, escrows, invoices and webhook payloads
+- **Auto-Retry** — Built-in retry logic with exponential backoff for network/server errors
+- **Idempotency** — Automatic idempotency key generation for safe retries
+- **Webhook Helpers** — Auto-verified handlers with optional deduplication and framework adapters
 
 ## Installation
 
 ```bash
 npm install @zendfi/sdk
 # or
-yarn add @zendfi/sdk
-# or
 pnpm add @zendfi/sdk
 ```
 
@@ -38,6 +35,7 @@ ZENDFI_API_KEY=zfi_test_your_api_key_here
 ```typescript
 import { zendfi } from '@zendfi/sdk';
 
+// Singleton auto-configured from environment
 const payment = await zendfi.createPayment({
   amount: 50,
   description: 'Premium subscription',
@@ -46,6 +44,22 @@ const payment = await zendfi.createPayment({
 console.log(payment.checkout_url); // Send this to your customer
 ```
 
+### 3. Or use an explicit client (recommended for server code)
+
+```typescript
+import { ZendFiClient } from '@zendfi/sdk';
+
+const client = new ZendFiClient({ 
+  apiKey: process.env.ZENDFI_API_KEY 
+});
+
+const payment = await client.createPayment({
+  amount: 99.99,
+  currency: 'USD',
+  description: 'Annual subscription',
+});
+```
+
 That's it! The SDK handles everything else automatically. 🎉
 
 ## Usage
@@ -72,317 +86,204 @@ const payment = await zendfi.createPayment({
 window.location.href = payment.checkout_url;
 ```
 
-#### Get Payment Status
+### Payment Links
 
 ```typescript
-const payment = await zendfi.getPayment('payment_id');
-
-console.log(payment.status); // 'pending' | 'confirmed' | 'failed' | 'expired'
-```
-
-#### List Payments
+const client = new ZendFiClient({ 
+  apiKey: process.env.ZENDFI_API_KEY 
+});
 
-```typescript
-const payments = await zendfi.listPayments({
-  page: 1,
-  limit: 10,
-  status: 'confirmed',
-  from_date: '2025-01-01',
-  to_date: '2025-12-31',
+// Create a payment link
+const link = await client.createPaymentLink({
+  amount: 20,
+  currency: 'USD',
+  description: 'Product purchase',
 });
 
-console.log(payments.data); // Array of payments
-console.log(payments.pagination); // Pagination info
+console.log(link.hosted_page_url);
+
+// List all payment links
+const links = await client.listPaymentLinks();
+console.log(`Total links: ${links.length}`);
 ```
 
-### Subscriptions
+> **Note:** If you get a 405 error when calling `listPaymentLinks()` in tests, confirm that `ZENDFI_API_URL` / `baseURL` and your API key point to a server that exposes `GET /api/v1/payment-links`.
 
-#### Create a Plan
+## Webhooks
 
-```typescript
-const plan = await zendfi.createSubscriptionPlan({
-  name: 'Pro Plan',
-  description: 'Access to all premium features',
-  amount: 29.99,
-  interval: 'monthly',
-  trial_days: 14,
-});
-```
+The SDK includes robust webhook processing with signature verification, optional deduplication, and typed handler dispatch.
 
-#### Create a Subscription
+### Next.js App Router (Recommended)
 
 ```typescript
-const subscription = await zendfi.createSubscription({
-  plan_id: plan.id,
-  customer_email: 'customer@example.com',
-  metadata: {
-    userId: 'user_123',
+// app/api/webhooks/zendfi/route.ts
+import { createNextWebhookHandler } from '@zendfi/sdk/next';
+
+export const POST = createNextWebhookHandler({
+  secret: process.env.ZENDFI_WEBHOOK_SECRET!,
+  handlers: {
+    'payment.confirmed': async (payment) => {
+      // Payment is already verified and typed
+      await db.orders.update({
+        where: { id: payment.metadata.orderId },
+        data: { status: 'paid' },
+      });
+    },
   },
 });
 ```
 
-#### Cancel a Subscription
+### Next.js Pages Router (Legacy)
 
 ```typescript
-const canceled = await zendfi.cancelSubscription(subscription.id);
-```
+// pages/api/webhooks/zendfi.ts
+import { createPagesWebhookHandler } from '@zendfi/sdk/next';
+
+export default createPagesWebhookHandler({
+  secret: process.env.ZENDFI_WEBHOOK_SECRET!,
+  handlers: {
+    'payment.confirmed': async (payment) => {
+      await fulfillOrder(payment.metadata.orderId);
+    },
+  },
+});
 
-### Webhooks
+// Important: Disable body parser for signature verification
+export const config = {
+  api: { bodyParser: false },
+};
+```
 
-#### Verify Webhook Signature
+### Express
 
 ```typescript
-import { zendfi } from '@zendfi/sdk';
+import express from 'express';
+import { createExpressWebhookHandler } from '@zendfi/sdk/express';
 
-// In your webhook handler (e.g., /api/webhooks/zendfi)
-export async function POST(request: Request) {
-  const payload = await request.text();
-  const signature = request.headers.get('x-zendfi-signature');
+const app = express();
 
-  const isValid = zendfi.verifyWebhook({
-    payload,
-    signature,
+app.post(
+  '/api/webhooks/zendfi',
+  express.raw({ type: 'application/json' }), // Preserve raw body
+  createExpressWebhookHandler({
     secret: process.env.ZENDFI_WEBHOOK_SECRET!,
-  });
-
-  if (!isValid) {
-    return new Response('Invalid signature', { status: 401 });
-  }
-
-  const event = JSON.parse(payload);
-
-  switch (event.event) {
-    case 'payment.confirmed':
-      // Handle payment confirmation
-      break;
-    case 'subscription.activated':
-      // Handle subscription activation
-      break;
-  }
-
-  return new Response('OK', { status: 200 });
-}
+    handlers: {
+      'payment.confirmed': async (payment) => {
+        // Handle confirmed payment
+      },
+    },
+  })
+);
 ```
 
-## Configuration
-
-### Environment Variables
-
-The SDK automatically detects and uses these environment variables:
-
-```bash
-# API Key (required)
-ZENDFI_API_KEY=zfi_test_...
-
-# Or for Next.js
-NEXT_PUBLIC_ZENDFI_API_KEY=zfi_test_...
+### Webhook Deduplication
 
-# Or for Create React App
-REACT_APP_ZENDFI_API_KEY=zfi_test_...
-
-# Environment (optional, auto-detected)
-ZENDFI_ENVIRONMENT=development # or staging, production
-
-# Custom API URL (optional)
-ZENDFI_API_URL=https://api.zendfi.tech
-```
-
-### Manual Configuration
+By default, the handler uses an in-memory Set for deduplication (suitable for development). For production, supply `isProcessed` and `onProcessed` hooks (or the aliases `checkDuplicate` / `markProcessed`) backed by Redis or your database:
 
 ```typescript
-import { ZendFiClient } from '@zendfi/sdk';
-
-const client = new ZendFiClient({
-  apiKey: 'zfi_test_...',
-  environment: 'development',
-  timeout: 30000, // 30 seconds
-  retries: 3,
-  idempotencyEnabled: true,
+export const POST = createNextWebhookHandler({
+  secret: process.env.ZENDFI_WEBHOOK_SECRET!,
+  isProcessed: async (eventId) => {
+    return await redis.exists(`webhook:${eventId}`);
+  },
+  onProcessed: async (eventId) => {
+    await redis.set(`webhook:${eventId}`, '1', 'EX', 86400);
+  },
+  handlers: {
+    'payment.confirmed': async (payment) => {
+      // Handle payment
+    },
+  },
 });
 ```
 
-## Advanced Features
-
-### Auto Environment Detection
-
-The SDK automatically detects your environment:
-
-| Environment | Detected When                          |
-| ----------- | -------------------------------------- |
-| Development | `localhost`, `127.0.0.1`, `NODE_ENV=development` |
-| Staging     | `*.staging.*`, `*.vercel.app`, `NODE_ENV=staging` |
-| Production  | `NODE_ENV=production`, production domains |
+When deduplication is enabled, duplicate requests are rejected with HTTP 409.
 
-### Automatic Retries
+### Manual Webhook Verification
 
-The SDK retries failed requests automatically:
-
-- **Server errors (5xx)**: Retries up to 3 times with exponential backoff
-- **Network errors**: Retries up to 3 times
-- **Client errors (4xx)**: No retry (fix your request)
+If you prefer manual verification:
 
 ```typescript
-// This will retry automatically on network errors
-const payment = await zendfi.createPayment({ amount: 50 });
-```
-
-### Idempotency Keys
-
-Prevent duplicate payments with automatic idempotency:
+import { verifyNextWebhook } from '@zendfi/sdk/webhooks';
 
-```typescript
-// SDK automatically adds: Idempotency-Key: zfi_idem_1234567890_abc123
-
-const payment = await zendfi.createPayment({
-  amount: 50,
-});
+export async function POST(request: Request) {
+  const payload = await verifyNextWebhook(request);
+  if (!payload) {
+    return new Response('Invalid signature', { status: 401 });
+  }
 
-// Safe to retry - won't create duplicate payments
+  // Handle verified payload
+  return new Response('OK');
+}
 ```
 
-## 🎯 TypeScript Support
-
-Full type definitions included:
+**Available helpers:**
+- `verifyNextWebhook(request, secret?)` — Next.js App Router
+- `verifyExpressWebhook(req, secret?)` — Express
+- `verifyWebhookSignature(payload, signature, secret)` — Low-level verifier
 
-```typescript
-import type {
-  Payment,
-  PaymentStatus,
-  Subscription,
-  SubscriptionPlan,
-  WebhookEvent,
-} from '@zendfi/sdk';
+## Configuration & Environment Variables
 
-const payment: Payment = await zendfi.createPayment({
-  amount: 50,
-});
-
-// IntelliSense for all fields
-console.log(payment.id);
-console.log(payment.status);
-console.log(payment.checkout_url);
-```
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ZENDFI_API_KEY` | Yes* | Your ZendFi API key (*unless passed to `ZendFiClient`) |
+| `ZENDFI_WEBHOOK_SECRET` | No | Used by webhook adapters for auto-verification |
+| `ZENDFI_API_URL` | No | Override API base URL (useful for local testing) |
+| `ZENDFI_ENVIRONMENT` | No | Optional environment override |
 
 ## Error Handling
 
+The SDK throws typed errors that you can import and check with `instanceof`:
+
 ```typescript
-import { AuthenticationError, ValidationError, NetworkError } from '@zendfi/sdk';
+import { 
+  AuthenticationError, 
+  ValidationError, 
+  NetworkError 
+} from '@zendfi/sdk';
 
 try {
-  const payment = await zendfi.createPayment({
-    amount: 50,
-  });
+  await zendfi.createPayment({ amount: 50 });
 } catch (error) {
   if (error instanceof AuthenticationError) {
-    console.error('Invalid API key');
+    // Handle authentication error
   } else if (error instanceof ValidationError) {
-    console.error('Invalid request:', error.details);
-  } else if (error instanceof NetworkError) {
-    console.error('Network error, will retry automatically');
+    // Handle validation error
   }
 }
 ```
 
-## Framework Examples
-
-### Next.js App Router
-
-```typescript
-// app/api/checkout/route.ts
-import { zendfi } from '@zendfi/sdk';
-import { NextResponse } from 'next/server';
-
-export async function POST(request: Request) {
-  const { amount } = await request.json();
-
-  const payment = await zendfi.createPayment({
-    amount,
-    redirect_url: `${process.env.NEXT_PUBLIC_URL}/success`,
-  });
-
-  return NextResponse.json({ url: payment.checkout_url });
-}
-```
-
-### Express.js
-
-```typescript
-import express from 'express';
-import { zendfi } from '@zendfi/sdk';
-
-const app = express();
-
-app.post('/api/checkout', async (req, res) => {
-  const { amount } = req.body;
-
-  const payment = await zendfi.createPayment({
-    amount,
-    redirect_url: 'https://yourapp.com/success',
-  });
-
-  res.json({ url: payment.checkout_url });
-});
-```
-
-### React
-
-```typescript
-import { useState } from 'react';
-import { zendfi } from '@zendfi/sdk';
-
-function CheckoutButton() {
-  const [loading, setLoading] = useState(false);
-
-  const handleCheckout = async () => {
-    setLoading(true);
-
-    const payment = await zendfi.createPayment({
-      amount: 50,
-    });
-
-    window.location.href = payment.checkout_url;
-  };
-
-  return (
-    <button onClick={handleCheckout} disabled={loading}>
-      {loading ? 'Creating checkout...' : 'Pay with Crypto'}
-    </button>
-  );
-}
-```
-
-## API Reference
+## Troubleshooting
 
-### Methods
+**Webhook verification failures:**
+- Ensure you're using `express.raw({ type: 'application/json' })` for Express
+- For Next.js Pages Router, set `export const config = { api: { bodyParser: false } }`
+- Middleware consuming the raw body will break signature verification
 
-| Method                      | Description                |
-| --------------------------- | -------------------------- |
-| `createPayment()`           | Create a new payment       |
-| `getPayment(id)`            | Get payment by ID          |
-| `listPayments(options)`     | List all payments          |
-| `createSubscriptionPlan()`  | Create subscription plan   |
-| `getSubscriptionPlan(id)`   | Get plan by ID             |
-| `createSubscription()`      | Create a subscription      |
-| `getSubscription(id)`       | Get subscription by ID     |
-| `cancelSubscription(id)`    | Cancel a subscription      |
-| `verifyWebhook()`           | Verify webhook signature   |
+**405 errors on `listPaymentLinks()`:**
+- Verify your `ZENDFI_API_URL` is correct
+- Confirm your API server exposes `GET /api/v1/payment-links`
 
-See [full API documentation](https://docs.zendfi.tech/sdk) for detailed reference.
+**tsup warnings about types condition:**
+- This is a packaging order issue that doesn't affect runtime behavior
 
-## Debugging
+## Contributing
 
-Enable debug logs:
+Run the SDK build and tests locally before opening a PR:
 
 ```bash
-DEBUG=zendfi:* node your-app.js
+cd packages/sdk
+pnpm install
+pnpm run build
+pnpm test
 ```
 
 ## Support
 
-- [Documentation](https://docs.zendfi.tech)
-- [API Reference](https://docs.zendfi.tech/api)
-- [GitHub Issues](https://github.com/zendfi/zendfi-toolkit/issues)
-- Email: dev@zendfi.tech
+- **Documentation:** https://docs.zendfi.tech
+- **API Reference:** https://docs.zendfi.tech/api
+- **GitHub Issues:** https://github.com/zendfi/zendfi-toolkit/issues
+- **Email:** dev@zendfi.tech
 
 ## License
 

package/dist/chunk-YFOBPGQE.mjs

@@ -0,0 +1,152 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/webhook-handler.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var processedWebhooks = /* @__PURE__ */ new Set();
+var defaultIsProcessed = async (webhookId) => {
+  return processedWebhooks.has(webhookId);
+};
+var defaultOnProcessed = async (webhookId) => {
+  processedWebhooks.add(webhookId);
+  if (processedWebhooks.size > 1e4) {
+    const iterator = processedWebhooks.values();
+    for (let i = 0; i < 1e3; i++) {
+      const { value } = iterator.next();
+      if (value) processedWebhooks.delete(value);
+    }
+  }
+};
+function generateWebhookId(payload) {
+  return `${payload.merchant_id}:${payload.event}:${payload.timestamp}`;
+}
+async function processPayload(payload, handlers, config) {
+  try {
+    const webhookId = generateWebhookId(payload);
+    const isProcessed = config.isProcessed || config.checkDuplicate || defaultIsProcessed;
+    const onProcessed = config.onProcessed || config.markProcessed || defaultOnProcessed;
+    const dedupEnabled = !!(config.enableDeduplication || config.isProcessed || config.checkDuplicate);
+    if (dedupEnabled && await isProcessed(webhookId)) {
+      return {
+        success: false,
+        processed: false,
+        event: payload.event,
+        error: "Duplicate webhook",
+        statusCode: 409
+      };
+    }
+    const handler = handlers[payload.event];
+    if (!handler) {
+      return {
+        success: true,
+        processed: false,
+        event: payload.event,
+        statusCode: 200
+      };
+    }
+    await handler(payload.data, payload);
+    await onProcessed(webhookId);
+    return {
+      success: true,
+      processed: true,
+      event: payload.event
+    };
+  } catch (error) {
+    const err = error;
+    if (config?.onError) {
+      await config.onError(err, error?.event);
+    }
+    return {
+      success: false,
+      processed: false,
+      error: err.message,
+      event: error?.event,
+      statusCode: 500
+    };
+  }
+}
+async function processWebhook(a, b, c) {
+  if (a && typeof a === "object" && a.event && b && c) {
+    return processPayload(a, b, c);
+  }
+  const opts = a;
+  if (!opts || !opts.signature && !opts.body && !opts.handlers) {
+    return {
+      success: false,
+      processed: false,
+      error: "Invalid arguments to processWebhook",
+      statusCode: 400
+    };
+  }
+  const signature = opts.signature;
+  const body = opts.body;
+  const handlers = opts.handlers || {};
+  const cfg = opts.config || {};
+  const secret = cfg.webhookSecret || cfg.secret;
+  if (!secret) {
+    return {
+      success: false,
+      processed: false,
+      error: "Webhook secret not provided",
+      statusCode: 400
+    };
+  }
+  if (!signature || !body) {
+    return {
+      success: false,
+      processed: false,
+      error: "Missing signature or body",
+      statusCode: 400
+    };
+  }
+  try {
+    const sig = typeof signature === "string" && signature.startsWith("sha256=") ? signature.slice("sha256=".length) : String(signature);
+    const hmac = createHmac("sha256", secret).update(body, "utf8").digest("hex");
+    let ok = false;
+    try {
+      const sigBuf = Buffer.from(sig, "hex");
+      const hmacBuf = Buffer.from(hmac, "hex");
+      if (sigBuf.length === hmacBuf.length) {
+        ok = timingSafeEqual(sigBuf, hmacBuf);
+      }
+    } catch (e) {
+      ok = timingSafeEqual(Buffer.from(String(sig), "utf8"), Buffer.from(hmac, "utf8"));
+    }
+    if (!ok) {
+      return {
+        success: false,
+        processed: false,
+        error: "Invalid signature",
+        statusCode: 401
+      };
+    }
+    const payload = JSON.parse(body);
+    const fullConfig = {
+      secret,
+      isProcessed: cfg.isProcessed,
+      onProcessed: cfg.onProcessed,
+      onError: cfg.onError,
+      // Forward compatibility for alternate names and flags
+      enableDeduplication: cfg.enableDeduplication,
+      checkDuplicate: cfg.checkDuplicate,
+      markProcessed: cfg.markProcessed
+    };
+    return await processPayload(payload, handlers, fullConfig);
+  } catch (err) {
+    return {
+      success: false,
+      processed: false,
+      error: err.message,
+      statusCode: 500
+    };
+  }
+}
+
+export {
+  __require,
+  processWebhook
+};