@settlr/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Settlr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,510 @@
+# @settlr/sdk
+
+> Solana USDC payments in 7 lines of code
+
+## 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.
+
+### 2. Create a Payment Link
+
+```typescript
+import { Settlr } from "@settlr/sdk";
+
+const settlr = new Settlr({
+  apiKey: "sk_live_xxxxxxxxxxxx", // Your API key
+  merchant: {
+    name: "My Store",
+    walletAddress: "YOUR_SOLANA_WALLET_ADDRESS",
+  },
+});
+
+const payment = await settlr.createPayment({
+  amount: 29.99,
+  memo: "Premium subscription",
+});
+
+// Redirect customer to checkout
+window.location.href = payment.checkoutUrl;
+```
+
+### 3. Drop-in Buy Button ⭐ NEW
+
+The easiest way to accept payments - just drop in a button:
+
+```tsx
+import { SettlrProvider, BuyButton } from "@settlr/sdk";
+
+function App() {
+  return (
+    <SettlrProvider
+      config={{
+        apiKey: "sk_live_xxxxxxxxxxxx",
+        merchant: { name: "GameStore", walletAddress: "YOUR_WALLET" },
+      }}
+    >
+      <BuyButton
+        amount={49.99}
+        memo="Premium Game Bundle"
+        onSuccess={(result) => {
+          console.log("Payment successful!", result.signature);
+          unlockContent();
+        }}
+      >
+        Buy Now - $49.99
+      </BuyButton>
+    </SettlrProvider>
+  );
+}
+```
+
+### 4. Checkout Widget ⭐ NEW
+
+Full embeddable checkout with product info:
+
+```tsx
+import { CheckoutWidget } from "@settlr/sdk";
+
+<CheckoutWidget
+  amount={149.99}
+  productName="Annual Subscription"
+  productDescription="Full access to all premium features"
+  productImage="/subscription.png"
+  onSuccess={(result) => router.push("/success")}
+  onError={(error) => console.error(error)}
+/>;
+```
+
+### Direct Payment (with wallet adapter)
+
+```typescript
+import { Settlr } from "@settlr/sdk";
+import { useWallet } from "@solana/wallet-adapter-react";
+
+const settlr = new Settlr({
+  apiKey: "sk_live_xxxxxxxxxxxx",
+  merchant: {
+    name: "My Store",
+    walletAddress: "YOUR_WALLET",
+  },
+});
+
+// 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);
+}
+```
+
+### 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>
+  );
+}
+
+// In your component
+function CheckoutButton() {
+  const { pay, connected } = useSettlr();
+
+  return (
+    <button onClick={() => pay({ amount: 29.99 })} disabled={!connected}>
+      Pay $29.99
+    </button>
+  );
+}
+```
+
+### Payment Link Generator Hook ⭐ NEW
+
+Generate shareable payment links programmatically:
+
+```tsx
+import { usePaymentLink } from "@settlr/sdk";
+
+function InvoicePage() {
+  const { generateLink, generateQRCode } = usePaymentLink({
+    merchantWallet: "YOUR_WALLET",
+    merchantName: "My Store",
+  });
+
+  const link = generateLink({
+    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
+}
+```
+
+## React Components
+
+### `<BuyButton>`
+
+Drop-in payment button component.
+
+```tsx
+<BuyButton
+  amount={49.99} // Required: amount in USDC
+  memo="Order description" // Optional
+  orderId="order_123" // Optional: your order ID
+  onSuccess={(result) => {}} // Called on successful payment
+  onError={(error) => {}} // Called on payment failure
+  onProcessing={() => {}} // Called when payment starts
+  useRedirect={false} // Use redirect flow instead of direct payment
+  successUrl="https://..." // Redirect URL (if useRedirect=true)
+  cancelUrl="https://..." // Cancel URL (if useRedirect=true)
+  variant="primary" // "primary" | "secondary" | "outline"
+  size="md" // "sm" | "md" | "lg"
+  disabled={false}
+  className=""
+  style={{}}
+>
+  Buy Now - $49.99
+</BuyButton>
+```
+
+### `<CheckoutWidget>`
+
+Full checkout UI component with product info.
+
+```tsx
+<CheckoutWidget
+  amount={149.99} // Required
+  productName="Annual Subscription" // Required
+  productDescription="Description" // Optional
+  productImage="/image.png" // Optional
+  merchantName="My Store" // Optional (uses config)
+  memo="Transaction memo" // Optional
+  orderId="order_123" // Optional
+  onSuccess={(result) => {}} // Called on success
+  onError={(error) => {}} // Called on error
+  onCancel={() => {}} // Called on cancel
+  theme="dark" // "dark" | "light"
+  showBranding={true} // Show "Powered by Settlr"
+  className=""
+  style={{}}
+/>
+```
+
+## API Keys
+
+### Types of Keys
+
+| Key Type | Prefix     | Use Case                            |
+| -------- | ---------- | ----------------------------------- |
+| Live     | `sk_live_` | Production payments                 |
+| Test     | `sk_test_` | Development/testing (no validation) |
+
+### Rate Limits
+
+| Tier       | Requests/min | Platform Fee |
+| ---------- | ------------ | ------------ |
+| Free       | 60           | 2%           |
+| Pro        | 300          | 1.5%         |
+| Enterprise | 1000         | 1%           |
+
+### Get Your API Key
+
+1. Go to [settlr.dev/dashboard](https://settlr.dev/dashboard)
+2. Connect your wallet
+3. Click "Create API Key"
+4. Save the key securely (only shown once!)
+
+## API Reference
+
+### `Settlr`
+
+Main client class.
+
+#### Constructor Options
+
+```typescript
+interface SettlrConfig {
+  merchant: {
+    name: string;
+    walletAddress: string;
+    logoUrl?: string;
+    webhookUrl?: string;
+  };
+  network?: "devnet" | "mainnet-beta"; // default: 'devnet'
+  rpcEndpoint?: string;
+  testMode?: boolean;
+}
+```
+
+#### Methods
+
+##### `createPayment(options)`
+
+Create a payment link.
+
+```typescript
+const payment = await settlr.createPayment({
+  amount: 29.99,           // Required: amount in USDC
+  memo: 'Order #123',      // Optional: description
+  orderId: 'order_123',    // Optional: your order ID
+  successUrl: 'https://...',  // Optional: redirect after success
+  cancelUrl: 'https://...',   // Optional: redirect on cancel
+  expiresIn: 3600,         // Optional: expiry in seconds (default: 1 hour)
+});
+
+// Returns
+{
+  id: 'pay_abc123',
+  amount: 29.99,
+  status: 'pending',
+  checkoutUrl: 'https://settlr.dev/pay?...',
+  qrCode: 'data:image/svg+xml,...',
+  createdAt: Date,
+  expiresAt: Date,
+}
+```
+
+##### `buildTransaction(options)`
+
+Build a transaction for signing.
+
+```typescript
+const tx = await settlr.buildTransaction({
+  payerPublicKey: wallet.publicKey,
+  amount: 29.99,
+  memo: "Order #123",
+});
+
+// Sign and send
+const signature = await wallet.sendTransaction(tx, connection);
+```
+
+##### `pay(options)`
+
+Execute a direct payment.
+
+```typescript
+const result = await settlr.pay({
+  wallet: {
+    publicKey: wallet.publicKey,
+    signTransaction: wallet.signTransaction,
+  },
+  amount: 29.99,
+  memo: 'Order #123',
+});
+
+// Returns
+{
+  success: true,
+  signature: '5KtP...',
+  amount: 29.99,
+  merchantAddress: '...',
+}
+```
+
+##### `getPaymentStatus(signature)`
+
+Check payment status.
+
+```typescript
+const status = await settlr.getPaymentStatus("5KtP...");
+// Returns: 'pending' | 'completed' | 'failed'
+```
+
+##### `createCheckoutSession(options)` ⭐ NEW
+
+Create a hosted checkout session (like Stripe Checkout).
+
+```typescript
+const session = await settlr.createCheckoutSession({
+  amount: 29.99,
+  description: 'Premium Plan',
+  successUrl: 'https://mystore.com/success?session_id={CHECKOUT_SESSION_ID}',
+  cancelUrl: 'https://mystore.com/cancel',
+  webhookUrl: 'https://mystore.com/api/webhooks/settlr', // Optional
+  metadata: { orderId: 'order_123' }, // Optional
+});
+
+// Redirect to hosted checkout
+window.location.href = session.url;
+
+// Returns
+{
+  id: 'cs_abc123...',
+  url: 'https://settlr.dev/checkout/cs_abc123...',
+  expiresAt: 1702659600000, // 30 min expiry
+}
+```
+
+## Webhooks ⭐ UPDATED
+
+Get notified when payments complete to fulfill orders automatically.
+
+### Quick Setup (Next.js)
+
+```typescript
+// app/api/webhooks/settlr/route.ts
+import { createWebhookHandler } from "@settlr/sdk";
+
+export const POST = createWebhookHandler({
+  secret: process.env.SETTLR_WEBHOOK_SECRET!,
+  handlers: {
+    "payment.completed": async (event) => {
+      console.log("Payment completed!", event.payment.id);
+      await fulfillOrder(event.payment.orderId);
+      await sendConfirmationEmail(event.payment);
+    },
+    "payment.failed": async (event) => {
+      await notifyCustomer(event.payment.orderId);
+    },
+  },
+});
+```
+
+### Express.js
+
+```typescript
+import express from "express";
+import { createWebhookHandler } from "@settlr/sdk";
+
+const app = express();
+
+app.post(
+  "/webhooks/settlr",
+  express.raw({ type: "application/json" }),
+  createWebhookHandler({
+    secret: process.env.SETTLR_WEBHOOK_SECRET!,
+    handlers: {
+      "payment.completed": async (event) => {
+        await fulfillOrder(event.payment.orderId);
+      },
+    },
+  })
+);
+```
+
+### Manual Verification
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from "@settlr/sdk";
+
+export async function POST(request: Request) {
+  const signature = request.headers.get("x-settlr-signature")!;
+  const body = await request.text();
+
+  // Verify signature
+  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET!)) {
+    return new Response("Invalid signature", { status: 401 });
+  }
+
+  const event = JSON.parse(body);
+
+  if (event.type === "payment.completed") {
+    await fulfillOrder(event.payment.orderId);
+  }
+
+  return new Response("OK", { status: 200 });
+}
+```
+
+### Webhook Events
+
+| Event               | Description                |
+| ------------------- | -------------------------- |
+| `payment.created`   | Payment link was created   |
+| `payment.completed` | Payment confirmed on-chain |
+| `payment.failed`    | Payment failed             |
+| `payment.expired`   | Payment link expired       |
+| `payment.refunded`  | Payment was refunded       |
+
+### Webhook Payload
+
+```json
+{
+  "id": "evt_abc123",
+  "type": "payment.completed",
+  "payment": {
+    "id": "pay_xyz789",
+    "amount": 29.99,
+    "status": "completed",
+    "orderId": "order_123",
+    "memo": "Premium subscription",
+    "txSignature": "5KtP...",
+    "payerAddress": "7xKX...3mPq",
+    "merchantAddress": "4dGo...7Ywd"
+  },
+  "timestamp": "2025-12-17T10:30:00.000Z",
+  "signature": "hmac_sha256_signature"
+}
+```
+
+##### `getMerchantBalance()`
+
+Get merchant's USDC balance.
+
+```typescript
+const balance = await settlr.getMerchantBalance();
+console.log(`Balance: $${balance} USDC`);
+```
+
+### Utilities
+
+```typescript
+import { formatUSDC, parseUSDC, shortenAddress } from "@settlr/sdk";
+
+formatUSDC(29990000n); // "29.99"
+parseUSDC(29.99); // 29990000n
+shortenAddress("ABC...XYZ"); // "ABC...XYZ"
+```
+
+## Networks
+
+| Network | USDC Mint                                      |
+| ------- | ---------------------------------------------- |
+| Devnet  | `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU` |
+| Mainnet | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
+
+## License
+
+MIT