l402-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 refined-element
+
+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,133 @@
+# l402-server
+
+[![npm](https://img.shields.io/npm/v/l402-server.svg)](https://www.npmjs.com/package/l402-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**L402 server SDK for Node.** Mint Lightning invoices and macaroons. Verify L402 tokens. Wrap any HTTP API with pay-per-request Lightning payments — one `npm install`, two methods.
+
+This is the **producer-side** companion to [`l402-requests`](https://www.npmjs.com/package/l402-requests) (the consumer-side auto-paying HTTP client). Use `l402-requests` to *call* paid APIs from agents. Use `l402-server` to *build* paid APIs that those agents pay for.
+
+## What you're paying for
+
+`l402-server` is a thin TypeScript wrapper around [Lightning Enable](https://lightningenable.com)'s hosted producer API. The protocol-heavy work — invoice minting, macaroon signing, preimage verification, replay protection, wallet integration (Strike / OpenNode / LND / NWC) — all runs on Lightning Enable's side. The SDK is ~200 lines of HTTP-client glue.
+
+**Requires a Lightning Enable merchant API key** and an Agentic Commerce subscription ($99/mo Individual or $299/mo Business). Get both at [lightningenable.com/dashboard](https://api.lightningenable.com/dashboard).
+
+## Install
+
+```bash
+npm install l402-server
+```
+
+Node 18+. ESM + CJS dual exports. TypeScript types included.
+
+## Quick start
+
+```ts
+import { L402Server } from "l402-server";
+
+const l402 = new L402Server({
+  apiKey: process.env.LIGHTNING_ENABLE_API_KEY!,
+});
+
+// 1. On an unauthenticated incoming request, mint a challenge:
+const challenge = await l402.createChallenge({
+  resource: "/api/premium/weather",
+  priceSats: 100,
+  description: "Premium weather forecast",
+});
+// → { invoice: "lnbc100n1...", macaroon: "AgEL...", paymentHash: "...", expiresAt, ... }
+
+// Send back as 402 Payment Required with the macaroon + invoice in headers.
+// (Use a framework middleware on top of this SDK to automate that step.)
+
+// 2. When the client retries with Authorization: L402 <macaroon>:<preimage>,
+// parse the header and verify:
+const result = await l402.verifyToken({
+  macaroon: parsedMacaroon,
+  preimage: parsedPreimage,
+});
+
+if (result.valid) {
+  // result.resource → which path the token is bound to
+  // result.amountSats → how much was paid
+  // Serve your real response.
+}
+```
+
+## Surface
+
+### `new L402Server(options)`
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `apiKey` | `string` | **required** | Your Lightning Enable merchant API key |
+| `baseUrl` | `string` | `https://api.lightningenable.com` | Override for testing |
+| `timeoutMs` | `number` | `10000` | Per-request timeout |
+| `fetch` | `typeof fetch` | global `fetch` | Inject for tests / retries |
+
+### `createChallenge(args)` → `Promise<Challenge>`
+
+```ts
+{
+  resource: string;       // bound as a macaroon caveat
+  priceSats: number;      // ≥ 1
+  description?: string;   // shown in payer's wallet
+  idempotencyKey?: string; // optional; falls back to client IP
+}
+```
+
+Returns: `{ invoice, macaroon, paymentHash, expiresAt, resource, priceSats, mppChallenge? }`.
+
+### `verifyToken(args)` → `Promise<VerificationResult>`
+
+```ts
+{
+  macaroon?: string;  // required for L402; omit only for MPP
+  preimage: string;
+}
+```
+
+Returns: `{ valid, error?, resource?, merchantId?, amountSats?, paymentHash? }`. Inspect `result.valid` — the producer API returns 200 OK for both valid and invalid tokens.
+
+### Errors
+
+All SDK errors extend `L402ServerError`:
+
+| Class | When |
+|---|---|
+| `L402AuthError` | 401 — API key missing / invalid / revoked |
+| `L402PlanError` | 403 — L402 not enabled on merchant's plan (surfaces `currentPlan`) |
+| `L402ApiError` | Other non-2xx (400 / 429 / 5xx); surfaces `statusCode` + `responseBody` |
+| `L402NetworkError` | Timeout, DNS, TLS, transport failure (surfaces `cause`) |
+
+## Two integration modes
+
+Lightning Enable supports two integration shapes:
+
+- **Proxy mode** — point Lightning Enable at your API URL; we forward authenticated requests on your behalf. Best for public APIs or quick experiments. [Setup walkthrough](https://docs.lightningenable.com/products/l402-microtransactions/proxy-setup-walkthrough).
+- **Native mode** — install this SDK in your existing API. Lightning Enable handles payment; your API handles everything else. Best for commercial APIs with their own auth, observability, or sensitive infrastructure. **This SDK is the Native mode building block.**
+
+Framework-specific middleware that wraps this SDK is in development:
+
+- `l402-express` — Express middleware
+- ASP.NET Core middleware (separate package)
+- FastAPI dependency (separate package)
+- `l402-server-go` — Go middleware (Phase 2 of the roadmap)
+
+## Architectural notes
+
+The architectural decisions baked into this SDK are deliberate:
+
+- **No protocol code in the SDK.** Macaroon signing, preimage hashing, payment-hash linking — all server-side. The SDK is HTTP-client glue.
+- **Verification via the hosted endpoint, not local key material.** We don't distribute the L402 root key to merchants. Every `verifyToken` call goes to `/api/l402/challenges/verify`. One round-trip per paid request (~50ms regional). The trade-off is acceptable until a high-volume partner complains; we'll revisit then.
+- **Replay prevention centralized.** Lightning Enable tracks consumed preimages. Merchants don't maintain a local cache. Consistent across the merchant's whole API surface.
+- **No credentials stored anywhere.** Lightning Enable never asks for your upstream API credentials. The SDK just calls our two endpoints; your traffic stays on your server.
+
+## Contributing
+
+Open source under MIT. Issues and pull requests welcome. For protocol-level discussion, see the [L402 spec at lightninglabs/L402](https://github.com/lightninglabs/L402).
+
+## License
+
+MIT © Refined Element, LLC

package/dist/index.cjs

@@ -0,0 +1,267 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  L402ApiError: () => L402ApiError,
+  L402AuthError: () => L402AuthError,
+  L402NetworkError: () => L402NetworkError,
+  L402PlanError: () => L402PlanError,
+  L402Server: () => L402Server,
+  L402ServerError: () => L402ServerError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var L402ServerError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "L402ServerError";
+  }
+};
+var L402AuthError = class extends L402ServerError {
+  constructor(message = "Merchant API key is missing or invalid.") {
+    super(message);
+    this.name = "L402AuthError";
+  }
+};
+var L402PlanError = class extends L402ServerError {
+  /**
+   * The plan tier currently on the merchant (e.g., "starter").
+   * Populated when the server includes it in the error payload.
+   */
+  currentPlan;
+  constructor(message = "L402 is not enabled on this merchant's plan.", currentPlan) {
+    super(message);
+    this.name = "L402PlanError";
+    this.currentPlan = currentPlan;
+  }
+};
+var L402NetworkError = class extends L402ServerError {
+  constructor(message, cause) {
+    super(message, { cause });
+    this.name = "L402NetworkError";
+  }
+};
+var L402ApiError = class extends L402ServerError {
+  /**
+   * HTTP status code returned by the producer API.
+   */
+  statusCode;
+  /**
+   * Raw response body, useful for debugging. May be a parsed object or a
+   * string if parsing failed.
+   */
+  responseBody;
+  constructor(statusCode, message, responseBody) {
+    super(message);
+    this.name = "L402ApiError";
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+  }
+};
+
+// src/L402Server.ts
+var DEFAULT_BASE_URL = "https://api.lightningenable.com";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var L402Server = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  fetchImpl;
+  constructor(options) {
+    if (!options.apiKey || options.apiKey.trim().length === 0) {
+      throw new Error(
+        "L402Server: `apiKey` is required. Get one from your Lightning Enable dashboard."
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * Mint an L402 challenge — a Lightning invoice plus a macaroon scoped to
+   * the given resource. Present this to the requesting client/agent in a
+   * `402 Payment Required` response. Once they pay the invoice and obtain
+   * the preimage, they will retry the request with
+   * `Authorization: L402 <macaroon>:<preimage>`.
+   *
+   * @param args - resource path, price in sats, optional description and idempotency key.
+   * @returns The {@link Challenge} containing the invoice, macaroon, and metadata.
+   * @throws {@link L402AuthError} on 401 (invalid API key).
+   * @throws {@link L402PlanError} on 403 (L402 not enabled on merchant's plan).
+   * @throws {@link L402ApiError} on other non-2xx responses.
+   * @throws {@link L402NetworkError} on timeout or transport failure.
+   */
+  async createChallenge(args) {
+    if (!args.resource || args.resource.trim().length === 0) {
+      throw new Error("createChallenge: `resource` is required.");
+    }
+    if (!Number.isFinite(args.priceSats) || args.priceSats < 1) {
+      throw new Error("createChallenge: `priceSats` must be an integer \u2265 1.");
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.apiKey,
+      Accept: "application/json"
+    };
+    if (args.idempotencyKey) {
+      headers["X-Idempotency-Key"] = args.idempotencyKey;
+    }
+    const body = JSON.stringify({
+      resource: args.resource,
+      priceSats: args.priceSats,
+      description: args.description
+    });
+    const response = await this.request(
+      "/api/l402/challenges",
+      "POST",
+      headers,
+      body
+    );
+    if (response.status === 200) {
+      const data = await response.json();
+      return {
+        invoice: data.invoice,
+        macaroon: data.macaroon,
+        paymentHash: data.paymentHash,
+        expiresAt: data.expiresAt,
+        resource: data.resource,
+        priceSats: data.priceSats,
+        mppChallenge: data.mppChallenge ?? void 0
+      };
+    }
+    await this.throwForStatus(response);
+    throw new L402ApiError(
+      response.status,
+      "Unexpected response from L402 producer API."
+    );
+  }
+  /**
+   * Verify an L402 token. Returns a {@link VerificationResult} indicating
+   * whether the token is valid plus metadata extracted from the macaroon
+   * (resource, merchant ID, amount).
+   *
+   * The producer API returns `200 OK` for both valid and invalid tokens;
+   * inspect `result.valid` rather than relying on HTTP status. Non-200
+   * responses indicate a higher-level problem (auth, plan, transport).
+   *
+   * @param args - macaroon (required for L402; omit only for MPP) + preimage.
+   * @returns The {@link VerificationResult}.
+   * @throws {@link L402AuthError} on 401 (invalid API key).
+   * @throws {@link L402PlanError} on 403 (L402 not enabled on merchant's plan).
+   * @throws {@link L402ApiError} on other non-2xx responses.
+   * @throws {@link L402NetworkError} on timeout or transport failure.
+   */
+  async verifyToken(args) {
+    if (!args.preimage || args.preimage.trim().length === 0) {
+      throw new Error("verifyToken: `preimage` is required.");
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      "X-API-Key": this.apiKey,
+      Accept: "application/json"
+    };
+    const body = JSON.stringify({
+      macaroon: args.macaroon,
+      preimage: args.preimage
+    });
+    const response = await this.request(
+      "/api/l402/challenges/verify",
+      "POST",
+      headers,
+      body
+    );
+    if (response.status === 200) {
+      const data = await response.json();
+      return {
+        valid: data.valid,
+        error: data.error ?? void 0,
+        resource: data.resource ?? void 0,
+        merchantId: data.merchantId ?? void 0,
+        amountSats: data.amountSats ?? void 0,
+        paymentHash: data.paymentHash ?? void 0
+      };
+    }
+    await this.throwForStatus(response);
+    throw new L402ApiError(
+      response.status,
+      "Unexpected response from L402 producer API."
+    );
+  }
+  async request(path, method, headers, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await this.fetchImpl(url, {
+        method,
+        headers,
+        body,
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err?.name === "AbortError") {
+        throw new L402NetworkError(
+          `Request to ${url} timed out after ${this.timeoutMs}ms`,
+          err
+        );
+      }
+      throw new L402NetworkError(
+        `Network error talking to ${url}: ${err.message}`,
+        err
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async throwForStatus(response) {
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      try {
+        body = await response.text();
+      } catch {
+        body = void 0;
+      }
+    }
+    const errorMessage = body?.error ?? body?.message ?? `HTTP ${response.status} from ${response.url}`;
+    if (response.status === 401) {
+      throw new L402AuthError(errorMessage);
+    }
+    if (response.status === 403) {
+      const currentPlan = body?.current_plan;
+      throw new L402PlanError(errorMessage, currentPlan);
+    }
+    throw new L402ApiError(response.status, errorMessage, body);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  L402ApiError,
+  L402AuthError,
+  L402NetworkError,
+  L402PlanError,
+  L402Server,
+  L402ServerError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/L402Server.ts"],"sourcesContent":["export { L402Server } from \"./L402Server.js\";\nexport {\n  L402ApiError,\n  L402AuthError,\n  L402NetworkError,\n  L402PlanError,\n  L402ServerError,\n} from \"./errors.js\";\nexport type {\n  Challenge,\n  CreateChallengeArgs,\n  L402ServerOptions,\n  VerificationResult,\n  VerifyTokenArgs,\n} from \"./types.js\";\n","/**\n * Base error class for all SDK-thrown errors. Distinguishable from arbitrary\n * `Error` instances via `instanceof L402ServerError`.\n */\nexport class L402ServerError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"L402ServerError\";\n  }\n}\n\n/**\n * Thrown on `401 Unauthorized` from the producer API. Almost always means\n * the merchant API key is missing, malformed, expired, or revoked.\n */\nexport class L402AuthError extends L402ServerError {\n  constructor(message: string = \"Merchant API key is missing or invalid.\") {\n    super(message);\n    this.name = \"L402AuthError\";\n  }\n}\n\n/**\n * Thrown on `403 Forbidden` from the producer API. Means the merchant\n * exists and the key is valid, but L402 is not enabled on their plan.\n * The merchant needs to upgrade to an Agentic Commerce plan.\n */\nexport class L402PlanError extends L402ServerError {\n  /**\n   * The plan tier currently on the merchant (e.g., \"starter\").\n   * Populated when the server includes it in the error payload.\n   */\n  readonly currentPlan?: string;\n\n  constructor(\n    message: string = \"L402 is not enabled on this merchant's plan.\",\n    currentPlan?: string,\n  ) {\n    super(message);\n    this.name = \"L402PlanError\";\n    this.currentPlan = currentPlan;\n  }\n}\n\n/**\n * Thrown for transport-level failures: timeout, DNS error, TLS error,\n * unreachable host. The `cause` carries the original error.\n */\nexport class L402NetworkError extends L402ServerError {\n  constructor(message: string, cause?: unknown) {\n    super(message, { cause });\n    this.name = \"L402NetworkError\";\n  }\n}\n\n/**\n * Thrown when the server returns a non-success status that doesn't map to\n * a more specific error class above (e.g., 400 with a request-validation\n * problem, 500 from upstream wallet failure, 429 from rate limiting).\n */\nexport class L402ApiError extends L402ServerError {\n  /**\n   * HTTP status code returned by the producer API.\n   */\n  readonly statusCode: number;\n\n  /**\n   * Raw response body, useful for debugging. May be a parsed object or a\n   * string if parsing failed.\n   */\n  readonly responseBody?: unknown;\n\n  constructor(\n    statusCode: number,\n    message: string,\n    responseBody?: unknown,\n  ) {\n    super(message);\n    this.name = \"L402ApiError\";\n    this.statusCode = statusCode;\n    this.responseBody = responseBody;\n  }\n}\n","import {\n  L402ApiError,\n  L402AuthError,\n  L402NetworkError,\n  L402PlanError,\n} from \"./errors.js\";\nimport type {\n  Challenge,\n  CreateChallengeArgs,\n  L402ServerOptions,\n  VerificationResult,\n  VerifyTokenArgs,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.lightningenable.com\";\nconst DEFAULT_TIMEOUT_MS = 10_000;\n\n/**\n * Server-side client for Lightning Enable's L402 producer API. Wraps two\n * endpoints:\n *\n * - {@link createChallenge} → `POST /api/l402/challenges` — mint a\n *   Lightning invoice + macaroon for a given resource and price.\n * - {@link verifyToken} → `POST /api/l402/challenges/verify` — validate\n *   an incoming L402 token (macaroon + preimage).\n *\n * **No protocol logic lives in this SDK.** The Lightning Enable backend\n * signs macaroons, mints invoices, verifies preimages, and tracks consumed\n * tokens for replay protection. The SDK is purely an HTTP client with\n * typed inputs/outputs.\n *\n * @example\n * ```ts\n * import { L402Server } from \"l402-server\";\n *\n * const l402 = new L402Server({\n *   apiKey: process.env.LIGHTNING_ENABLE_API_KEY!,\n * });\n *\n * // On an unauthenticated incoming request:\n * const challenge = await l402.createChallenge({\n *   resource: \"/api/premium/weather\",\n *   priceSats: 100,\n *   description: \"Premium weather forecast\",\n * });\n *\n * // Send back as 402 Payment Required with the challenge headers.\n *\n * // When client comes back with Authorization: L402 mac:preimage,\n * // parse and verify:\n * const verification = await l402.verifyToken({\n *   macaroon: parsedMacaroon,\n *   preimage: parsedPreimage,\n * });\n * if (verification.valid) {\n *   // Serve the response.\n * }\n * ```\n */\nexport class L402Server {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly timeoutMs: number;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(options: L402ServerOptions) {\n    if (!options.apiKey || options.apiKey.trim().length === 0) {\n      throw new Error(\n        \"L402Server: `apiKey` is required. Get one from your Lightning Enable dashboard.\",\n      );\n    }\n\n    this.apiKey = options.apiKey;\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n    this.fetchImpl = options.fetch ?? fetch;\n  }\n\n  /**\n   * Mint an L402 challenge — a Lightning invoice plus a macaroon scoped to\n   * the given resource. Present this to the requesting client/agent in a\n   * `402 Payment Required` response. Once they pay the invoice and obtain\n   * the preimage, they will retry the request with\n   * `Authorization: L402 <macaroon>:<preimage>`.\n   *\n   * @param args - resource path, price in sats, optional description and idempotency key.\n   * @returns The {@link Challenge} containing the invoice, macaroon, and metadata.\n   * @throws {@link L402AuthError} on 401 (invalid API key).\n   * @throws {@link L402PlanError} on 403 (L402 not enabled on merchant's plan).\n   * @throws {@link L402ApiError} on other non-2xx responses.\n   * @throws {@link L402NetworkError} on timeout or transport failure.\n   */\n  async createChallenge(args: CreateChallengeArgs): Promise<Challenge> {\n    if (!args.resource || args.resource.trim().length === 0) {\n      throw new Error(\"createChallenge: `resource` is required.\");\n    }\n    if (!Number.isFinite(args.priceSats) || args.priceSats < 1) {\n      throw new Error(\"createChallenge: `priceSats` must be an integer ≥ 1.\");\n    }\n\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      \"X-API-Key\": this.apiKey,\n      Accept: \"application/json\",\n    };\n    if (args.idempotencyKey) {\n      headers[\"X-Idempotency-Key\"] = args.idempotencyKey;\n    }\n\n    const body = JSON.stringify({\n      resource: args.resource,\n      priceSats: args.priceSats,\n      description: args.description,\n    });\n\n    const response = await this.request(\n      \"/api/l402/challenges\",\n      \"POST\",\n      headers,\n      body,\n    );\n\n    if (response.status === 200) {\n      const data = (await response.json()) as {\n        invoice: string;\n        macaroon: string;\n        paymentHash: string;\n        expiresAt: string;\n        resource: string;\n        priceSats: number;\n        mppChallenge?: string | null;\n      };\n      return {\n        invoice: data.invoice,\n        macaroon: data.macaroon,\n        paymentHash: data.paymentHash,\n        expiresAt: data.expiresAt,\n        resource: data.resource,\n        priceSats: data.priceSats,\n        mppChallenge: data.mppChallenge ?? undefined,\n      };\n    }\n\n    await this.throwForStatus(response);\n    // Unreachable — throwForStatus always throws on non-2xx.\n    throw new L402ApiError(\n      response.status,\n      \"Unexpected response from L402 producer API.\",\n    );\n  }\n\n  /**\n   * Verify an L402 token. Returns a {@link VerificationResult} indicating\n   * whether the token is valid plus metadata extracted from the macaroon\n   * (resource, merchant ID, amount).\n   *\n   * The producer API returns `200 OK` for both valid and invalid tokens;\n   * inspect `result.valid` rather than relying on HTTP status. Non-200\n   * responses indicate a higher-level problem (auth, plan, transport).\n   *\n   * @param args - macaroon (required for L402; omit only for MPP) + preimage.\n   * @returns The {@link VerificationResult}.\n   * @throws {@link L402AuthError} on 401 (invalid API key).\n   * @throws {@link L402PlanError} on 403 (L402 not enabled on merchant's plan).\n   * @throws {@link L402ApiError} on other non-2xx responses.\n   * @throws {@link L402NetworkError} on timeout or transport failure.\n   */\n  async verifyToken(args: VerifyTokenArgs): Promise<VerificationResult> {\n    if (!args.preimage || args.preimage.trim().length === 0) {\n      throw new Error(\"verifyToken: `preimage` is required.\");\n    }\n\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n      \"X-API-Key\": this.apiKey,\n      Accept: \"application/json\",\n    };\n\n    const body = JSON.stringify({\n      macaroon: args.macaroon,\n      preimage: args.preimage,\n    });\n\n    const response = await this.request(\n      \"/api/l402/challenges/verify\",\n      \"POST\",\n      headers,\n      body,\n    );\n\n    if (response.status === 200) {\n      const data = (await response.json()) as {\n        valid: boolean;\n        resource?: string | null;\n        merchantId?: number | null;\n        amountSats?: number | null;\n        paymentHash?: string | null;\n        error?: string | null;\n      };\n      return {\n        valid: data.valid,\n        error: data.error ?? undefined,\n        resource: data.resource ?? undefined,\n        merchantId: data.merchantId ?? undefined,\n        amountSats: data.amountSats ?? undefined,\n        paymentHash: data.paymentHash ?? undefined,\n      };\n    }\n\n    await this.throwForStatus(response);\n    throw new L402ApiError(\n      response.status,\n      \"Unexpected response from L402 producer API.\",\n    );\n  }\n\n  private async request(\n    path: string,\n    method: string,\n    headers: Record<string, string>,\n    body: string,\n  ): Promise<Response> {\n    const url = `${this.baseUrl}${path}`;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeoutMs);\n\n    try {\n      return await this.fetchImpl(url, {\n        method,\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } catch (err) {\n      if ((err as { name?: string })?.name === \"AbortError\") {\n        throw new L402NetworkError(\n          `Request to ${url} timed out after ${this.timeoutMs}ms`,\n          err,\n        );\n      }\n      throw new L402NetworkError(\n        `Network error talking to ${url}: ${(err as Error).message}`,\n        err,\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n\n  private async throwForStatus(response: Response): Promise<never> {\n    let body: unknown;\n    try {\n      body = await response.json();\n    } catch {\n      try {\n        body = await response.text();\n      } catch {\n        body = undefined;\n      }\n    }\n\n    const errorMessage =\n      (body as { error?: string; message?: string })?.error ??\n      (body as { error?: string; message?: string })?.message ??\n      `HTTP ${response.status} from ${response.url}`;\n\n    if (response.status === 401) {\n      throw new L402AuthError(errorMessage);\n    }\n    if (response.status === 403) {\n      const currentPlan = (body as { current_plan?: string })?.current_plan;\n      throw new L402PlanError(errorMessage, currentPlan);\n    }\n    throw new L402ApiError(response.status, errorMessage, body);\n  }\n}\n"],"mappings":"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","names":[]}