@oobe-protocol-labs/synapse-client-sdk 1.0.0-beta → 1.0.2

package/dist/cjs/ai/gateway/session.js

@@ -0,0 +1,352 @@
+"use strict";
+/**
+ * @module ai/gateway/session
+ * @description AgentSession — Metered, budget-tracked sessions for agent-to-agent RPC commerce.
+ *
+ * A session is opened when a buyer agent presents a PaymentIntent.
+ * Every RPC call deducts from the budget and increments counters.
+ * Rate limiting, TTL expiry, and budget exhaustion are enforced in real-time.
+ *
+ * @since 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentSession = exports.CallLimitExceededError = exports.SessionExpiredError = exports.RateLimitExceededError = exports.BudgetExhaustedError = exports.SessionError = void 0;
+const crypto_1 = require("crypto");
+/* ═══════════════════════════════════════════════════════════════
+ *  Session errors
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Base error class for session-related errors.
+ * @since 1.0.0
+ */
+class SessionError extends Error {
+    code;
+    sessionId;
+    /**
+     * @description Create a new SessionError.
+     * @param {string} message - Human-readable error message
+     * @param {string} code - Machine-readable error code
+     * @param {string} [sessionId] - The session ID associated with the error
+     * @since 1.0.0
+     */
+    constructor(message, code, sessionId) {
+        super(message);
+        this.code = code;
+        this.sessionId = sessionId;
+        this.name = 'SessionError';
+    }
+}
+exports.SessionError = SessionError;
+/**
+ * @description Error thrown when a session's budget has been fully consumed.
+ * @since 1.0.0
+ */
+class BudgetExhaustedError extends SessionError {
+    /**
+     * @description Create a new BudgetExhaustedError.
+     * @param {string} sessionId - The exhausted session ID
+     * @since 1.0.0
+     */
+    constructor(sessionId) {
+        super('Session budget exhausted', 'BUDGET_EXHAUSTED', sessionId);
+    }
+}
+exports.BudgetExhaustedError = BudgetExhaustedError;
+/**
+ * @description Error thrown when a session exceeds its configured rate limit.
+ * @since 1.0.0
+ */
+class RateLimitExceededError extends SessionError {
+    /**
+     * @description Create a new RateLimitExceededError.
+     * @param {string} sessionId - The rate-limited session ID
+     * @param {number} retryAfterMs - Milliseconds to wait before retrying
+     * @since 1.0.0
+     */
+    constructor(sessionId, retryAfterMs) {
+        super(`Rate limit exceeded, retry after ${retryAfterMs}ms`, 'RATE_LIMIT_EXCEEDED', sessionId);
+        this.retryAfterMs = retryAfterMs;
+    }
+    retryAfterMs;
+}
+exports.RateLimitExceededError = RateLimitExceededError;
+/**
+ * @description Error thrown when a session has exceeded its TTL.
+ * @since 1.0.0
+ */
+class SessionExpiredError extends SessionError {
+    /**
+     * @description Create a new SessionExpiredError.
+     * @param {string} sessionId - The expired session ID
+     * @since 1.0.0
+     */
+    constructor(sessionId) {
+        super('Session expired', 'SESSION_EXPIRED', sessionId);
+    }
+}
+exports.SessionExpiredError = SessionExpiredError;
+/**
+ * @description Error thrown when a session has exhausted its maximum call count.
+ * @since 1.0.0
+ */
+class CallLimitExceededError extends SessionError {
+    /**
+     * @description Create a new CallLimitExceededError.
+     * @param {string} sessionId - The session ID that exceeded its call limit
+     * @since 1.0.0
+     */
+    constructor(sessionId) {
+        super('Session call limit exceeded', 'CALL_LIMIT_EXCEEDED', sessionId);
+    }
+}
+exports.CallLimitExceededError = CallLimitExceededError;
+/* ═══════════════════════════════════════════════════════════════
+ *  AgentSession
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Metered, budget-tracked session for agent-to-agent RPC commerce.
+ *
+ * Tracks usage counters, budget remaining, rate limits, and TTL expiry.
+ * Emits events for lifecycle transitions and budget warnings.
+ *
+ * @example
+ * ```ts
+ * const session = new AgentSession(intent, tier, sellerId, 3600);
+ * session.activate();
+ * const cost = session.preCall('getBalance');
+ * // ... execute RPC ...
+ * session.postCall('getBalance', cost);
+ * ```
+ *
+ * @since 1.0.0
+ */
+class AgentSession {
+    state;
+    listeners = new Map();
+    /**
+     * @description Create a new AgentSession.
+     * @param {PaymentIntent} intent - The buyer's payment intent
+     * @param {PricingTier} tier - The pricing tier for this session
+     * @param {AgentId} sellerId - The seller's agent ID
+     * @param {number} [ttl=3600] - Session time-to-live in seconds
+     * @since 1.0.0
+     */
+    constructor(intent, tier, sellerId, ttl = 3600) {
+        const now = Date.now();
+        this.state = {
+            id: (0, crypto_1.randomUUID)(),
+            status: 'pending',
+            buyer: intent.buyer,
+            seller: sellerId,
+            tier,
+            intentNonce: intent.nonce,
+            budgetRemaining: intent.maxBudget,
+            budgetTotal: intent.maxBudget,
+            callsMade: 0,
+            callsRemaining: tier.maxCallsPerSession || -1,
+            methodCounts: {},
+            rateLimiter: {
+                windowMs: 1000,
+                maxPerWindow: tier.rateLimit,
+                timestamps: [],
+            },
+            metadata: {},
+            createdAt: now,
+            lastActivityAt: now,
+            ttl,
+        };
+    }
+    /* ── Public API ──────────────────────────────────────────── */
+    /**
+     * @description Get the session ID.
+     * @returns {string} The unique session identifier
+     * @since 1.0.0
+     */
+    get id() { return this.state.id; }
+    /**
+     * @description Get the current session status.
+     * @returns {SessionStatus} The current lifecycle status
+     * @since 1.0.0
+     */
+    get status() { return this.state.status; }
+    /**
+     * @description Get a frozen snapshot of the full session state.
+     * @returns {Readonly<SessionState>} Immutable copy of the session state
+     * @since 1.0.0
+     */
+    snapshot() { return { ...this.state }; }
+    /**
+     * @description Activate the session (after payment verification).
+     * @throws {SessionError} If session is not in 'pending' state
+     * @returns {void}
+     * @since 1.0.0
+     */
+    activate() {
+        if (this.state.status !== 'pending') {
+            throw new SessionError(`Cannot activate session in '${this.state.status}' state`, 'INVALID_STATE', this.state.id);
+        }
+        this.state.status = 'active';
+        this.emit('session:activated', { sessionId: this.state.id });
+    }
+    /**
+     * @description Pause the session (preserves budget). No-op if not active.
+     * @returns {void}
+     * @since 1.0.0
+     */
+    pause() {
+        if (this.state.status !== 'active')
+            return;
+        this.state.status = 'paused';
+        this.emit('session:paused', { sessionId: this.state.id });
+    }
+    /**
+     * @description Resume a paused session. No-op if not paused.
+     * @returns {void}
+     * @since 1.0.0
+     */
+    resume() {
+        if (this.state.status !== 'paused')
+            return;
+        this.state.status = 'active';
+        this.emit('session:activated', { sessionId: this.state.id, resumed: true });
+    }
+    /**
+     * @description Pre-flight check: validates that a call can proceed.
+     * Throws a typed error if the call should be rejected.
+     *
+     * @param {string} method - The RPC method about to be called
+     * @returns {bigint} The deducted cost in smallest token unit
+     * @throws {SessionError} If session is not active
+     * @throws {SessionExpiredError} If session TTL has elapsed
+     * @throws {RateLimitExceededError} If rate limit window is full
+     * @throws {CallLimitExceededError} If max calls reached
+     * @throws {BudgetExhaustedError} If insufficient budget
+     * @since 1.0.0
+     */
+    preCall(method) {
+        // ── Status check
+        if (this.state.status !== 'active') {
+            throw new SessionError(`Session is '${this.state.status}', cannot make calls`, 'INVALID_STATE', this.state.id);
+        }
+        // ── TTL check
+        if (this.state.ttl > 0) {
+            const elapsed = (Date.now() - this.state.createdAt) / 1000;
+            if (elapsed >= this.state.ttl) {
+                this.state.status = 'expired';
+                this.emit('session:expired', { sessionId: this.state.id });
+                throw new SessionExpiredError(this.state.id);
+            }
+        }
+        // ── Rate limit check (sliding window)
+        const now = Date.now();
+        const rl = this.state.rateLimiter;
+        rl.timestamps = rl.timestamps.filter(ts => now - ts < rl.windowMs);
+        if (rl.timestamps.length >= rl.maxPerWindow) {
+            const oldestInWindow = rl.timestamps[0];
+            const retryAfter = rl.windowMs - (now - oldestInWindow);
+            this.emit('ratelimit:exceeded', { method, retryAfterMs: retryAfter });
+            throw new RateLimitExceededError(this.state.id, retryAfter);
+        }
+        // ── Call limit check
+        if (this.state.callsRemaining !== -1 && this.state.callsRemaining <= 0) {
+            this.state.status = 'exhausted';
+            this.emit('session:exhausted', { sessionId: this.state.id, reason: 'call_limit' });
+            throw new CallLimitExceededError(this.state.id);
+        }
+        // ── Budget check
+        const cost = this.state.tier.pricePerCall;
+        if (this.state.budgetRemaining < cost) {
+            this.state.status = 'exhausted';
+            this.emit('budget:exhausted', { sessionId: this.state.id, budgetRemaining: this.state.budgetRemaining.toString() });
+            throw new BudgetExhaustedError(this.state.id);
+        }
+        return cost;
+    }
+    /**
+     * @description Post-call: deduct budget, increment counters, update timestamps.
+     * Call this after a successful RPC execution.
+     *
+     * @param {string} method - The RPC method that was called
+     * @param {bigint} cost - The cost returned by preCall()
+     * @returns {void}
+     * @since 1.0.0
+     */
+    postCall(method, cost) {
+        const now = Date.now();
+        // Deduct
+        this.state.budgetRemaining -= cost;
+        this.state.callsMade += 1;
+        if (this.state.callsRemaining !== -1)
+            this.state.callsRemaining -= 1;
+        this.state.methodCounts[method] = (this.state.methodCounts[method] ?? 0) + 1;
+        this.state.lastActivityAt = now;
+        // Rate limiter window update
+        this.state.rateLimiter.timestamps.push(now);
+        // Budget warning
+        const budgetFraction = Number(this.state.budgetRemaining) / Number(this.state.budgetTotal);
+        if (budgetFraction <= 0.2 && budgetFraction > 0) {
+            this.emit('budget:warning', {
+                sessionId: this.state.id,
+                budgetRemaining: this.state.budgetRemaining.toString(),
+                budgetPercent: Math.round(budgetFraction * 100),
+            });
+        }
+        // Check if budget is now exhausted
+        if (this.state.budgetRemaining <= 0n) {
+            this.state.status = 'exhausted';
+            this.emit('budget:exhausted', { sessionId: this.state.id });
+        }
+    }
+    /**
+     * @description Settle the session — mark as complete and return usage summary.
+     * Should be called when the buyer is done or the session expires.
+     *
+     * @returns {{ amountCharged: bigint; callCount: number; methodCounts: Record<string, number> }} Usage summary
+     * @since 1.0.0
+     */
+    settle() {
+        const amountCharged = this.state.budgetTotal - this.state.budgetRemaining;
+        this.state.status = 'settled';
+        this.emit('session:settled', {
+            sessionId: this.state.id,
+            amountCharged: amountCharged.toString(),
+            callCount: this.state.callsMade,
+        });
+        return {
+            amountCharged,
+            callCount: this.state.callsMade,
+            methodCounts: { ...this.state.methodCounts },
+        };
+    }
+    /**
+     * @description Attach custom metadata to the session.
+     * @param {string} key - Metadata key
+     * @param {unknown} value - Metadata value
+     * @returns {void}
+     * @since 1.0.0
+     */
+    setMetadata(key, value) {
+        this.state.metadata[key] = value;
+    }
+    /* ── Events ──────────────────────────────────────────────── */
+    on(event, handler) {
+        if (!this.listeners.has(event))
+            this.listeners.set(event, new Set());
+        this.listeners.get(event).add(handler);
+        return () => { this.listeners.get(event)?.delete(handler); };
+    }
+    emit(type, data) {
+        const event = {
+            type: type,
+            sessionId: this.state.id,
+            timestamp: Date.now(),
+            data,
+        };
+        // Fire specific listeners
+        this.listeners.get(type)?.forEach(fn => fn(event));
+        // Fire wildcard listeners
+        this.listeners.get('*')?.forEach(fn => fn(event));
+    }
+}
+exports.AgentSession = AgentSession;
+//# sourceMappingURL=session.js.map

