@routedock/routedock 0.1.2 → 0.3.0

package/dist/routedockMiddleware-57gUaEMf.d.ts

@@ -0,0 +1,64 @@
+import { RequestHandler } from 'express';
+import { P as PaymentMode, h as RouteDockManifest, g as RouteDockLogger } from './logger-D8_Q2ytp.js';
+import { O as OrphanedSessionInfo, S as SeenTxStore } from './MppSessionHandler-Bq4S-JTE.js';
+
+interface RouteDockMiddlewareOptions {
+    modes: PaymentMode[];
+    pricing: {
+        x402?: string;
+        'mpp-charge'?: string;
+        'mpp-session'?: {
+            rate: string;
+            channelFactory: string;
+        };
+    };
+    asset?: string;
+    /** Stellar Asset Contract address for the payment asset */
+    assetContract?: string;
+    payee: string;
+    network: 'testnet' | 'mainnet';
+    /** Private key (S...) of the server/payee account */
+    payeeSecretKey: string;
+    /** Required for x402 mode */
+    facilitatorApiKey?: string;
+    /** Required for mpp-session mode — ed25519 public key (G...) for verifying commitments */
+    commitmentPublicKey?: string;
+    /** Full RouteDock manifest — served at /.well-known/routedock.json */
+    manifest: RouteDockManifest;
+    /**
+     * Called after each successful on-chain settlement.
+     * `payer` is the Stellar G... public key of the agent that paid.
+     * May be `null` if the payer address could not be extracted from the payment headers.
+     */
+    onSettled?: (txHash: string, amount: string, mode: string, payer: string | null) => Promise<void>;
+    /**
+     * Called when a new mpp-session is opened (first voucher received).
+     * `payer` is the Stellar G... public key of the agent that opened the channel.
+     * May be `null` if the payer address could not be extracted.
+     */
+    onSessionOpen?: (channelId: string, payer: string | null) => Promise<void>;
+    /** Called after each verified voucher in an mpp-session */
+    onVoucher?: (channelId: string, voucherIndex: number, cumulativeAmount: string, signature: string) => Promise<void>;
+    /** Called if any of the above callbacks throw an error */
+    onCallbackError?: (err: unknown, cbName: string) => void;
+    /**
+     * Called when an mpp-session connection drops or goes idle before a clean
+     * close. Persist the session as `closing` for the SessionReconciler.
+     */
+    onOrphaned?: (channelId: string, info: OrphanedSessionInfo) => Promise<void>;
+    /** Idle timeout (ms) after which an mpp-session is flagged orphaned. */
+    idleTimeoutMs?: number;
+    /**
+     * Idempotency store shared by the x402 and mpp-charge handlers to dedupe
+     * duplicate settlement on agent retries. Defaults to per-handler in-memory.
+     */
+    seenTxStore?: SeenTxStore;
+    /**
+     * Structured log sink for every adapter diagnostic (settlement errors,
+     * callback failures, orphaned sessions). Defaults to a console-backed logger.
+     */
+    logger?: RouteDockLogger;
+}
+declare function routedock(opts: RouteDockMiddlewareOptions): RequestHandler;
+
+export { type RouteDockMiddlewareOptions as R, routedock as r };

package/dist/routedockMiddleware-DlyLrxp7.d.cts

