@directcryptopay/sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,14 +1,15 @@
 # @directcryptopay/sdk
 
-Official TypeScript/JavaScript SDK for DirectCryptoPay. Create payment intents, verify webhooks, and manage crypto payments from Node.js, Edge Functions, or the browser.
+Official SDK for DirectCryptoPay — accept crypto payments directly to your wallet. Non-custodial, multi-chain, developer-first.
 
 ## Features
 
-✅ **TypeScript-first** - Full type safety with exported types
-✅ **Web Crypto API** - Works in Node.js, Edge (Vercel, Cloudflare), and browsers
-✅ **Webhook verification** - HMAC-SHA256 signature validation
-✅ **Zero dependencies** - Lightweight, uses only platform APIs
-✅ **Idempotency support** - Prevent duplicate requests
+- **Non-custodial** — Funds go directly from customer wallet to yours
+- **Multi-chain** — Ethereum, Polygon, BNB Chain, Base, Arbitrum, Optimism (mainnet + testnet)
+- **Shadow DOM isolation** — Payment modal won't interfere with your app's styles or state
+- **WalletConnect support** — MetaMask, Rabby, WalletConnect, and 300+ wallets via Reown AppKit
+- **Two payment modes** — Tool-based (pre-configured) or Integration-based (dynamic amounts)
+- **TypeScript-first** — Full type safety with exported types
 
 ## Installation
 
@@ -22,335 +23,280 @@ yarn add @directcryptopay/sdk
 
 ## Quick Start
 
-### Server-side: Create Payment Intent
+### 1. Initialize the SDK
 
