@lnbot/l402 0.1.0

package/README.md

@@ -0,0 +1,309 @@
+# @lnbot/l402
+
+[![npm version](https://img.shields.io/npm/v/@lnbot/l402)](https://www.npmjs.com/package/@lnbot/l402)
+[![npm downloads](https://img.shields.io/npm/dm/@lnbot/l402)](https://www.npmjs.com/package/@lnbot/l402)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@lnbot/l402)](https://bundlephobia.com/package/@lnbot/l402)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+**L402 payment middleware for Express.js** — paywall any API in one line. Built on [ln.bot](https://ln.bot).
+
+Add Lightning-powered pay-per-request to any Express API. Protect premium routes with a paywall, or build clients that auto-pay L402-protected services — all without touching any cryptography.
+
+```typescript
+import express from "express";
+import { l402, LnBot } from "@lnbot/l402";
+
+const app = express();
+const ln = new LnBot({ apiKey: "key_..." });
+
+app.use("/api/premium", l402.paywall(ln, { price: 10 }));
+
+app.get("/api/premium/data", (req, res) => {
+  res.json({ data: "premium content" });
+});
+```
+
+> This package is a thin glue layer. All L402 logic — macaroon creation, signature verification, preimage checking — lives in the [ln.bot API](https://ln.bot/docs) via [`@lnbot/sdk`](https://www.npmjs.com/package/@lnbot/sdk). Zero crypto dependencies.
+
+---
+
+## What is L402?
+
+[L402](https://github.com/lightninglabs/L402) is a protocol built on HTTP `402 Payment Required`. It enables machine-to-machine micropayments over the Lightning Network:
+
+1. **Client** requests a protected resource
+2. **Server** returns `402` with a Lightning invoice and a macaroon token
+3. **Client** pays the invoice, obtains the preimage as proof of payment
+4. **Client** retries the request with `Authorization: L402 <macaroon>:<preimage>`
+5. **Server** verifies the token and grants access
+
+L402 is ideal for API monetization, AI agent tool access, pay-per-request data feeds, and any scenario where you want instant, permissionless, per-request payments without subscriptions or API key provisioning.
+
+---
+
+## Install
+
+```bash
+npm install @lnbot/l402
+```
+
+```bash
+pnpm add @lnbot/l402
+```
+
+```bash
+yarn add @lnbot/l402
+```
+
+`@lnbot/sdk` and `express` are peer dependencies and will be resolved automatically.
+
+---
+
+## Server — Protect Routes with L402
+
+The `l402.paywall()` middleware intercepts requests, verifies L402 tokens via the SDK, and issues new challenges when payment is needed. Two SDK calls, ~40 lines of glue code, zero crypto.
+
+```typescript
+import express from "express";
+import { l402, LnBot } from "@lnbot/l402";
+
+const app = express();
+const ln = new LnBot({ apiKey: "key_..." });
+
+// Paywall a route group — 10 sats per request
+app.use("/api/premium", l402.paywall(ln, {
+  price: 10,
+  description: "API access",
+}));
+
+app.get("/api/premium/data", (req, res) => {
+  // req.l402 is populated after successful payment verification
+  res.json({
+    data: "premium content",
+    paymentHash: req.l402?.paymentHash,
+  });
+});
+
+// Free routes still work normally
+app.get("/api/free/health", (req, res) => {
+  res.json({ status: "ok" });
+});
+
+app.listen(3000);
+```
+
+### How the middleware works
+
+1. Checks for an `Authorization: L402 ...` header
+2. If present, calls `ln.l402.verify()` — the SDK checks signature, preimage, and caveats server-side
+3. If valid, populates `req.l402` and calls `next()`
+4. If missing or invalid, calls `ln.l402.createChallenge()` and returns a `402` response with the invoice and macaroon
+
+### Dynamic pricing
+
+```typescript
+// Fixed price per route
+app.use("/api/cheap", l402.paywall(ln, { price: 1 }));
+app.use("/api/expensive", l402.paywall(ln, { price: 100 }));
+
+// Custom pricing function — receives the request, returns price in sats
+app.use("/api/dynamic", l402.paywall(ln, {
+  price: (req) => {
+    if (req.path.includes("/bulk")) return 50;
+    return 5;
+  },
+}));
+```
+
+### Paywall options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `price` | `number \| (req) => number` | Price in satoshis — fixed or per-request |
+| `description` | `string` | Invoice memo shown in wallets |
+| `expirySeconds` | `number` | Challenge expiry in seconds |
+| `caveats` | `string[]` | Macaroon caveats to attach |
+
+---
+
+## Client — Auto-Pay L402 APIs
+
+The `l402.client()` wrapper makes L402 payment transparent. It detects `402` responses, pays the Lightning invoice via the SDK, caches the token, and retries — all in one `fetch` call.
+
+```typescript
+import { l402, LnBot } from "@lnbot/l402";
+
+const ln = new LnBot({ apiKey: "key_..." });
+
+const client = l402.client(ln, {
+  maxPrice: 100,         // refuse to pay more than 100 sats per request
+  budgetSats: 50000,     // spending limit for the period
+  budgetPeriod: "day",   // reset period: "hour" | "day" | "week" | "month"
+  store: "memory",       // token cache: "memory" (default) | "none" | custom TokenStore
+});
+
+// Use like fetch — L402 payment is transparent
+const response = await client.fetch("https://api.example.com/premium/data");
+const data = await response.json();
+
+// Convenience methods
+const json = await client.get("https://api.example.com/premium/data");
+const result = await client.post("https://api.example.com/premium/submit", {
+  body: JSON.stringify({ query: "test" }),
+});
+```
+
+### How the client works
+
+1. Checks the token cache for a valid credential
+2. If cached, sends the request with the `Authorization` header
+3. If no cache (or server rejects), makes a plain request
+4. On `402`, parses the challenge and checks budget limits
+5. Calls `ln.l402.pay()` — the SDK pays the invoice and returns a ready-to-use token
+6. Caches the token and retries the request with authorization
+
+### Client options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxPrice` | `number` | `1000` | Max sats to pay for a single request |
+| `budgetSats` | `number` | unlimited | Total budget in sats for the period |
+| `budgetPeriod` | `string` | — | Reset period: `"hour"`, `"day"`, `"week"`, `"month"` |
+| `store` | `string \| TokenStore` | `"memory"` | Token cache: `"memory"`, `"none"`, or custom |
+
+### Custom token store
+
+Implement the `TokenStore` interface for Redis, file system, or any persistence layer:
+
+```typescript
+import { l402, LnBot } from "@lnbot/l402";
+import type { TokenStore } from "@lnbot/l402";
+
+const ln = new LnBot({ apiKey: "key_..." });
+
+const redisStore: TokenStore = {
+  async get(url) { /* read from Redis */ },
+  async set(url, token) { /* write to Redis */ },
+  async delete(url) { /* delete from Redis */ },
+};
+
+const client = l402.client(ln, { store: redisStore });
+```
+
+---
+
+## Header Utilities
+
+Parse and format L402 headers for custom integrations:
+
+```typescript
+import { l402 } from "@lnbot/l402";
+
+// Parse Authorization: L402 <macaroon>:<preimage>
+l402.parseAuthorization("L402 mac_base64:preimage_hex");
+// → { macaroon: "mac_base64", preimage: "preimage_hex" }
+
+// Parse WWW-Authenticate: L402 macaroon="...", invoice="..."
+l402.parseChallenge('L402 macaroon="abc", invoice="lnbc1..."');
+// → { macaroon: "abc", invoice: "lnbc1..." }
+
+// Format headers
+l402.formatAuthorization("mac_base64", "preimage_hex");
+// → "L402 mac_base64:preimage_hex"
+
+l402.formatChallenge("abc", "lnbc1...");
+// → 'L402 macaroon="abc", invoice="lnbc1..."'
+```
+
+---
+
+## Error Handling
+
+```typescript
+import { L402Error, L402BudgetExceededError, L402PaymentFailedError } from "@lnbot/l402";
+
+try {
+  const data = await client.get("https://api.example.com/expensive");
+} catch (err) {
+  if (err instanceof L402BudgetExceededError) {
+    // Price exceeds maxPrice or total budget exhausted
+  } else if (err instanceof L402PaymentFailedError) {
+    // Lightning payment failed or didn't settle
+  } else if (err instanceof L402Error) {
+    // Other L402 protocol error (missing header, parse failure)
+  }
+}
+```
+
+---
+
+## API Reference
+
+### Server
+
+| Export | Description |
+| --- | --- |
+| `l402.paywall(ln, options)` | Express middleware factory — protects routes behind an L402 paywall |
+
+### Client
+
+| Export | Description |
+| --- | --- |
+| `l402.client(ln, options?)` | Creates an L402-aware HTTP client with automatic payment |
+
+### Header Utilities
+
+| Export | Description |
+| --- | --- |
+| `l402.parseAuthorization(header)` | Parse `Authorization: L402 ...` into `{ macaroon, preimage }` |
+| `l402.parseChallenge(header)` | Parse `WWW-Authenticate: L402 ...` into `{ macaroon, invoice }` |
+| `l402.formatAuthorization(macaroon, preimage)` | Format an `Authorization` header value |
+| `l402.formatChallenge(macaroon, invoice)` | Format a `WWW-Authenticate` header value |
+
+### Types
+
+| Type | Description |
+| --- | --- |
+| `L402PaywallOptions` | Options for `l402.paywall()` |
+| `L402ClientOptions` | Options for `l402.client()` |
+| `L402Token` | Cached L402 credential (macaroon + preimage + metadata) |
+| `TokenStore` | Interface for custom token caches |
+| `L402RequestData` | Data attached to `req.l402` after verification |
+
+### Errors
+
+| Class | Description |
+| --- | --- |
+| `L402Error` | Base error for all L402 protocol errors |
+| `L402BudgetExceededError` | Price or cumulative spend exceeds configured limits |
+| `L402PaymentFailedError` | Lightning payment failed or didn't return authorization |
+
+---
+
+## Requirements
+
+- **Node.js 18+**, Bun, or Deno
+- **Express 4+** (server middleware)
+- An [ln.bot](https://ln.bot) API key — [create a wallet](https://ln.bot/docs) to get one
+
+---
+
+## Related packages
+
+- [`@lnbot/sdk`](https://www.npmjs.com/package/@lnbot/sdk) — The TypeScript SDK this package is built on
+- [Python SDK](https://github.com/lnbotdev/python-sdk) · [pypi](https://pypi.org/project/lnbot/)
+- [Go SDK](https://github.com/lnbotdev/go-sdk) · [pkg.go.dev](https://pkg.go.dev/github.com/lnbotdev/go-sdk)
+- [Rust SDK](https://github.com/lnbotdev/rust-sdk) · [crates.io](https://crates.io/crates/lnbot)
+
+## Links
+
+- [ln.bot](https://ln.bot) — website
+- [Documentation](https://ln.bot/docs)
+- [L402 specification](https://github.com/lightninglabs/L402)
+- [GitHub](https://github.com/lnbotdev)
+- [npm](https://www.npmjs.com/package/@lnbot/l402)
+
+## License
+
+MIT

package/dist/client/index.cjs

@@ -0,0 +1,225 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  Budget: () => Budget,
+  MemoryStore: () => MemoryStore,
+  NoStore: () => NoStore,
+  client: () => client,
+  resolveStore: () => resolveStore
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/errors.ts
+var L402Error = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "L402Error";
+  }
+};
+var L402BudgetExceededError = class extends L402Error {
+  constructor(message) {
+    super(message);
+    this.name = "L402BudgetExceededError";
+  }
+};
+var L402PaymentFailedError = class extends L402Error {
+  constructor(message) {
+    super(message);
+    this.name = "L402PaymentFailedError";
+  }
+};
+
+// src/server/headers.ts
+function parseAuthorization(header) {
+  if (!header.startsWith("L402 ")) return null;
+  const token = header.slice(5);
+  const colonIndex = token.lastIndexOf(":");
+  if (colonIndex === -1) return null;
+  return {
+    macaroon: token.slice(0, colonIndex),
+    preimage: token.slice(colonIndex + 1)
+  };
+}
+function parseChallenge(header) {
+  if (!header.startsWith("L402 ")) return null;
+  const macaroonMatch = header.match(/macaroon="([^"]+)"/);
+  const invoiceMatch = header.match(/invoice="([^"]+)"/);
+  if (!macaroonMatch || !invoiceMatch) return null;
+  return { macaroon: macaroonMatch[1], invoice: invoiceMatch[1] };
+}
+
+// src/client/budget.ts
+var PERIOD_MS = {
+  hour: 60 * 60 * 1e3,
+  day: 24 * 60 * 60 * 1e3,
+  week: 7 * 24 * 60 * 60 * 1e3,
+  month: 30 * 24 * 60 * 60 * 1e3
+};
+var Budget = class {
+  spent = 0;
+  periodStart = Date.now();
+  totalSats;
+  periodMs;
+  constructor(options) {
+    this.totalSats = options.budgetSats;
+    if (options.budgetPeriod) {
+      this.periodMs = PERIOD_MS[options.budgetPeriod];
+    }
+  }
+  maybeReset() {
+    if (this.periodMs && Date.now() - this.periodStart >= this.periodMs) {
+      this.spent = 0;
+      this.periodStart = Date.now();
+    }
+  }
+  /** Throws L402BudgetExceededError if spending `price` would exceed the budget. */
+  check(price) {
+    if (this.totalSats === void 0) return;
+    this.maybeReset();
+    if (this.spent + price > this.totalSats) {
+      throw new L402BudgetExceededError(
+        `Payment of ${price} sats would exceed budget (${this.spent}/${this.totalSats} sats spent)`
+      );
+    }
+  }
+  /** Record a successful payment. */
+  record(price) {
+    this.maybeReset();
+    this.spent += price;
+  }
+};
+
+// src/client/store.ts
+function normalizeUrl(url) {
+  try {
+    const u = new URL(url);
+    u.search = "";
+    u.hash = "";
+    return u.toString().replace(/\/+$/, "");
+  } catch {
+    return url;
+  }
+}
+var MemoryStore = class {
+  tokens = /* @__PURE__ */ new Map();
+  async get(url) {
+    return this.tokens.get(normalizeUrl(url)) ?? null;
+  }
+  async set(url, token) {
+    this.tokens.set(normalizeUrl(url), token);
+  }
+  async delete(url) {
+    this.tokens.delete(normalizeUrl(url));
+  }
+};
+var NoStore = class {
+  async get() {
+    return null;
+  }
+  async set() {
+  }
+  async delete() {
+  }
+};
+function resolveStore(store) {
+  if (!store || store === "memory") return new MemoryStore();
+  if (store === "none") return new NoStore();
+  return store;
+}
+
+// src/client/fetch.ts
+function client(ln, options = {}) {
+  const store = resolveStore(options.store);
+  const budget = new Budget(options);
+  const maxPrice = options.maxPrice ?? 1e3;
+  async function l402Fetch(url, init) {
+    const cached = await store.get(url);
+    if (cached) {
+      const isExpired = cached.expiresAt && cached.expiresAt.getTime() <= Date.now();
+      if (!isExpired) {
+        const headers = new Headers(init?.headers);
+        headers.set("Authorization", cached.authorization);
+        const res2 = await globalThis.fetch(url, { ...init, headers });
+        if (res2.status !== 402) return res2;
+        await store.delete(url);
+      } else {
+        await store.delete(url);
+      }
+    }
+    const res = await globalThis.fetch(url, init);
+    if (res.status !== 402) return res;
+    const wwwAuth = res.headers.get("www-authenticate");
+    if (!wwwAuth)
+      throw new L402Error("402 response missing WWW-Authenticate header");
+    const challenge = parseChallenge(wwwAuth);
+    if (!challenge) throw new L402Error("Could not parse L402 challenge");
+    const body = await res.json().catch(() => null);
+    const price = body?.price ?? 0;
+    if (price > maxPrice) {
+      throw new L402Error(
+        `Price ${price} sats exceeds maxPrice ${maxPrice}`
+      );
+    }
+    budget.check(price);
+    const payment = await ln.l402.pay({ wwwAuthenticate: wwwAuth });
+    if (payment.status === "failed") {
+      throw new L402PaymentFailedError("L402 payment failed");
+    }
+    if (!payment.authorization) {
+      throw new L402PaymentFailedError(
+        "Payment did not return authorization token"
+      );
+    }
+    const parsed = parseAuthorization(payment.authorization);
+    await store.set(url, {
+      macaroon: parsed?.macaroon ?? challenge.macaroon,
+      preimage: payment.preimage ?? parsed?.preimage ?? "",
+      authorization: payment.authorization,
+      paidAt: /* @__PURE__ */ new Date(),
+      expiresAt: body?.expiresAt ? new Date(body.expiresAt) : void 0
+    });
+    budget.record(price);
+    const retryHeaders = new Headers(init?.headers);
+    retryHeaders.set("Authorization", payment.authorization);
+    return globalThis.fetch(url, { ...init, headers: retryHeaders });
+  }
+  return {
+    fetch: l402Fetch,
+    async get(url, init) {
+      const res = await l402Fetch(url, { ...init, method: "GET" });
+      return res.json();
+    },
+    async post(url, init) {
+      const res = await l402Fetch(url, { ...init, method: "POST" });
+      return res.json();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Budget,
+  MemoryStore,
+  NoStore,
+  client,
+  resolveStore
+});
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts","../../src/errors.ts","../../src/server/headers.ts","../../src/client/budget.ts","../../src/client/store.ts","../../src/client/fetch.ts"],"sourcesContent":["export { client, type L402Client } from \"./fetch.js\";\nexport { Budget } from \"./budget.js\";\nexport { MemoryStore, NoStore, resolveStore } from \"./store.js\";\n","export class L402Error extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"L402Error\";\n  }\n}\n\nexport class L402BudgetExceededError extends L402Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"L402BudgetExceededError\";\n  }\n}\n\nexport class L402PaymentFailedError extends L402Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"L402PaymentFailedError\";\n  }\n}\n","/** Parse an L402 Authorization header into { macaroon, preimage }. */\nexport function parseAuthorization(\n  header: string,\n): { macaroon: string; preimage: string } | null {\n  if (!header.startsWith(\"L402 \")) return null;\n  const token = header.slice(5);\n  const colonIndex = token.lastIndexOf(\":\");\n  if (colonIndex === -1) return null;\n  return {\n    macaroon: token.slice(0, colonIndex),\n    preimage: token.slice(colonIndex + 1),\n  };\n}\n\n/** Parse a WWW-Authenticate: L402 header into { macaroon, invoice }. */\nexport function parseChallenge(\n  header: string,\n): { macaroon: string; invoice: string } | null {\n  if (!header.startsWith(\"L402 \")) return null;\n  const macaroonMatch = header.match(/macaroon=\"([^\"]+)\"/);\n  const invoiceMatch = header.match(/invoice=\"([^\"]+)\"/);\n  if (!macaroonMatch || !invoiceMatch) return null;\n  return { macaroon: macaroonMatch[1], invoice: invoiceMatch[1] };\n}\n\n/** Format an Authorization header value. */\nexport function formatAuthorization(\n  macaroon: string,\n  preimage: string,\n): string {\n  return `L402 ${macaroon}:${preimage}`;\n}\n\n/** Format a WWW-Authenticate header value. */\nexport function formatChallenge(\n  macaroon: string,\n  invoice: string,\n): string {\n  return `L402 macaroon=\"${macaroon}\", invoice=\"${invoice}\"`;\n}\n","import type { L402ClientOptions } from \"../types.js\";\nimport { L402BudgetExceededError } from \"../errors.js\";\n\nconst PERIOD_MS: Record<string, number> = {\n  hour: 60 * 60 * 1000,\n  day: 24 * 60 * 60 * 1000,\n  week: 7 * 24 * 60 * 60 * 1000,\n  month: 30 * 24 * 60 * 60 * 1000,\n};\n\n/** In-memory budget tracker with periodic resets. */\nexport class Budget {\n  private spent = 0;\n  private periodStart = Date.now();\n  private readonly totalSats: number | undefined;\n  private readonly periodMs: number | undefined;\n\n  constructor(options: L402ClientOptions) {\n    this.totalSats = options.budgetSats;\n    if (options.budgetPeriod) {\n      this.periodMs = PERIOD_MS[options.budgetPeriod];\n    }\n  }\n\n  private maybeReset(): void {\n    if (this.periodMs && Date.now() - this.periodStart >= this.periodMs) {\n      this.spent = 0;\n      this.periodStart = Date.now();\n    }\n  }\n\n  /** Throws L402BudgetExceededError if spending `price` would exceed the budget. */\n  check(price: number): void {\n    if (this.totalSats === undefined) return;\n    this.maybeReset();\n    if (this.spent + price > this.totalSats) {\n      throw new L402BudgetExceededError(\n        `Payment of ${price} sats would exceed budget (${this.spent}/${this.totalSats} sats spent)`,\n      );\n    }\n  }\n\n  /** Record a successful payment. */\n  record(price: number): void {\n    this.maybeReset();\n    this.spent += price;\n  }\n}\n","import type { TokenStore, L402Token } from \"../types.js\";\n\n/** Strip query params, hash, and trailing slashes for consistent cache keys. */\nfunction normalizeUrl(url: string): string {\n  try {\n    const u = new URL(url);\n    u.search = \"\";\n    u.hash = \"\";\n    return u.toString().replace(/\\/+$/, \"\");\n  } catch {\n    return url;\n  }\n}\n\n/** Default in-memory token cache backed by a Map. */\nexport class MemoryStore implements TokenStore {\n  private tokens = new Map<string, L402Token>();\n\n  async get(url: string): Promise<L402Token | null> {\n    return this.tokens.get(normalizeUrl(url)) ?? null;\n  }\n\n  async set(url: string, token: L402Token): Promise<void> {\n    this.tokens.set(normalizeUrl(url), token);\n  }\n\n  async delete(url: string): Promise<void> {\n    this.tokens.delete(normalizeUrl(url));\n  }\n}\n\n/** No-op store — never caches, every request pays fresh. */\nexport class NoStore implements TokenStore {\n  async get(): Promise<null> {\n    return null;\n  }\n  async set(): Promise<void> {}\n  async delete(): Promise<void> {}\n}\n\n/** Resolve the `store` option into a concrete TokenStore. */\nexport function resolveStore(\n  store?: \"memory\" | \"none\" | TokenStore,\n): TokenStore {\n  if (!store || store === \"memory\") return new MemoryStore();\n  if (store === \"none\") return new NoStore();\n  return store;\n}\n","import type { LnBot } from \"@lnbot/sdk\";\nimport type { L402ClientOptions } from \"../types.js\";\nimport {\n  L402Error,\n  L402PaymentFailedError,\n} from \"../errors.js\";\nimport { parseChallenge, parseAuthorization } from \"../server/headers.js\";\nimport { Budget } from \"./budget.js\";\nimport { resolveStore } from \"./store.js\";\n\n/** An L402-aware HTTP client that transparently pays Lightning invoices on 402 responses. */\nexport interface L402Client {\n  /** L402-aware fetch — pays 402 challenges automatically. */\n  fetch(url: string, init?: RequestInit): Promise<Response>;\n  /** GET + JSON parse with automatic L402 payment. */\n  get(url: string, init?: RequestInit): Promise<unknown>;\n  /** POST + JSON parse with automatic L402 payment. */\n  post(url: string, init?: RequestInit): Promise<unknown>;\n}\n\n/**\n * Create an L402-aware HTTP client.\n *\n * One SDK call: `ln.l402.pay()` — pays the invoice and returns the Authorization token.\n */\nexport function client(ln: LnBot, options: L402ClientOptions = {}): L402Client {\n  const store = resolveStore(options.store);\n  const budget = new Budget(options);\n  const maxPrice = options.maxPrice ?? 1000;\n\n  async function l402Fetch(\n    url: string,\n    init?: RequestInit,\n  ): Promise<Response> {\n    // Step 1: Check token cache\n    const cached = await store.get(url);\n    if (cached) {\n      const isExpired =\n        cached.expiresAt && cached.expiresAt.getTime() <= Date.now();\n      if (!isExpired) {\n        const headers = new Headers(init?.headers);\n        headers.set(\"Authorization\", cached.authorization);\n        const res = await globalThis.fetch(url, { ...init, headers });\n        // If the cached token was rejected (expired server-side), fall through\n        if (res.status !== 402) return res;\n        await store.delete(url);\n      } else {\n        await store.delete(url);\n      }\n    }\n\n    // Step 2: Make request without auth\n    const res = await globalThis.fetch(url, init);\n    if (res.status !== 402) return res;\n\n    // Step 3: Parse the 402 challenge\n    const wwwAuth = res.headers.get(\"www-authenticate\");\n    if (!wwwAuth)\n      throw new L402Error(\"402 response missing WWW-Authenticate header\");\n\n    const challenge = parseChallenge(wwwAuth);\n    if (!challenge) throw new L402Error(\"Could not parse L402 challenge\");\n\n    // Parse body for price info\n    const body = await res.json().catch(() => null);\n    const price: number = body?.price ?? 0;\n\n    // Step 4: Budget checks\n    if (price > maxPrice) {\n      throw new L402Error(\n        `Price ${price} sats exceeds maxPrice ${maxPrice}`,\n      );\n    }\n    budget.check(price);\n\n    // Step 5: Pay via SDK\n    const payment = await ln.l402.pay({ wwwAuthenticate: wwwAuth });\n\n    if (payment.status === \"failed\") {\n      throw new L402PaymentFailedError(\"L402 payment failed\");\n    }\n    if (!payment.authorization) {\n      throw new L402PaymentFailedError(\n        \"Payment did not return authorization token\",\n      );\n    }\n\n    // Step 6: Cache the token\n    const parsed = parseAuthorization(payment.authorization);\n    await store.set(url, {\n      macaroon: parsed?.macaroon ?? challenge.macaroon,\n      preimage: payment.preimage ?? parsed?.preimage ?? \"\",\n      authorization: payment.authorization,\n      paidAt: new Date(),\n      expiresAt: body?.expiresAt\n        ? new Date(body.expiresAt)\n        : undefined,\n    });\n\n    budget.record(price);\n\n    // Step 7: Retry with L402 Authorization\n    const retryHeaders = new Headers(init?.headers);\n    retryHeaders.set(\"Authorization\", payment.authorization);\n    return globalThis.fetch(url, { ...init, headers: retryHeaders });\n  }\n\n  return {\n    fetch: l402Fetch,\n    async get(url: string, init?: RequestInit) {\n      const res = await l402Fetch(url, { ...init, method: \"GET\" });\n      return res.json();\n    },\n    async post(url: string, init?: RequestInit) {\n      const res = await l402Fetch(url, { ...init, method: \"POST\" });\n      return res.json();\n    },\n  };\n}\n"],"mappings":"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","names":["res"]}

package/dist/client/index.d.cts

@@ -0,0 +1,36 @@
+export { L as L402Client, c as client } from '../fetch-B0tuycqO.cjs';
+import { L as L402ClientOptions, T as TokenStore, c as L402Token } from '../types-FRMMn5ej.cjs';
+import '@lnbot/sdk';
+import 'express';
+
+/** In-memory budget tracker with periodic resets. */
+declare class Budget {
+    private spent;
+    private periodStart;
+    private readonly totalSats;
+    private readonly periodMs;
+    constructor(options: L402ClientOptions);
+    private maybeReset;
+    /** Throws L402BudgetExceededError if spending `price` would exceed the budget. */
+    check(price: number): void;
+    /** Record a successful payment. */
+    record(price: number): void;
+}
+
+/** Default in-memory token cache backed by a Map. */
+declare class MemoryStore implements TokenStore {
+    private tokens;
+    get(url: string): Promise<L402Token | null>;
+    set(url: string, token: L402Token): Promise<void>;
+    delete(url: string): Promise<void>;
+}
+/** No-op store — never caches, every request pays fresh. */
+declare class NoStore implements TokenStore {
+    get(): Promise<null>;
+    set(): Promise<void>;
+    delete(): Promise<void>;
+}
+/** Resolve the `store` option into a concrete TokenStore. */
+declare function resolveStore(store?: "memory" | "none" | TokenStore): TokenStore;
+
+export { Budget, MemoryStore, NoStore, resolveStore };

package/dist/client/index.d.ts

@@ -0,0 +1,36 @@
+export { L as L402Client, c as client } from '../fetch-BPQpEg8M.js';
+import { L as L402ClientOptions, T as TokenStore, c as L402Token } from '../types-FRMMn5ej.js';
+import '@lnbot/sdk';
+import 'express';
+
+/** In-memory budget tracker with periodic resets. */
+declare class Budget {
+    private spent;
+    private periodStart;
+    private readonly totalSats;
+    private readonly periodMs;
+    constructor(options: L402ClientOptions);
+    private maybeReset;
+    /** Throws L402BudgetExceededError if spending `price` would exceed the budget. */
+    check(price: number): void;
+    /** Record a successful payment. */
+    record(price: number): void;
+}
+
+/** Default in-memory token cache backed by a Map. */
+declare class MemoryStore implements TokenStore {
+    private tokens;
+    get(url: string): Promise<L402Token | null>;
+    set(url: string, token: L402Token): Promise<void>;
+    delete(url: string): Promise<void>;
+}
+/** No-op store — never caches, every request pays fresh. */
+declare class NoStore implements TokenStore {
+    get(): Promise<null>;
+    set(): Promise<void>;
+    delete(): Promise<void>;
+}
+/** Resolve the `store` option into a concrete TokenStore. */
+declare function resolveStore(store?: "memory" | "none" | TokenStore): TokenStore;
+
+export { Budget, MemoryStore, NoStore, resolveStore };