@satpath/gateless 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 satpath
+
+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,251 @@
+# Gateless
+
+Sovereign L402 payments for AI agents on Lightning.
+
+Gateless is a JavaScript/TypeScript library that lets AI agents in Node.js autonomously pay for L402-protected web resources over the Lightning Network. Supports both the classic L402 protocol (macaroon + invoice) and Fewsats L402 v0.2 (offers + payment request). You run your own node. Your agent handles payments within spending limits you define. No accounts, no API keys, no identity - payment is authentication.
+
+## Why
+
+AI agents need to pay for things. The emerging solutions either lock you into custodial stablecoins ([x402](https://www.x402.org/)) or require shell access to Go CLI tools ([lnget](https://github.com/lightninglabs/lightning-agent-tools)). Neither works for a web developer building an agent in TypeScript.
+
+Gateless fills the gap: a self-contained JS/TS toolkit that connects to **your own LND node** and handles L402 payments programmatically. No custodian, no corporate infrastructure, your keys.
+
+## Install
+
+```bash
+npm install gateless
+```
+
+## Quick Start
+
+```typescript
+import { LndClient, L402Client } from "gateless";
+
+const lnd = new LndClient({
+  host: "127.0.0.1",
+  port: 8080,
+  tlsCertPath: "./creds/tls.cert",
+  macaroonPath: "./creds/admin.macaroon",
+});
+
+const client = new L402Client({
+  paymentProvider: lnd,
+  maxPaymentSats: 100,
+  spendingLimits: {
+    maxPerPaymentSats: 50,
+    maxTotalSats: 1000,
+    maxPaymentsPerMinute: 10,
+  },
+});
+
+// Use it like fetch - L402 payments happen automatically
+const response = await client.fetch("https://api.example.com/paid-resource");
+const data = await response.json();
+```
+
+If the server returns `402 Payment Required`, Gateless automatically detects the protocol version and handles payment:
+
+**Classic L402** - Parses the `WWW-Authenticate` header, pays the invoice, caches the macaroon+preimage token, and retries with `Authorization: L402`. Second requests reuse the cached token.
+
+**Fewsats v0.2** - Parses the JSON offers body, selects an offer, fetches a Lightning invoice from the payment request endpoint, pays it, and retries with the original request headers (Bearer token). The server credits your account after payment.
+
+### Fewsats v0.2
+
+Most live L402 endpoints today use the Fewsats v0.2 protocol. Your Bearer token (obtained separately) is your credential - Gateless handles the payment when the server returns 402:
+
+```typescript
+const client = new L402Client({
+  paymentProvider: lnd,
+  maxPaymentSats: 100,
+});
+
+// Bearer token is passed through - Gateless pays when the server demands it
+const response = await client.fetch("https://api.example.com/paid-resource", {
+  headers: { Authorization: "Bearer your-api-token" },
+});
+const data = await response.json();
+```
+
+You can customize which offer is selected when multiple are available:
+
+```typescript
+import { L402Client, type OfferStrategy } from "gateless";
+
+const pickMostCredits: OfferStrategy = (offers) => {
+  const lightning = offers.filter((o) =>
+    o.payment_methods.includes("lightning"),
+  );
+  if (lightning.length === 0) throw new Error("No lightning offers");
+  lightning.sort((a, b) => b.balance - a.balance);
+  return lightning[0]!;
+};
+
+const client = new L402Client({
+  paymentProvider: lnd,
+  maxPaymentSats: 100,
+  offerStrategy: pickMostCredits, // default: cheapest lightning-compatible offer
+});
+```
+
+## Features
+
+**L402 Client** - Drop-in `fetch` wrapper that handles the full 402 → pay → retry flow automatically. Supports both classic L402 and Fewsats v0.2.
+
+**Fewsats v0.2** - Automatic offer selection, payment request negotiation, and Bearer token auth. Pluggable offer strategy (default: cheapest lightning-compatible).
+
+**Token Cache** - Stores paid macaroon+preimage pairs for classic L402. Avoids double-paying for the same resource. Supports optional TTL expiry.
+
+**Spending Controls** - Set per-payment limits, total budgets, and rate limits. Applies to both classic and v0.2 flows. An AI agent physically cannot exceed the budget you define.
+
+**Payment Provider Interface** - Ships with an LND client over REST. Bring your own provider by implementing a simple interface:
+
+```typescript
+interface PaymentProvider {
+  payInvoice(paymentRequest: string): Promise<PaymentResult>;
+}
+```
+
+## How L402 Works
+
+L402 is a protocol that uses Lightning Network payments for authentication. Gateless supports two variants:
+
+### Classic L402
+
+The server returns a macaroon and invoice in the `WWW-Authenticate` header. After payment, the preimage proves you paid.
+
+```
+Agent                          Server
+  |      GET /resource           |
+  |----------------------------->|
+  |  402 + WWW-Authenticate:     |
+  |    L402 macaroon="...",      |
+  |    invoice="lnbc..."         |
+  |<-----------------------------|
+  |  [pays Lightning invoice]    |
+  |  GET /resource               |
+  |  Authorization: L402         |
+  |    <macaroon>:<preimage>     |
+  |----------------------------->|
+  |  200 OK { data }             |
+  |<-----------------------------|
+```
+
+### Fewsats v0.2
+
+The server returns a JSON body with offers. The agent selects an offer, fetches a Lightning invoice, pays it, and retries with the original Bearer token.
+
+```
+Agent                          Server            Payment Endpoint
+  |      GET /resource           |                     |
+  |  Authorization: Bearer ...   |                     |
+  |----------------------------->|                     |
+  |  402 + JSON body:            |                     |
+  |    { offers, payment_        |                     |
+  |      context_token,          |                     |
+  |      payment_request_url }   |                     |
+  |<-----------------------------|                     |
+  |  POST /payment-request       |                     |
+  |    { offer_id,               |-------------------->|
+  |      payment_method,         |                     |
+  |      payment_context_token } |                     |
+  |  { lightning_invoice }       |<--------------------|
+  |<-----------------------------|                     |
+  |  [pays Lightning invoice]    |                     |
+  |  GET /resource               |                     |
+  |  Authorization: Bearer ...   |                     |
+  |----------------------------->|                     |
+  |  200 OK { data }             |                     |
+  |<-----------------------------|                     |
+```
+
+No accounts. No passwords. No tracking. Payment is the authentication.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│          Your Application               │
+│                                         │
+│   const res = await client.fetch(url)   │
+└────────────────┬────────────────────────┘
+                 │
+┌────────────────▼────────────────────────┐
+│            L402Client                   │
+│                                         │
+│  ┌──────────┐ ┌──────────┐ ┌─────────┐  │
+│  │  Token   │ │ Spending │ │ Invoice │  │
+│  │  Cache   │ │ Tracker  │ │ Decoder │  │
+│  └──────────┘ └──────────┘ └─────────┘  │
+└────────────────┬────────────────────────┘
+                 │
+┌────────────────▼────────────────────────┐
+│         PaymentProvider                 │
+│                                         │
+│  LndClient  │  (NWC - planned)          │
+│  REST API   │  (LNC - planned)          │
+└────────────────┬────────────────────────┘
+                 │
+┌────────────────▼────────────────────────┐
+│          Your LND Node                  │
+│          (your keys, your node)         │
+└─────────────────────────────────────────┘
+```
+
+## Comparison
+
+|                   | Gateless            | lnget (Lightning Labs) | x402 (Coinbase)        |
+| ----------------- | ------------------- | ---------------------- | ---------------------- |
+| Language          | TypeScript          | Go                     | Multiple               |
+| Runtime           | Node.js             | CLI only               | Server SDKs            |
+| Payment rail      | Lightning (Bitcoin) | Lightning (Bitcoin)    | USDC (stablecoins)     |
+| Node              | Your own LND        | Your own LND           | Coinbase custody       |
+| Identity required | No                  | No                     | Yes (Coinbase account) |
+| npm install       | Yes                 | No                     | Yes                    |
+| Self-sovereign    | Yes                 | Yes                    | No                     |
+
+Gateless and lnget are complementary. lnget is for terminal-based agents (Claude Code, Codex). Gateless is for web developers building agents in TypeScript.
+
+## Roadmap
+
+- ✅ LND REST payment provider
+- ✅ L402 fetch client with automatic payment
+- ✅ Token caching
+- ✅ Spending limits and rate controls
+- ✅ Fewsats L402 v0.2 support (offers, payment requests, pluggable offer strategy)
+- ⬜ Nostr Wallet Connect (NWC) payment provider
+- ⬜ Lightning Node Connect (LNC) provider
+- ⬜ Nostr endpoint discovery
+- ⬜ React hooks (`useL402Fetch`)
+- ⬜ Macaroon attenuation and inspection
+- ⬜ Server-side middleware (Aperture alternative in JS)
+
+## Requirements
+
+- Node.js 18+
+- An LND node (v0.16+) with REST API enabled
+- A funded Lightning channel
+
+### LND Credentials
+
+Gateless needs two files from your LND node:
+
+- **TLS certificate** — usually at `~/.lnd/tls.cert`
+- **Admin macaroon** — usually at `~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon`
+
+Copy them to your project (e.g. a `creds/` directory) and point `LndClient` at them. If your node is on a different machine, use an SSH tunnel to forward the REST port:
+
+```bash
+ssh -L 8080:127.0.0.1:8080 user@your-node-ip
+```
+
+## ⚠️ Disclaimer
+
+Gateless is experimental software. It interacts with real Bitcoin on the Lightning Network. By using this software you accept full responsibility for any funds sent or lost. Always start with small amounts, use spending limits, and test thoroughly before deploying in any production environment. This software is provided as-is with no warranty of any kind.
+
+## License
+
+MIT
+
+## Author
+
+[satpath](https://github.com/satpathdev)

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+/** The invoice amount or total spend would exceed configured limits */
+export declare class L402BudgetError extends Error {
+    name: "L402BudgetError";
+}
+/** The Lightning payment failed (routing failure, insufficient funds, etc.) */
+export declare class L402PaymentError extends Error {
+    name: "L402PaymentError";
+}
+/** The server's L402 challenge was malformed or the invoice could not be parsed */
+export declare class L402ProtocolError extends Error {
+    name: "L402ProtocolError";
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,qBAAa,eAAgB,SAAQ,KAAK;IAC/B,IAAI,EAAG,iBAAiB,CAAU;CAC5C;AAED,+EAA+E;AAC/E,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,EAAG,kBAAkB,CAAU;CAC7C;AAED,mFAAmF;AACnF,qBAAa,iBAAkB,SAAQ,KAAK;IACjC,IAAI,EAAG,mBAAmB,CAAU;CAC9C"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+/** The invoice amount or total spend would exceed configured limits */
+export class L402BudgetError extends Error {
+    name = "L402BudgetError";
+}
+/** The Lightning payment failed (routing failure, insufficient funds, etc.) */
+export class L402PaymentError extends Error {
+    name = "L402PaymentError";
+}
+/** The server's L402 challenge was malformed or the invoice could not be parsed */
+export class L402ProtocolError extends Error {
+    name = "L402ProtocolError";
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,GAAG,iBAA0B,CAAC;CAC5C;AAED,+EAA+E;AAC/E,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,GAAG,kBAA2B,CAAC;CAC7C;AAED,mFAAmF;AACnF,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,GAAG,mBAA4B,CAAC;CAC9C"}

package/dist/fewsats.d.ts

@@ -0,0 +1,41 @@
+/** A single offer from the Fewsats v0.2 402 JSON body */
+export interface FewsatsOffer {
+    offer_id: string;
+    title: string;
+    description: string;
+    amount: number;
+    balance: number;
+    currency: string;
+    payment_methods: string[];
+    type: string;
+}
+/** The JSON body of a Fewsats v0.2 402 response */
+export interface FewsatsPaymentRequired {
+    offers: FewsatsOffer[];
+    payment_context_token: string;
+    payment_request_url: string;
+    version: string;
+}
+/** The response from POSTing to the payment_request_url */
+export interface FewsatsPaymentRequestResponse {
+    payment_request: {
+        lightning_invoice: string;
+    };
+    expires_at: string;
+    offer_id: string;
+    version: string;
+}
+/** Strategy function for selecting an offer from the array */
+export type OfferStrategy = (offers: FewsatsOffer[]) => FewsatsOffer;
+/**
+ * Attempts to parse an unknown value as a Fewsats v0.2 payment-required payload.
+ * Returns the parsed payload if valid, or undefined if the shape doesn't match.
+ * Does not throw.
+ */
+export declare function parseFewsatsPaymentRequired(body: unknown): FewsatsPaymentRequired | undefined;
+/**
+ * Default offer strategy: selects the cheapest offer that supports lightning.
+ * Throws L402ProtocolError if no lightning-compatible offer exists.
+ */
+export declare function selectCheapestLightningOffer(offers: FewsatsOffer[]): FewsatsOffer;
+//# sourceMappingURL=fewsats.d.ts.map

package/dist/fewsats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fewsats.d.ts","sourceRoot":"","sources":["../src/fewsats.ts"],"names":[],"mappings":"AAEA,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2DAA2D;AAC3D,MAAM,WAAW,6BAA6B;IAC5C,eAAe,EAAE;QAAE,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,YAAY,CAAC;AAErE;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,OAAO,GACZ,sBAAsB,GAAG,SAAS,CAqCpC;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,YAAY,EAAE,GACrB,YAAY,CAad"}

package/dist/fewsats.js

@@ -0,0 +1,47 @@
+import { L402ProtocolError } from "./errors.js";
+/**
+ * Attempts to parse an unknown value as a Fewsats v0.2 payment-required payload.
+ * Returns the parsed payload if valid, or undefined if the shape doesn't match.
+ * Does not throw.
+ */
+export function parseFewsatsPaymentRequired(body) {
+    if (typeof body !== "object" ||
+        body === null ||
+        !("offers" in body) ||
+        !("payment_context_token" in body) ||
+        !("payment_request_url" in body) ||
+        !("version" in body)) {
+        return undefined;
+    }
+    const obj = body;
+    if (!Array.isArray(obj["offers"]) ||
+        obj["offers"].length === 0 ||
+        typeof obj["payment_context_token"] !== "string" ||
+        typeof obj["payment_request_url"] !== "string" ||
+        typeof obj["version"] !== "string") {
+        return undefined;
+    }
+    for (const offer of obj["offers"]) {
+        if (typeof offer !== "object" ||
+            offer === null ||
+            typeof offer["offer_id"] !== "string" ||
+            typeof offer["amount"] !== "number" ||
+            !Array.isArray(offer["payment_methods"])) {
+            return undefined;
+        }
+    }
+    return body;
+}
+/**
+ * Default offer strategy: selects the cheapest offer that supports lightning.
+ * Throws L402ProtocolError if no lightning-compatible offer exists.
+ */
+export function selectCheapestLightningOffer(offers) {
+    const lightningOffers = offers.filter((o) => o.payment_methods.includes("lightning"));
+    if (lightningOffers.length === 0) {
+        throw new L402ProtocolError("No offers support lightning payment method");
+    }
+    lightningOffers.sort((a, b) => a.amount - b.amount);
+    return lightningOffers[0];
+}
+//# sourceMappingURL=fewsats.js.map

package/dist/fewsats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fewsats.js","sourceRoot":"","sources":["../src/fewsats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAiChD;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAa;IAEb,IACE,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC;QACnB,CAAC,CAAC,uBAAuB,IAAI,IAAI,CAAC;QAClC,CAAC,CAAC,qBAAqB,IAAI,IAAI,CAAC;QAChC,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,EACpB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,GAAG,GAAG,IAA+B,CAAC;IAE5C,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC;QAC1B,OAAO,GAAG,CAAC,uBAAuB,CAAC,KAAK,QAAQ;QAChD,OAAO,GAAG,CAAC,qBAAqB,CAAC,KAAK,QAAQ;QAC9C,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,QAAQ,EAClC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,QAAQ,CAAc,EAAE,CAAC;QAC/C,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACd,OAAQ,KAAiC,CAAC,UAAU,CAAC,KAAK,QAAQ;YAClE,OAAQ,KAAiC,CAAC,QAAQ,CAAC,KAAK,QAAQ;YAChE,CAAC,KAAK,CAAC,OAAO,CAAE,KAAiC,CAAC,iBAAiB,CAAC,CAAC,EACrE,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,IAA8B,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAAsB;IAEtB,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1C,CAAC,CAAC,eAAe,CAAC,QAAQ,CAAC,WAAW,CAAC,CACxC,CAAC;IAEF,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,iBAAiB,CACzB,4CAA4C,CAC7C,CAAC;IACJ,CAAC;IAED,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACpD,OAAO,eAAe,CAAC,CAAC,CAAE,CAAC;AAC7B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { LndClient } from "./lnd.js";
+export type { LndConfig } from "./lnd.js";
+export { L402Client } from "./l402.js";
+export type { L402ClientConfig } from "./l402.js";
+export { TokenCache } from "./token-cache.js";
+export type { CachedToken } from "./token-cache.js";
+export type { PaymentProvider, PaymentResult } from "./payment-provider.js";
+export type { SpendingLimit, SpendingRecord } from "./spending.js";
+export { L402BudgetError, L402PaymentError, L402ProtocolError } from "./errors.js";
+export type { FewsatsOffer, FewsatsPaymentRequired, FewsatsPaymentRequestResponse, OfferStrategy, } from "./fewsats.js";
+export { selectCheapestLightningOffer } from "./fewsats.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC5E,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACnF,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,6BAA6B,EAC7B,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { LndClient } from "./lnd.js";
+export { L402Client } from "./l402.js";
+export { TokenCache } from "./token-cache.js";
+export { L402BudgetError, L402PaymentError, L402ProtocolError } from "./errors.js";
+export { selectCheapestLightningOffer } from "./fewsats.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAI9C,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAOnF,OAAO,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC"}

package/dist/l402.d.ts

@@ -0,0 +1,38 @@
+import { type SpendingLimit } from "./spending.js";
+import type { PaymentProvider } from "./payment-provider.js";
+import { type OfferStrategy } from "./fewsats.js";
+export interface L402ClientConfig {
+    paymentProvider: PaymentProvider;
+    /**
+     * Maximum sats allowed per individual payment (default: 1000).
+     * This is a simple safety cap. For full budget control, use spendingLimits
+     * which provides per-payment, total budget, and rate limiting together.
+     */
+    maxPaymentSats?: number;
+    /** Optional spending limits for budget and rate control */
+    spendingLimits?: SpendingLimit;
+    /** Strategy for selecting from Fewsats v0.2 offers (default: cheapest lightning-compatible) */
+    offerStrategy?: OfferStrategy;
+}
+export declare class L402Client {
+    private paymentProvider;
+    private maxPaymentSats;
+    private cache;
+    private spending;
+    private inflightPayments;
+    private offerStrategy;
+    constructor(config: L402ClientConfig);
+    /** Remove all cached tokens */
+    clearCache(): void;
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    private handleClassicL402;
+    private handleFewsatsV02;
+    private parseWwwAuthenticate;
+    /**
+     * Local BOLT11 amount parser. Used only as a fallback when the payment
+     * provider does not implement getInvoiceAmountSats(). Supports mainnet
+     * (lnbc), testnet (lntb), and regtest (lnbcrt) invoices.
+     */
+    private decodeInvoiceAmountLocal;
+}
+//# sourceMappingURL=l402.d.ts.map

package/dist/l402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l402.d.ts","sourceRoot":"","sources":["../src/l402.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAM7D,OAAO,EAGL,KAAK,aAAa,EAGnB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,+FAA+F;IAC/F,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,gBAAgB,CAAoC;IAC5D,OAAO,CAAC,aAAa,CAAgB;gBAEzB,MAAM,EAAE,gBAAgB;IAUpC,+BAA+B;IAC/B,UAAU,IAAI,IAAI;IAIZ,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;YAoEjD,iBAAiB;YA4CjB,gBAAgB;IAyF9B,OAAO,CAAC,oBAAoB;IAiB5B;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;CA8CjC"}

package/dist/l402.js

@@ -0,0 +1,224 @@
+import { TokenCache } from "./token-cache.js";
+import { SpendingTracker } from "./spending.js";
+import { L402BudgetError, L402PaymentError, L402ProtocolError, } from "./errors.js";
+import { parseFewsatsPaymentRequired, selectCheapestLightningOffer, } from "./fewsats.js";
+export class L402Client {
+    paymentProvider;
+    maxPaymentSats;
+    cache;
+    spending;
+    inflightPayments = new Map();
+    offerStrategy;
+    constructor(config) {
+        this.paymentProvider = config.paymentProvider;
+        this.maxPaymentSats = config.maxPaymentSats ?? 1000;
+        this.cache = new TokenCache();
+        this.offerStrategy = config.offerStrategy ?? selectCheapestLightningOffer;
+        if (config.spendingLimits) {
+            this.spending = new SpendingTracker(config.spendingLimits);
+        }
+    }
+    /** Remove all cached tokens */
+    clearCache() {
+        this.cache.clear();
+    }
+    async fetch(url, init) {
+        const cached = this.cache.get(url);
+        if (cached) {
+            const headers = new Headers(init?.headers);
+            headers.set("Authorization", `L402 ${cached.macaroon}:${cached.preimage}`);
+            const cachedResponse = await fetch(url, { ...init, headers });
+            if (cachedResponse.status !== 402) {
+                return cachedResponse;
+            }
+            // Token expired server-side - discard and fall through to payment flow
+            this.cache.delete(url);
+        }
+        // If another call is already paying for this URL, wait for it then use the cache
+        const inflight = this.inflightPayments.get(url);
+        if (inflight) {
+            await inflight;
+            const token = this.cache.get(url);
+            if (token) {
+                const headers = new Headers(init?.headers);
+                headers.set("Authorization", `L402 ${token.macaroon}:${token.preimage}`);
+                return fetch(url, { ...init, headers });
+            }
+        }
+        const response = await fetch(url, init);
+        if (response.status !== 402) {
+            return response;
+        }
+        // Detect which L402 flavor was returned
+        const wwwAuth = response.headers.get("www-authenticate");
+        if (wwwAuth) {
+            // Classic L402: WWW-Authenticate header present
+            await response.body?.cancel();
+            return this.handleClassicL402(url, init, wwwAuth);
+        }
+        // Try Fewsats v0.2: parse JSON body
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            throw new L402ProtocolError("402 response has no WWW-Authenticate header and body is not valid JSON");
+        }
+        const fewsatsPayload = parseFewsatsPaymentRequired(body);
+        if (!fewsatsPayload) {
+            throw new L402ProtocolError("402 response has no WWW-Authenticate header and body does not match Fewsats v0.2 format");
+        }
+        return this.handleFewsatsV02(url, init, fewsatsPayload);
+    }
+    async handleClassicL402(url, init, wwwAuth) {
+        const { macaroon, invoice } = this.parseWwwAuthenticate(wwwAuth);
+        const amountSats = this.paymentProvider.getInvoiceAmountSats
+            ? await this.paymentProvider.getInvoiceAmountSats(invoice)
+            : this.decodeInvoiceAmountLocal(invoice);
+        if (amountSats > this.maxPaymentSats) {
+            throw new L402BudgetError(`Invoice amount ${amountSats} sats exceeds limit of ${this.maxPaymentSats} sats`);
+        }
+        this.spending?.check(amountSats);
+        let resolveInflight;
+        const paymentPromise = new Promise((r) => {
+            resolveInflight = r;
+        });
+        this.inflightPayments.set(url, paymentPromise);
+        try {
+            const payment = await this.paymentProvider.payInvoice(invoice);
+            this.spending?.record(amountSats, url);
+            this.cache.set(url, macaroon, payment.preimage);
+            const headers = new Headers(init?.headers);
+            headers.set("Authorization", `L402 ${macaroon}:${payment.preimage}`);
+            return fetch(url, { ...init, headers });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new L402PaymentError(`Payment failed: ${message}`);
+        }
+        finally {
+            this.inflightPayments.delete(url);
+            resolveInflight();
+        }
+    }
+    async handleFewsatsV02(url, init, payload) {
+        const selectedOffer = this.offerStrategy(payload.offers);
+        // POST to payment_request_url to get a lightning invoice
+        let paymentRequestResponse;
+        try {
+            paymentRequestResponse = await fetch(payload.payment_request_url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    offer_id: selectedOffer.offer_id,
+                    payment_method: "lightning",
+                    payment_context_token: payload.payment_context_token,
+                }),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new L402PaymentError(`Failed to fetch payment request: ${message}`);
+        }
+        if (!paymentRequestResponse.ok) {
+            const errorText = await paymentRequestResponse
+                .text()
+                .catch(() => "unknown error");
+            throw new L402PaymentError(`Payment request endpoint returned ${paymentRequestResponse.status}: ${errorText}`);
+        }
+        let paymentRequestData;
+        try {
+            paymentRequestData =
+                (await paymentRequestResponse.json());
+        }
+        catch {
+            throw new L402ProtocolError("Payment request response is not valid JSON");
+        }
+        const invoice = paymentRequestData.payment_request?.lightning_invoice;
+        if (!invoice) {
+            throw new L402ProtocolError("Payment request response missing lightning_invoice");
+        }
+        // Validate invoice amount against spending limits
+        const amountSats = this.paymentProvider.getInvoiceAmountSats
+            ? await this.paymentProvider.getInvoiceAmountSats(invoice)
+            : this.decodeInvoiceAmountLocal(invoice);
+        if (amountSats > this.maxPaymentSats) {
+            throw new L402BudgetError(`Invoice amount ${amountSats} sats exceeds limit of ${this.maxPaymentSats} sats`);
+        }
+        this.spending?.check(amountSats);
+        try {
+            await this.paymentProvider.payInvoice(invoice);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new L402PaymentError(`Payment failed: ${message}`);
+        }
+        this.spending?.record(amountSats, url);
+        const maxRetries = 5;
+        const baseDelayMs = 500;
+        for (let i = 0; i < maxRetries; i++) {
+            await new Promise((resolve) => setTimeout(resolve, baseDelayMs * (i + 1)));
+            const retryResponse = await fetch(url, init);
+            if (retryResponse.status !== 402) {
+                return retryResponse;
+            }
+            // Still 402 — server hasn't credited yet, try again
+            await retryResponse.body?.cancel();
+        }
+        // All retries exhausted — return whatever the server gives
+        return fetch(url, init);
+    }
+    parseWwwAuthenticate(header) {
+        const macaroonMatch = header.match(/macaroon="([^"]+)"/);
+        const invoiceMatch = header.match(/invoice="([^"]+)"/);
+        if (!macaroonMatch?.[1] || !invoiceMatch?.[1]) {
+            throw new L402ProtocolError(`Invalid WWW-Authenticate header: ${header}`);
+        }
+        return {
+            macaroon: macaroonMatch[1],
+            invoice: invoiceMatch[1],
+        };
+    }
+    /**
+     * Local BOLT11 amount parser. Used only as a fallback when the payment
+     * provider does not implement getInvoiceAmountSats(). Supports mainnet
+     * (lnbc), testnet (lntb), and regtest (lnbcrt) invoices.
+     */
+    decodeInvoiceAmountLocal(invoice) {
+        const lower = invoice.toLowerCase();
+        // Find amount start after the network prefix
+        let amountStart;
+        if (lower.startsWith("lnbcrt")) {
+            amountStart = 6;
+        }
+        else if (lower.startsWith("lntb") || lower.startsWith("lnbc")) {
+            amountStart = 4;
+        }
+        else {
+            throw new L402ProtocolError("Cannot decode invoice: unrecognized network prefix");
+        }
+        // The human-readable part ends at the last '1' before the data section
+        const separatorIndex = lower.lastIndexOf("1");
+        if (separatorIndex <= amountStart) {
+            throw new L402ProtocolError("Cannot decode invoice amount: no amount specified");
+        }
+        const amountPart = lower.slice(amountStart, separatorIndex);
+        const match = amountPart.match(/^(\d+)([munp])$/);
+        if (!match?.[1] || !match[2]) {
+            throw new L402ProtocolError("Cannot decode invoice amount: invalid format");
+        }
+        const amount = parseInt(match[1], 10);
+        const multipliers = {
+            m: 100_000,
+            u: 100,
+            n: 0.1,
+            p: 0.0001,
+        };
+        const mult = multipliers[match[2]];
+        if (mult === undefined) {
+            throw new L402ProtocolError("Cannot decode invoice amount");
+        }
+        return Math.round(amount * mult);
+    }
+}
+//# sourceMappingURL=l402.js.map

package/dist/l402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"l402.js","sourceRoot":"","sources":["../src/l402.ts"],"names":[],"mappings":"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"}

package/dist/lnd.d.ts

@@ -0,0 +1,45 @@
+import type { PaymentProvider, PaymentResult } from "./payment-provider.js";
+export type { PaymentResult } from "./payment-provider.js";
+export interface LndConfig {
+    /** Hostname or IP of the LND REST API */
+    host: string;
+    /** REST API port (default LND: 8080) */
+    port: number;
+    /** Path to LND's TLS certificate (tls.cert) */
+    tlsCertPath: string;
+    /** Path to a macaroon file for authentication (e.g. admin.macaroon) */
+    macaroonPath: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}
+/**
+ * Connects to an LND node via its REST API.
+ * Reads the TLS cert and macaroon from disk once at construction.
+ * The macaroon is sent as a hex-encoded header on every request.
+ */
+export declare class LndClient implements PaymentProvider {
+    private config;
+    private tlsCert;
+    private macaroon;
+    private baseUrl;
+    private timeoutMs;
+    constructor(config: LndConfig);
+    /**
+     * Makes an authenticated HTTPS request to the LND REST API.
+     * The TLS cert is used as a CA to verify the self-signed certificate.
+     */
+    private request;
+    /** Returns general information about the node (alias, sync status, block height, etc.) */
+    getInfo(): Promise<Record<string, unknown>>;
+    /**
+     * Pays a BOLT11 Lightning invoice.
+     * LND returns the preimage as base64 - we convert it to hex
+     * because the L402 Authorization header requires hex encoding.
+     */
+    payInvoice(paymentRequest: string): Promise<PaymentResult>;
+    /** Returns the invoice amount in satoshis by decoding via LND's REST API */
+    getInvoiceAmountSats(paymentRequest: string): Promise<number>;
+    /** Decodes a BOLT11 invoice without paying it. Returns amount, destination, description, etc. */
+    decodeInvoice(paymentRequest: string): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=lnd.d.ts.map

package/dist/lnd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lnd.d.ts","sourceRoot":"","sources":["../src/lnd.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE5E,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,SAAU,YAAW,eAAe;IAMnC,OAAO,CAAC,MAAM;IAL1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;gBAEN,MAAM,EAAE,SAAS;IAOrC;;;OAGG;YACW,OAAO;IA8CrB,0FAA0F;IACpF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIjD;;;;OAIG;IACG,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6BhE,4EAA4E;IACtE,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQnE,iGAAiG;IAC3F,aAAa,CACjB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAGpC"}

package/dist/lnd.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import https from "node:https";
+/**
+ * Connects to an LND node via its REST API.
+ * Reads the TLS cert and macaroon from disk once at construction.
+ * The macaroon is sent as a hex-encoded header on every request.
+ */
+export class LndClient {
+    config;
+    tlsCert;
+    macaroon;
+    baseUrl;
+    timeoutMs;
+    constructor(config) {
+        this.config = config;
+        this.tlsCert = fs.readFileSync(config.tlsCertPath);
+        this.macaroon = fs.readFileSync(config.macaroonPath).toString("hex");
+        this.baseUrl = `https://${config.host}:${config.port}`;
+        this.timeoutMs = config.timeoutMs ?? 30_000;
+    }
+    /**
+     * Makes an authenticated HTTPS request to the LND REST API.
+     * The TLS cert is used as a CA to verify the self-signed certificate.
+     */
+    async request(method, path, body) {
+        const url = new URL(path, this.baseUrl);
+        const options = {
+            method,
+            ca: this.tlsCert,
+            headers: {
+                "Grpc-Metadata-macaroon": this.macaroon,
+                "Content-Type": "application/json",
+            },
+        };
+        return new Promise((resolve, reject) => {
+            const req = https.request(url, options, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk.toString();
+                });
+                res.on("end", () => {
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        resolve(JSON.parse(data));
+                    }
+                    else {
+                        reject(new Error(`LND API error ${res.statusCode}: ${data}`));
+                    }
+                });
+            });
+            req.setTimeout(this.timeoutMs, () => {
+                req.destroy();
+                reject(new Error(`LND request timed out after ${this.timeoutMs}ms`));
+            });
+            req.on("error", reject);
+            if (body) {
+                req.write(JSON.stringify(body));
+            }
+            req.end();
+        });
+    }
+    /** Returns general information about the node (alias, sync status, block height, etc.) */
+    async getInfo() {
+        return this.request("GET", "/v1/getinfo");
+    }
+    /**
+     * Pays a BOLT11 Lightning invoice.
+     * LND returns the preimage as base64 - we convert it to hex
+     * because the L402 Authorization header requires hex encoding.
+     */
+    async payInvoice(paymentRequest) {
+        const response = await this.request("POST", "/v1/channels/transactions", {
+            payment_request: paymentRequest,
+        });
+        if (response.payment_error) {
+            throw new Error(`Payment failed: ${response.payment_error}`);
+        }
+        if (typeof response.payment_preimage !== "string" ||
+            !response.payment_preimage) {
+            throw new Error("LND response missing payment_preimage");
+        }
+        return {
+            preimage: Buffer.from(response.payment_preimage, "base64").toString("hex"),
+            paymentHash: Buffer.from(response.payment_hash, "base64").toString("hex"),
+            status: "SUCCEEDED",
+        };
+    }
+    /** Returns the invoice amount in satoshis by decoding via LND's REST API */
+    async getInvoiceAmountSats(paymentRequest) {
+        const result = await this.request("GET", `/v1/payreq/${paymentRequest}`);
+        return parseInt(result.num_satoshis, 10);
+    }
+    /** Decodes a BOLT11 invoice without paying it. Returns amount, destination, description, etc. */
+    async decodeInvoice(paymentRequest) {
+        return this.request("GET", `/v1/payreq/${paymentRequest}`);
+    }
+}
+//# sourceMappingURL=lnd.js.map