-```typescript
-import { DirectCryptoPay } from '@directcryptopay/sdk';
-
-const dcp = new DirectCryptoPay({
-  baseURL: 'https://test-api.directcryptopay.com',
-  apiKey: process.env.DCP_API_KEY!,
-});
-
-const intent = await dcp.createPaymentIntent({
-  amount: 49.99,
-  currency: 'USD',
-  metadata: {
-    order_id: 'ORD-123',
-    customer_email: 'customer@example.com'
-  },
-  idempotencyKey: crypto.randomUUID(), // Recommended
-});
-
-console.log(intent.id); // pi_abc123...
-console.log(intent.recipient); // 0x1234...
-console.log(intent.amount_wei); // "50000000000000000"
-```
-
-### Server-side: Verify Webhook
+Call `DCP.init()` once when your app loads. You need a [Reown project ID](https://cloud.reown.com) (free) for WalletConnect support.
 
 ```typescript
-import { verifyWebhookSignature } from '@directcryptopay/sdk';
-
-export async function POST(req: Request) {
-  const rawBody = await req.text();
-  const signature = req.headers.get('x-dcp-signature') ?? '';
-
-  const isValid = await verifyWebhookSignature({
-    rawBody,
-    signatureHeader: signature,
-    secret: process.env.DCP_WEBHOOK_SECRET!,
-  });
-
-  if (!isValid) {
-    return new Response('Invalid signature', { status: 400 });
-  }
-
-  const event = JSON.parse(rawBody);
-
-  if (event.event === 'payment.succeeded') {
-    // Handle payment success
-    console.log('Payment confirmed:', event.data.id);
-  }
-
-  return new Response('OK', { status: 200 });
-}
-```
-
-## API Reference
-
-### `DirectCryptoPay`
-
-Main SDK class for interacting with DirectCryptoPay API.
+import { DCP } from '@directcryptopay/sdk';
 
-#### Constructor
-
-```typescript
-const dcp = new DirectCryptoPay({
-  baseURL: string;      // e.g., 'https://api.directcryptopay.com'
-  apiKey: string;       // Your server-side API key
-  fetch?: typeof fetch; // Optional: custom fetch (for testing)
+DCP.init({
+  projectId: 'your-reown-project-id', // Free at cloud.reown.com
 });
 ```
 
-#### Methods
+### 2. Accept a payment
 
-##### `createPaymentIntent(input)`
-
-Create a new payment intent.
+**Option A: Payment Tool** (pre-configured amount, token, and chain)
 
 ```typescript
-const intent = await dcp.createPaymentIntent({
-  amount: 49.99,
-  currency: 'USD',
-  metadata?: { order_id: 'ORD-123' },
-  expiry_seconds?: 900, // Default: 900 (15 min)
-  idempotencyKey?: string, // Recommended
+DCP.pay({
+  toolId: 'your-tool-id', // From Dashboard > Payment Tools > Get Code
+  callbacks: {
+    onSuccess: (data) => {
+      console.log('Payment confirmed:', data);
+    },
+    onError: (error) => {
+      console.error('Payment failed:', error);
+    },
+  },
 });
 ```
 
-**Returns:** `Promise<Intent>`
-
-##### `declareTx(input)`
-
-Declare a blockchain transaction for a payment intent.
+**Option B: Integration** (dynamic amount, token selector)
 
 ```typescript
-await dcp.declareTx({
-  intentId: 'pi_abc123',
-  txHash: '0x1234...',
-  idempotencyKey?: string,
+DCP.Payment({
+  integrationId: 'your-integration-id',
+  amount_usd: '49.99',
+  callbacks: {
+    onSuccess: (data) => {
+      console.log('Paid:', data.txHash);
+    },
+  },
 });
 ```
 
-**Returns:** `Promise<{ accepted: true }>`
-
-##### `getIntentStatus(intentId)`
-
-Get current status of a payment intent.
-
-```typescript
-const intent = await dcp.getIntentStatus('pi_abc123');
-console.log(intent.status); // 'created' | 'pending' | 'paid' | 'failed' | 'expired'
-```
-
-**Returns:** `Promise<Intent>`
+## API Reference
 
-##### `waitForConfirmation(intentId, options?)`
+### `DCP.init(config)`
 
-Poll for payment confirmation with automatic retry.
+Initialize the SDK. Must be called once before `pay()` or `Payment()`.
 
 ```typescript
-const confirmedIntent = await dcp.waitForConfirmation('pi_abc123', {
-  intervalMs: 2000,     // Poll every 2 seconds
-  maxAttempts: 60,      // Max 60 attempts (2 min total)
-  onTick: (attempt, status) => {
-    console.log(`Attempt ${attempt}: ${status}`);
-  },
+DCP.init({
+  projectId: string;            // Required — Reown/WalletConnect project ID
+  apiUrl?: string;              // Default: 'https://api.directcryptopay.com'
+  defaultChainId?: number;      // Default chain for wallet connection
+  gasWarningThreshold?: number; // Gas warning % threshold (default: 15)
+  env?: 'test' | 'prod';       // Environment hint
 });
-
-console.log('Payment confirmed:', confirmedIntent.tx_hash);
 ```
 
-**Returns:** `Promise<Intent>` (with `status: 'paid'`)
-**Throws:** If payment fails, expires, or times out
-
-##### `listPaymentIntents(options?)`
+### `DCP.pay(options)`
 
-List payment intents with pagination.
+Open the payment modal for a pre-configured Payment Tool. The tool defines the amount, accepted tokens, and target chain.
 
 ```typescript
-const { data, hasMore, nextCursor } = await dcp.listPaymentIntents({
-  limit: 20,
-  cursor: 'cursor_abc',
-  status: 'paid',
+DCP.pay({
+  toolId: string;                          // Required — Payment Tool ID
+  amountUsd?: number;                      // Override USD amount (for donations)
+  token?: string;                          // Pre-select token symbol
+  chainId?: number;                        // Pre-select chain
+  metadata?: Record<string, string>;       // Custom metadata
+  callbacks?: PaymentCallbacks;            // Event handlers
 });
 ```
 
-**Returns:** `Promise<{ data: Intent[], hasMore: boolean, nextCursor?: string }>`
+### `DCP.Payment(options)`
 
-### `verifyWebhookSignature(options)`
-
-Verify HMAC-SHA256 webhook signature (timing-safe).
+Open the payment modal for an Integration-based payment. Use this for dynamic amounts (carts, subscriptions, per-user pricing).
 
 ```typescript
-const isValid = await verifyWebhookSignature({
-  rawBody: string,          // Request body as string (exact as received)
-  signatureHeader: string,  // 'X-DCP-Signature' header value
-  secret: string,           // Your webhook secret
-  toleranceSec?: number,    // Default: 300 (5 minutes)
+DCP.Payment({
+  integrationId: string;                   // Required — Integration public ID
+  amount_usd?: string;                     // Amount in USD (e.g., '49.99')
+  amount?: string | number;                // OR amount in token units (not both)
+  currency?: string;                       // Pre-select token (skips selector if set)
+  chainId?: number;                        // Pre-select chain
+  metadata?: Record<string, any>;          // Custom metadata
+  callbacks?: PaymentCallbacks;            // Event handlers
 });
 ```
 
-**Returns:** `Promise<boolean>`
+> **Note:** Provide either `amount_usd` or `amount`, not both.
 
-## Types
+### Callbacks
 
-All types are exported:
+All callbacks are optional.
 
 ```typescript
-import type {
-  Intent,
-  PaymentStatus,
-  CreateIntentInput,
-  DeclareTxInput,
-  SdkConfig,
-  ChainId,
-} from '@directcryptopay/sdk';
-```
-
-### `Intent`
-
-```typescript
-interface Intent {
-  id: string;
-  chain_id: ChainId;
-  recipient: `0x${string}`;
-  amount_wei: string;
-  currency: string;
-  amount: number;
-  expires_at: string;
-  status: PaymentStatus;
-  signature: string;
-  asset_type: 'native' | 'erc20';
-  token_address?: `0x${string}`;
-  tx_hash?: `0x${string}`;
-  confirmed_at?: string;
+interface PaymentCallbacks {
+  onOpen?: () => void;                         // Modal opened
+  onClose?: () => void;                        // Modal closed
+  onStatus?: (status: PaymentStatus) => void;  // Status updates
+  onTxSubmitted?: (txHash: string) => void;    // Transaction sent to chain
+  onSuccess?: (data: any) => void;             // Payment confirmed
+  onCancel?: () => void;                       // User cancelled
+  onError?: (error: Error) => void;            // Error occurred
 }
 ```
 
-### `PaymentStatus`
+### Payment Status
+
+Real-time status updates via `onStatus`:
 
 ```typescript
-type PaymentStatus = 'created' | 'pending' | 'paid' | 'failed' | 'expired' | 'late_confirmed';
+type PaymentStatus =
+  | { type: 'fetching_tool_data' }
+  | { type: 'fetching_token_balances' }
+  | { type: 'awaiting_token_selection' }
+  | { type: 'creating_payment_intent' }
+  | { type: 'estimating_gas' }
+  | { type: 'gas_estimated'; estimate: GasEstimate }
+  | { type: 'awaiting_wallet_connection' }
+  | { type: 'wallet_connected'; address: string }
+  | { type: 'awaiting_signature' }
+  | { type: 'transaction_submitted'; txHash: string }
+  | { type: 'confirming'; txHash: string; confirmations: number }
+  | { type: 'verifying'; txHash: string; paymentId: string }
+  | { type: 'confirmed'; txHash: string; paymentId?: string }
+  | { type: 'failed'; error: Error }
+  | { type: 'rejected' }
+  | { type: 'cancelled' };
 ```
 
-## Usage Examples
+## Framework Examples
 
-### Next.js API Route (App Router)
+### Next.js (App Router)
 
-```typescript
-// app/api/dcp/create-intent/route.ts
-import { DirectCryptoPay } from '@directcryptopay/sdk';
+**1. Create a provider:**
 
-const dcp = new DirectCryptoPay({
-  baseURL: process.env.DCP_API_BASE!,
-  apiKey: process.env.DCP_API_KEY!,
-});
+```tsx
+// components/DCPProvider.tsx
+'use client';
 
-export async function POST(req: Request) {
-  const { amount, currency } = await req.json();
+import { useEffect } from 'react';
+import { DCP } from '@directcryptopay/sdk';
 
-  const intent = await dcp.createPaymentIntent({
-    amount,
-    currency,
-    idempotencyKey: crypto.randomUUID(),
-  });
+export function DCPProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    DCP.init({
+      projectId: 'your-reown-project-id'
+    });
+  }, []);
 
