l402-server 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,300 @@
+/**
+ * Public types for the L402 server SDK. Mirrors the wire contract of
+ * Lightning Enable's hosted producer API at
+ * https://api.lightningenable.com/api/l402/challenges.
+ */
+/**
+ * Configuration for the {@link L402Server} client.
+ */
+interface L402ServerOptions {
+    /**
+     * Your Lightning Enable merchant API key. Required.
+     *
+     * Generate one at https://api.lightningenable.com/dashboard/settings.
+     * Tied to a specific merchant + an Agentic Commerce plan (L402 must be
+     * enabled on the plan).
+     */
+    apiKey: string;
+    /**
+     * Base URL for the producer API. Defaults to the hosted Lightning Enable
+     * instance. Override for testing against a local dev instance.
+     *
+     * @default "https://api.lightningenable.com"
+     */
+    baseUrl?: string;
+    /**
+     * Per-request timeout in milliseconds. Defaults to 10s.
+     *
+     * @default 10000
+     */
+    timeoutMs?: number;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch`. Inject a
+     * mock here for tests, or a fetch-with-retry wrapper if you want
+     * application-level retry policy on top of the SDK's per-call timeout.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Arguments for {@link L402Server.createChallenge}.
+ */
+interface CreateChallengeArgs {
+    /**
+     * The resource the challenge is for, typically the request path. Bound as
+     * a caveat in the macaroon so the resulting token can only access this
+     * exact resource. Example: "/api/weather/forecast".
+     */
+    resource: string;
+    /**
+     * Price in satoshis. Must be ≥ 1.
+     */
+    priceSats: number;
+    /**
+     * Optional description embedded in the Lightning invoice. Visible to the
+     * payer in their wallet UI.
+     */
+    description?: string;
+    /**
+     * Optional idempotency key. If the same key is sent twice within the
+     * invoice's expiry window, the same challenge is returned (no duplicate
+     * invoice). Useful for retry-safe issue from a middleware. Truncated to
+     * 256 chars server-side.
+     *
+     * Defaults to none — the server falls back to client IP for
+     * deduplication, which is usually correct for middleware use.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * The 402 challenge returned from {@link L402Server.createChallenge}.
+ * Present this to the calling client/agent; they must pay the Lightning
+ * invoice to obtain the preimage required for L402 authentication.
+ */
+interface Challenge {
+    /**
+     * BOLT11 Lightning invoice the client must pay.
+     */
+    invoice: string;
+    /**
+     * Base64-encoded macaroon containing the payment hash and caveats
+     * (resource, merchant_id, amount_sats). Sent as part of the
+     * `WWW-Authenticate` header on the 402 response.
+     */
+    macaroon: string;
+    /**
+     * Payment hash (hex) — links the macaroon to the invoice. Useful for
+     * matching incoming payment-confirmation webhooks or for debugging.
+     */
+    paymentHash: string;
+    /**
+     * When the Lightning invoice expires (ISO 8601). After this time the
+     * invoice can no longer be paid and a fresh challenge must be issued.
+     */
+    expiresAt: string;
+    /**
+     * The resource the challenge is bound to. Echoed back from the request
+     * so middleware can build the 402 response header without re-tracking
+     * the original argument.
+     */
+    resource: string;
+    /**
+     * Price in satoshis. Echoed from the request.
+     */
+    priceSats: number;
+    /**
+     * MPP-formatted `WWW-Authenticate` challenge header value. Only present
+     * if the server has MPP support enabled. Clients that speak MPP can
+     * consume this directly without needing to know about macaroons.
+     */
+    mppChallenge?: string;
+}
+/**
+ * Arguments for {@link L402Server.verifyToken}.
+ */
+interface VerifyTokenArgs {
+    /**
+     * Base64-encoded macaroon from the L402 credential
+     * (`Authorization: L402 <macaroon>:<preimage>`).
+     *
+     * Omit only if verifying an MPP-style preimage-only token — and only if
+     * your Lightning Enable instance has MPP enabled. Defaults to required.
+     */
+    macaroon?: string;
+    /**
+     * Hex-encoded payment preimage (64 chars).
+     */
+    preimage: string;
+}
+/**
+ * Result from {@link L402Server.verifyToken}. The producer API returns
+ * `200 OK` for both valid and invalid tokens — `valid` is the gate.
+ */
+interface VerificationResult {
+    /**
+     * Whether the token is valid. When `false`, `error` is populated.
+     */
+    valid: boolean;
+    /**
+     * Human-readable failure reason. Only populated when `valid === false`.
+     * Examples: "Invalid preimage", "Token bound to a different resource",
+     * "Macaroon signature invalid".
+     */
+    error?: string;
+    /**
+     * The resource the token was bound to (from the macaroon's path caveat).
+     * Only populated when `valid === true`. Use this to assert the token
+     * matches the resource the caller is actually requesting.
+     */
+    resource?: string;
+    /**
+     * Merchant ID the token was bound to. Only populated when valid.
+     */
+    merchantId?: number;
+    /**
+     * Amount the token was issued for, in satoshis. Only populated when
+     * valid.
+     */
+    amountSats?: number;
+    /**
+     * Payment hash from the macaroon identifier.
+     */
+    paymentHash?: string;
+}
+
+/**
+ * Server-side client for Lightning Enable's L402 producer API. Wraps two
+ * endpoints:
+ *
+ * - {@link createChallenge} → `POST /api/l402/challenges` — mint a
+ *   Lightning invoice + macaroon for a given resource and price.
+ * - {@link verifyToken} → `POST /api/l402/challenges/verify` — validate
+ *   an incoming L402 token (macaroon + preimage).
+ *
+ * **No protocol logic lives in this SDK.** The Lightning Enable backend
+ * signs macaroons, mints invoices, verifies preimages, and tracks consumed
+ * tokens for replay protection. The SDK is purely an HTTP client with
+ * typed inputs/outputs.
+ *
+ * @example
+ * ```ts
+ * import { L402Server } from "l402-server";
+ *
+ * const l402 = new L402Server({
+ *   apiKey: process.env.LIGHTNING_ENABLE_API_KEY!,
+ * });
+ *
+ * // On an unauthenticated incoming request:
+ * const challenge = await l402.createChallenge({
+ *   resource: "/api/premium/weather",
+ *   priceSats: 100,
+ *   description: "Premium weather forecast",
+ * });
+ *
+ * // Send back as 402 Payment Required with the challenge headers.
+ *
+ * // When client comes back with Authorization: L402 mac:preimage,
+ * // parse and verify:
+ * const verification = await l402.verifyToken({
+ *   macaroon: parsedMacaroon,
+ *   preimage: parsedPreimage,
+ * });
+ * if (verification.valid) {
+ *   // Serve the response.
+ * }
+ * ```
+ */
+declare class L402Server {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: L402ServerOptions);
+    /**
+     * 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.
+     */
+    createChallenge(args: CreateChallengeArgs): Promise<Challenge>;
+    /**
+     * 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.
+     */
+    verifyToken(args: VerifyTokenArgs): Promise<VerificationResult>;
+    private request;
+    private throwForStatus;
+}
+
+/**
+ * Base error class for all SDK-thrown errors. Distinguishable from arbitrary
+ * `Error` instances via `instanceof L402ServerError`.
+ */
+declare class L402ServerError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown on `401 Unauthorized` from the producer API. Almost always means
+ * the merchant API key is missing, malformed, expired, or revoked.
+ */
+declare class L402AuthError extends L402ServerError {
+    constructor(message?: string);
+}
+/**
+ * Thrown on `403 Forbidden` from the producer API. Means the merchant
+ * exists and the key is valid, but L402 is not enabled on their plan.
+ * The merchant needs to upgrade to an Agentic Commerce plan.
+ */
+declare class L402PlanError extends L402ServerError {
+    /**
+     * The plan tier currently on the merchant (e.g., "starter").
+     * Populated when the server includes it in the error payload.
+     */
+    readonly currentPlan?: string;
+    constructor(message?: string, currentPlan?: string);
+}
+/**
+ * Thrown for transport-level failures: timeout, DNS error, TLS error,
+ * unreachable host. The `cause` carries the original error.
+ */
+declare class L402NetworkError extends L402ServerError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when the server returns a non-success status that doesn't map to
+ * a more specific error class above (e.g., 400 with a request-validation
+ * problem, 500 from upstream wallet failure, 429 from rate limiting).
+ */
+declare class L402ApiError extends L402ServerError {
+    /**
+     * HTTP status code returned by the producer API.
+     */
+    readonly statusCode: number;
+    /**
+     * Raw response body, useful for debugging. May be a parsed object or a
+     * string if parsing failed.
+     */
+    readonly responseBody?: unknown;
+    constructor(statusCode: number, message: string, responseBody?: unknown);
+}
+
+export { type Challenge, type CreateChallengeArgs, L402ApiError, L402AuthError, L402NetworkError, L402PlanError, L402Server, L402ServerError, type L402ServerOptions, type VerificationResult, type VerifyTokenArgs };

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Public types for the L402 server SDK. Mirrors the wire contract of
+ * Lightning Enable's hosted producer API at
+ * https://api.lightningenable.com/api/l402/challenges.
+ */
+/**
+ * Configuration for the {@link L402Server} client.
+ */
+interface L402ServerOptions {
+    /**
+     * Your Lightning Enable merchant API key. Required.
+     *
+     * Generate one at https://api.lightningenable.com/dashboard/settings.
+     * Tied to a specific merchant + an Agentic Commerce plan (L402 must be
+     * enabled on the plan).
+     */
+    apiKey: string;
+    /**
+     * Base URL for the producer API. Defaults to the hosted Lightning Enable
+     * instance. Override for testing against a local dev instance.
+     *
+     * @default "https://api.lightningenable.com"
+     */
+    baseUrl?: string;
+    /**
+     * Per-request timeout in milliseconds. Defaults to 10s.
+     *
+     * @default 10000
+     */
+    timeoutMs?: number;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch`. Inject a
+     * mock here for tests, or a fetch-with-retry wrapper if you want
+     * application-level retry policy on top of the SDK's per-call timeout.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Arguments for {@link L402Server.createChallenge}.
+ */
+interface CreateChallengeArgs {
+    /**
+     * The resource the challenge is for, typically the request path. Bound as
+     * a caveat in the macaroon so the resulting token can only access this
+     * exact resource. Example: "/api/weather/forecast".
+     */
+    resource: string;
+    /**
+     * Price in satoshis. Must be ≥ 1.
+     */
+    priceSats: number;
+    /**
+     * Optional description embedded in the Lightning invoice. Visible to the
+     * payer in their wallet UI.
+     */
+    description?: string;
+    /**
+     * Optional idempotency key. If the same key is sent twice within the
+     * invoice's expiry window, the same challenge is returned (no duplicate
+     * invoice). Useful for retry-safe issue from a middleware. Truncated to
+     * 256 chars server-side.
+     *
+     * Defaults to none — the server falls back to client IP for
+     * deduplication, which is usually correct for middleware use.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * The 402 challenge returned from {@link L402Server.createChallenge}.
+ * Present this to the calling client/agent; they must pay the Lightning
+ * invoice to obtain the preimage required for L402 authentication.
+ */
+interface Challenge {
+    /**
+     * BOLT11 Lightning invoice the client must pay.
+     */
+    invoice: string;
+    /**
+     * Base64-encoded macaroon containing the payment hash and caveats
+     * (resource, merchant_id, amount_sats). Sent as part of the
+     * `WWW-Authenticate` header on the 402 response.
+     */
+    macaroon: string;
+    /**
+     * Payment hash (hex) — links the macaroon to the invoice. Useful for
+     * matching incoming payment-confirmation webhooks or for debugging.
+     */
+    paymentHash: string;
+    /**
+     * When the Lightning invoice expires (ISO 8601). After this time the
+     * invoice can no longer be paid and a fresh challenge must be issued.
+     */
+    expiresAt: string;
+    /**
+     * The resource the challenge is bound to. Echoed back from the request
+     * so middleware can build the 402 response header without re-tracking
+     * the original argument.
+     */
+    resource: string;
+    /**
+     * Price in satoshis. Echoed from the request.
+     */
+    priceSats: number;
+    /**
+     * MPP-formatted `WWW-Authenticate` challenge header value. Only present
+     * if the server has MPP support enabled. Clients that speak MPP can
+     * consume this directly without needing to know about macaroons.
+     */
+    mppChallenge?: string;
+}
+/**
+ * Arguments for {@link L402Server.verifyToken}.
+ */
+interface VerifyTokenArgs {
+    /**
+     * Base64-encoded macaroon from the L402 credential
+     * (`Authorization: L402 <macaroon>:<preimage>`).
+     *
+     * Omit only if verifying an MPP-style preimage-only token — and only if
+     * your Lightning Enable instance has MPP enabled. Defaults to required.
+     */
+    macaroon?: string;
+    /**
+     * Hex-encoded payment preimage (64 chars).
+     */
+    preimage: string;
+}
+/**
+ * Result from {@link L402Server.verifyToken}. The producer API returns
+ * `200 OK` for both valid and invalid tokens — `valid` is the gate.
+ */
+interface VerificationResult {
+    /**
+     * Whether the token is valid. When `false`, `error` is populated.
+     */
+    valid: boolean;
+    /**
+     * Human-readable failure reason. Only populated when `valid === false`.
+     * Examples: "Invalid preimage", "Token bound to a different resource",
+     * "Macaroon signature invalid".
+     */
+    error?: string;
+    /**
+     * The resource the token was bound to (from the macaroon's path caveat).
+     * Only populated when `valid === true`. Use this to assert the token
+     * matches the resource the caller is actually requesting.
+     */
+    resource?: string;
+    /**
+     * Merchant ID the token was bound to. Only populated when valid.
+     */
+    merchantId?: number;
+    /**
+     * Amount the token was issued for, in satoshis. Only populated when
+     * valid.
+     */
+    amountSats?: number;
+    /**
+     * Payment hash from the macaroon identifier.
+     */
+    paymentHash?: string;
+}
+
+/**
+ * Server-side client for Lightning Enable's L402 producer API. Wraps two
+ * endpoints:
+ *
+ * - {@link createChallenge} → `POST /api/l402/challenges` — mint a
+ *   Lightning invoice + macaroon for a given resource and price.
+ * - {@link verifyToken} → `POST /api/l402/challenges/verify` — validate
+ *   an incoming L402 token (macaroon + preimage).
+ *
+ * **No protocol logic lives in this SDK.** The Lightning Enable backend
+ * signs macaroons, mints invoices, verifies preimages, and tracks consumed
+ * tokens for replay protection. The SDK is purely an HTTP client with
+ * typed inputs/outputs.
+ *
+ * @example
+ * ```ts
+ * import { L402Server } from "l402-server";
+ *
+ * const l402 = new L402Server({
+ *   apiKey: process.env.LIGHTNING_ENABLE_API_KEY!,
+ * });
+ *
+ * // On an unauthenticated incoming request:
+ * const challenge = await l402.createChallenge({
+ *   resource: "/api/premium/weather",
+ *   priceSats: 100,
+ *   description: "Premium weather forecast",
+ * });
+ *
+ * // Send back as 402 Payment Required with the challenge headers.
+ *
+ * // When client comes back with Authorization: L402 mac:preimage,
+ * // parse and verify:
+ * const verification = await l402.verifyToken({
+ *   macaroon: parsedMacaroon,
+ *   preimage: parsedPreimage,
+ * });
+ * if (verification.valid) {
+ *   // Serve the response.
+ * }
+ * ```
+ */
+declare class L402Server {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: L402ServerOptions);
+    /**
+     * 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.
+     */
+    createChallenge(args: CreateChallengeArgs): Promise<Challenge>;
+    /**
+     * 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.
+     */
+    verifyToken(args: VerifyTokenArgs): Promise<VerificationResult>;
+    private request;
+    private throwForStatus;
+}
+
+/**
+ * Base error class for all SDK-thrown errors. Distinguishable from arbitrary
+ * `Error` instances via `instanceof L402ServerError`.
+ */
+declare class L402ServerError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown on `401 Unauthorized` from the producer API. Almost always means
+ * the merchant API key is missing, malformed, expired, or revoked.
+ */
+declare class L402AuthError extends L402ServerError {
+    constructor(message?: string);
+}
+/**
+ * Thrown on `403 Forbidden` from the producer API. Means the merchant
+ * exists and the key is valid, but L402 is not enabled on their plan.
+ * The merchant needs to upgrade to an Agentic Commerce plan.
+ */
+declare class L402PlanError extends L402ServerError {
+    /**
+     * The plan tier currently on the merchant (e.g., "starter").
+     * Populated when the server includes it in the error payload.
+     */
+    readonly currentPlan?: string;
+    constructor(message?: string, currentPlan?: string);
+}
+/**
+ * Thrown for transport-level failures: timeout, DNS error, TLS error,
+ * unreachable host. The `cause` carries the original error.
+ */
+declare class L402NetworkError extends L402ServerError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when the server returns a non-success status that doesn't map to
+ * a more specific error class above (e.g., 400 with a request-validation
+ * problem, 500 from upstream wallet failure, 429 from rate limiting).
+ */
+declare class L402ApiError extends L402ServerError {
+    /**
+     * HTTP status code returned by the producer API.
+     */
+    readonly statusCode: number;
+    /**
+     * Raw response body, useful for debugging. May be a parsed object or a
+     * string if parsing failed.
+     */
+    readonly responseBody?: unknown;
+    constructor(statusCode: number, message: string, responseBody?: unknown);
+}
+
+export { type Challenge, type CreateChallengeArgs, L402ApiError, L402AuthError, L402NetworkError, L402PlanError, L402Server, L402ServerError, type L402ServerOptions, type VerificationResult, type VerifyTokenArgs };