@puga-labs/x402-mantle-sdk 0.3.7 → 0.3.9

package/dist/types-BWfKovFm.d.cts

@@ -0,0 +1,103 @@
+import { Request, Response, NextFunction } from 'express';
+import { N as NetworkId, P as PaymentRequirements } from './types-BFUqKBBO.cjs';
+
+/** Unique key for a protected route, e.g. "GET /api/protected". */
+type RouteKey = string;
+/** Pricing config for a single route. */
+interface RoutePricingConfig {
+    /** Price in USD cents, e.g. 1 => $0.01. */
+    priceUsdCents: number;
+    /** Network identifier (e.g. "mantle-mainnet"). */
+    network: NetworkId;
+}
+/** Map of route keys to pricing config. */
+type RoutesConfig = Record<RouteKey, RoutePricingConfig>;
+/** Log entry for a successfully settled payment. */
+interface PaymentLogEntry {
+    id: string;
+    from: string;
+    to: string;
+    valueAtomic: string;
+    network: NetworkId;
+    asset: string;
+    route?: RouteKey;
+    txHash?: string;
+    timestamp: number;
+    facilitatorUrl?: string;
+    paymentRequirements?: PaymentRequirements;
+}
+/** Config for optional telemetry (billing/analytics). */
+interface TelemetryConfig {
+    /** Project key from nosubs.ai dashboard. */
+    projectKey: string;
+    /**
+     * Telemetry endpoint URL.
+     * If not specified, uses DEFAULT_TELEMETRY_ENDPOINT (see server/constants.ts).
+     * If both are undefined, telemetry is not sent.
+     */
+    endpoint?: string;
+}
+/** Telemetry event payload for payment_verified. */
+interface TelemetryEvent {
+    event: "payment_verified";
+    ts: number;
+    projectKey: string;
+    network: string;
+    buyer: string;
+    payTo: string;
+    amountAtomic: string;
+    asset: string;
+    decimals: number;
+    nonce: string;
+    route: string;
+    facilitatorType: "hosted" | "self-hosted";
+    facilitatorUrl?: string;
+    facilitatorAddress?: string;
+    txHash?: string;
+    priceUsd?: string;
+}
+/** Config for createPaymentMiddleware. */
+interface PaymentMiddlewareConfig {
+    /** Base URL of facilitator, e.g. https://facilitator.nosubs.ai */
+    facilitatorUrl: string;
+    /** Recipient address (developer). Validated at runtime. */
+    receiverAddress: string;
+    /** Map of protected routes and their pricing. */
+    routes: RoutesConfig;
+    /**
+     * Optional hook called whenever a payment is successfully settled.
+     * You can use this to push logs into your DB / analytics pipeline.
+     */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+    /** Optional: Send usage telemetry for billing/analytics. */
+    telemetry?: TelemetryConfig;
+}
+/**
+ * Minimal config for mantlePaywall() - simplified API for single-route protection.
+ * This is the "sweet path" for Mantle mainnet + USDC with sensible defaults.
+ */
+interface MinimalPaywallOptions {
+    /** Price in USD (e.g. 0.01 for 1 cent). */
+    priceUsd: number;
+    /** Recipient address (developer wallet). Validated at runtime. */
+    payTo: string;
+    /** Optional facilitator URL (defaults to localhost:8080 or NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /**
+     * Optional API key for hosted facilitator billing.
+     * Required when using hosted facilitator (e.g., https://facilitator.x402mantlesdk.xyz).
+     * Not needed for self-hosted facilitator.
+     */
+    apiKey?: string;
+    /** Optional telemetry config. */
+    telemetry?: TelemetryConfig;
+    /** Optional payment settled hook. */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+/**
+ * Express middleware function type for Mantle paywall.
+ * Async function that returns Promise<void>.
+ */
+type MantleMiddleware = (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export type { MantleMiddleware as M, PaymentLogEntry as P, RouteKey as R, TelemetryConfig as T, RoutePricingConfig as a, RoutesConfig as b, TelemetryEvent as c, PaymentMiddlewareConfig as d, MinimalPaywallOptions as e };

package/dist/types-BmK0G74m.d.cts

@@ -0,0 +1,93 @@
+import { N as NetworkId, P as PaymentRequirements } from './types-BFUqKBBO.cjs';
+
+/** Unique key for a protected route, e.g. "GET /api/protected". */
+type RouteKey = string;
+/** Pricing config for a single route. */
+interface RoutePricingConfig {
+    /** Price in USD cents, e.g. 1 => $0.01. */
+    priceUsdCents: number;
+    /** Network identifier (e.g. "mantle-mainnet"). */
+    network: NetworkId;
+}
+/** Map of route keys to pricing config. */
+type RoutesConfig = Record<RouteKey, RoutePricingConfig>;
+/** Log entry for a successfully settled payment. */
+interface PaymentLogEntry {
+    id: string;
+    from: string;
+    to: string;
+    valueAtomic: string;
+    network: NetworkId;
+    asset: string;
+    route?: RouteKey;
+    txHash?: string;
+    timestamp: number;
+    facilitatorUrl?: string;
+    paymentRequirements?: PaymentRequirements;
+}
+/** Config for optional telemetry (billing/analytics). */
+interface TelemetryConfig {
+    /** Project key from nosubs.ai dashboard. */
+    projectKey: string;
+    /**
+     * Telemetry endpoint URL.
+     * If not specified, uses DEFAULT_TELEMETRY_ENDPOINT (see server/constants.ts).
+     */
+    endpoint?: string;
+}
+/**
+ * Minimal config for mantlePaywall() - simplified API for single-route protection.
+ * This is the "sweet path" for Mantle mainnet + USDC with sensible defaults.
+ */
+interface MinimalPaywallOptions {
+    /** Price in USD (e.g. 0.01 for 1 cent). */
+    priceUsd: number;
+    /** Recipient address (developer wallet). Validated at runtime. */
+    payTo: string;
+    /** Optional facilitator URL (defaults to localhost:8080 or NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /**
+     * Optional API key for hosted facilitator billing.
+     * Required when using hosted facilitator (e.g., https://facilitator.x402mantlesdk.xyz).
+     * Not needed for self-hosted facilitator.
+     */
+    apiKey?: string;
+    /** Optional telemetry config. */
+    telemetry?: TelemetryConfig;
+    /** Optional payment settled hook. */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+/** Input for checkPayment function. */
+interface PaymentCheckInput {
+    /** X-PAYMENT header value (base64 encoded), or null if not present. */
+    paymentHeader: string | null;
+    /** Payment requirements for this route. */
+    paymentRequirements: PaymentRequirements;
+    /** Facilitator URL for verification. */
+    facilitatorUrl: string;
+    /** Optional API key for hosted facilitator billing. */
+    apiKey?: string;
+    /** Route key for logging, e.g. "POST /api/generate-image". */
+    routeKey?: RouteKey;
+    /** Network ID for this payment. */
+    network: NetworkId;
+    /** Asset address (ERC-20 token). */
+    asset: string;
+    /** Telemetry config (optional). */
+    telemetry?: TelemetryConfig;
+    /** Payment settled callback (optional). */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+/** Result from checkPayment function. */
+interface PaymentCheckResult {
+    /** Status of the payment check. */
+    status: "require_payment" | "verification_error" | "invalid_payment" | "verified";
+    /** HTTP status code to return. */
+    statusCode: 402 | 500 | 200;
+    /** Response body to return (null if verified). */
+    responseBody: any | null;
+    /** Whether payment is valid (only true if status is "verified"). */
+    isValid: boolean;
+}
+
+export type { MinimalPaywallOptions as M, PaymentLogEntry as P, RouteKey as R, TelemetryConfig as T, RoutePricingConfig as a, RoutesConfig as b, PaymentCheckInput as c, PaymentCheckResult as d };

package/dist/types-CXdNC0Ra.d.ts

@@ -0,0 +1,93 @@
+import { N as NetworkId, P as PaymentRequirements } from './types-BFUqKBBO.js';
+
+/** Unique key for a protected route, e.g. "GET /api/protected". */
+type RouteKey = string;
+/** Pricing config for a single route. */
+interface RoutePricingConfig {
+    /** Price in USD cents, e.g. 1 => $0.01. */
+    priceUsdCents: number;
+    /** Network identifier (e.g. "mantle-mainnet"). */
+    network: NetworkId;
+}
+/** Map of route keys to pricing config. */
+type RoutesConfig = Record<RouteKey, RoutePricingConfig>;
+/** Log entry for a successfully settled payment. */
+interface PaymentLogEntry {
+    id: string;
+    from: string;
+    to: string;
+    valueAtomic: string;
+    network: NetworkId;
+    asset: string;
+    route?: RouteKey;
+    txHash?: string;
+    timestamp: number;
+    facilitatorUrl?: string;
+    paymentRequirements?: PaymentRequirements;
+}
+/** Config for optional telemetry (billing/analytics). */
+interface TelemetryConfig {
+    /** Project key from nosubs.ai dashboard. */
+    projectKey: string;
+    /**
+     * Telemetry endpoint URL.
+     * If not specified, uses DEFAULT_TELEMETRY_ENDPOINT (see server/constants.ts).
+     */
+    endpoint?: string;
+}
+/**
+ * Minimal config for mantlePaywall() - simplified API for single-route protection.
+ * This is the "sweet path" for Mantle mainnet + USDC with sensible defaults.
+ */
+interface MinimalPaywallOptions {
+    /** Price in USD (e.g. 0.01 for 1 cent). */
+    priceUsd: number;
+    /** Recipient address (developer wallet). Validated at runtime. */
+    payTo: string;
+    /** Optional facilitator URL (defaults to localhost:8080 or NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /**
+     * Optional API key for hosted facilitator billing.
+     * Required when using hosted facilitator (e.g., https://facilitator.x402mantlesdk.xyz).
+     * Not needed for self-hosted facilitator.
+     */
+    apiKey?: string;
+    /** Optional telemetry config. */
+    telemetry?: TelemetryConfig;
+    /** Optional payment settled hook. */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+/** Input for checkPayment function. */
+interface PaymentCheckInput {
+    /** X-PAYMENT header value (base64 encoded), or null if not present. */
+    paymentHeader: string | null;
+    /** Payment requirements for this route. */
+    paymentRequirements: PaymentRequirements;
+    /** Facilitator URL for verification. */
+    facilitatorUrl: string;
+    /** Optional API key for hosted facilitator billing. */
+    apiKey?: string;
+    /** Route key for logging, e.g. "POST /api/generate-image". */
+    routeKey?: RouteKey;
+    /** Network ID for this payment. */
+    network: NetworkId;
+    /** Asset address (ERC-20 token). */
+    asset: string;
+    /** Telemetry config (optional). */
+    telemetry?: TelemetryConfig;
+    /** Payment settled callback (optional). */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+/** Result from checkPayment function. */
+interface PaymentCheckResult {
+    /** Status of the payment check. */
+    status: "require_payment" | "verification_error" | "invalid_payment" | "verified";
+    /** HTTP status code to return. */
+    statusCode: 402 | 500 | 200;
+    /** Response body to return (null if verified). */
+    responseBody: any | null;
+    /** Whether payment is valid (only true if status is "verified"). */
+    isValid: boolean;
+}
+
+export type { MinimalPaywallOptions as M, PaymentLogEntry as P, RouteKey as R, TelemetryConfig as T, RoutePricingConfig as a, RoutesConfig as b, PaymentCheckInput as c, PaymentCheckResult as d };

package/dist/types-DgfVPQFb.d.ts

@@ -0,0 +1,103 @@
+import { Request, Response, NextFunction } from 'express';
+import { N as NetworkId, P as PaymentRequirements } from './types-BFUqKBBO.js';
+
+/** Unique key for a protected route, e.g. "GET /api/protected". */
+type RouteKey = string;
+/** Pricing config for a single route. */
+interface RoutePricingConfig {
+    /** Price in USD cents, e.g. 1 => $0.01. */
+    priceUsdCents: number;
+    /** Network identifier (e.g. "mantle-mainnet"). */
+    network: NetworkId;
+}
+/** Map of route keys to pricing config. */
+type RoutesConfig = Record<RouteKey, RoutePricingConfig>;
+/** Log entry for a successfully settled payment. */
+interface PaymentLogEntry {
+    id: string;
+    from: string;
+    to: string;
+    valueAtomic: string;
+    network: NetworkId;
+    asset: string;
+    route?: RouteKey;
+    txHash?: string;
+    timestamp: number;
+    facilitatorUrl?: string;
+    paymentRequirements?: PaymentRequirements;
+}
+/** Config for optional telemetry (billing/analytics). */
+interface TelemetryConfig {
+    /** Project key from nosubs.ai dashboard. */
+    projectKey: string;
+    /**
+     * Telemetry endpoint URL.
+     * If not specified, uses DEFAULT_TELEMETRY_ENDPOINT (see server/constants.ts).
+     * If both are undefined, telemetry is not sent.
+     */
+    endpoint?: string;
+}
+/** Telemetry event payload for payment_verified. */
+interface TelemetryEvent {
+    event: "payment_verified";
+    ts: number;
+    projectKey: string;
+    network: string;
+    buyer: string;
+    payTo: string;
+    amountAtomic: string;
+    asset: string;
+    decimals: number;
+    nonce: string;
+    route: string;
+    facilitatorType: "hosted" | "self-hosted";
+    facilitatorUrl?: string;
+    facilitatorAddress?: string;
+    txHash?: string;
+    priceUsd?: string;
+}
+/** Config for createPaymentMiddleware. */
+interface PaymentMiddlewareConfig {
+    /** Base URL of facilitator, e.g. https://facilitator.nosubs.ai */
+    facilitatorUrl: string;
+    /** Recipient address (developer). Validated at runtime. */
+    receiverAddress: string;
+    /** Map of protected routes and their pricing. */
+    routes: RoutesConfig;
+    /**
+     * Optional hook called whenever a payment is successfully settled.
+     * You can use this to push logs into your DB / analytics pipeline.
+     */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+    /** Optional: Send usage telemetry for billing/analytics. */
+    telemetry?: TelemetryConfig;
+}
+/**
+ * Minimal config for mantlePaywall() - simplified API for single-route protection.
+ * This is the "sweet path" for Mantle mainnet + USDC with sensible defaults.
+ */
+interface MinimalPaywallOptions {
+    /** Price in USD (e.g. 0.01 for 1 cent). */
+    priceUsd: number;
+    /** Recipient address (developer wallet). Validated at runtime. */
+    payTo: string;
+    /** Optional facilitator URL (defaults to localhost:8080 or NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /**
+     * Optional API key for hosted facilitator billing.
+     * Required when using hosted facilitator (e.g., https://facilitator.x402mantlesdk.xyz).
+     * Not needed for self-hosted facilitator.
+     */
+    apiKey?: string;
+    /** Optional telemetry config. */
+    telemetry?: TelemetryConfig;
+    /** Optional payment settled hook. */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+/**
+ * Express middleware function type for Mantle paywall.
+ * Async function that returns Promise<void>.
+ */
+type MantleMiddleware = (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export type { MantleMiddleware as M, PaymentLogEntry as P, RouteKey as R, TelemetryConfig as T, RoutePricingConfig as a, RoutesConfig as b, TelemetryEvent as c, PaymentMiddlewareConfig as d, MinimalPaywallOptions as e };

package/dist/types-DvKDSdL6.d.ts

@@ -0,0 +1,106 @@
+import { Request, Response, NextFunction } from 'express';
+import { N as NetworkId, P as PaymentRequirements } from './types-BFUqKBBO.js';
+
+/** Unique key for a protected route, e.g. "GET /api/protected". */
+type RouteKey = string;
+/** Pricing config for a single route. */
+interface RoutePricingConfig {
+    /** Price in USD cents, e.g. 1 => $0.01. */
+    priceUsdCents: number;
+    /** Network identifier (e.g. "mantle-mainnet"). */
+    network: NetworkId;
+}
+/** Map of route keys to pricing config. */
+type RoutesConfig = Record<RouteKey, RoutePricingConfig>;
+/** Log entry for a successfully settled payment. */
+interface PaymentLogEntry {
+    id: string;
+    from: string;
+    to: string;
+    valueAtomic: string;
+    network: NetworkId;
+    asset: string;
+    route?: RouteKey;
+    txHash?: string;
+    timestamp: number;
+    facilitatorUrl?: string;
+    paymentRequirements?: PaymentRequirements;
+}
+/** Config for optional telemetry (billing/analytics). */
+interface TelemetryConfig {
+    /** Project key from nosubs.ai dashboard. */
+    projectKey: string;
+    /**
+     * Telemetry endpoint URL.
+     * If not specified, uses DEFAULT_TELEMETRY_ENDPOINT (see server/constants.ts).
+     * If both are undefined, telemetry is not sent.
+     */
+    endpoint?: string;
+}
+/** Telemetry event payload for payment_verified. */
+interface TelemetryEvent {
+    event: "payment_verified";
+    ts: number;
+    projectKey: string;
+    network: string;
+    buyer: string;
+    payTo: string;
+    amountAtomic: string;
+    asset: string;
+    decimals: number;
+    nonce: string;
+    route: string;
+    facilitatorType: "hosted" | "self-hosted";
+    facilitatorUrl?: string;
+    facilitatorAddress?: string;
+    txHash?: string;
+    priceUsd?: string;
+    responseStatus?: number;
+    errorMessage?: string;
+    serviceDelivered?: boolean;
+}
+/** Config for createPaymentMiddleware. */
+interface PaymentMiddlewareConfig {
+    /** Base URL of facilitator, e.g. https://facilitator.nosubs.ai */
+    facilitatorUrl: string;
+    /** Recipient address (developer). Validated at runtime. */
+    receiverAddress: string;
+    /** Map of protected routes and their pricing. */
+    routes: RoutesConfig;
+    /**
+     * Optional hook called whenever a payment is successfully settled.
+     * You can use this to push logs into your DB / analytics pipeline.
+     */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+    /** Optional: Send usage telemetry for billing/analytics. */
+    telemetry?: TelemetryConfig;
+}
+/**
+ * Minimal config for mantlePaywall() - simplified API for single-route protection.
+ * This is the "sweet path" for Mantle mainnet + USDC with sensible defaults.
+ */
+interface MinimalPaywallOptions {
+    /** Price in USD (e.g. 0.01 for 1 cent). */
+    priceUsd: number;
+    /** Recipient address (developer wallet). Validated at runtime. */
+    payTo: string;
+    /** Optional facilitator URL (defaults to localhost:8080 or NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /**
+     * Optional API key for hosted facilitator billing.
+     * Required when using hosted facilitator (e.g., https://facilitator.x402mantlesdk.xyz).
+     * Not needed for self-hosted facilitator.
+     */
+    apiKey?: string;
+    /** Optional telemetry config. */
+    telemetry?: TelemetryConfig;
+    /** Optional payment settled hook. */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+/**
+ * Express middleware function type for Mantle paywall.
+ * Async function that returns Promise<void>.
+ */
+type MantleMiddleware = (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export type { MantleMiddleware as M, PaymentLogEntry as P, RouteKey as R, TelemetryConfig as T, RoutePricingConfig as a, RoutesConfig as b, TelemetryEvent as c, PaymentMiddlewareConfig as d, MinimalPaywallOptions as e };

package/dist/types-X6DeBEgb.d.cts

@@ -0,0 +1,106 @@
+import { Request, Response, NextFunction } from 'express';
+import { N as NetworkId, P as PaymentRequirements } from './types-BFUqKBBO.cjs';
+
+/** Unique key for a protected route, e.g. "GET /api/protected". */
+type RouteKey = string;
+/** Pricing config for a single route. */
+interface RoutePricingConfig {
+    /** Price in USD cents, e.g. 1 => $0.01. */
+    priceUsdCents: number;
+    /** Network identifier (e.g. "mantle-mainnet"). */
+    network: NetworkId;
+}
+/** Map of route keys to pricing config. */
+type RoutesConfig = Record<RouteKey, RoutePricingConfig>;
+/** Log entry for a successfully settled payment. */
+interface PaymentLogEntry {
+    id: string;
+    from: string;
+    to: string;
+    valueAtomic: string;
+    network: NetworkId;
+    asset: string;
+    route?: RouteKey;
+    txHash?: string;
+    timestamp: number;
+    facilitatorUrl?: string;
+    paymentRequirements?: PaymentRequirements;
+}
+/** Config for optional telemetry (billing/analytics). */
+interface TelemetryConfig {
+    /** Project key from nosubs.ai dashboard. */
+    projectKey: string;
+    /**
+     * Telemetry endpoint URL.
+     * If not specified, uses DEFAULT_TELEMETRY_ENDPOINT (see server/constants.ts).
+     * If both are undefined, telemetry is not sent.
+     */
+    endpoint?: string;
+}
+/** Telemetry event payload for payment_verified. */
+interface TelemetryEvent {
+    event: "payment_verified";
+    ts: number;
+    projectKey: string;
+    network: string;
+    buyer: string;
+    payTo: string;
+    amountAtomic: string;
+    asset: string;
+    decimals: number;
+    nonce: string;
+    route: string;
+    facilitatorType: "hosted" | "self-hosted";
+    facilitatorUrl?: string;
+    facilitatorAddress?: string;
+    txHash?: string;
+    priceUsd?: string;
+    responseStatus?: number;
+    errorMessage?: string;
+    serviceDelivered?: boolean;
+}
+/** Config for createPaymentMiddleware. */
+interface PaymentMiddlewareConfig {
+    /** Base URL of facilitator, e.g. https://facilitator.nosubs.ai */
+    facilitatorUrl: string;
+    /** Recipient address (developer). Validated at runtime. */
+    receiverAddress: string;
+    /** Map of protected routes and their pricing. */
+    routes: RoutesConfig;
+    /**
+     * Optional hook called whenever a payment is successfully settled.
+     * You can use this to push logs into your DB / analytics pipeline.
+     */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+    /** Optional: Send usage telemetry for billing/analytics. */
+    telemetry?: TelemetryConfig;
+}
+/**
+ * Minimal config for mantlePaywall() - simplified API for single-route protection.
+ * This is the "sweet path" for Mantle mainnet + USDC with sensible defaults.
+ */
+interface MinimalPaywallOptions {
+    /** Price in USD (e.g. 0.01 for 1 cent). */
+    priceUsd: number;
+    /** Recipient address (developer wallet). Validated at runtime. */
+    payTo: string;
+    /** Optional facilitator URL (defaults to localhost:8080 or NEXT_PUBLIC_FACILITATOR_URL). */
+    facilitatorUrl?: string;
+    /**
+     * Optional API key for hosted facilitator billing.
+     * Required when using hosted facilitator (e.g., https://facilitator.x402mantlesdk.xyz).
+     * Not needed for self-hosted facilitator.
+     */
+    apiKey?: string;
+    /** Optional telemetry config. */
+    telemetry?: TelemetryConfig;
+    /** Optional payment settled hook. */
+    onPaymentSettled?: (entry: PaymentLogEntry) => void;
+}
+/**
+ * Express middleware function type for Mantle paywall.
+ * Async function that returns Promise<void>.
+ */
+type MantleMiddleware = (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+export type { MantleMiddleware as M, PaymentLogEntry as P, RouteKey as R, TelemetryConfig as T, RoutePricingConfig as a, RoutesConfig as b, TelemetryEvent as c, PaymentMiddlewareConfig as d, MinimalPaywallOptions as e };