@settlr/sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,22 +1,18 @@
 # @settlr/sdk
 
-> Solana USDC payments in 7 lines of code
+> Solana USDC payments for games - email checkout, no wallet required
 
 ## Installation
 
 ```bash
 npm install @settlr/sdk
-# or
-yarn add @settlr/sdk
-# or
-pnpm add @settlr/sdk
 ```
 
 ## Quick Start
 
 ### 1. Get Your API Key
 
-Sign up at [settlr.dev/dashboard](https://settlr.dev/dashboard) and create an API key.
+Sign up at [settlr.app/dashboard](https://settlr.app/dashboard) and create an API key.
 
 ### 2. Create a Payment Link
 
@@ -87,97 +83,65 @@ import { CheckoutWidget } from "@settlr/sdk";
 />;
 ```
 
-### Direct Payment (with wallet adapter)
+### How It Works
 
-```typescript
-import { Settlr } from "@settlr/sdk";
-import { useWallet } from "@solana/wallet-adapter-react";
+Settlr checkout handles authentication via Privy:
 
-const settlr = new Settlr({
-  apiKey: "sk_live_xxxxxxxxxxxx",
-  merchant: {
-    name: "My Store",
-    walletAddress: "YOUR_WALLET",
-  },
-});
+- **Email login** → Creates embedded Solana wallet automatically
+- **Wallet login** → Connects Phantom, Solflare, or Backpack
 
-// In your component
-const wallet = useWallet();
-
-const result = await settlr.pay({
-  wallet: {
-    publicKey: wallet.publicKey!,
-    signTransaction: wallet.signTransaction!,
-  },
-  amount: 29.99,
-  memo: "Order #1234",
-});
-
-if (result.success) {
-  console.log("Payment successful!", result.signature);
-}
-```
+No wallet-adapter setup needed. Just redirect to checkout.
 
 ### React Hook
 
 ```tsx
 import { SettlrProvider, useSettlr } from "@settlr/sdk";
 
-// Wrap your app
 function App() {
   return (
-    <WalletProvider wallets={wallets}>
-      <ConnectionProvider endpoint={endpoint}>
-        <SettlrProvider
-          config={{
-            apiKey: "sk_live_xxxxxxxxxxxx",
-            merchant: {
-              name: "My Store",
-              walletAddress: "YOUR_WALLET",
-            },
-          }}
-        >
-          <YourApp />
-        </SettlrProvider>
-      </ConnectionProvider>
-    </WalletProvider>
+    <SettlrProvider
+      config={{
+        apiKey: "sk_live_xxxxxxxxxxxx",
+        merchant: {
+          name: "My Game",
+          walletAddress: "YOUR_WALLET",
+        },
+      }}
+    >
+      <YourApp />
+    </SettlrProvider>
   );
 }
 
 // In your component
 function CheckoutButton() {
-  const { pay, connected } = useSettlr();
+  const { getCheckoutUrl } = useSettlr();
 
-  return (
-    <button onClick={() => pay({ amount: 29.99 })} disabled={!connected}>
-      Pay $29.99
-    </button>
-  );
+  const handlePay = () => {
+    const url = getCheckoutUrl({ amount: 29.99, memo: "Premium Pack" });
+    window.location.href = url;
+  };
+
+  return <button onClick={handlePay}>Pay $29.99</button>;
 }
 ```
 
-### Payment Link Generator Hook ⭐ NEW
+### Payment Link Generator Hook
 
 Generate shareable payment links programmatically:
 
 ```tsx
-import { usePaymentLink } from "@settlr/sdk";
+import { useSettlr } from "@settlr/sdk";
 
 function InvoicePage() {
-  const { generateLink, generateQRCode } = usePaymentLink({
-    merchantWallet: "YOUR_WALLET",
-    merchantName: "My Store",
-  });
+  const { getCheckoutUrl } = useSettlr();
 
-  const link = generateLink({
+  const link = getCheckoutUrl({
     amount: 500,
     memo: "Invoice #1234",
     orderId: "inv_1234",
   });
-  // → https://settlr.dev/pay?amount=500&merchant=My+Store&...
-
-  const qrCode = await generateQRCode({ amount: 500 });
-  // → QR code image URL
+  // → https://settlr.app/checkout?amount=500&merchant=My+Game&...
 }
 ```
 
@@ -250,7 +214,7 @@ Full checkout UI component with product info.
 
 ### Get Your API Key
 
-1. Go to [settlr.dev/dashboard](https://settlr.dev/dashboard)
+1. Go to [settlr.app/dashboard](https://settlr.app/dashboard)
 2. Connect your wallet
 3. Click "Create API Key"
 4. Save the key securely (only shown once!)
@@ -298,7 +262,7 @@ const payment = await settlr.createPayment({
   id: 'pay_abc123',
   amount: 29.99,
   status: 'pending',
-  checkoutUrl: 'https://settlr.dev/pay?...',
+  checkoutUrl: 'https://settlr.app/checkout?...',
   qrCode: 'data:image/svg+xml,...',
   createdAt: Date,
   expiresAt: Date,
@@ -372,7 +336,7 @@ window.location.href = session.url;
 // Returns
 {
   id: 'cs_abc123...',
-  url: 'https://settlr.dev/checkout/cs_abc123...',
+  url: 'https://settlr.app/checkout/cs_abc123...',
   expiresAt: 1702659600000, // 30 min expiry
 }
 ```

package/dist/index.d.mts

@@ -5,8 +5,8 @@ import { ReactNode, CSSProperties } from 'react';
 declare const USDC_MINT_DEVNET: PublicKey;
 declare const USDC_MINT_MAINNET: PublicKey;
 declare const SETTLR_CHECKOUT_URL: {
-    readonly production: "https://settlr.dev/pay";
-    readonly development: "http://localhost:3000/pay";
+    readonly production: "https://settlr.dev/checkout";
+    readonly development: "http://localhost:3000/checkout";
 };
 declare const SUPPORTED_NETWORKS: readonly ["devnet", "mainnet-beta"];
 type SupportedNetwork = typeof SUPPORTED_NETWORKS[number];
@@ -182,6 +182,30 @@ declare class Settlr {
      * Get the current tier
      */
     getTier(): 'free' | 'pro' | 'enterprise' | undefined;
+    /**
+     * Get a checkout URL for redirect-based payments
+     *
+     * This is the simplest integration - just redirect users to this URL.
+     * Settlr handles auth (email or wallet) and payment processing.
+     *
+     * @example
+     * ```typescript
+     * const url = settlr.getCheckoutUrl({
+     *   amount: 29.99,
+     *   memo: 'Premium Pack',
+     * });
+     *
+     * // Redirect user to checkout
+     * window.location.href = url;
+     * ```
+     */
+    getCheckoutUrl(options: {
+        amount: number;
+        memo?: string;
+        orderId?: string;
+        successUrl?: string;
+        cancelUrl?: string;
+    }): string;
     /**
      * Create a payment link
      *
@@ -314,21 +338,28 @@ declare function parseUSDC(amount: number | string): bigint;
  */
 declare function shortenAddress(address: string, chars?: number): string;
 
+/**
+ * Checkout URL options
+ */
+interface CheckoutUrlOptions {
+    amount: number;
+    memo?: string;
+    orderId?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+}
 /**
  * Settlr context value
  */
 interface SettlrContextValue {
     /** Settlr client instance */
     settlr: Settlr | null;
-    /** Whether wallet is connected */
-    connected: boolean;
-    /** Create a payment link */
+    /** Whether user is authenticated */
+    authenticated: boolean;
+    /** Create a payment link (redirect flow) */
     createPayment: (options: CreatePaymentOptions) => Promise<Payment>;
-    /** Execute a direct payment */
-    pay: (options: {
-        amount: number;
-        memo?: string;
-    }) => Promise<PaymentResult>;
+    /** Generate checkout URL for redirect */
+    getCheckoutUrl: (options: CheckoutUrlOptions) => string;
     /** Get merchant's USDC balance */
     getBalance: () => Promise<number>;
 }
@@ -337,32 +368,41 @@ interface SettlrContextValue {
  */
 interface SettlrProviderProps {
     children: ReactNode;
-    config: Omit<SettlrConfig, "rpcEndpoint">;
+    config: SettlrConfig;
+    /** Whether user is authenticated (from Privy or other auth) */
+    authenticated?: boolean;
 }
 /**
  * Settlr Provider - Wraps your app to provide Settlr functionality
  *
+ * Works with Privy authentication - just pass the authenticated state.
+ *
  * @example
  * ```tsx
  * import { SettlrProvider } from '@settlr/sdk';
+ * import { usePrivy } from '@privy-io/react-auth';
  *
  * function App() {
+ *   const { authenticated } = usePrivy();
+ *
  *   return (
- *     <WalletProvider wallets={wallets}>
- *       <SettlrProvider config={{
+ *     <SettlrProvider
+ *       authenticated={authenticated}
+ *       config={{
+ *         apiKey: 'sk_live_xxxxxxxxxxxx',
  *         merchant: {
- *           name: 'My Store',
+ *           name: 'My Game',
  *           walletAddress: 'YOUR_WALLET',
  *         },
- *       }}>
- *         <YourApp />
- *       </SettlrProvider>
- *     </WalletProvider>
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </SettlrProvider>
  *   );
  * }
  * ```
  */
-declare function SettlrProvider({ children, config }: SettlrProviderProps): react_jsx_runtime.JSX.Element;
+declare function SettlrProvider({ children, config, authenticated, }: SettlrProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * useSettlr hook - Access Settlr functionality in your components
  *
@@ -371,23 +411,17 @@ declare function SettlrProvider({ children, config }: SettlrProviderProps): reac
  * import { useSettlr } from '@settlr/sdk';
  *
  * function CheckoutButton() {
- *   const { createPayment, pay, connected } = useSettlr();
- *
- *   const handlePay = async () => {
- *     // Option 1: Create payment link
- *     const payment = await createPayment({ amount: 29.99 });
- *     window.location.href = payment.checkoutUrl;
+ *   const { getCheckoutUrl, authenticated } = useSettlr();
  *
- *     // Option 2: Direct payment
- *     const result = await pay({ amount: 29.99 });
- *     if (result.success) {
- *       console.log('Paid!');
- *     }
+ *   const handleCheckout = () => {
+ *     // Redirect to Settlr checkout (handles Privy auth internally)
+ *     const url = getCheckoutUrl({ amount: 29.99, memo: 'Premium Pack' });
+ *     window.location.href = url;
  *   };
  *
  *   return (
- *     <button onClick={handlePay} disabled={!connected}>
- *       Pay $29.99
+ *     <button onClick={handleCheckout}>
+ *       Buy Premium Pack - $29.99
  *     </button>
  *   );
  * }
@@ -455,7 +489,8 @@ interface BuyButtonProps {
     /** Button size */
     size?: "sm" | "md" | "lg";
 }
-declare function BuyButton({ amount, memo, orderId, children, onSuccess, onError, onProcessing, useRedirect, successUrl, cancelUrl, className, style, disabled, variant, size, }: BuyButtonProps): react_jsx_runtime.JSX.Element;
+declare function BuyButton({ amount, memo, orderId, children, onSuccess, onError, onProcessing, useRedirect, // Default to redirect flow (works with Privy)
+successUrl, cancelUrl, className, style, disabled, variant, size, }: BuyButtonProps): react_jsx_runtime.JSX.Element;
 /**
  * Checkout Widget - Embeddable checkout form
  *
@@ -549,6 +584,111 @@ declare function usePaymentLink(config: {
         cancelUrl?: string;
     }) => string>[0]) => Promise<string>;
 };
+/**
+ * Payment Modal - Iframe-based checkout that keeps users on your site
+ *
+ * @example
+ * ```tsx
+ * import { PaymentModal } from '@settlr/sdk';
+ *
+ * function ProductPage() {
+ *   const [showPayment, setShowPayment] = useState(false);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => setShowPayment(true)}>
+ *         Buy Now - $49.99
+ *       </button>
+ *
+ *       {showPayment && (
+ *         <PaymentModal
+ *           amount={49.99}
+ *           merchantName="Arena GG"
+ *           merchantWallet="YOUR_WALLET_ADDRESS"
+ *           memo="Tournament Entry"
+ *           onSuccess={(result) => {
+ *             console.log('Paid!', result.signature);
+ *             setShowPayment(false);
+ *           }}
+ *           onClose={() => setShowPayment(false)}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+interface PaymentModalProps {
+    /** Payment amount in USDC */
+    amount: number;
+    /** Merchant display name */
+    merchantName: string;
+    /** Merchant wallet address */
+    merchantWallet: string;
+    /** Optional memo/description */
+    memo?: string;
+    /** Optional order ID */
+    orderId?: string;
+    /** Called when payment succeeds */
+    onSuccess?: (result: {
+        signature: string;
+        amount: number;
+    }) => void;
+    /** Called when modal is closed */
+    onClose?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Checkout base URL (default: https://settlr.dev/checkout) */
+    checkoutUrl?: string;
+}
+declare function PaymentModal({ amount, merchantName, merchantWallet, memo, orderId, onSuccess, onClose, onError, checkoutUrl, }: PaymentModalProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to open payment modal programmatically
+ *
+ * @example
+ * ```tsx
+ * import { usePaymentModal } from '@settlr/sdk';
+ *
+ * function ProductPage() {
+ *   const { openPayment, PaymentModalComponent } = usePaymentModal({
+ *     merchantName: "Arena GG",
+ *     merchantWallet: "YOUR_WALLET",
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => openPayment({
+ *         amount: 49.99,
+ *         memo: "Tournament Entry",
+ *         onSuccess: (result) => console.log("Paid!", result),
+ *       })}>
+ *         Buy Now
+ *       </button>
+ *       <PaymentModalComponent />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function usePaymentModal(config: {
+    merchantName: string;
+    merchantWallet: string;
+    checkoutUrl?: string;
+}): {
+    openPayment: (options: {
+        amount: number;
+        memo?: string;
+        orderId?: string;
+        onSuccess?: (result: {
+            signature: string;
+            amount: number;
+        }) => void;
+        onError?: (error: Error) => void;
+    }) => void;
+    closePayment: () => void;
+    isOpen: boolean;
+    PaymentModalComponent: () => react_jsx_runtime.JSX.Element | null;
+};
 
 /**
  * Verify a webhook signature
@@ -632,4 +772,4 @@ declare function createWebhookHandler(options: {
     onError?: (error: Error) => void;
 }): (req: any, res: any) => Promise<void>;
 
-export { BuyButton, type BuyButtonProps, CheckoutWidget, type CheckoutWidgetProps, type CreatePaymentOptions, type MerchantConfig, type Payment, type PaymentResult, type PaymentStatus, SETTLR_CHECKOUT_URL, SUPPORTED_NETWORKS, Settlr, type SettlrConfig, SettlrProvider, type TransactionOptions, USDC_MINT_DEVNET, USDC_MINT_MAINNET, type WebhookEventType, type WebhookHandler, type WebhookHandlers, type WebhookPayload, createWebhookHandler, formatUSDC, parseUSDC, parseWebhookPayload, shortenAddress, usePaymentLink, useSettlr, verifyWebhookSignature };
+export { BuyButton, type BuyButtonProps, CheckoutWidget, type CheckoutWidgetProps, type CreatePaymentOptions, type MerchantConfig, type Payment, PaymentModal, type PaymentModalProps, type PaymentResult, type PaymentStatus, SETTLR_CHECKOUT_URL, SUPPORTED_NETWORKS, Settlr, type SettlrConfig, SettlrProvider, type TransactionOptions, USDC_MINT_DEVNET, USDC_MINT_MAINNET, type WebhookEventType, type WebhookHandler, type WebhookHandlers, type WebhookPayload, createWebhookHandler, formatUSDC, parseUSDC, parseWebhookPayload, shortenAddress, usePaymentLink, usePaymentModal, useSettlr, verifyWebhookSignature };