@@ -0,0 +1,64 @@
+import { RequestHandler } from 'express';
+import { P as PaymentMode, h as RouteDockManifest, g as RouteDockLogger } from './logger-D8_Q2ytp.cjs';
+import { O as OrphanedSessionInfo, S as SeenTxStore } from './MppSessionHandler-1EL8QBAn.cjs';
+
+interface RouteDockMiddlewareOptions {
+    modes: PaymentMode[];
+    pricing: {
+        x402?: string;
+        'mpp-charge'?: string;
+        'mpp-session'?: {
+            rate: string;
+            channelFactory: string;
+        };
+    };
+    asset?: string;
+    /** Stellar Asset Contract address for the payment asset */
+    assetContract?: string;
+    payee: string;
+    network: 'testnet' | 'mainnet';
+    /** Private key (S...) of the server/payee account */
+    payeeSecretKey: string;
+    /** Required for x402 mode */
+    facilitatorApiKey?: string;
+    /** Required for mpp-session mode — ed25519 public key (G...) for verifying commitments */
+    commitmentPublicKey?: string;
+    /** Full RouteDock manifest — served at /.well-known/routedock.json */
+    manifest: RouteDockManifest;
+    /**
+     * Called after each successful on-chain settlement.
+     * `payer` is the Stellar G... public key of the agent that paid.
+     * May be `null` if the payer address could not be extracted from the payment headers.
+     */
+    onSettled?: (txHash: string, amount: string, mode: string, payer: string | null) => Promise<void>;
+    /**
+     * Called when a new mpp-session is opened (first voucher received).
+     * `payer` is the Stellar G... public key of the agent that opened the channel.
+     * May be `null` if the payer address could not be extracted.
+     */
+    onSessionOpen?: (channelId: string, payer: string | null) => Promise<void>;
+    /** Called after each verified voucher in an mpp-session */
+    onVoucher?: (channelId: string, voucherIndex: number, cumulativeAmount: string, signature: string) => Promise<void>;
+    /** Called if any of the above callbacks throw an error */
+    onCallbackError?: (err: unknown, cbName: string) => void;
+    /**
+     * Called when an mpp-session connection drops or goes idle before a clean
+     * close. Persist the session as `closing` for the SessionReconciler.
+     */
+    onOrphaned?: (channelId: string, info: OrphanedSessionInfo) => Promise<void>;
+    /** Idle timeout (ms) after which an mpp-session is flagged orphaned. */
+    idleTimeoutMs?: number;
+    /**
+     * Idempotency store shared by the x402 and mpp-charge handlers to dedupe
+     * duplicate settlement on agent retries. Defaults to per-handler in-memory.
+     */
+    seenTxStore?: SeenTxStore;
+    /**
+     * Structured log sink for every adapter diagnostic (settlement errors,
+     * callback failures, orphaned sessions). Defaults to a console-backed logger.
+     */
+    logger?: RouteDockLogger;
+}
+declare function routedock(opts: RouteDockMiddlewareOptions): RequestHandler;
+
+export { type RouteDockMiddlewareOptions as R, routedock as r };

package/dist/schema.cjs