package/dist/lnd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lnd.js","sourceRoot":"","sources":["../src/lnd.ts"],"names":[],"mappings":"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"}

package/dist/payment-provider.d.ts

@@ -0,0 +1,23 @@
+export interface PaymentResult {
+    /** Hex-encoded preimage proving payment was made */
+    preimage: string;
+    /** Hex-encoded payment hash identifying this payment */
+    paymentHash: string;
+    status: string;
+}
+/**
+ * Interface for any Lightning payment backend.
+ * Implement this to add support for payment methods beyond LND,
+ * such as Nostr Wallet Connect (NWC) or Lightning Node Connect (LNC).
+ */
+export interface PaymentProvider {
+    /** Pays a BOLT11 Lightning invoice and returns the preimage as proof of payment */
+    payInvoice(paymentRequest: string): Promise<PaymentResult>;
+    /**
+     * Returns the invoice amount in satoshis by decoding the BOLT11 invoice.
+     * Used for pre-payment amount validation. If not implemented, the client
+     * falls back to local BOLT11 parsing (less reliable).
+     */
+    getInvoiceAmountSats?(paymentRequest: string): Promise<number>;
+}
+//# sourceMappingURL=payment-provider.d.ts.map

package/dist/payment-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-provider.d.ts","sourceRoot":"","sources":["../src/payment-provider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE3D;;;;OAIG;IACH,oBAAoB,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAChE"}