-  return Response.json(intent);
+  return <>{children}</>;
 }
 ```
 
-### Next.js Webhook Handler
-
-```typescript
-// app/api/dcp/webhook/route.ts
-import { verifyWebhookSignature } from '@directcryptopay/sdk';
+**2. Wrap your layout:**
 
-export async function POST(req: Request) {
-  const rawBody = await req.text();
-  const signature = req.headers.get('x-dcp-signature') ?? '';
+```tsx
+// app/layout.tsx
+import { DCPProvider } from '@/components/DCPProvider';
 
-  const isValid = await verifyWebhookSignature({
-    rawBody,
-    signatureHeader: signature,
-    secret: process.env.DCP_WEBHOOK_SECRET!,
-  });
-
-  if (!isValid) {
-    return new Response('Invalid signature', { status: 400 });
-  }
-
-  const event = JSON.parse(rawBody);
-
-  switch (event.event) {
-    case 'payment.succeeded':
-      // Handle success
-      break;
-    case 'payment.failed':
-      // Handle failure
-      break;
-  }
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <DCPProvider>{children}</DCPProvider>
+      </body>
+    </html>
+  );
+}
+```
 
-  return new Response('OK');
+**3. Create a pay button:**
+
+```tsx
+// components/PayButton.tsx
+'use client';
+
+import { useState } from 'react';
+import { DCP } from '@directcryptopay/sdk';
+
+export function PayButton({ toolId, label = 'Pay with Crypto' }: {
+  toolId: string;
+  label?: string;
+}) {
+  const [status, setStatus] = useState<string | null>(null);
+
+  const handlePay = () => {
+    setStatus('pending');
+    DCP.pay({
+      toolId,
+      callbacks: {
+        onSuccess: (data) => {
+          setStatus('confirmed');
+          console.log('Payment confirmed:', data);
+        },
+        onError: (error) => {
+          setStatus('failed');
+          console.error('Payment failed:', error);
+        },
+        onClose: () => setStatus(null),
+      }
+    });
+  };
+
+  return (
+    <button onClick={handlePay} disabled={status === 'pending'}>
+      {status === 'confirmed' ? 'Payment Confirmed!' :
+       status === 'pending' ? 'Processing...' : label}
+    </button>
+  );
 }
 ```
 
-### Cloudflare Workers / Edge
+### Vanilla JavaScript
 
-```typescript
-export default {
-  async fetch(req: Request, env: Env) {
-    const dcp = new DirectCryptoPay({
-      baseURL: 'https://api.directcryptopay.com',
-      apiKey: env.DCP_API_KEY,
-    });
+```html
+<script type="module">
+  import { DCP } from 'https://unpkg.com/@directcryptopay/sdk/dist/index.js';
 
-    const intent = await dcp.createPaymentIntent({
-      amount: 99.99,
-      currency: 'USD',
-    });
+  DCP.init({ projectId: 'your-reown-project-id' });
 
-    return new Response(JSON.stringify(intent), {
-      headers: { 'Content-Type': 'application/json' },
+  document.getElementById('pay-btn').addEventListener('click', () => {
+    DCP.pay({
+      toolId: 'your-tool-id',
+      callbacks: {
+        onSuccess: (data) => alert('Payment confirmed!'),
+        onError: (error) => alert('Payment failed: ' + error.message),
+      }
     });
-  },
-};
+  });
+</script>
 ```
 
-## Security Best Practices
+## Supported Networks
 
-### ✅ DO:
+| Network | Chain ID | Type |
+|---------|----------|------|
+| Ethereum | 1 | Mainnet |
+| Polygon | 137 | Mainnet |
+| BNB Chain | 56 | Mainnet |
+| Base | 8453 | Mainnet |
+| Arbitrum One | 42161 | Mainnet |
+| Optimism | 10 | Mainnet |
+| Sepolia | 11155111 | Testnet |
+| Polygon Amoy | 80002 | Testnet |
+| BNB Testnet | 97 | Testnet |
+| Base Sepolia | 84532 | Testnet |
+| Arbitrum Sepolia | 421614 | Testnet |
+| Optimism Sepolia | 11155420 | Testnet |
 
-1. **Always verify webhook signatures** using `verifyWebhookSignature`
-2. **Use environment variables** for API keys and secrets
-3. **Use HTTPS in production**
-4. **Use idempotency keys** to prevent duplicate payments
-5. **Validate payment amounts** server-side before fulfillment
+## Security
 
-### ❌ DON'T:
+The frontend callbacks (`onSuccess`, `onError`) are for **UX purposes only** — updating your UI when a payment completes. For production apps, always verify payments server-side using [webhooks](https://docs.directcryptopay.com).
 
-1. **Never expose API keys** to the client (browser)
-2. **Never trust client-side payment amounts**
-3. **Never skip signature verification** on webhooks
-4. **Never hardcode secrets** in source code
+DirectCryptoPay is non-custodial: transactions go directly from the customer's wallet to your wallet address. No funds are held by DirectCryptoPay at any point.
 
 ## Testing
 
-The SDK uses Web Crypto API which works in:
-
-- Node.js 16+ (with `globalThis.crypto`)
-- Deno
-- Cloudflare Workers
-- Vercel Edge Functions
-- Modern browsers
-
-### Test Networks
-
-- **Sepolia** (Ethereum) - chainId: 11155111
-- **Polygon Amoy** - chainId: 80002
-- **BSC Testnet** - chainId: 97
-
-### Get Test Tokens
+Both testnet and mainnet are available on every account from day one. Test with:
 
-- Sepolia ETH: https://sepoliafaucet.com
-- Sepolia USDC: https://faucet.circle.com
+- **Sepolia ETH:** [sepoliafaucet.com](https://sepoliafaucet.com)
+- **Sepolia USDC:** [faucet.circle.com](https://faucet.circle.com)
 
-## Support
+## Links
 
-- **Documentation:** https://docs.directcryptopay.com
-- **API Reference:** https://api.directcryptopay.com/docs
-- **Dashboard:** https://app.directcryptopay.com
+- **Website:** [directcryptopay.com](https://directcryptopay.com)
+- **Dashboard:** [directcryptopay.com/dashboard](https://directcryptopay.com/dashboard)
+- **Documentation:** [docs.directcryptopay.com](https://docs.directcryptopay.com)
+- **API Docs:** [api.directcryptopay.com/api/docs](https://api.directcryptopay.com/api/docs)
+- **Discord:** [discord.com/invite/PPdJNkXh](https://discord.com/invite/PPdJNkXh)
+- **GitHub:** [github.com/directcryptopay](https://github.com/directcryptopay)
 
 ## License
 

package/dist/{add-KF4m4jFK.js → add-sji6scSD.js}

@@ -1,4 +1,4 @@
-import { cy as l } from "./index-DiHImG4L.js";
+import { cD as l } from "./index-BJ7cbG3N.js";
 const o = l`<svg
   width="14"
   height="14"

package/dist/{all-wallets-D6NAjQgX.js → all-wallets-B4H-890E.js}

@@ -1,4 +1,4 @@
-import { cy as a } from "./index-DiHImG4L.js";
+import { cD as a } from "./index-BJ7cbG3N.js";
 const o = a`<svg fill="none" viewBox="0 0 24 24">
   <path
     style="fill: var(--wui-color-accent-100);"

package/dist/{app-store-D7TTn-EO.js → app-store-Z433s97G.js}

@@ -1,4 +1,4 @@
-import { cy as a } from "./index-DiHImG4L.js";
+import { cD as a } from "./index-BJ7cbG3N.js";
 const e = a`
 <svg width="36" height="36">
   <path

package/dist/{apple-DjX2E2hE.js → apple-b8Lxj7nb.js}

@@ -1,4 +1,4 @@
-import { cy as l } from "./index-DiHImG4L.js";
+import { cD as l } from "./index-BJ7cbG3N.js";
 const f = l`<svg fill="none" viewBox="0 0 40 40">
   <g clip-path="url(#a)">
     <g clip-path="url(#b)">

package/dist/{arrow-bottom-C0YrNJYB.js → arrow-bottom-M9oWWo_9.js}

@@ -1,4 +1,4 @@
-import { cy as o } from "./index-DiHImG4L.js";
+import { cD as o } from "./index-BJ7cbG3N.js";
 const e = o`<svg fill="none" viewBox="0 0 14 15">
   <path
     fill="currentColor"

package/dist/{arrow-bottom-circle-Dlxvx_XG.js → arrow-bottom-circle-N9c4CXY1.js}

@@ -1,4 +1,4 @@
-import { cy as C } from "./index-DiHImG4L.js";
+import { cD as C } from "./index-BJ7cbG3N.js";
 const e = C`<svg
   fill="none"
   viewBox="0 0 21 20"

package/dist/{arrow-left-x8_-lUyK.js → arrow-left-Dw8AKfwf.js}

@@ -1,4 +1,4 @@
-import { cy as e } from "./index-DiHImG4L.js";
+import { cD as e } from "./index-BJ7cbG3N.js";
 const o = e`<svg fill="none" viewBox="0 0 14 15">
   <path
     fill="currentColor"

package/dist/{arrow-right-BTZybj80.js → arrow-right-DwLQZSC_.js}

@@ -1,4 +1,4 @@
-import { cy as l } from "./index-DiHImG4L.js";
+import { cD as l } from "./index-BJ7cbG3N.js";
 const e = l`<svg fill="none" viewBox="0 0 14 15">
   <path
     fill="currentColor"

package/dist/{arrow-top-LzH7iLCp.js → arrow-top-zhUjkBe1.js}

@@ -1,4 +1,4 @@
-import { cy as o } from "./index-DiHImG4L.js";
+import { cD as o } from "./index-BJ7cbG3N.js";
 const e = o`<svg fill="none" viewBox="0 0 14 15">
   <path
     fill="currentColor"

package/dist/{bank-23jp-IV_.js → bank-CbQdnILK.js}

@@ -1,4 +1,4 @@
-import { cy as e } from "./index-DiHImG4L.js";
+import { cD as e } from "./index-BJ7cbG3N.js";
 const o = e`<svg
   xmlns="http://www.w3.org/2000/svg"
   width="12"

package/dist/{browser-EjoorDid.js → browser-xAqNwt7z.js}

@@ -1,4 +1,4 @@
-import { cy as l } from "./index-DiHImG4L.js";
+import { cD as l } from "./index-BJ7cbG3N.js";
 const a = l`<svg fill="none" viewBox="0 0 20 20">
   <path
     fill="currentColor"

package/dist/{card-DGgWwtwC.js → card-Dr1QBmWp.js}

@@ -1,4 +1,4 @@
-import { cy as C } from "./index-DiHImG4L.js";
+import { cD as C } from "./index-BJ7cbG3N.js";
 const l = C`<svg
   xmlns="http://www.w3.org/2000/svg"
   width="12"