package/dist/cjs/ai/gateway/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../../src/ai/gateway/session.ts"],"names":[],"mappings":"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"}

package/dist/cjs/ai/gateway/types.d.ts

@@ -0,0 +1,324 @@
+/**
+ * @module ai/gateway/types
+ * @description Synapse Agent Gateway — Core type definitions.
+ *
+ * This module defines the primitives for agent-to-agent commerce:
+ * metered sessions, payment channels, response attestations,
+ * and tool marketplace listings.
+ *
+ * @since 1.0.0
+ */
+/**
+ * @description Unique identifier for an agent within the Synapse network.
+ * @since 1.0.0
+ */
+export type AgentId = string & {
+    readonly __brand: 'AgentId';
+};
+/**
+ * @description Create a branded AgentId from a plain string.
+ * @param {string} v - The string value to brand as an AgentId
+ * @returns {AgentId} A branded AgentId
+ * @since 1.0.0
+ */
+export declare const AgentId: (v: string) => AgentId;
+/**
+ * @description DID-style agent identity with optional verification.
+ * @since 1.0.0
+ */
+export interface AgentIdentity {
+    /** Agent unique identifier (e.g. did:synapse:agent:<pubkey>) */
+    id: AgentId;
+    /** Human-readable display name */
+    name: string;
+    /** Agent's Solana wallet pubkey — used for payments & signing */
+    walletPubkey: string;
+    /** Optional description of the agent's capabilities */
+    description?: string;
+    /** Capabilities tags for marketplace discovery */
+    tags?: string[];
+    /** Unix timestamp of identity creation */
+    createdAt: number;
+}
+/**
+ * @description Signed credential proving an agent's identity ownership.
+ * @since 1.0.0
+ */
+export interface AgentCredential {
+    identity: AgentIdentity;
+    /** Ed25519 signature of JSON.stringify(identity) by walletPubkey */
+    signature: string;
+    /** Expiration timestamp (0 = no expiry) */
+    expiresAt: number;
+}
+/**
+ * @description Supported payment tokens for x402 settlements.
+ * @since 1.0.0
+ */
+export type PaymentToken = {
+    type: 'SOL';
+} | {
+    type: 'SPL';
+    mint: string;
+    decimals: number;
+} | {
+    type: 'USDC';
+};
+/**
+ * @description A single pricing tier for a tool or bundle.
+ * @since 1.0.0
+ */
+export interface PricingTier {
+    /** Tier identifier (e.g. 'free', 'standard', 'premium') */
+    id: string;
+    /** Human-readable label */
+    label: string;
+    /** Price per call in the smallest token unit (lamports, USDC micro-units) */
+    pricePerCall: bigint;
+    /** Max calls per session (0 = unlimited) */
+    maxCallsPerSession: number;
+    /** Max calls per second (rate limit) */
+    rateLimit: number;
+    /** Token used for payment */
+    token: PaymentToken;
+    /** Whether response attestation is included */
+    includesAttestation: boolean;
+}
+/**
+ * @description x402 payment intent — what the buyer sends before a session starts.
+ * @since 1.0.0
+ */
+export interface PaymentIntent {
+    /** Unique nonce to prevent replay */
+    nonce: string;
+    /** Buyer agent identity */
+    buyer: AgentId;
+    /** Seller agent identity */
+    seller: AgentId;
+    /** The pricing tier being purchased */
+    tierId: string;
+    /** Max budget for this session (smallest token unit) */
+    maxBudget: bigint;
+    /** Token for this payment */
+    token: PaymentToken;
+    /** Buyer's signature of the intent (Ed25519) */
+    signature: string;
+    /** Unix timestamp of creation */
+    createdAt: number;
+    /** TTL in seconds for this intent */
+    ttl: number;
+}
+/**
+ * @description Receipt of a settled payment (on-chain or off-chain).
+ * @since 1.0.0
+ */
+export interface PaymentReceipt {
+    /** Payment intent that originated this receipt */
+    intentNonce: string;
+    /** Total amount actually charged */
+    amountCharged: bigint;
+    /** Total calls made in the session */
+    callCount: number;
+    /** Transaction signature if settled on-chain, null if off-chain */
+    txSignature: string | null;
+    /** Settlement method */
+    settlement: 'onchain' | 'offchain-escrow' | 'streaming';
+    /** Unix timestamp of settlement */
+    settledAt: number;
+}
+/**
+ * @description Possible lifecycle states for an agent session.
+ * @since 1.0.0
+ */
+export type SessionStatus = 'pending' | 'active' | 'paused' | 'exhausted' | 'settled' | 'expired';
+/**
+ * @description A metered agent session — tracks usage, budget, rate limits.
+ * @since 1.0.0
+ */
+export interface SessionState {
+    /** Unique session id */
+    id: string;
+    /** Current lifecycle status */
+    status: SessionStatus;
+    /** Buyer agent */
+    buyer: AgentId;
+    /** Seller agent (the gateway owner) */
+    seller: AgentId;
+    /** Active pricing tier */
+    tier: PricingTier;
+    /** Payment intent that opened this session */
+    intentNonce: string;
+    /** Budget remaining (smallest token unit) */
+    budgetRemaining: bigint;
+    /** Total budget allocated at session start */
+    budgetTotal: bigint;
+    /** Calls made in this session */
+    callsMade: number;
+    /** Calls remaining in this session (Infinity stored as -1) */
+    callsRemaining: number;
+    /** Per-method call counts for granular metering */
+    methodCounts: Record<string, number>;
+    /** Sliding window rate limiter state */
+    rateLimiter: {
+        windowMs: number;
+        maxPerWindow: number;
+        /** Timestamps of calls in the current window */
+        timestamps: number[];
+    };
+    /** Session-level metadata (can store custom agent data) */
+    metadata: Record<string, unknown>;
+    /** Unix timestamp of creation */
+    createdAt: number;
+    /** Unix timestamp of last activity */
+    lastActivityAt: number;
+    /** TTL in seconds (0 = no expiry) */
+    ttl: number;
+}
+/**
+ * @description Cryptographic attestation of an RPC response (Proof of Computation).
+ * @since 1.0.0
+ */
+export interface ResponseAttestation {
+    /** The session this attestation belongs to */
+    sessionId: string;
+    /** RPC method name */
+    method: string;
+    /** SHA-256 hash of the request params (for binding) */
+    requestHash: string;
+    /** SHA-256 hash of the response body (for integrity) */
+    responseHash: string;
+    /** The upstream RPC slot at the time of response (chain timestamp anchor) */
+    slot: number;
+    /** Attester's agent identity */
+    attesterId: AgentId;
+    /** Ed25519 signature over (method + requestHash + responseHash + slot) */
+    signature: string;
+    /** Unix timestamp of attestation */
+    timestamp: number;
+}
+/**
+ * @description Result wrapper that includes optional attestation and latency info.
+ * @template T The type of the RPC result data
+ * @since 1.0.0
+ */
+export interface AttestedResult<T = unknown> {
+    /** The actual RPC result */
+    data: T;
+    /** Attestation, present if the pricing tier includes it */
+    attestation?: ResponseAttestation;
+    /** Latency in milliseconds for the RPC call */
+    latencyMs: number;
+    /** Session call number (sequential) */
+    callIndex: number;
+}
+/**
+ * @description A tool listing in the agent marketplace.
+ * @since 1.0.0
+ */
+export interface ToolListing {
+    /** RPC method name (e.g. 'getBalance') */
+    method: string;
+    /** Human-readable description */
+    description: string;
+    /** Seller agent */
+    seller: AgentIdentity;
+    /** Available pricing tiers */
+    tiers: PricingTier[];
+    /** Average response latency (ms) — self-reported or verified */
+    avgLatencyMs: number;
+    /** Uptime percentage (0-100) */
+    uptimePercent: number;
+    /** Number of attested calls served */
+    totalServed: number;
+    /** Reputation score (0-1000) computed from attestations */
+    reputationScore: number;
+    /** Whether the seller provides response attestation */
+    attestationAvailable: boolean;
+    /** Geographic region hint (e.g. 'us-east', 'eu-west') */
+    region?: string;
+    /** Supported commitment levels */
+    commitments: ('processed' | 'confirmed' | 'finalized')[];
+    /** Unix timestamp of listing creation */
+    listedAt: number;
+    /** Unix timestamp of last update */
+    updatedAt: number;
+}
+/**
+ * @description A bundle of tools sold together (e.g. "DeFi Pack", "NFT Read-Only").
+ * @since 1.0.0
+ */
+export interface ToolBundle {
+    /** Unique bundle identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the bundle */
+    description: string;
+    /** Method names included */
+    methods: string[];
+    /** Seller agent */
+    seller: AgentIdentity;
+    /** Bundle pricing tiers (overrides per-method pricing) */
+    tiers: PricingTier[];
+    /** Unix timestamp of creation */
+    createdAt: number;
+}
+/**
+ * @description Union type of all observable gateway event types.
+ * @since 1.0.0
+ */
+export type GatewayEventType = 'session:created' | 'session:activated' | 'session:paused' | 'session:exhausted' | 'session:settled' | 'session:expired' | 'call:before' | 'call:after' | 'call:error' | 'call:attested' | 'payment:intent' | 'payment:settled' | 'ratelimit:exceeded' | 'budget:warning' | 'budget:exhausted' | 'x402:payment-required' | 'x402:payment-verified' | 'x402:payment-settled' | 'x402:payment-sent';
+/**
+ * @description Event object emitted by the gateway event bus.
+ * @template T The type of the event data payload
+ * @since 1.0.0
+ */
+export interface GatewayEvent<T = unknown> {
+    type: GatewayEventType;
+    sessionId: string;
+    timestamp: number;
+    data: T;
+}
+/**
+ * @description Handler function for gateway events.
+ * @template T The type of the event data payload
+ * @since 1.0.0
+ */
+export type GatewayEventHandler<T = unknown> = (event: GatewayEvent<T>) => void | Promise<void>;
+import type { X402Config } from './x402/types';
+import type { X402ClientConfig } from './x402/client';
+/**
+ * @description Full configuration for an AgentGateway instance.
+ * @since 1.0.0
+ */
+export interface GatewayConfig {
+    /** The seller's agent identity */
+    identity: AgentIdentity;
+    /** Default pricing tiers for all methods */
+    defaultTiers: PricingTier[];
+    /** Per-method pricing overrides (method name → tiers) */
+    methodTiers?: Record<string, PricingTier[]>;
+    /** Session TTL in seconds (default: 3600) */
+    sessionTtl?: number;
+    /** Budget warning threshold (0-1, fraction of total budget, default: 0.2) */
+    budgetWarningThreshold?: number;
+    /** Maximum concurrent sessions (default: 100) */
+    maxConcurrentSessions?: number;
+    /** Whether to produce response attestations by default */
+    attestByDefault?: boolean;
+    /** Custom signer function for attestations (default: no-op, integrate with wallet) */
+    signer?: (message: Uint8Array) => Promise<Uint8Array>;
+    /**
+     * x402 Paywall configuration (SELLER side).
+     * When set, the gateway generates 402 responses and settles
+     * payments via the configured facilitator.
+     */
+    x402?: X402Config;
+    /**
+     * x402 Client configuration (BUYER side).
+     * When set, the gateway can pay for RPC access on remote
+     * x402-enabled servers.
+     */
+    x402Client?: X402ClientConfig;
+}
+//# sourceMappingURL=types.d.ts.map