package/dist/payment-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=payment-provider.js.map

package/dist/payment-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-provider.js","sourceRoot":"","sources":["../src/payment-provider.ts"],"names":[],"mappings":""}

package/dist/spending.d.ts

@@ -0,0 +1,23 @@
+export interface SpendingLimit {
+    maxPerPaymentSats: number;
+    maxTotalSats: number;
+    maxPaymentsPerMinute: number;
+}
+export interface SpendingRecord {
+    amount: number;
+    url: string;
+    timestamp: number;
+}
+export declare class SpendingTracker {
+    private limits;
+    private history;
+    private totalSpent;
+    constructor(limits: SpendingLimit);
+    check(amountSats: number): void;
+    record(amountSats: number, url: string): void;
+    get spent(): number;
+    get remaining(): number;
+    get paymentCount(): number;
+    reset(): void;
+}
+//# sourceMappingURL=spending.d.ts.map

package/dist/spending.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spending.d.ts","sourceRoot":"","sources":["../src/spending.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,eAAe;IAId,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,UAAU,CAAK;gBAEH,MAAM,EAAE,aAAa;IAEzC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAwB/B,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAmB7C,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,KAAK,IAAI,IAAI;CAId"}

package/dist/spending.js

@@ -0,0 +1,51 @@
+import { L402BudgetError } from "./errors.js";
+export class SpendingTracker {
+    limits;
+    history = [];
+    totalSpent = 0;
+    constructor(limits) {
+        this.limits = limits;
+    }
+    check(amountSats) {
+        if (amountSats > this.limits.maxPerPaymentSats) {
+            throw new L402BudgetError(`Payment of ${amountSats} sats exceeds per-payment limit of ${this.limits.maxPerPaymentSats} sats`);
+        }
+        if (this.totalSpent + amountSats > this.limits.maxTotalSats) {
+            throw new L402BudgetError(`Payment of ${amountSats} sats would exceed total budget. Spent: ${this.totalSpent}/${this.limits.maxTotalSats} sats`);
+        }
+        const oneMinuteAgo = Date.now() - 60_000;
+        const recentPayments = this.history.filter((r) => r.timestamp > oneMinuteAgo);
+        if (recentPayments.length >= this.limits.maxPaymentsPerMinute) {
+            throw new L402BudgetError(`Rate limit: ${this.limits.maxPaymentsPerMinute} payments per minute exceeded`);
+        }
+    }
+    record(amountSats, url) {
+        const now = Date.now();
+        this.history.push({
+            amount: amountSats,
+            url,
+            timestamp: now,
+        });
+        this.totalSpent += amountSats;
+        // Prune records older than 1 minute (only needed for rate limiting)
+        const oneMinuteAgo = now - 60_000;
+        const firstRecentIndex = this.history.findIndex((r) => r.timestamp > oneMinuteAgo);
+        if (firstRecentIndex > 0) {
+            this.history = this.history.slice(firstRecentIndex);
+        }
+    }
+    get spent() {
+        return this.totalSpent;
+    }
+    get remaining() {
+        return this.limits.maxTotalSats - this.totalSpent;
+    }
+    get paymentCount() {
+        return this.history.length;
+    }
+    reset() {
+        this.history = [];
+        this.totalSpent = 0;
+    }
+}
+//# sourceMappingURL=spending.js.map

