@settlr/sdk 0.6.0 → 0.6.1

package/README.md

@@ -97,6 +97,71 @@ const accounts = await buildPrivateReceiptAccounts({
 
 > **Private on-chain. Compliant off-chain.** Your competitors can't see your revenue, but your accountant can.
 
+## 🛡️ Wallet Security (Range)
+
+Settlr integrates Range Security to screen wallets before processing payments:
+
+```typescript
+import { screenWallet, isWalletBlocked, RiskLevel } from "@settlr/sdk";
+
+// Screen a wallet for sanctions, fraud, mixers, etc.
+const result = await screenWallet("SomeWalletAddress...");
+
+if (result.riskLevel === RiskLevel.SEVERE || result.isSanctioned) {
+  console.log("Wallet is blocked:", result.categories);
+  // Don't process payment
+}
+
+// Quick check
+const blocked = await isWalletBlocked("SuspiciousWallet...");
+if (blocked) {
+  return { error: "Payment blocked for compliance" };
+}
+```
+
+**What Range screens for:**
+
+- 🚫 **Sanctions** - OFAC, EU sanctions lists
+- 🕵️ **Fraud** - Known scam wallets
+- 🌀 **Mixers** - Tornado Cash, etc.
+- 🌑 **Darknet** - Illicit marketplace activity
+- 💀 **Ransomware** - Known attack wallets
+- 🎰 **Gambling** - Unlicensed gambling (configurable)
+
+## 💸 Private Payouts (Privacy Cash)
+
+Enable ZK-shielded payments for privacy-conscious merchants:
+
+```typescript
+import {
+  createPrivacyCashClient,
+  shieldPayment,
+  privateTransfer,
+} from "@settlr/sdk";
+
+// Initialize Privacy Cash
+const privacy = createPrivacyCashClient({
+  connection,
+  wallet,
+  network: "mainnet-beta",
+});
+
+// Shield funds (move to private pool)
+const shieldTx = await shieldPayment(privacy, 100); // $100 USDC
+console.log("Shielded:", shieldTx);
+
+// Private transfer (ZK-shielded, amount hidden)
+const transferTx = await privateTransfer(privacy, "RecipientWallet...", 50);
+console.log("Private transfer:", transferTx);
+```
+
+**Privacy Cash features:**
+
+- 🔐 ZK-shielded transactions
+- 👁️ Amount hidden from on-chain observers
+- ⚡ Fast finality on Solana
+- 💰 Supports USDC and SOL
+
 ## Installation
 
 ```bash
@@ -499,7 +564,7 @@ app.post(
         await fulfillOrder(event.payment.orderId);
       },
     },
-  })
+  }),
 );
 ```
 

package/dist/index.d.mts

@@ -1143,4 +1143,114 @@ declare class OneClickClient {
  */
 declare function createOneClickClient(baseUrl?: string): OneClickClient;
 
-export { type ApproveOneClickOptions, BuyButton, type BuyButtonProps, type ChargeOneClickOptions, CheckoutWidget, type CheckoutWidgetProps, type CreatePaymentOptions, type CreateSubscriptionOptions, INCO_LIGHTNING_PROGRAM_ID, type IssuePrivateReceiptResult, type MerchantConfig, OneClickClient, type OneClickResult, type Payment, PaymentModal, type PaymentModalProps, type PaymentResult, type PaymentStatus, PrivacyFeatures, type PrivateReceiptConfig, SETTLR_CHECKOUT_URL, SETTLR_PROGRAM_ID, SUPPORTED_NETWORKS, SUPPORTED_TOKENS, Settlr, type SettlrConfig, SettlrProvider, type SpendingApproval, type Subscription, type SubscriptionInterval, type SubscriptionPlan, type SubscriptionStatus, type SupportedToken, type TransactionOptions, USDC_MINT_DEVNET, USDC_MINT_MAINNET, USDT_MINT_DEVNET, USDT_MINT_MAINNET, type WebhookEventType, type WebhookHandler, type WebhookHandlers, type WebhookPayload, buildAllowanceRemainingAccounts, buildPrivateReceiptAccounts, createOneClickClient, createWebhookHandler, encryptAmount, findAllowancePda, findPrivateReceiptPda, formatUSDC, getTokenDecimals, getTokenMint, parseUSDC, parseWebhookPayload, shortenAddress, simulateAndGetHandle, usePaymentLink, usePaymentModal, useSettlr, verifyWebhookSignature };
+/**
+ * Mobile Game Integration Utilities
+ *
+ * Simple helpers for integrating Settlr payments in mobile games.
+ * Works with Unity, Unreal, native iOS/Android, React Native, etc.
+ *
+ * The simplest integration is URL-based - just open the checkout URL
+ * and listen for the callback.
+ */
+interface MobileCheckoutOptions {
+    /** Amount in USDC */
+    amount: number;
+    /** Merchant wallet address */
+    merchantWallet: string;
+    /** Optional: Merchant display name */
+    merchantName?: string;
+    /** Optional: Payment description */
+    memo?: string;
+    /** URL to redirect after success */
+    successUrl?: string;
+    /** URL to redirect on cancel */
+    cancelUrl?: string;
+    /** Optional: Your order/transaction ID */
+    orderId?: string;
+    /** Optional: Customer ID for one-click */
+    customerId?: string;
+}
+interface MobileCheckoutResult {
+    success: boolean;
+    signature?: string;
+    orderId?: string;
+    error?: string;
+}
+/**
+ * Generate a checkout URL for mobile games
+ *
+ * Usage in Unity (C#):
+ * ```csharp
+ * string url = $"https://settlr.dev/checkout?amount={amount}&merchant={wallet}";
+ * Application.OpenURL(url);
+ * ```
+ *
+ * Usage in Swift:
+ * ```swift
+ * let url = "https://settlr.dev/checkout?amount=\(amount)&merchant=\(wallet)"
+ * UIApplication.shared.open(URL(string: url)!)
+ * ```
+ */
+declare function generateCheckoutUrl(options: MobileCheckoutOptions, baseUrl?: string): string;
+/**
+ * Generate a deep link for mobile app integration
+ *
+ * For apps that register a custom URL scheme (e.g., mygame://)
+ * the success/cancel URLs can redirect back to the app.
+ *
+ * Example:
+ * - successUrl: "mygame://payment-success?order=123"
+ * - cancelUrl: "mygame://payment-cancel?order=123"
+ */
+declare function generateDeepLinkCheckout(options: MobileCheckoutOptions, appScheme: string, baseUrl?: string): string;
+/**
+ * Parse the callback URL when user returns to app
+ *
+ * Usage in Swift:
+ * ```swift
+ * func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+ *     if url.scheme == "mygame" && url.host == "payment-success" {
+ *         let signature = URLComponents(url: url, resolvingAgainstBaseURL: true)?
+ *             .queryItems?.first(where: { $0.name == "signature" })?.value
+ *         // Handle success
+ *     }
+ * }
+ * ```
+ */
+declare function parseCallbackUrl(url: string): MobileCheckoutResult;
+/**
+ * REST API endpoint info for server-side integration
+ *
+ * Mobile games can use these APIs directly without the SDK:
+ *
+ * 1. Create checkout session:
+ *    POST /api/checkout/create
+ *    { amount, merchantWallet, memo }
+ *    → { sessionId, checkoutUrl }
+ *
+ * 2. Check payment status:
+ *    GET /api/checkout/status?session={sessionId}
+ *    → { status: 'pending' | 'completed' | 'expired', signature? }
+ *
+ * 3. One-click payment (for returning players):
+ *    POST /api/one-click
+ *    { action: 'charge', customerWallet, merchantWallet, amount }
+ *    → { success, signature }
+ */
+declare const REST_API: {
+    createSession: string;
+    checkStatus: string;
+    oneClick: string;
+    webhook: string;
+};
+/**
+ * Example Unity C# integration code
+ * (For documentation purposes)
+ */
+declare const UNITY_EXAMPLE = "\n// SettlrPayment.cs - Drop into your Unity project\n\nusing UnityEngine;\nusing UnityEngine.Networking;\nusing System.Collections;\n\npublic class SettlrPayment : MonoBehaviour\n{\n    public string merchantWallet = \"YOUR_WALLET_ADDRESS\";\n    public string settlrUrl = \"https://settlr.dev\";\n    \n    // Call this to start a payment\n    public void StartPayment(float amount, string orderId, System.Action<bool, string> callback)\n    {\n        string url = $\"{settlrUrl}/checkout?amount={amount}&merchant={merchantWallet}&order_id={orderId}\";\n        \n        // Add deep link callback (register mygame:// scheme in your app)\n        url += $\"&success_url=mygame://payment-success?order={orderId}\";\n        url += $\"&cancel_url=mygame://payment-cancel?order={orderId}\";\n        \n        Application.OpenURL(url);\n        \n        // Start polling for completion\n        StartCoroutine(PollPaymentStatus(orderId, callback));\n    }\n    \n    IEnumerator PollPaymentStatus(string orderId, System.Action<bool, string> callback)\n    {\n        string statusUrl = $\"{settlrUrl}/api/checkout/status?order_id={orderId}\";\n        \n        for (int i = 0; i < 60; i++) // Poll for 5 minutes\n        {\n            using (UnityWebRequest request = UnityWebRequest.Get(statusUrl))\n            {\n                yield return request.SendWebRequest();\n                \n                if (request.result == UnityWebRequest.Result.Success)\n                {\n                    var response = JsonUtility.FromJson<PaymentStatusResponse>(request.downloadHandler.text);\n                    \n                    if (response.status == \"completed\")\n                    {\n                        callback(true, response.signature);\n                        yield break;\n                    }\n                    else if (response.status == \"expired\" || response.status == \"cancelled\")\n                    {\n                        callback(false, null);\n                        yield break;\n                    }\n                }\n            }\n            \n            yield return new WaitForSeconds(5f); // Check every 5 seconds\n        }\n        \n        callback(false, \"Timeout\");\n    }\n    \n    [System.Serializable]\n    class PaymentStatusResponse\n    {\n        public string status;\n        public string signature;\n    }\n}\n";
+/**
+ * Example React Native integration
+ */
+declare const REACT_NATIVE_EXAMPLE = "\n// SettlrPayment.tsx - React Native component\n\nimport { Linking, Alert } from 'react-native';\nimport { useEffect } from 'react';\n\nconst SETTLR_URL = 'https://settlr.dev';\nconst APP_SCHEME = 'mygame';\n\nexport function useSettlrPayment(onSuccess: (sig: string) => void) {\n  useEffect(() => {\n    const handleDeepLink = ({ url }: { url: string }) => {\n      if (url.includes('payment-success')) {\n        const sig = new URL(url).searchParams.get('signature');\n        if (sig) onSuccess(sig);\n      }\n    };\n    \n    Linking.addEventListener('url', handleDeepLink);\n    return () => Linking.removeAllListeners('url');\n  }, [onSuccess]);\n  \n  const startPayment = async (amount: number, merchantWallet: string) => {\n    const orderId = `order_${Date.now()}`;\n    const url = `${SETTLR_URL}/checkout?amount=${amount}&merchant=${merchantWallet}` +\n      `&success_url=${APP_SCHEME}://payment-success?order=${orderId}` +\n      `&cancel_url=${APP_SCHEME}://payment-cancel?order=${orderId}`;\n    \n    await Linking.openURL(url);\n  };\n  \n  return { startPayment };\n}\n";
+
+export { type ApproveOneClickOptions, BuyButton, type BuyButtonProps, type ChargeOneClickOptions, CheckoutWidget, type CheckoutWidgetProps, type CreatePaymentOptions, type CreateSubscriptionOptions, INCO_LIGHTNING_PROGRAM_ID, type IssuePrivateReceiptResult, type MerchantConfig, type MobileCheckoutOptions, type MobileCheckoutResult, OneClickClient, type OneClickResult, type Payment, PaymentModal, type PaymentModalProps, type PaymentResult, type PaymentStatus, PrivacyFeatures, type PrivateReceiptConfig, REACT_NATIVE_EXAMPLE, REST_API, SETTLR_CHECKOUT_URL, SETTLR_PROGRAM_ID, SUPPORTED_NETWORKS, SUPPORTED_TOKENS, Settlr, type SettlrConfig, SettlrProvider, type SpendingApproval, type Subscription, type SubscriptionInterval, type SubscriptionPlan, type SubscriptionStatus, type SupportedToken, type TransactionOptions, UNITY_EXAMPLE, USDC_MINT_DEVNET, USDC_MINT_MAINNET, USDT_MINT_DEVNET, USDT_MINT_MAINNET, type WebhookEventType, type WebhookHandler, type WebhookHandlers, type WebhookPayload, buildAllowanceRemainingAccounts, buildPrivateReceiptAccounts, createOneClickClient, createWebhookHandler, encryptAmount, findAllowancePda, findPrivateReceiptPda, formatUSDC, generateCheckoutUrl, generateDeepLinkCheckout, getTokenDecimals, getTokenMint, parseCallbackUrl, parseUSDC, parseWebhookPayload, shortenAddress, simulateAndGetHandle, usePaymentLink, usePaymentModal, useSettlr, verifyWebhookSignature };

package/dist/index.d.ts

@@ -1143,4 +1143,114 @@ declare class OneClickClient {
  */
 declare function createOneClickClient(baseUrl?: string): OneClickClient;
 
-export { type ApproveOneClickOptions, BuyButton, type BuyButtonProps, type ChargeOneClickOptions, CheckoutWidget, type CheckoutWidgetProps, type CreatePaymentOptions, type CreateSubscriptionOptions, INCO_LIGHTNING_PROGRAM_ID, type IssuePrivateReceiptResult, type MerchantConfig, OneClickClient, type OneClickResult, type Payment, PaymentModal, type PaymentModalProps, type PaymentResult, type PaymentStatus, PrivacyFeatures, type PrivateReceiptConfig, SETTLR_CHECKOUT_URL, SETTLR_PROGRAM_ID, SUPPORTED_NETWORKS, SUPPORTED_TOKENS, Settlr, type SettlrConfig, SettlrProvider, type SpendingApproval, type Subscription, type SubscriptionInterval, type SubscriptionPlan, type SubscriptionStatus, type SupportedToken, type TransactionOptions, USDC_MINT_DEVNET, USDC_MINT_MAINNET, USDT_MINT_DEVNET, USDT_MINT_MAINNET, type WebhookEventType, type WebhookHandler, type WebhookHandlers, type WebhookPayload, buildAllowanceRemainingAccounts, buildPrivateReceiptAccounts, createOneClickClient, createWebhookHandler, encryptAmount, findAllowancePda, findPrivateReceiptPda, formatUSDC, getTokenDecimals, getTokenMint, parseUSDC, parseWebhookPayload, shortenAddress, simulateAndGetHandle, usePaymentLink, usePaymentModal, useSettlr, verifyWebhookSignature };
+/**
+ * Mobile Game Integration Utilities
+ *
+ * Simple helpers for integrating Settlr payments in mobile games.
+ * Works with Unity, Unreal, native iOS/Android, React Native, etc.
+ *
+ * The simplest integration is URL-based - just open the checkout URL
+ * and listen for the callback.
+ */
+interface MobileCheckoutOptions {
+    /** Amount in USDC */
+    amount: number;
+    /** Merchant wallet address */
+    merchantWallet: string;
+    /** Optional: Merchant display name */
+    merchantName?: string;
+    /** Optional: Payment description */
+    memo?: string;
+    /** URL to redirect after success */
+    successUrl?: string;
+    /** URL to redirect on cancel */
+    cancelUrl?: string;
+    /** Optional: Your order/transaction ID */
+    orderId?: string;
+    /** Optional: Customer ID for one-click */
+    customerId?: string;
+}
+interface MobileCheckoutResult {
+    success: boolean;
+    signature?: string;
+    orderId?: string;
+    error?: string;
+}
+/**
+ * Generate a checkout URL for mobile games
+ *
+ * Usage in Unity (C#):
+ * ```csharp
+ * string url = $"https://settlr.dev/checkout?amount={amount}&merchant={wallet}";
+ * Application.OpenURL(url);
+ * ```
+ *
+ * Usage in Swift:
+ * ```swift
+ * let url = "https://settlr.dev/checkout?amount=\(amount)&merchant=\(wallet)"
+ * UIApplication.shared.open(URL(string: url)!)
+ * ```
+ */
+declare function generateCheckoutUrl(options: MobileCheckoutOptions, baseUrl?: string): string;
+/**
+ * Generate a deep link for mobile app integration
+ *
+ * For apps that register a custom URL scheme (e.g., mygame://)
+ * the success/cancel URLs can redirect back to the app.
+ *
+ * Example:
+ * - successUrl: "mygame://payment-success?order=123"
+ * - cancelUrl: "mygame://payment-cancel?order=123"
+ */
+declare function generateDeepLinkCheckout(options: MobileCheckoutOptions, appScheme: string, baseUrl?: string): string;
+/**
+ * Parse the callback URL when user returns to app
+ *
+ * Usage in Swift:
+ * ```swift
+ * func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+ *     if url.scheme == "mygame" && url.host == "payment-success" {
+ *         let signature = URLComponents(url: url, resolvingAgainstBaseURL: true)?
+ *             .queryItems?.first(where: { $0.name == "signature" })?.value
+ *         // Handle success
+ *     }
+ * }
+ * ```
+ */
+declare function parseCallbackUrl(url: string): MobileCheckoutResult;
+/**
+ * REST API endpoint info for server-side integration
+ *
+ * Mobile games can use these APIs directly without the SDK:
+ *
+ * 1. Create checkout session:
+ *    POST /api/checkout/create
+ *    { amount, merchantWallet, memo }
+ *    → { sessionId, checkoutUrl }
+ *
+ * 2. Check payment status:
+ *    GET /api/checkout/status?session={sessionId}
+ *    → { status: 'pending' | 'completed' | 'expired', signature? }
+ *
+ * 3. One-click payment (for returning players):
+ *    POST /api/one-click
+ *    { action: 'charge', customerWallet, merchantWallet, amount }
+ *    → { success, signature }
+ */
+declare const REST_API: {
+    createSession: string;
+    checkStatus: string;
+    oneClick: string;
+    webhook: string;
+};
+/**
+ * Example Unity C# integration code
+ * (For documentation purposes)
+ */
+declare const UNITY_EXAMPLE = "\n// SettlrPayment.cs - Drop into your Unity project\n\nusing UnityEngine;\nusing UnityEngine.Networking;\nusing System.Collections;\n\npublic class SettlrPayment : MonoBehaviour\n{\n    public string merchantWallet = \"YOUR_WALLET_ADDRESS\";\n    public string settlrUrl = \"https://settlr.dev\";\n    \n    // Call this to start a payment\n    public void StartPayment(float amount, string orderId, System.Action<bool, string> callback)\n    {\n        string url = $\"{settlrUrl}/checkout?amount={amount}&merchant={merchantWallet}&order_id={orderId}\";\n        \n        // Add deep link callback (register mygame:// scheme in your app)\n        url += $\"&success_url=mygame://payment-success?order={orderId}\";\n        url += $\"&cancel_url=mygame://payment-cancel?order={orderId}\";\n        \n        Application.OpenURL(url);\n        \n        // Start polling for completion\n        StartCoroutine(PollPaymentStatus(orderId, callback));\n    }\n    \n    IEnumerator PollPaymentStatus(string orderId, System.Action<bool, string> callback)\n    {\n        string statusUrl = $\"{settlrUrl}/api/checkout/status?order_id={orderId}\";\n        \n        for (int i = 0; i < 60; i++) // Poll for 5 minutes\n        {\n            using (UnityWebRequest request = UnityWebRequest.Get(statusUrl))\n            {\n                yield return request.SendWebRequest();\n                \n                if (request.result == UnityWebRequest.Result.Success)\n                {\n                    var response = JsonUtility.FromJson<PaymentStatusResponse>(request.downloadHandler.text);\n                    \n                    if (response.status == \"completed\")\n                    {\n                        callback(true, response.signature);\n                        yield break;\n                    }\n                    else if (response.status == \"expired\" || response.status == \"cancelled\")\n                    {\n                        callback(false, null);\n                        yield break;\n                    }\n                }\n            }\n            \n            yield return new WaitForSeconds(5f); // Check every 5 seconds\n        }\n        \n        callback(false, \"Timeout\");\n    }\n    \n    [System.Serializable]\n    class PaymentStatusResponse\n    {\n        public string status;\n        public string signature;\n    }\n}\n";
+/**
+ * Example React Native integration
+ */
+declare const REACT_NATIVE_EXAMPLE = "\n// SettlrPayment.tsx - React Native component\n\nimport { Linking, Alert } from 'react-native';\nimport { useEffect } from 'react';\n\nconst SETTLR_URL = 'https://settlr.dev';\nconst APP_SCHEME = 'mygame';\n\nexport function useSettlrPayment(onSuccess: (sig: string) => void) {\n  useEffect(() => {\n    const handleDeepLink = ({ url }: { url: string }) => {\n      if (url.includes('payment-success')) {\n        const sig = new URL(url).searchParams.get('signature');\n        if (sig) onSuccess(sig);\n      }\n    };\n    \n    Linking.addEventListener('url', handleDeepLink);\n    return () => Linking.removeAllListeners('url');\n  }, [onSuccess]);\n  \n  const startPayment = async (amount: number, merchantWallet: string) => {\n    const orderId = `order_${Date.now()}`;\n    const url = `${SETTLR_URL}/checkout?amount=${amount}&merchant=${merchantWallet}` +\n      `&success_url=${APP_SCHEME}://payment-success?order=${orderId}` +\n      `&cancel_url=${APP_SCHEME}://payment-cancel?order=${orderId}`;\n    \n    await Linking.openURL(url);\n  };\n  \n  return { startPayment };\n}\n";
+
+export { type ApproveOneClickOptions, BuyButton, type BuyButtonProps, type ChargeOneClickOptions, CheckoutWidget, type CheckoutWidgetProps, type CreatePaymentOptions, type CreateSubscriptionOptions, INCO_LIGHTNING_PROGRAM_ID, type IssuePrivateReceiptResult, type MerchantConfig, type MobileCheckoutOptions, type MobileCheckoutResult, OneClickClient, type OneClickResult, type Payment, PaymentModal, type PaymentModalProps, type PaymentResult, type PaymentStatus, PrivacyFeatures, type PrivateReceiptConfig, REACT_NATIVE_EXAMPLE, REST_API, SETTLR_CHECKOUT_URL, SETTLR_PROGRAM_ID, SUPPORTED_NETWORKS, SUPPORTED_TOKENS, Settlr, type SettlrConfig, SettlrProvider, type SpendingApproval, type Subscription, type SubscriptionInterval, type SubscriptionPlan, type SubscriptionStatus, type SupportedToken, type TransactionOptions, UNITY_EXAMPLE, USDC_MINT_DEVNET, USDC_MINT_MAINNET, USDT_MINT_DEVNET, USDT_MINT_MAINNET, type WebhookEventType, type WebhookHandler, type WebhookHandlers, type WebhookPayload, buildAllowanceRemainingAccounts, buildPrivateReceiptAccounts, createOneClickClient, createWebhookHandler, encryptAmount, findAllowancePda, findPrivateReceiptPda, formatUSDC, generateCheckoutUrl, generateDeepLinkCheckout, getTokenDecimals, getTokenMint, parseCallbackUrl, parseUSDC, parseWebhookPayload, shortenAddress, simulateAndGetHandle, usePaymentLink, usePaymentModal, useSettlr, verifyWebhookSignature };

package/dist/index.js

@@ -36,12 +36,15 @@ __export(index_exports, {
   OneClickClient: () => OneClickClient,
   PaymentModal: () => PaymentModal,
   PrivacyFeatures: () => PrivacyFeatures,
+  REACT_NATIVE_EXAMPLE: () => REACT_NATIVE_EXAMPLE,
+  REST_API: () => REST_API,
   SETTLR_CHECKOUT_URL: () => SETTLR_CHECKOUT_URL,
   SETTLR_PROGRAM_ID: () => SETTLR_PROGRAM_ID,
   SUPPORTED_NETWORKS: () => SUPPORTED_NETWORKS,
   SUPPORTED_TOKENS: () => SUPPORTED_TOKENS,
   Settlr: () => Settlr,
   SettlrProvider: () => SettlrProvider,
+  UNITY_EXAMPLE: () => UNITY_EXAMPLE,
   USDC_MINT_DEVNET: () => USDC_MINT_DEVNET,
   USDC_MINT_MAINNET: () => USDC_MINT_MAINNET,
   USDT_MINT_DEVNET: () => USDT_MINT_DEVNET,
@@ -54,8 +57,11 @@ __export(index_exports, {
   findAllowancePda: () => findAllowancePda,
   findPrivateReceiptPda: () => findPrivateReceiptPda,
   formatUSDC: () => formatUSDC,
+  generateCheckoutUrl: () => generateCheckoutUrl,
+  generateDeepLinkCheckout: () => generateDeepLinkCheckout,
   getTokenDecimals: () => getTokenDecimals,
   getTokenMint: () => getTokenMint,
+  parseCallbackUrl: () => parseCallbackUrl,
   parseUSDC: () => parseUSDC,
   parseWebhookPayload: () => parseWebhookPayload,
   shortenAddress: () => shortenAddress,
@@ -1426,6 +1432,167 @@ var OneClickClient = class {
 function createOneClickClient(baseUrl) {
   return new OneClickClient(baseUrl);
 }
+
+// src/mobile.ts
+function generateCheckoutUrl(options, baseUrl = "https://settlr.dev") {
+  const params = new URLSearchParams();
+  params.set("amount", options.amount.toString());
+  params.set("merchant", options.merchantWallet);
+  if (options.merchantName) params.set("name", options.merchantName);
+  if (options.memo) params.set("memo", options.memo);
+  if (options.successUrl) params.set("success_url", options.successUrl);
+  if (options.cancelUrl) params.set("cancel_url", options.cancelUrl);
+  if (options.orderId) params.set("order_id", options.orderId);
+  if (options.customerId) params.set("customer_id", options.customerId);
+  return `${baseUrl}/checkout?${params.toString()}`;
+}
+function generateDeepLinkCheckout(options, appScheme, baseUrl = "https://settlr.dev") {
+  const orderId = options.orderId || `order_${Date.now()}`;
+  return generateCheckoutUrl({
+    ...options,
+    orderId,
+    successUrl: `${appScheme}://payment-success?order=${orderId}`,
+    cancelUrl: `${appScheme}://payment-cancel?order=${orderId}`
+  }, baseUrl);
+}
+function parseCallbackUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const params = parsed.searchParams;
+    if (parsed.host === "payment-success" || parsed.pathname.includes("success")) {
+      return {
+        success: true,
+        signature: params.get("signature") || void 0,
+        orderId: params.get("order") || params.get("order_id") || void 0
+      };
+    }
+    if (parsed.host === "payment-cancel" || parsed.pathname.includes("cancel")) {
+      return {
+        success: false,
+        orderId: params.get("order") || params.get("order_id") || void 0,
+        error: "Payment cancelled by user"
+      };
+    }
+    return {
+      success: false,
+      error: "Unknown callback URL format"
+    };
+  } catch {
+    return {
+      success: false,
+      error: "Failed to parse callback URL"
+    };
+  }
+}
+var REST_API = {
+  createSession: "/api/checkout/create",
+  checkStatus: "/api/checkout/status",
+  oneClick: "/api/one-click",
+  webhook: "/api/webhooks"
+  // For server-to-server notifications
+};
+var UNITY_EXAMPLE = `
+// SettlrPayment.cs - Drop into your Unity project
+
+using UnityEngine;
+using UnityEngine.Networking;
+using System.Collections;
+
+public class SettlrPayment : MonoBehaviour
+{
+    public string merchantWallet = "YOUR_WALLET_ADDRESS";
+    public string settlrUrl = "https://settlr.dev";
+    
+    // Call this to start a payment
+    public void StartPayment(float amount, string orderId, System.Action<bool, string> callback)
+    {
+        string url = $"{settlrUrl}/checkout?amount={amount}&merchant={merchantWallet}&order_id={orderId}";
+        
+        // Add deep link callback (register mygame:// scheme in your app)
+        url += $"&success_url=mygame://payment-success?order={orderId}";
+        url += $"&cancel_url=mygame://payment-cancel?order={orderId}";
+        
+        Application.OpenURL(url);
+        
+        // Start polling for completion
+        StartCoroutine(PollPaymentStatus(orderId, callback));
+    }
+    
+    IEnumerator PollPaymentStatus(string orderId, System.Action<bool, string> callback)
+    {
+        string statusUrl = $"{settlrUrl}/api/checkout/status?order_id={orderId}";
+        
+        for (int i = 0; i < 60; i++) // Poll for 5 minutes
+        {
+            using (UnityWebRequest request = UnityWebRequest.Get(statusUrl))
+            {
+                yield return request.SendWebRequest();
+                
+                if (request.result == UnityWebRequest.Result.Success)
+                {
+                    var response = JsonUtility.FromJson<PaymentStatusResponse>(request.downloadHandler.text);
+                    
+                    if (response.status == "completed")
+                    {
+                        callback(true, response.signature);
+                        yield break;
+                    }
+                    else if (response.status == "expired" || response.status == "cancelled")
+                    {
+                        callback(false, null);
+                        yield break;
+                    }
+                }
+            }
+            
+            yield return new WaitForSeconds(5f); // Check every 5 seconds
+        }
+        
+        callback(false, "Timeout");
+    }
+    
+    [System.Serializable]
+    class PaymentStatusResponse
+    {
+        public string status;
+        public string signature;
+    }
+}
+`;
+var REACT_NATIVE_EXAMPLE = `
+// SettlrPayment.tsx - React Native component
+
+import { Linking, Alert } from 'react-native';
+import { useEffect } from 'react';
+
+const SETTLR_URL = 'https://settlr.dev';
+const APP_SCHEME = 'mygame';
+
+export function useSettlrPayment(onSuccess: (sig: string) => void) {
+  useEffect(() => {
+    const handleDeepLink = ({ url }: { url: string }) => {
+      if (url.includes('payment-success')) {
+        const sig = new URL(url).searchParams.get('signature');
+        if (sig) onSuccess(sig);
+      }
+    };
+    
+    Linking.addEventListener('url', handleDeepLink);
+    return () => Linking.removeAllListeners('url');
+  }, [onSuccess]);
+  
+  const startPayment = async (amount: number, merchantWallet: string) => {
+    const orderId = \`order_\${Date.now()}\`;
+    const url = \`\${SETTLR_URL}/checkout?amount=\${amount}&merchant=\${merchantWallet}\` +
+      \`&success_url=\${APP_SCHEME}://payment-success?order=\${orderId}\` +
+      \`&cancel_url=\${APP_SCHEME}://payment-cancel?order=\${orderId}\`;
+    
+    await Linking.openURL(url);
+  };
+  
+  return { startPayment };
+}
+`;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BuyButton,
@@ -1434,12 +1601,15 @@ function createOneClickClient(baseUrl) {
   OneClickClient,
   PaymentModal,
   PrivacyFeatures,
+  REACT_NATIVE_EXAMPLE,
+  REST_API,
   SETTLR_CHECKOUT_URL,
   SETTLR_PROGRAM_ID,
   SUPPORTED_NETWORKS,
   SUPPORTED_TOKENS,
   Settlr,
   SettlrProvider,
+  UNITY_EXAMPLE,
   USDC_MINT_DEVNET,
   USDC_MINT_MAINNET,
   USDT_MINT_DEVNET,
@@ -1452,8 +1622,11 @@ function createOneClickClient(baseUrl) {
   findAllowancePda,
   findPrivateReceiptPda,
   formatUSDC,
+  generateCheckoutUrl,
+  generateDeepLinkCheckout,
   getTokenDecimals,
   getTokenMint,
+  parseCallbackUrl,
   parseUSDC,
   parseWebhookPayload,
   shortenAddress,

package/dist/index.mjs

@@ -1372,6 +1372,167 @@ var OneClickClient = class {
 function createOneClickClient(baseUrl) {
   return new OneClickClient(baseUrl);
 }
+
+// src/mobile.ts
+function generateCheckoutUrl(options, baseUrl = "https://settlr.dev") {
+  const params = new URLSearchParams();
+  params.set("amount", options.amount.toString());
+  params.set("merchant", options.merchantWallet);
+  if (options.merchantName) params.set("name", options.merchantName);
+  if (options.memo) params.set("memo", options.memo);
+  if (options.successUrl) params.set("success_url", options.successUrl);
+  if (options.cancelUrl) params.set("cancel_url", options.cancelUrl);
+  if (options.orderId) params.set("order_id", options.orderId);
+  if (options.customerId) params.set("customer_id", options.customerId);
+  return `${baseUrl}/checkout?${params.toString()}`;
+}
+function generateDeepLinkCheckout(options, appScheme, baseUrl = "https://settlr.dev") {
+  const orderId = options.orderId || `order_${Date.now()}`;
+  return generateCheckoutUrl({
+    ...options,
+    orderId,
+    successUrl: `${appScheme}://payment-success?order=${orderId}`,
+    cancelUrl: `${appScheme}://payment-cancel?order=${orderId}`
+  }, baseUrl);
+}
+function parseCallbackUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const params = parsed.searchParams;
+    if (parsed.host === "payment-success" || parsed.pathname.includes("success")) {
+      return {
+        success: true,
+        signature: params.get("signature") || void 0,
+        orderId: params.get("order") || params.get("order_id") || void 0
+      };
+    }
+    if (parsed.host === "payment-cancel" || parsed.pathname.includes("cancel")) {
+      return {
+        success: false,
+        orderId: params.get("order") || params.get("order_id") || void 0,
+        error: "Payment cancelled by user"
+      };
+    }
+    return {
+      success: false,
+      error: "Unknown callback URL format"
+    };
+  } catch {
+    return {
+      success: false,
+      error: "Failed to parse callback URL"
+    };
+  }
+}
+var REST_API = {
+  createSession: "/api/checkout/create",
+  checkStatus: "/api/checkout/status",
+  oneClick: "/api/one-click",
+  webhook: "/api/webhooks"
+  // For server-to-server notifications
+};
+var UNITY_EXAMPLE = `
+// SettlrPayment.cs - Drop into your Unity project
+
+using UnityEngine;
+using UnityEngine.Networking;
+using System.Collections;
+
+public class SettlrPayment : MonoBehaviour
+{
+    public string merchantWallet = "YOUR_WALLET_ADDRESS";
+    public string settlrUrl = "https://settlr.dev";
+    
+    // Call this to start a payment
+    public void StartPayment(float amount, string orderId, System.Action<bool, string> callback)
+    {
+        string url = $"{settlrUrl}/checkout?amount={amount}&merchant={merchantWallet}&order_id={orderId}";
+        
+        // Add deep link callback (register mygame:// scheme in your app)
+        url += $"&success_url=mygame://payment-success?order={orderId}";
+        url += $"&cancel_url=mygame://payment-cancel?order={orderId}";
+        
+        Application.OpenURL(url);
+        
+        // Start polling for completion
+        StartCoroutine(PollPaymentStatus(orderId, callback));
+    }
+    
+    IEnumerator PollPaymentStatus(string orderId, System.Action<bool, string> callback)
+    {
+        string statusUrl = $"{settlrUrl}/api/checkout/status?order_id={orderId}";
+        
+        for (int i = 0; i < 60; i++) // Poll for 5 minutes
+        {
+            using (UnityWebRequest request = UnityWebRequest.Get(statusUrl))
+            {
+                yield return request.SendWebRequest();
+                
+                if (request.result == UnityWebRequest.Result.Success)
+                {
+                    var response = JsonUtility.FromJson<PaymentStatusResponse>(request.downloadHandler.text);
+                    
+                    if (response.status == "completed")
+                    {
+                        callback(true, response.signature);
+                        yield break;
+                    }
+                    else if (response.status == "expired" || response.status == "cancelled")
+                    {
+                        callback(false, null);
+                        yield break;
+                    }
+                }
+            }
+            
+            yield return new WaitForSeconds(5f); // Check every 5 seconds
+        }
+        
+        callback(false, "Timeout");
+    }
+    
+    [System.Serializable]
+    class PaymentStatusResponse
+    {
+        public string status;
+        public string signature;
+    }
+}
+`;
+var REACT_NATIVE_EXAMPLE = `
+// SettlrPayment.tsx - React Native component
+
+import { Linking, Alert } from 'react-native';
+import { useEffect } from 'react';
+
+const SETTLR_URL = 'https://settlr.dev';
+const APP_SCHEME = 'mygame';
+
+export function useSettlrPayment(onSuccess: (sig: string) => void) {
+  useEffect(() => {
+    const handleDeepLink = ({ url }: { url: string }) => {
+      if (url.includes('payment-success')) {
+        const sig = new URL(url).searchParams.get('signature');
+        if (sig) onSuccess(sig);
+      }
+    };
+    
+    Linking.addEventListener('url', handleDeepLink);
+    return () => Linking.removeAllListeners('url');
+  }, [onSuccess]);
+  
+  const startPayment = async (amount: number, merchantWallet: string) => {
+    const orderId = \`order_\${Date.now()}\`;
+    const url = \`\${SETTLR_URL}/checkout?amount=\${amount}&merchant=\${merchantWallet}\` +
+      \`&success_url=\${APP_SCHEME}://payment-success?order=\${orderId}\` +
+      \`&cancel_url=\${APP_SCHEME}://payment-cancel?order=\${orderId}\`;
+    
+    await Linking.openURL(url);
+  };
+  
+  return { startPayment };
+}
+`;
 export {
   BuyButton,
   CheckoutWidget,
@@ -1379,12 +1540,15 @@ export {
   OneClickClient,
   PaymentModal,
   PrivacyFeatures,
+  REACT_NATIVE_EXAMPLE,
+  REST_API,
   SETTLR_CHECKOUT_URL,
   SETTLR_PROGRAM_ID,
   SUPPORTED_NETWORKS,
   SUPPORTED_TOKENS,
   Settlr,
   SettlrProvider,
+  UNITY_EXAMPLE,
   USDC_MINT_DEVNET,
   USDC_MINT_MAINNET,
   USDT_MINT_DEVNET,
@@ -1397,8 +1561,11 @@ export {
   findAllowancePda,
   findPrivateReceiptPda,
   formatUSDC,
+  generateCheckoutUrl,
+  generateDeepLinkCheckout,
   getTokenDecimals,
   getTokenMint,
+  parseCallbackUrl,
   parseUSDC,
   parseWebhookPayload,
   shortenAddress,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@settlr/sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Settlr SDK - Accept Solana USDC payments with privacy. Email checkout, gasless transactions, FHE-encrypted receipts. Private on-chain, compliant off-chain.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -21,6 +21,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "lint": "eslint src/",
+    "test": "npx tsx node_modules/mocha/bin/mocha.js 'src/__tests__/**/*.test.ts'",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -46,7 +47,17 @@
     "typescript",
     "email-checkout",
     "no-wallet",
-    "privy"
+    "privy",
+    "inco-lightning",
+    "fhe",
+    "homomorphic-encryption",
+    "private-receipts",
+    "privacy-cash",
+    "zk-payments",
+    "range-security",
+    "compliance",
+    "sanctions-screening",
+    "one-click-payments"
   ],
   "author": "Settlr <hello@settlr.dev> (https://settlr.dev)",
   "license": "MIT",
@@ -68,10 +79,16 @@
     "@solana/web3.js": "^1.98.0"
   },
   "devDependencies": {
+    "@types/chai": "^5.2.3",
+    "@types/mocha": "^10.0.10",
     "@types/node": "^20.0.0",
     "@types/react": "^19.2.7",
+    "chai": "^6.2.2",
+    "mocha": "^11.7.5",
     "react": "^19.2.3",
+    "ts-node": "^10.9.2",
     "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {