@agentokratia/x402-escrow 2.0.0 → 2.0.1

package/dist/{session-wrapper-Cf7U8ObX.d.ts → session-wrapper-CcQU6BOI.d.ts}

@@ -77,6 +77,7 @@ declare function parsePaymentResponseHeader(header: string): PaymentResponseData
  * - LocalStorage: For browser persistence across page loads
  */
 
+type SessionStatus = 'active' | 'inactive' | 'expired';
 interface StoredSession {
     sessionId: string;
     sessionToken: string;
@@ -86,6 +87,7 @@ interface StoredSession {
     balance: string;
     authorizationExpiry: number;
     createdAt: number;
+    status: SessionStatus;
 }
 interface SessionStorage {
     get(network: string, receiver: Address): StoredSession | null;
@@ -146,7 +148,11 @@ declare class SessionManager {
     /**
      * Store a session from escrow settlement response.
      */
-    store(session: Omit<StoredSession, 'createdAt'>): void;
+    store(session: Omit<StoredSession, 'createdAt' | 'status'>): void;
+    /**
+     * Update session status (e.g., mark as inactive when reclaimed).
+     */
+    setStatus(sessionId: string, status: SessionStatus): void;
     /**
      * Get session for a specific receiver.
      */
@@ -167,6 +173,14 @@ declare class SessionManager {
      * Get all stored sessions.
      */
     getAll(): StoredSession[];
+    /**
+     * Get all active sessions for a specific receiver.
+     */
+    getAllForReceiver(receiver: Address): StoredSession[];
+    /**
+     * Get session by ID.
+     */
+    getById(sessionId: string): StoredSession | null;
     /**
      * Remove a specific session.
      */
@@ -202,7 +216,22 @@ interface PaymentPayload {
 }
 interface SchemeNetworkClient {
     readonly scheme: string;
-    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, 'x402Version' | 'payload'>>;
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements, options?: PayloadOptions): Promise<Pick<PaymentPayload, 'x402Version' | 'payload'>>;
+}
+/**
+ * Options for createPaymentPayload
+ */
+interface PayloadOptions {
+    /**
+     * Force creation of a new session even if a valid existing session exists.
+     * Useful when the user explicitly wants a fresh session with new deposit.
+     */
+    forceNew?: boolean;
+    /**
+     * Use a specific session by ID instead of auto-selecting the best one.
+     * If the session doesn't exist or is expired, falls back to creating new session.
+     */
+    sessionId?: string;
 }
 interface EscrowSchemeOptions {
     /** Session duration in seconds (default: 1 hour) */
@@ -240,13 +269,22 @@ declare class EscrowScheme implements SchemeNetworkClient {
     private readonly sessionDuration;
     private readonly refundWindow;
     private readonly customDepositAmount?;
+    /** Force new session on next createPaymentPayload call (resets after use) */
+    forceNewSession: boolean;
+    /** Use specific session ID on next createPaymentPayload call (resets after use) */
+    selectedSessionId?: string;
     constructor(walletClient: WalletClient, options?: EscrowSchemeOptions);
     get address(): Address;
     /**
      * Creates payment payload for escrow scheme.
      * Auto-detects whether to create new session or use existing one.
+     *
+     * @param x402Version - Protocol version
+     * @param paymentRequirements - Payment requirements from 402 response
+     * @param options - Optional payload options
+     * @param options.forceNew - Skip session lookup, always create new session
      */
-    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements): Promise<Pick<PaymentPayload, 'x402Version' | 'payload'>>;
+    createPaymentPayload(x402Version: number, paymentRequirements: PaymentRequirements, options?: PayloadOptions): Promise<Pick<PaymentPayload, 'x402Version' | 'payload'>>;
     /**
      * Session USAGE payload - uses existing session (no signature).
      */
@@ -291,6 +329,35 @@ declare class EscrowScheme implements SchemeNetworkClient {
  */
 
 type FetchLike = typeof globalThis.fetch;
+/**
+ * Extended RequestInit with session selection option.
+ */
+interface EscrowRequestInit extends RequestInit {
+    /**
+     * Session selection mode:
+     * - 'auto' (default): Auto-select best available session for the receiver
+     * - 'new': Force create new session (ignores existing sessions)
+     * - string (session ID): Use a specific session by ID
+     *
+     * @example
+     * ```typescript
+     * // Auto-select best session (default)
+     * await escrowFetch(url);
+     * await escrowFetch(url, { session: 'auto' });
+     *
+     * // Force new session creation
+     * await escrowFetch(url, { session: 'new' });
+     *
+     * // Use specific session
+     * await escrowFetch(url, { session: 'abc-123-def' });
+     * ```
+     */
+    session?: 'auto' | 'new' | string;
+}
+/**
+ * Escrow-aware fetch function with session options.
+ */
+type EscrowFetch = (input: RequestInfo | URL, init?: EscrowRequestInit) => Promise<Response>;
 /** Options for createEscrowFetch */
 interface CreateEscrowFetchOptions extends EscrowSchemeOptions {
     /** Custom fetch implementation (default: globalThis.fetch) */
@@ -299,7 +366,7 @@ interface CreateEscrowFetchOptions extends EscrowSchemeOptions {
 /** Result from createEscrowFetch */
 interface EscrowFetchResult {
     /** Fetch function with automatic payment + session handling */
-    fetch: FetchLike;
+    fetch: EscrowFetch;
     /** Access to underlying scheme for session management */
     scheme: EscrowScheme;
     /** Access to x402Client for adding hooks (onBeforePaymentCreation, etc.) */
@@ -309,26 +376,34 @@ interface EscrowFetchResult {
  * Creates a fetch function with automatic escrow payment and session handling.
  * This is the simplest way to integrate x402 escrow payments.
  *
- * @example Simple usage
+ * @example Basic usage (auto-selects best session)
  * ```typescript
- * const { fetch: escrowFetch, scheme, x402 } = createEscrowFetch(walletClient);
+ * const { fetch: escrowFetch, scheme } = createEscrowFetch(walletClient);
  * const response = await escrowFetch('https://api.example.com/premium');
+ * ```
  *
- * // Access sessions
- * scheme.sessions.getAll();
- * scheme.sessions.hasValid(receiverAddress, '10000');
+ * @example Session selection options
+ * ```typescript
+ * // Auto-select best session (default)
+ * await escrowFetch(url);
+ * await escrowFetch(url, { session: 'auto' });
+ *
+ * // Force new session creation
+ * await escrowFetch(url, { session: 'new' });
+ *
+ * // Use specific session by ID
+ * await escrowFetch(url, { session: 'session-abc-123' });
  * ```
  *
- * @example With custom fetch and hooks
+ * @example Access session manager
  * ```typescript
- * const { fetch: escrowFetch, x402 } = createEscrowFetch(walletClient, {
- *   fetch: customFetch, // Use ky, undici, node-fetch, etc.
- * });
+ * const { fetch: escrowFetch, scheme } = createEscrowFetch(walletClient);
  *
- * // Add hooks for user control
- * x402.onBeforePaymentCreation(async (ctx) => {
- *   console.log('About to pay:', ctx.paymentRequirements);
- * });
+ * // List all sessions for a receiver
+ * const sessions = scheme.sessions.getAllForReceiver(receiverAddress);
+ *
+ * // Check if valid session exists
+ * scheme.sessions.hasValid(receiverAddress, '10000');
  * ```
  */
 declare function createEscrowFetch(walletClient: WalletClient, options?: CreateEscrowFetchOptions): EscrowFetchResult;
@@ -369,4 +444,4 @@ interface AxiosResponseLike {
  */
 declare function withAxiosSessionExtraction(escrowScheme: EscrowScheme): <T extends AxiosResponseLike>(response: T) => T;
 
-export { BrowserLocalStorage as B, type CreateEscrowFetchOptions as C, type EscrowFetchResult as E, InMemoryStorage as I, type PaymentResponseData as P, type StoredSession as S, X402_HEADERS as X, EscrowScheme as a, type EscrowSchemeOptions as b, createEscrowFetch as c, withAxiosSessionExtraction as d, type SettleResponse as e, SessionManager as f, type SessionManagerOptions as g, type SessionStorage as h, createStorage as i, X402_VERSION as j, parsePaymentResponseHeader as p, withSessionExtraction as w };
+export { BrowserLocalStorage as B, type CreateEscrowFetchOptions as C, type EscrowFetchResult as E, InMemoryStorage as I, type PaymentResponseData as P, type StoredSession as S, X402_HEADERS as X, EscrowScheme as a, type EscrowSchemeOptions as b, createEscrowFetch as c, withAxiosSessionExtraction as d, type SettleResponse as e, type EscrowFetch as f, type EscrowRequestInit as g, type PayloadOptions as h, SessionManager as i, type SessionManagerOptions as j, type SessionStorage as k, createStorage as l, X402_VERSION as m, parsePaymentResponseHeader as p, withSessionExtraction as w };

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@agentokratia/x402-escrow",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Escrow payment scheme for x402 protocol - session-based payments for high-frequency APIs",
   "license": "MIT",
   "author": "Agentokratia",
   "repository": {
     "type": "git",
-    "url": "https://github.com/agentokratia/x402-escrow",
+    "url": "https://github.com/Agentokratia/x402-escrow",
     "directory": "packages/escrow"
   },
-  "homepage": "https://github.com/agentokratia/x402-escrow/tree/main/packages/escrow",
-  "bugs": "https://github.com/agentokratia/x402-escrow/issues",
+  "homepage": "https://github.com/Agentokratia/x402-escrow/tree/main/packages/escrow",
+  "bugs": "https://github.com/Agentokratia/x402-escrow/issues",
   "keywords": [
     "x402",
     "escrow",
@@ -48,12 +48,15 @@
   "files": [
     "dist"
   ],
-  "dependencies": {
-    "viem": "^2.21.9"
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
     "@x402/core": "^2.0.0",
-    "@x402/fetch": "^2.0.0"
+    "@x402/fetch": "^2.0.0",
+    "viem": "^2.21.9"
   },
   "peerDependenciesMeta": {
     "@x402/fetch": {
@@ -64,11 +67,7 @@
     "@x402/core": "^2.0.0",
     "@x402/fetch": "^2.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
+    "typescript": "^5.0.0",
+    "viem": "^2.21.9"
   }
-}
+}