package/dist/spending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spending.js","sourceRoot":"","sources":["../src/spending.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAc9C,MAAM,OAAO,eAAe;IAIN;IAHZ,OAAO,GAAqB,EAAE,CAAC;IAC/B,UAAU,GAAG,CAAC,CAAC;IAEvB,YAAoB,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAE7C,KAAK,CAAC,UAAkB;QACtB,IAAI,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;YAC/C,MAAM,IAAI,eAAe,CACvB,cAAc,UAAU,sCAAsC,IAAI,CAAC,MAAM,CAAC,iBAAiB,OAAO,CACnG,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,GAAG,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;YAC5D,MAAM,IAAI,eAAe,CACvB,cAAc,UAAU,2CAA2C,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,OAAO,CACtH,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;QACzC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CACxC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,YAAY,CAClC,CAAC;QACF,IAAI,cAAc,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;YAC9D,MAAM,IAAI,eAAe,CACvB,eAAe,IAAI,CAAC,MAAM,CAAC,oBAAoB,+BAA+B,CAC/E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,CAAC,UAAkB,EAAE,GAAW;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,MAAM,EAAE,UAAU;YAClB,GAAG;YACH,SAAS,EAAE,GAAG;SACf,CAAC,CAAC;QACH,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC;QAE9B,oEAAoE;QACpE,MAAM,YAAY,GAAG,GAAG,GAAG,MAAM,CAAC;QAClC,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAC7C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,YAAY,CAClC,CAAC;QACF,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC;IACpD,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAClB,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;IACtB,CAAC;CACF"}

