@directcryptopay/sdk 0.2.3 → 0.3.0

package/README.md

@@ -6,8 +6,8 @@ Official SDK for DirectCryptoPay — accept crypto payments directly to your wal
 
 - **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
+- **Lightweight** — ~5 KB bundle, opens checkout in an iframe overlay (like Stripe Checkout)
+- **WalletConnect support** — MetaMask, Rabby, WalletConnect, and 300+ wallets
 - **Two payment modes** — Tool-based (pre-configured) or Integration-based (dynamic amounts)
 - **TypeScript-first** — Full type safety with exported types
 
@@ -25,13 +25,14 @@ yarn add @directcryptopay/sdk
 
 ### 1. Initialize the SDK
 
-Call `DCP.init()` once when your app loads. You need a [Reown project ID](https://cloud.reown.com) (free) for WalletConnect support.
+Call `DCP.init()` once when your app loads.
 
 ```typescript
 import { DCP } from '@directcryptopay/sdk';
 
 DCP.init({
-  projectId: 'your-reown-project-id', // Free at cloud.reown.com
+  // Optional: defaults to 'https://directcryptopay.com'
+  // checkoutUrl: 'https://preview.directcryptopay.com',
 });
 ```
 
@@ -44,7 +45,7 @@ DCP.pay({
   toolId: 'your-tool-id', // From Dashboard > Payment Tools > Get Code
   callbacks: {
     onSuccess: (data) => {
-      console.log('Payment confirmed:', data);
+      console.log('Payment confirmed:', data.txHash);
     },
     onError: (error) => {
       console.error('Payment failed:', error);
@@ -75,87 +76,61 @@ Initialize the SDK. Must be called once before `pay()` or `Payment()`.
 
 ```typescript
 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
+  checkoutUrl?: string;   // Default: 'https://directcryptopay.com'
+  projectId?: string;     // Deprecated — no longer needed
+  env?: 'test' | 'prod';
 });
 ```
 
 ### `DCP.pay(options)`
 
-Open the payment modal for a pre-configured Payment Tool. The tool defines the amount, accepted tokens, and target chain.
+Open the checkout iframe for a pre-configured Payment Tool.
 
 ```typescript
 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
+  toolId: string;               // Required — Payment Tool ID
+  amountUsd?: number;           // Override USD amount (for donations)
+  callbacks?: PaymentCallbacks;
 });
 ```
 
 ### `DCP.Payment(options)`
 
-Open the payment modal for an Integration-based payment. Use this for dynamic amounts (carts, subscriptions, per-user pricing).
+Open the checkout iframe for an Integration-based payment.
 
 ```typescript
 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)
+  currency?: string;                       // Pre-select token (skips selector)
   chainId?: number;                        // Pre-select chain
   metadata?: Record<string, any>;          // Custom metadata
-  callbacks?: PaymentCallbacks;            // Event handlers
+  callbacks?: PaymentCallbacks;
 });
 ```
 
 > **Note:** Provide either `amount_usd` or `amount`, not both.
 
+### `DCP.close()`
+
+Programmatically close the checkout iframe.
+
 ### Callbacks
 
 All callbacks are optional.
 
 ```typescript
 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
+  onOpen?: () => void;                                          // Iframe opened
+  onClose?: () => void;                                         // Iframe closed
+  onTxSubmitted?: (txHash: string) => void;                     // Transaction sent
+  onSuccess?: (data: { txHash: string; intentId?: string }) => void;  // Payment confirmed
+  onCancel?: () => void;                                        // User cancelled
+  onError?: (error: Error) => void;                             // Error occurred
 }
 ```
 
-### Payment Status
-
-Real-time status updates via `onStatus`:
-
-```typescript
-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' };
-```
-
 ## Framework Examples
 
 ### Next.js (App Router)
@@ -167,12 +142,11 @@ type PaymentStatus =
 'use client';
 
 import { useEffect } from 'react';
-import { DCP } from '@directcryptopay/sdk';
 
 export function DCPProvider({ children }: { children: React.ReactNode }) {
   useEffect(() => {
-    DCP.init({
-      projectId: 'your-reown-project-id'
+    import('@directcryptopay/sdk').then(({ DCP }) => {
+      DCP.init({});
     });
   }, []);
 
@@ -204,7 +178,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 'use client';
 
 import { useState } from 'react';
-import { DCP } from '@directcryptopay/sdk';
 
 export function PayButton({ toolId, label = 'Pay with Crypto' }: {
   toolId: string;
@@ -212,19 +185,14 @@ export function PayButton({ toolId, label = 'Pay with Crypto' }: {
 }) {
   const [status, setStatus] = useState<string | null>(null);
 
-  const handlePay = () => {
+  const handlePay = async () => {
     setStatus('pending');
+    const { DCP } = await import('@directcryptopay/sdk');
     DCP.pay({
       toolId,
       callbacks: {
-        onSuccess: (data) => {
-          setStatus('confirmed');
-          console.log('Payment confirmed:', data);
-        },
-        onError: (error) => {
-          setStatus('failed');
-          console.error('Payment failed:', error);
-        },
+        onSuccess: () => setStatus('confirmed'),
+        onError: () => setStatus('failed'),
         onClose: () => setStatus(null),
       }
     });
@@ -245,7 +213,7 @@ export function PayButton({ toolId, label = 'Pay with Crypto' }: {
 <script type="module">
   import { DCP } from 'https://unpkg.com/@directcryptopay/sdk/dist/index.js';
 
-  DCP.init({ projectId: 'your-reown-project-id' });
+  DCP.init({});
 
   document.getElementById('pay-btn').addEventListener('click', () => {
     DCP.pay({
@@ -259,35 +227,32 @@ export function PayButton({ toolId, label = 'Pay with Crypto' }: {
 </script>
 ```
 
-## Supported Networks
-
-| 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 |
+## How It Works
+
+When `DCP.pay()` or `DCP.Payment()` is called, the SDK opens an iframe overlay pointing to the DirectCryptoPay checkout page. The checkout page handles:
+
+1. Wallet connection (MetaMask, Rabby, WalletConnect, etc.)
+2. Smart token detection and balance display
+3. Network switching
+4. Transaction signing and submission
+5. On-chain verification
+
+The SDK communicates with the iframe via `postMessage` and maps events to your callbacks. This architecture keeps the SDK lightweight (~5 KB) while providing the full checkout experience.
 
 ## Security
 
-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).
+The frontend callbacks (`onSuccess`, `onError`) are for **UX purposes only**. For production apps, always verify payments server-side using [webhooks](https://docs.directcryptopay.com).
 
 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
+## Migrating from v0.2.x
 
-Both testnet and mainnet are available on every account from day one. Test with:
+v0.3.0 is a major refactor. The public API is the same, but:
 
-- **Sepolia ETH:** [sepoliafaucet.com](https://sepoliafaucet.com)
-- **Sepolia USDC:** [faucet.circle.com](https://faucet.circle.com)
+- `DCP.init({ projectId })` — `projectId` is no longer required (can be omitted)
+- `DCP.init({ checkoutUrl })` — new option to customize checkout URL
+- `onStatus` callback removed — use `onTxSubmitted` and `onSuccess` instead
+- Bundle size reduced from ~3 MB to ~5 KB
 
 ## Links
 
@@ -295,7 +260,6 @@ Both testnet and mainnet are available on every account from day one. Test with:
 - **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/core/config.d.ts

@@ -1,59 +1,22 @@
-export interface NetworkConfig {
-    chainId: number;
-    name: string;
-    currency: string;
-    isTestnet: boolean;
-    rpcUrl: string;
-    explorerUrl: string;
-}
 export interface DCPInitConfig {
+    /** Checkout page base URL. Default: 'https://directcryptopay.com' */
+    checkoutUrl?: string;
+    /** @deprecated No longer needed — wallet connection happens inside iframe */
+    projectId?: string;
+    /** @deprecated Use checkoutUrl instead */
     apiUrl?: string;
+    /** @deprecated Use checkoutUrl instead */
     widgetUrl?: string;
-    projectId: string;
     env?: 'test' | 'prod';
-    defaultChainId?: number;
-    gasWarningThreshold?: number;
 }
-export interface DCPConfig extends DCPInitConfig {
-    apiUrl: string;
-    widgetUrl: string;
-    gasWarningThreshold: number;
+export interface DCPConfig {
+    checkoutUrl: string;
 }
 declare class Config {
     private config;
-    init(config: DCPInitConfig): void;
+    init(userConfig: DCPInitConfig): void;
     get(): DCPConfig;
     isInitialized(): boolean;
 }
 export declare const config: Config;
-export declare const NETWORKS: Record<number, NetworkConfig>;
-export declare function getNetwork(chainId: number): NetworkConfig;
-export declare const ERC20_ABI: readonly [{
-    readonly constant: false;
-    readonly inputs: readonly [{
-        readonly name: "_to";
-        readonly type: "address";
-    }, {
-        readonly name: "_value";
-        readonly type: "uint256";
-    }];
-    readonly name: "transfer";
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "bool";
-    }];
-    readonly type: "function";
-}, {
-    readonly constant: true;
-    readonly inputs: readonly [{
-        readonly name: "_owner";
-        readonly type: "address";
-    }];
-    readonly name: "balanceOf";
-    readonly outputs: readonly [{
-        readonly name: "balance";
-        readonly type: "uint256";
-    }];
-    readonly type: "function";
-}];
 export {};

package/dist/core/iframe.d.ts

@@ -0,0 +1,16 @@
+export interface IframeCallbacks {
+    onReady?: () => void;
+    onTxSubmitted?: (txHash: string) => void;
+    onSuccess?: (data: {
+        txHash: string;
+        intentId?: string;
+    }) => void;
+    onError?: (error: string) => void;
+    onClose?: () => void;
+    onCancel?: () => void;
+}
+/**
+ * Opens the DirectCryptoPay checkout page in an iframe overlay.
+ * Returns a cleanup function to programmatically close the overlay.
+ */
+export declare function openCheckoutIframe(url: string, callbacks?: IframeCallbacks): () => void;