@lunora/x402 1.0.0-alpha.4 → 1.0.0-alpha.40

package/LICENSE.md

@@ -108,4 +108,22 @@ specific language governing permissions and limitations under the License.
 <!-- /DEPENDENCIES -->
 
 <!-- TYPE_DEPENDENCIES -->
+
+# Licenses of bundled types
+The published @lunora/x402 artifact additionally contains code with the following licenses:
+Apache-2.0
+
+# Bundled types:
+## @x402/evm
+License: Apache-2.0
+By: x402 Foundation
+Repository: https://github.com/x402-foundation/x402
+
+---------------------------------------
+
+## @x402/svm
+License: Apache-2.0
+By: x402 Foundation
+Repository: https://github.com/x402-foundation/x402
+
 <!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -25,6 +25,24 @@ The root export (`@lunora/x402`) carries only the shared config/types
 (`.x402({ price })`), and MCP tools behind a USDC price; the **pay** rail signs and
 retries `402` challenges under a mandatory spend policy.
 
+## Install
+
+The chain toolchains are **optional peers**, so an EVM-only deployment never
+installs Solana's (heavy) toolchain and vice versa. Install the pair your
+network family needs alongside the package:
+
+```bash
+pnpm add @lunora/x402                       # protocol core only
+pnpm add @x402/evm viem                     # + EVM networks (Base, Arbitrum, …)
+pnpm add @x402/svm @solana/kit              # + Solana networks
+pnpm add @coinbase/cdp-sdk                  # + CDP-managed custody (EVM)
+```
+
+Missing a peer fails with an `ENV_INVALID` error naming exactly what to install.
+Note that TypeScript needs the same peers present to resolve the pay rail's
+signer types (`ClientSvmSigner` resolves through `@solana/kit`); with neither
+family installed, compile the package's declarations under `skipLibCheck`.
+
 ## Networks & custody
 
 - **EVM** (Base, Arbitrum, Ethereum, Polygon, …) is signed via [`@x402/evm`](https://npmjs.com/package/@x402/evm) + [viem](https://viem.sh); pass a raw CAIP-2 id for chains without a friendly alias.

package/dist/charge/index.d.mts

@@ -1,112 +1,136 @@
-import { F as FacilitatorConfig, c as X402ChargeConfig, f as X402Price } from "../packem_shared/config.d-5Nqi5iox.mjs";
-export { type C as Caip2, D as DEFAULT_FACILITATOR_URL, type a as EvmAddress, type P as PaymentEventRow, type d as X402Network, type g as X402Receipt, type h as X402ReceiptSink, type i as X402Recipient, k as isEvmNetwork, l as isSvmNetwork, r as resolveFacilitatorUrl, t as toCaip2, x as toPaymentEventRow, y as toReceipt } from "../packem_shared/config.d-5Nqi5iox.mjs";
+import { F as FacilitatorConfig, q as X402ChargeConfig, h as X402Price } from "../packem_shared/index.d-CzQaqaP6.mjs";
+export { type b as Caip2, c as DEFAULT_FACILITATOR_URL,
+/**
+ * `@lunora/x402/charge` — the charge rail (server side).
+ *
+ * A Lunora deployment gates a resource (an HTTP-action route, a procedure, or
+ * an MCP tool) behind a USDC price: it returns `402 Payment Required` with a
+ * `PAYMENT-REQUIRED` header, verifies the client's `X-PAYMENT` payload (via a
+ * facilitator), runs the handler, settles, and attaches `X-PAYMENT-RESPONSE`.
+ *
+ * `withX402` gates a Lunora HTTP action; `createChargeMiddleware` is the
+ * framework-agnostic core for other surfaces (procedures, MCP tools).
+ */
+type E as EvmAddress, type P as PaymentEventRow, type g as X402Network, type s as X402Receipt, type v as X402ReceiptSink,
+/**
+ * `@lunora/x402/charge` — the charge rail (server side).
+ *
+ * A Lunora deployment gates a resource (an HTTP-action route, a procedure, or
+ * an MCP tool) behind a USDC price: it returns `402 Payment Required` with a
+ * `PAYMENT-REQUIRED` header, verifies the client's `X-PAYMENT` payload (via a
+ * facilitator), runs the handler, settles, and attaches `X-PAYMENT-RESPONSE`.
+ *
+ * `withX402` gates a Lunora HTTP action; `createChargeMiddleware` is the
+ * framework-agnostic core for other surfaces (procedures, MCP tools).
+ */
+type w as X402Recipient, n as isEvmNetwork, o as isSvmNetwork, p as resolveFacilitatorUrl, t as toCaip2, x as toPaymentEventRow, y as toReceipt } from "../packem_shared/index.d-CzQaqaP6.mjs";
 import { HTTPFacilitatorClient } from '@x402/core/server';
 import { RouteConfig } from '@x402/core/http';
-import '@x402/evm';
-import '@x402/svm';
 import '@x402/core/client';
 import '@x402/core/types';
+import '@solana/accounts';
 /**
-* Build an `@x402/core` facilitator client from Lunora's {@link FacilitatorConfig}.
-*
-* `config.headers` (e.g. a CDP bearer token) are applied to every facilitator
-* call — `@x402/core` splits auth per endpoint (`verify` / `settle` /
-* `supported`), so the same header map is handed to each. With no config the
-* client points at the public {@link resolveFacilitatorUrl default} and sends no
-* auth headers.
-* @experimental
-*/
+ * Build an `@x402/core` facilitator client from Lunora's {@link FacilitatorConfig}.
+ *
+ * `config.headers` (e.g. a CDP bearer token) are applied to every facilitator
+ * call — `@x402/core` splits auth per endpoint (`verify` / `settle` /
+ * `supported`), so the same header map is handed to each. With no config the
+ * client points at the public {@link resolveFacilitatorUrl default} and sends no
+ * auth headers.
+ * @experimental
+ */
 declare const createFacilitatorClient: (config?: FacilitatorConfig) => HTTPFacilitatorClient;
 /**
-* A handler shaped like a Lunora HTTP action: `(context, request) => Response`.
-* @experimental
-*/
+ * A handler shaped like a Lunora HTTP action: `(context, request) => Response`.
+ * @experimental
+ */
 type HttpActionHandler<Context> = (context: Context, request: Request) => Promise<Response> | Response;
 /**
-* Gate `handler` behind an x402 paywall described by `config`. Returns a handler
-* of the same shape, ready to pass to `httpAction`.
-* @experimental
-*/
+ * Gate `handler` behind an x402 paywall described by `config`. Returns a handler
+ * of the same shape, ready to pass to `httpAction`.
+ * @experimental
+ */
 declare const withX402: <Context>(config: X402ChargeConfig, handler: HttpActionHandler<Context>) => HttpActionHandler<Context>;
 /**
-* Runs the protected resource handler, producing the Response to gate.
-* @experimental
-*/
+ * Runs the protected resource handler, producing the Response to gate.
+ * @experimental
+ */
 type ChargeHandler = () => Promise<Response> | Response;
 /**
-* Per-request platform seams `handle` can use, beyond the request/handler pair.
-* @experimental
-*/
+ * Per-request platform seams `handle` can use, beyond the request/handler pair.
+ * @experimental
+ */
 interface ChargeHandlerDeps {
   /**
-  * Keep background work (the receipt sink) alive past the response — the
-  * request's `ctx.waitUntil`. Absent on paths with no platform execution
-  * context reaching the middleware (e.g. today's HTTP-action rail).
-  */
+   * Keep background work (the receipt sink) alive past the response — the
+   * request's `ctx.waitUntil`. Absent on paths with no platform execution
+   * context reaching the middleware (e.g. today's HTTP-action rail).
+   */
   readonly waitUntil?: (promise: Promise<unknown>) => void;
 }
 /**
-* A prepared, initialised paywall. Build once (it fetches facilitator support), reuse per request.
-* @experimental
-*/
+ * A prepared, initialised paywall. Build once (it fetches facilitator support), reuse per request.
+ * @experimental
+ */
 interface ChargeMiddleware {
   /** Gate `request`: challenge / verify / settle around `runHandler`. */
   handle: (request: Request, runHandler: ChargeHandler, deps?: ChargeHandlerDeps) => Promise<Response>;
 }
 /**
-* Route metadata a caller can layer onto the generated catch-all route. The
-* procedure gate sets `resource` to the `functionPath` so the x402 challenge
-* names the paid function (x402 core falls back to the request URL otherwise —
-* every RPC POSTs to the same `/_lunora/rpc`, so the URL can't tell two paid
-* procedures apart).
-* @experimental
-*/
+ * Route metadata a caller can layer onto the generated catch-all route. The
+ * procedure gate sets `resource` to the `functionPath` so the x402 challenge
+ * names the paid function (x402 core falls back to the request URL otherwise —
+ * every RPC POSTs to the same `/_lunora/rpc`, so the URL can't tell two paid
+ * procedures apart).
+ * @experimental
+ */
 type ChargeRouteOverrides = Pick<RouteConfig, "description" | "resource">;
 /**
-* Behaviour knobs for {@link createChargeMiddleware} beyond route metadata.
-* @experimental
-*/
+ * Behaviour knobs for {@link createChargeMiddleware} beyond route metadata.
+ * @experimental
+ */
 interface ChargeMiddlewareOptions {
   /**
-  * Settle the verified payment **before** dispatching `runHandler`, instead
-  * of after. Use this for a mutation/procedure gate: a settlement failure
-  * then means the handler never runs at all, so a paid mutation's writes can
-  * never be committed without payment (the free-execution gap X402-04
-  * closes). Once settlement succeeds the payment is final (on-chain) — a
-  * handler failure after that point is a normal application error, not a
-  * payment to unwind: there is nothing left to cancel, so it is not caught
-  * here and simply propagates.
-  *
-  * Default `false` (settle-after, the historical behaviour): the handler's
-  * response is passed to settlement as transport context (`responseHeaders`
-  * — read by some schemes for settlement overrides), and a handler throw
-  * still releases the verified-but-unsettled payment via
-  * `cancellationDispatcher.cancel`. Because settlement can still fail after
-  * the handler already ran on this path, `.x402()` handlers gated this way
-  * MUST be idempotent or compensatable — see the `@lunora/x402` charge docs.
-  */
+   * Settle the verified payment **before** dispatching `runHandler`, instead
+   * of after. **Default `true`** — a settlement failure then means the handler
+   * never runs at all, so its side effects (writes, LLM calls, mail, push) can
+   * never happen unpaid. This matters because `verifyPayment` only checks the
+   * signed intent, NOT solvency: an underfunded or facilitator-refused payment
+   * passes verify and fails at `/settle`. Once settlement succeeds the payment
+   * is final (on-chain) — a handler failure after that point is a normal
+   * application error, not a payment to unwind: there is nothing left to
+   * cancel, so it is not caught here and simply propagates.
+   *
+   * Set `false` for settle-after: the handler's response is passed to
+   * settlement as transport context (`responseHeaders` — read by some schemes
+   * for settlement overrides), and a handler throw releases the
+   * verified-but-unsettled payment via `cancellationDispatcher.cancel`.
+   * Settlement can still FAIL after the handler already ran on this path, so a
+   * handler gated this way MUST be idempotent or compensatable — opt in only
+   * when you need the response as settlement context and can accept that.
+   */
   readonly settleBeforeHandler?: boolean;
 }
 /**
-* Build and initialise a {@link ChargeMiddleware} for `config`. Fetches
-* facilitator support once (via `initialize()`), so call this once per config
-* and reuse the result across requests. `routeOverrides` layers extra route
-* metadata (e.g. `resource`) onto the generated catch-all route; `options`
-* controls settlement ordering (see {@link ChargeMiddlewareOptions}).
-* @experimental
-*/
+ * Build and initialise a {@link ChargeMiddleware} for `config`. Fetches
+ * facilitator support once (via `initialize()`), so call this once per config
+ * and reuse the result across requests. `routeOverrides` layers extra route
+ * metadata (e.g. `resource`) onto the generated catch-all route; `options`
+ * controls settlement ordering (see {@link ChargeMiddlewareOptions}).
+ * @experimental
+ */
 declare const createChargeMiddleware: (config: X402ChargeConfig, routeOverrides?: ChargeRouteOverrides, options?: ChargeMiddlewareOptions) => Promise<ChargeMiddleware>;
 /**
-* Charge config for the procedure gate: the worker-level settlement vocabulary
-* (network, recipient, facilitator) minus `price` — price is per-procedure and
-* arrives with each {@link X402ProcedureSpec}.
-* @experimental
-*/
+ * Charge config for the procedure gate: the worker-level settlement vocabulary
+ * (network, recipient, facilitator) minus `price` — price is per-procedure and
+ * arrives with each {@link X402ProcedureSpec}.
+ * @experimental
+ */
 type X402ProcedureChargeConfig = Omit<X402ChargeConfig, "price">;
 /**
-* The per-RPC charge spec the runtime passes the gate for each paid dispatch.
-* @experimental
-*/
+ * The per-RPC charge spec the runtime passes the gate for each paid dispatch.
+ * @experimental
+ */
 interface X402ProcedureSpec {
   /** The `file:function` id of the paid procedure; becomes the x402 challenge `resource`. */
   readonly functionPath: string;
@@ -114,26 +138,62 @@ interface X402ProcedureSpec {
   readonly price: X402Price;
 }
 /**
-* Gate one paid RPC. Returns a real `402` + `PAYMENT-REQUIRED` challenge when the
-* request is unpaid, or the dispatched response (with `X-PAYMENT-RESPONSE`
-* attached) once the client's `X-PAYMENT` is verified and settled. `dispatch`
-* runs the actual shard forward — settlement happens **before** `dispatch` is
-* invoked (settle-first), so a settlement failure means the shard forward
-* (the mutation's commit) never runs at all — no committed-but-unpaid write is
-* possible. `deps.waitUntil`, when supplied (the request's `ctx.waitUntil`),
-* keeps the opt-in receipt sink alive past the response.
-* @experimental
-*/
+ * Gate one paid RPC. Returns a real `402` + `PAYMENT-REQUIRED` challenge when the
+ * request is unpaid, or the dispatched response (with `X-PAYMENT-RESPONSE`
+ * attached) once the client's `X-PAYMENT` is verified and settled. `dispatch`
+ * runs the actual shard forward — settlement happens **before** `dispatch` is
+ * invoked (settle-first), so a settlement failure means the shard forward
+ * (the mutation's commit) never runs at all — no committed-but-unpaid write is
+ * possible. `deps.waitUntil`, when supplied (the request's `ctx.waitUntil`),
+ * keeps the opt-in receipt sink alive past the response.
+ * @experimental
+ */
 type X402ProcedureChargeGate = (request: Request, spec: X402ProcedureSpec, dispatch: () => Promise<Response>, deps?: ChargeHandlerDeps) => Promise<Response>;
 /**
-* Build the injectable procedure charge gate for `config`. One initialised
-* {@link ChargeMiddleware} is memoised per `functionPath` (each bakes that
-* function's price + `resource`), since `createChargeMiddleware` fetches
-* facilitator support on first use. A failed init is not cached, so a transient
-* facilitator outage retries on the next request. Settlement runs before
-* `dispatch` (`settleBeforeHandler: true`) since `dispatch` commits the
-* procedure's real mutation — see `createChargeMiddleware`'s `ChargeMiddlewareOptions`.
-* @experimental
-*/
+ * Build the injectable procedure charge gate for `config`. One initialised
+ * {@link ChargeMiddleware} is memoised per `functionPath` (each bakes that
+ * function's price + `resource`), since `createChargeMiddleware` fetches
+ * facilitator support on first use. A failed init is not cached, so a transient
+ * facilitator outage retries on the next request. Settlement runs before
+ * `dispatch` (the `settleBeforeHandler` default) since `dispatch` commits the
+ * procedure's real mutation — see `createChargeMiddleware`'s `ChargeMiddlewareOptions`.
+ * @experimental
+ */
 declare const createProcedureChargeGate: (config: X402ProcedureChargeConfig) => X402ProcedureChargeGate;
-export { type ChargeHandler, type ChargeHandlerDeps, type ChargeMiddleware, type ChargeMiddlewareOptions, type ChargeRouteOverrides, type FacilitatorConfig, type HttpActionHandler, type X402ChargeConfig, type X402Price, type X402ProcedureChargeConfig, type X402ProcedureChargeGate, type X402ProcedureSpec, createChargeMiddleware, createFacilitatorClient, createProcedureChargeGate, withX402 };
+export { type ChargeHandler, type ChargeHandlerDeps, type ChargeMiddleware, type ChargeMiddlewareOptions, type ChargeRouteOverrides,
+/**
+ * `@lunora/x402/charge` — the charge rail (server side).
+ *
+ * A Lunora deployment gates a resource (an HTTP-action route, a procedure, or
+ * an MCP tool) behind a USDC price: it returns `402 Payment Required` with a
+ * `PAYMENT-REQUIRED` header, verifies the client's `X-PAYMENT` payload (via a
+ * facilitator), runs the handler, settles, and attaches `X-PAYMENT-RESPONSE`.
+ *
+ * `withX402` gates a Lunora HTTP action; `createChargeMiddleware` is the
+ * framework-agnostic core for other surfaces (procedures, MCP tools).
+ */
+type FacilitatorConfig, type HttpActionHandler,
+/**
+ * `@lunora/x402/charge` — the charge rail (server side).
+ *
+ * A Lunora deployment gates a resource (an HTTP-action route, a procedure, or
+ * an MCP tool) behind a USDC price: it returns `402 Payment Required` with a
+ * `PAYMENT-REQUIRED` header, verifies the client's `X-PAYMENT` payload (via a
+ * facilitator), runs the handler, settles, and attaches `X-PAYMENT-RESPONSE`.
+ *
+ * `withX402` gates a Lunora HTTP action; `createChargeMiddleware` is the
+ * framework-agnostic core for other surfaces (procedures, MCP tools).
+ */
+type X402ChargeConfig,
+/**
+ * `@lunora/x402/charge` — the charge rail (server side).
+ *
+ * A Lunora deployment gates a resource (an HTTP-action route, a procedure, or
+ * an MCP tool) behind a USDC price: it returns `402 Payment Required` with a
+ * `PAYMENT-REQUIRED` header, verifies the client's `X-PAYMENT` payload (via a
+ * facilitator), runs the handler, settles, and attaches `X-PAYMENT-RESPONSE`.
+ *
+ * `withX402` gates a Lunora HTTP action; `createChargeMiddleware` is the
+ * framework-agnostic core for other surfaces (procedures, MCP tools).
+ */
+type X402Price, type X402ProcedureChargeConfig, type X402ProcedureChargeGate, type X402ProcedureSpec, createChargeMiddleware, createFacilitatorClient, createProcedureChargeGate, withX402 };