package/dist/token-cache.d.ts

@@ -0,0 +1,16 @@
+export interface CachedToken {
+    macaroon: string;
+    preimage: string;
+    url: string;
+    createdAt: number;
+    expiresAt?: number;
+}
+export declare class TokenCache {
+    private tokens;
+    get(url: string): CachedToken | undefined;
+    set(url: string, macaroon: string, preimage: string, ttlMs?: number): void;
+    delete(url: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=token-cache.d.ts.map

package/dist/token-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.d.ts","sourceRoot":"","sources":["../src/token-cache.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAkC;IAEhD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAYzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAe1E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/token-cache.js

@@ -0,0 +1,35 @@
+export class TokenCache {
+    tokens = new Map();
+    get(url) {
+        const token = this.tokens.get(url);
+        if (!token)
+            return undefined;
+        if (token.expiresAt && Date.now() > token.expiresAt) {
+            this.tokens.delete(url);
+            return undefined;
+        }
+        return token;
+    }
+    set(url, macaroon, preimage, ttlMs) {
+        const token = {
+            macaroon,
+            preimage,
+            url,
+            createdAt: Date.now(),
+        };
+        if (ttlMs) {
+            token.expiresAt = Date.now() + ttlMs;
+        }
+        this.tokens.set(url, token);
+    }
+    delete(url) {
+        return this.tokens.delete(url);
+    }
+    clear() {
+        this.tokens.clear();
+    }
+    get size() {
+        return this.tokens.size;
+    }
+}
+//# sourceMappingURL=token-cache.js.map

package/dist/token-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.js","sourceRoot":"","sources":["../src/token-cache.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,UAAU;IACb,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEhD,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACpD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,QAAgB,EAAE,QAAgB,EAAE,KAAc;QACjE,MAAM,KAAK,GAAgB;YACzB,QAAQ;YACR,QAAQ;YACR,GAAG;YACH,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QACvC,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@satpath/gateless",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Sovereign L402 payments for AI agents on Lightning",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "test": "tsc && node dist/test/test-e2e.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "lightning",
+    "bitcoin",
+    "l402",
+    "lsat",
+    "macaroon",
+    "ai-agent",
+    "payments",
+    "lnd",
+    "micropayments"
+  ],
+  "author": "satpath",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/satpathdev/gateless"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  }
+}