@moneydevkit/nextjs 0.16.0-beta.1 → 0.16.0-beta.10

package/README.md

@@ -92,6 +92,195 @@ export default withMdkCheckout({})
 
 You now have a complete Lightning checkout loop: the button creates a session, the dynamic route renders it, and the webhook endpoint signals your Lightning node to claim paid invoices.
 
+## Server-side payouts
+
+Programmatic payouts let your server send sats out to a Lightning destination (BOLT11 invoice, BOLT12 offer, or LNURL / Lightning address) without any user interaction. They must run from a server function (Server Action, route handler, cron, webhook), and the app must have programmatic payouts enabled in the moneydevkit dashboard.
+
+> **Trust:** the destination is whatever your server passes in. There is no end-user confirmation. Always apply your own authorization and business rules first (who is allowed to trigger this, how much, where to).
+
+### Minimal example
+
+```ts
+// app/actions.ts
+'use server'
+
+import { programmaticPayout } from '@moneydevkit/nextjs/server'
+
+export async function sendTip(orderId: string) {
+  const result = await programmaticPayout({
+    amountSats: 10_000,
+    destination: 'lnbc...',     // or 'satoshi@example.com', or 'lno1...'
+    idempotencyKey: orderId,    // pass the SAME value if you ever retry
+  })
+
+  if (result.error) {
+    // See the next section for how to handle this properly.
+    throw new Error(result.error.message)
+  }
+
+  return result.data  // { accepted: true, paymentId, paymentHash }
+}
+```
+
+### About `idempotencyKey`
+
+The key is how moneydevkit dedupes retries. If your code (or a cron, or a Vercel retry) fires the same payout twice with the same key, the second call is a no-op instead of a double-pay.
+
+- **Do** use a stable id from your own database: `orderId`, `withdrawalId`, `userId + payoutDate`, etc.
+- **Don't** generate a fresh `crypto.randomUUID()` on every call. That defeats the whole point and you can double-pay.
+- It's just a string, any length, your choice.
+
+### Full example with error handling
+
+The `result.error` object tells you whether the failure is worth retrying:
+
+- `result.error.retryable === true` - the failure was transient (limits, transient routing, fee issues). Retry the same call with the same `idempotencyKey`.
+- `result.error.retryable === false` - retrying won't help. Fix the input or your config.
+- `result.error.retryable === undefined` - the SDK couldn't classify the failure. Treat as not retryable, log and inspect `result.error`.
+
+```ts
+// app/actions.ts
+'use server'
+
+import { programmaticPayout } from '@moneydevkit/nextjs/server'
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+export async function sendPayout(orderId: string, destination: string) {
+  let attempt = 0
+  while (attempt < 3) {
+    const result = await programmaticPayout({
+      amountSats: 10_000,
+      destination,
+      idempotencyKey: orderId,
+    })
+
+    if (!result.error) {
+      // Note: result.data only confirms the node accepted the payout.
+      // The actual Lightning settlement happens asynchronously - listen
+      // for paymentSent / paymentFailed webhooks to confirm final outcome.
+      return { ok: true as const, paymentId: result.data.paymentId }
+    }
+
+    switch (result.error.reason) {
+      case 'app_scoped_api_key_required':
+        // The API key in MDK_ACCESS_TOKEN is not attached to a specific app.
+        // Copy the API key from your app's page in the Apps dashboard.
+        return { ok: false as const, fatal: 'use_the_app_api_key_from_dashboard' }
+
+      case 'programmatic_payouts_disabled':
+        // Toggle is off in the dashboard for this app.
+        return { ok: false as const, fatal: 'enable_programmatic_payouts_in_dashboard' }
+
+      case 'amount_too_large':
+        // Per-request cap. Ask the user for a smaller amount or split.
+        return { ok: false as const, fatal: 'amount_too_large' }
+
+      case 'amount_invalid':
+        // Non-positive or non-integer sat amount.
+        return { ok: false as const, fatal: 'amount_invalid' }
+
+      case 'daily_limit_exceeded':
+        // 24h rolling cap. Surface to the user; don't retry now.
+        return { ok: false as const, fatal: 'come_back_tomorrow' }
+
+      case 'payout_dispatch_failed':
+        // Backend dispatch failed (node offline, transient routing, fees).
+        // The error message has the specific cause. Safe to retry with the
+        // same idempotencyKey.
+        await sleep(1_000 * 2 ** attempt)
+        attempt++
+        continue
+
+      default:
+        // Unknown / unclassified. Don't retry blindly.
+        return {
+          ok: false as const,
+          fatal: 'unknown_error',
+          message: result.error.message,
+          code: result.error.code,
+        }
+    }
+  }
+
+  return { ok: false as const, fatal: 'retries_exhausted' }
+}
+```
+
+### Common gotchas
+
+- **Don't call from client code.** `programmaticPayout` checks for `window` and refuses to run in a browser. It only works in Server Actions, route handlers (`app/api/...`), cron jobs, or webhook receivers.
+- **Set `MDK_ACCESS_TOKEN`.** Same env var as the rest of the SDK. If missing, you get `missing_access_token` (not retryable).
+- **Always pass the same `idempotencyKey` on retry.** If you change it, moneydevkit treats it as a new payout and may charge you twice.
+
+### Error reference
+
+`result.error.reason` is a short machine-readable string. Use it for branching; use `result.error.message` for logs.
+
+| `reason`                          | `retryable` | What it means                                                              |
+|-----------------------------------|-------------|----------------------------------------------------------------------------|
+| `app_scoped_api_key_required`     | false       | The API key in `MDK_ACCESS_TOKEN` isn't tied to a specific app. Copy the key from the app's page in the Apps dashboard |
+| `programmatic_payouts_disabled`   | false       | Toggle is off in dashboard for this app                                    |
+| `amount_too_large`                | false       | Above per-request cap                                                      |
+| `amount_invalid`                  | false       | Backend rejected the amount (non-positive or non-integer sats)             |
+| `daily_limit_exceeded`            | true        | 24h rolling cap hit; retry tomorrow                                        |
+| `payout_dispatch_failed`          | true        | Backend dispatch failed (node offline, transient routing, fee issues). Inspect `error.message` for the specific cause; safe to retry with the same `idempotencyKey` |
+| _(undefined)_                     | _(undefined)_ | New / unknown backend code. Log `error.code` and don't retry blindly     |
+
+Also returned for client-side validation issues (always `retryable: false`):
+
+| `code`                      | When                                                       |
+|-----------------------------|------------------------------------------------------------|
+| `server_only`               | Called from a browser runtime                              |
+| `invalid_amount`            | `amountSats` is not a positive integer                     |
+| `invalid_destination`       | Empty, too long, or contains control characters            |
+| `invalid_idempotency_key`   | Empty / missing                                            |
+| `missing_access_token`      | `MDK_ACCESS_TOKEN` not set                                 |
+
+## Reading the merchant balance from a Server Action
+
+`getBalance()` reads the spendable (outbound) balance of the Lightning node tied to your `MDK_ACCESS_TOKEN`. Same server-only constraints as `programmaticPayout`: the helper refuses to run in a browser and routes through mdk.com over HTTPS, which in turn dials the merchant node over the WS control plane.
+
+```ts
+// app/actions.ts
+'use server'
+
+import { getBalance } from '@moneydevkit/nextjs/server'
+
+export async function fetchBalance() {
+  const result = await getBalance()
+
+  if (result.error) {
+    // retryable === true: transient (merchant function spinning up).
+    // retryable === false: terminal (invalid key, legacy org-level key, banned, or
+    // procedure-not-found from a pre-0.1.30 merchant / older mdk.com).
+    throw new Error(result.error.message)
+  }
+
+  return result.data.balanceSats // number, in sats
+}
+```
+
+### Notes
+
+- **App-scoped API key required.** Balance is meaningful per-app, not per-org. Legacy org-level keys return `GET_BALANCE_APP_KEY_REQUIRED` (not retryable). Use the API key from the App page in the dashboard.
+- **First call may take a few seconds.** If the merchant function is cold, mdk.com fires a spin-up webhook and waits for the WS to register. Subsequent calls within the function's lifetime are fast.
+- **Server-only.** Same `typeof window` check as `programmaticPayout`. Don't call from client components.
+- **Idempotent.** Safe to retry. Transient errors are flagged `retryable: true`; auth, app-scope, and procedure-not-found errors are `retryable: false`.
+
+### Error reference
+
+| `code`                            | `retryable` | What it means                                                  |
+|-----------------------------------|-------------|----------------------------------------------------------------|
+| `server_only`                     | false       | Called from a browser runtime                                  |
+| `missing_access_token`            | false       | `MDK_ACCESS_TOKEN` not set                                     |
+| `GET_BALANCE_APP_KEY_REQUIRED`    | false       | Using a legacy org-level key. Copy the key from the App page   |
+| `UNAUTHORIZED` / `FORBIDDEN`      | false       | Invalid API key or banned user                                 |
+| `NOT_FOUND`                       | false       | Procedure missing - pre-0.1.30 merchant SDK or older mdk.com   |
+| `BAD_REQUEST`                     | false       | Server rejected the request as malformed                       |
+| `GET_BALANCE_SPIN_UP_TIMEOUT`     | true        | Merchant function did not register WS in time. Safe to retry   |
+| `get_balance_failed`              | true        | Network / unclassified error                                   |
+
 ## Customer Data
 Collect and store customer information with each checkout. Pass `customer` to pre-fill data and `requireCustomerData` to prompt the user for specific fields:
 