@@ -0,0 +1,404 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/schemas/routedock.schema.json
+var routedock_schema_default = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://routedock.xyz/schemas/routedock.schema.json",
+  title: "RouteDock Manifest",
+  description: "Discovery manifest served at /.well-known/routedock.json on every RouteDock provider endpoint",
+  type: "object",
+  required: [
+    "routedock",
+    "name",
+    "description",
+    "modes",
+    "network",
+    "asset",
+    "asset_contract",
+    "payee",
+    "pricing",
+    "endpoints",
+    "tags"
+  ],
+  additionalProperties: false,
+  properties: {
+    routedock: {
+      type: "string",
+      pattern: "^[0-9]+\\.[0-9]+$",
+      description: "Manifest schema version, e.g. '1.0', '1.1', '2.0'."
+    },
+    min_client_version: {
+      type: "string",
+      pattern: "^[0-9]+\\.[0-9]+$",
+      description: "Minimum SDK client version (major.minor) required to use this manifest. Clients below this version must refuse to pay."
+    },
+    deprecated_modes: {
+      type: "array",
+      items: {
+        $ref: "#/definitions/PaymentMode"
+      },
+      uniqueItems: true,
+      description: "Payment modes still listed in 'modes' for backwards compatibility but deprecated for new integrations."
+    },
+    sunset_at: {
+      type: "string",
+      format: "date-time",
+      description: "ISO 8601 timestamp after which this manifest version is no longer supported by the provider."
+    },
+    name: {
+      type: "string",
+      minLength: 1,
+      maxLength: 120,
+      description: "Human-readable provider name"
+    },
+    description: {
+      type: "string",
+      minLength: 1,
+      maxLength: 500,
+      description: "Human-readable description of the provider's data or service"
+    },
+    modes: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: {
+        $ref: "#/definitions/PaymentMode"
+      },
+      description: "Payment modes supported by this provider"
+    },
+    network: {
+      type: "string",
+      enum: ["testnet", "mainnet"],
+      description: "Stellar network this provider operates on"
+    },
+    asset: {
+      type: "string",
+      description: "Asset ticker symbol (e.g. 'USDC')"
+    },
+    asset_contract: {
+      type: "string",
+      description: "Stellar Asset Contract (SAC) address for the payment asset"
+    },
+    assets: {
+      type: "array",
+      minItems: 1,
+      items: {
+        $ref: "#/definitions/AssetConfig"
+      },
+      description: "Payment assets accepted by this provider. Each asset can be scoped to specific modes and endpoints. When present, assets[0] must match the root-level asset and asset_contract."
+    },
+    payee: {
+      type: "string",
+      description: "Stellar address (G...) that receives payments"
+    },
+    pricing: {
+      type: "object",
+      description: "Pricing configuration per supported payment mode",
+      additionalProperties: false,
+      properties: {
+        x402: {
+          $ref: "#/definitions/PricingConfig"
+        },
+        "mpp-charge": {
+          $ref: "#/definitions/PricingConfig"
+        },
+        "mpp-session": {
+          $ref: "#/definitions/SessionPricingConfig"
+        },
+        "mpp-session-ws": {
+          $ref: "#/definitions/SessionPricingConfig",
+          description: "WebSocket transport variant of mpp-session: channel opened and first voucher negotiated over HTTP, then the connection upgrades to WebSocket for push-based streaming."
+        }
+      },
+      minProperties: 1
+    },
+    endpoints: {
+      type: "object",
+      description: "Map of endpoint name to endpoint descriptors",
+      additionalProperties: {
+        $ref: "#/definitions/EndpointDescriptor"
+      },
+      minProperties: 1
+    },
+    sla: {
+      $ref: "#/definitions/SLAConfig"
+    },
+    tags: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 1,
+        maxLength: 64
+      },
+      uniqueItems: true,
+      description: "Capability tags indexed with trigram search in the provider registry"
+    },
+    vault: {
+      $ref: "#/definitions/VaultMode"
+    },
+    nulth_account: {
+      type: "string",
+      description: "Optional Nulth smart account address associated with this provider"
+    },
+    capabilities: {
+      type: "object",
+      description: "Optional protocol features this provider supports",
+      properties: {
+        streaming: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: ["sse", "websocket"]
+          },
+          description: "Supported streaming transports"
+        },
+        webhooks: {
+          type: "boolean",
+          description: "Whether webhook callbacks are supported"
+        },
+        idempotency_keys: {
+          type: "boolean",
+          description: "Whether idempotency keys are supported"
+        },
+        content_types: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: "Supported content types for request/response"
+        }
+      },
+      additionalProperties: false
+    },
+    regions: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 2,
+        maxLength: 10
+      },
+      uniqueItems: true,
+      description: "IATA airport codes or UN/LOCODE identifiers for regions where this provider has infrastructure (e.g. ['IAD', 'AMS']). Used by agents to select the nearest provider."
+    },
+    latency_hints: {
+      type: "object",
+      additionalProperties: {
+        type: "number",
+        minimum: 0
+      },
+      description: "Provider-declared p50 latency in milliseconds per region code. Keys must be a subset of 'regions'. Example: { 'IAD': 14, 'AMS': 22 }."
+    },
+    signature: {
+      type: "string",
+      description: "Base64 Ed25519 signature (payee keypair) over the SHA-256 hash of this manifest with the signature field omitted. Clients must verify before trusting any routing field."
+    },
+    signature_version: {
+      type: "string",
+      const: "2",
+      description: "Manifest signature format. Version 2 recursively includes every nested manifest field in the signed digest."
+    },
+    categories: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 1,
+        maxLength: 128
+      },
+      uniqueItems: true,
+      description: "Optional hierarchical categories from a published taxonomy (e.g. data/price/crypto)"
+    }
+  },
+  definitions: {
+    VaultMode: {
+      type: "string",
+      enum: ["local-key", "agent-vault", "nulth"],
+      description: "Agent vault / custody mode for payments from this provider"
+    },
+    PaymentMode: {
+      type: "string",
+      enum: ["x402", "mpp-charge", "mpp-session", "mpp-session-ws"],
+      description: "A supported RouteDock payment mode"
+    },
+    AssetConfig: {
+      type: "object",
+      description: "Payment asset configuration with optional mode and endpoint scoping",
+      required: ["asset", "asset_contract"],
+      additionalProperties: false,
+      properties: {
+        asset: {
+          type: "string",
+          description: "Asset ticker symbol (e.g. 'USDC' or 'XLM')"
+        },
+        asset_contract: {
+          type: "string",
+          description: "Stellar Asset Contract (SAC) address for the payment asset"
+        },
+        modes: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/PaymentMode"
+          },
+          uniqueItems: true,
+          description: "Optional: restrict this asset to specific payment modes. If omitted, available for all modes."
+        },
+        endpoints: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          uniqueItems: true,
+          description: "Optional: restrict this asset to specific endpoints (by name). If omitted, available for all endpoints."
+        }
+      }
+    },
+    PricingConfig: {
+      type: "object",
+      description: "Per-request pricing for x402 or mpp-charge modes",
+      required: ["amount", "per"],
+      additionalProperties: false,
+      properties: {
+        amount: {
+          type: "string",
+          description: "Cost per request in the payment asset (decimal string, e.g. '0.001')"
+        },
+        per: {
+          type: "string",
+          const: "request",
+          description: "Billing unit \u2014 always 'request' for non-session modes"
+        },
+        facilitator: {
+          type: "string",
+          description: "x402 facilitator URL (required for x402 mode). OpenZeppelin Channels endpoint."
+        },
+        payee: {
+          type: "string",
+          description: "Optional per-mode payee override (Stellar G... address). Directs settlements for this mode to a separate account for treasury separation. Falls back to the top-level 'payee' when omitted."
+        }
+      }
+    },
+    SessionPricingConfig: {
+      type: "object",
+      description: "Per-voucher pricing for mpp-session (one-way-channel) mode",
+      required: ["rate", "per", "channel_factory", "min_deposit", "refund_waiting_period_ledgers"],
+      additionalProperties: false,
+      properties: {
+        rate: {
+          type: "string",
+          description: "Cost per voucher in the payment asset (decimal string, e.g. '0.0001')"
+        },
+        per: {
+          type: "string",
+          const: "voucher",
+          description: "Billing unit \u2014 always 'voucher' for session mode"
+        },
+        channel_factory: {
+          type: "string",
+          description: "Stable Soroban factory address (C...) used to deploy a per-session channel"
+        },
+        min_deposit: {
+          type: "string",
+          description: "Minimum initial deposit to open a channel (decimal string)"
+        },
+        refund_waiting_period_ledgers: {
+          type: "integer",
+          minimum: 1,
+          description: "Ledgers the server has to settle before the funder can reclaim. Default: 17280 (~24h). Do not reduce in production."
+        }
+      }
+    },
+    SLAConfig: {
+      type: "object",
+      description: "Service Level Agreement for the provider",
+      required: ["uptime_30d_percent", "p95_latency_ms"],
+      additionalProperties: false,
+      properties: {
+        uptime_30d_percent: {
+          type: "number",
+          description: "Uptime percentage over the last 30 days"
+        },
+        p95_latency_ms: {
+          type: "number",
+          description: "P95 latency in milliseconds"
+        },
+        maintenance_windows: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["cron", "duration_minutes"],
+            additionalProperties: false,
+            properties: {
+              cron: {
+                type: "string",
+                description: "Cron expression for the maintenance window"
+              },
+              duration_minutes: {
+                type: "number",
+                description: "Duration of the maintenance window in minutes"
+              }
+            }
+          }
+        }
+      }
+    },
+    EndpointDescriptor: {
+      type: "object",
+      description: "Descriptor for a provider endpoint",
+      required: ["method", "path"],
+      additionalProperties: false,
+      properties: {
+        method: {
+          type: "string",
+          description: "HTTP method for the endpoint"
+        },
+        path: {
+          type: "string",
+          description: "Path for the endpoint"
+        },
+        deprecated: {
+          type: "boolean",
+          description: "Whether this endpoint is retained only for backwards compatibility"
+        },
+        sunset_at: {
+          type: "string",
+          format: "date-time",
+          description: "ISO 8601 timestamp after which callers should stop using this endpoint"
+        },
+        headers: {
+          type: "object",
+          additionalProperties: {
+            type: "string"
+          },
+          description: "Expected request headers"
+        },
+        request_schema: {
+          description: "JSON schema for the request body"
+        },
+        response_schema: {
+          description: "JSON schema for the response body"
+        },
+        rate_limit: {
+          type: "object",
+          required: ["requests", "window_seconds"],
+          additionalProperties: false,
+          properties: {
+            requests: {
+              type: "number"
+            },
+            window_seconds: {
+              type: "number"
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/schema.ts
+var schema = routedock_schema_default;
+var schema_default = schema;
+
+exports.default = schema_default;
+exports.schema = schema;

package/dist/schema.d.cts

@@ -0,0 +1,3 @@
+declare const schema: Record<string, unknown>;
+
+export { schema as default, schema };

package/dist/schema.d.ts

@@ -0,0 +1,3 @@
+declare const schema: Record<string, unknown>;
+
+export { schema as default, schema };