@@ -450,4 +639,4 @@ If your handler returns without calling `settle()` (e.g. it throws or the servic
 | 500 | `pricing_error` | Dynamic pricing function threw an error |
 | 502 | `checkout_creation_failed` | Failed to create the checkout or invoice |
 
-> **Note:** A 402 is only returned when no L402/LSAT authorization header is present. If the header is present but malformed or invalid, you get a 401 - not a new invoice.
+> **Note:** A 402 is only returned when no L402/LSAT authorization header is present. If the header is present but malformed or invalid, you get a 401 - not a new invoice.

package/dist/server/index.d.ts

@@ -1,4 +1,7 @@
 export { createCheckoutUrl } from '@moneydevkit/core/route';
 export type { CreateCheckoutUrlOptions } from '@moneydevkit/core/route';
+export { programmaticPayout } from '@moneydevkit/core/server';
+export type { ProgrammaticPayoutOptions } from '@moneydevkit/core/server';
+export { getBalance } from '@moneydevkit/core/server';
 export { withPayment, withDeferredSettlement } from '@moneydevkit/core/mdk402';
 export type { PaymentConfig, SettleResult } from '@moneydevkit/core/mdk402';

package/dist/server/index.js

@@ -1,3 +1,5 @@
 export { createCheckoutUrl } from '@moneydevkit/core/route';
+export { programmaticPayout } from '@moneydevkit/core/server';
+export { getBalance } from '@moneydevkit/core/server';
 export { withPayment, withDeferredSettlement } from '@moneydevkit/core/mdk402';
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAG3D,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAE3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAE7D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAErD,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moneydevkit/nextjs",
-  "version": "0.16.0-beta.1",
+  "version": "0.16.0-beta.10",
   "title": "@moneydevkit/nextjs",
   "description": "moneydevkit checkout components for Next.js.",
   "repository": {
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@hookform/resolvers": "^5.0.1",
-    "@moneydevkit/lightning-js": "0.1.81",
+    "@moneydevkit/lightning-js": "0.1.82",
     "@orpc/client": "1.13.6",
     "@orpc/contract": "1.3.0",
     "@radix-ui/react-collapsible": "^1.1.11",
@@ -63,8 +63,8 @@
     "tailwind-merge": "^3.3.0",
     "vaul": "^1.1.2",
     "zod": "^3.25.42",
-    "@moneydevkit/api-contract": "0.1.24",
-    "@moneydevkit/core": "0.16.0-beta.1"
+    "@moneydevkit/api-contract": "0.1.31",
+    "@moneydevkit/core": "0.16.0-beta.10"
   },
   "devDependencies": {
     "@types/node": "^20.10.5",