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

package/dist/esm/ai/gateway/pricing.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @module ai/gateway/pricing
+ * @description PricingEngine — Dynamic pricing, tier management, and cost calculation.
+ *
+ * Supports:
+ * - Static per-method pricing
+ * - Dynamic pricing based on network congestion (slot-aware)
+ * - Bundle discounts
+ * - Free-tier with call limits
+ *
+ * @since 1.0.0
+ */
+import type { PricingTier, ToolBundle } from './types';
+/**
+ * @description Sensible default pricing tiers — providers override via GatewayConfig.
+ * Includes free, standard, premium (attested), and USDC tiers.
+ * @since 1.0.0
+ */
+export declare const DEFAULT_TIERS: PricingTier[];
+/**
+ * @description Configuration for dynamic pricing based on network conditions.
+ * @since 1.0.0
+ */
+export interface DynamicPricingConfig {
+    /** Base multiplier (1.0 = no change) */
+    baseMultiplier: number;
+    /** Increase price when recent slot latency exceeds this (ms) */
+    congestionThresholdMs: number;
+    /** Max multiplier during congestion */
+    congestionMaxMultiplier: number;
+    /** Discount factor for bundle purchases (0-1, e.g. 0.15 = 15% off) */
+    bundleDiscount: number;
+}
+/**
+ * @description Dynamic pricing engine for agent-to-agent RPC commerce.
+ *
+ * Manages pricing tiers, method-specific overrides, bundle discounts,
+ * and congestion-based dynamic pricing.
+ *
+ * @example
+ * ```ts
+ * const engine = new PricingEngine(DEFAULT_TIERS);
+ * const tier = engine.getTier('standard');
+ * const price = engine.computeCallPrice(tier);
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare class PricingEngine {
+    private readonly tiers;
+    private readonly methodOverrides;
+    private readonly bundles;
+    private readonly dynamicConfig;
+    /** Rolling average latency (updated externally via reportLatency) */
+    private avgLatencyMs;
+    private latencySamples;
+    /**
+     * @description Create a new PricingEngine instance.
+     * @param {PricingTier[]} [defaultTiers=DEFAULT_TIERS] - Default pricing tiers
+     * @param {Record<string, PricingTier[]>} [methodTiers={}] - Per-method tier overrides
+     * @param {Partial<DynamicPricingConfig>} [dynamicConfig={}] - Dynamic pricing configuration
+     * @since 1.0.0
+     */
+    constructor(defaultTiers?: PricingTier[], methodTiers?: Record<string, PricingTier[]>, dynamicConfig?: Partial<DynamicPricingConfig>);
+    /**
+     * @description Get the effective pricing tier for a method + tier ID.
+     * Method-specific overrides are checked first.
+     * @param {string} tierId - The tier identifier to look up
+     * @param {string} [method] - Optional method name for method-specific overrides
+     * @returns {PricingTier | undefined} The resolved pricing tier, or undefined
+     * @since 1.0.0
+     */
+    getTier(tierId: string, method?: string): PricingTier | undefined;
+    /**
+     * @description List all available tier IDs.
+     * @returns {string[]} Array of tier ID strings
+     * @since 1.0.0
+     */
+    listTierIds(): string[];
+    /**
+     * @description List all tiers as an array.
+     * @returns {PricingTier[]} Array of all configured pricing tiers
+     * @since 1.0.0
+     */
+    listTiers(): PricingTier[];
+    /**
+     * @description Compute the effective price for a single call.
+     * Applies congestion multiplier if latency is above threshold.
+     * @param {PricingTier} tier - The pricing tier to compute the price for
+     * @returns {bigint} The price in smallest token unit (lamports / micro-USDC)
+     * @since 1.0.0
+     */
+    computeCallPrice(tier: PricingTier): bigint;
+    /**
+     * @description Estimate total cost for a session with a given number of calls.
+     * Useful for buyers to budget ahead of time.
+     * @param {string} tierId - The pricing tier to use for estimation
+     * @param {number} estimatedCalls - Expected number of calls
+     * @param {string} [method] - Optional method for method-specific pricing
+     * @returns {bigint | null} Estimated cost, or null if tier not found
+     * @since 1.0.0
+     */
+    estimateSessionCost(tierId: string, estimatedCalls: number, method?: string): bigint | null;
+    /**
+     * @description Register a tool bundle for bundle pricing.
+     * @param {ToolBundle} bundle - The tool bundle to register
+     * @returns {void}
+     * @since 1.0.0
+     */
+    registerBundle(bundle: ToolBundle): void;
+    /**
+     * @description Get a registered bundle by ID.
+     * @param {string} id - The bundle identifier
+     * @returns {ToolBundle | undefined} The bundle, or undefined if not found
+     * @since 1.0.0
+     */
+    getBundle(id: string): ToolBundle | undefined;
+    /**
+     * @description List all registered bundles.
+     * @returns {ToolBundle[]} Array of all registered tool bundles
+     * @since 1.0.0
+     */
+    listBundles(): ToolBundle[];
+    /**
+     * @description Compute bundle price for a session.
+     * Applies the bundle discount from the dynamic config.
+     * @param {string} bundleId - The bundle identifier
+     * @param {string} tierId - The pricing tier identifier
+     * @param {number} estimatedCalls - Expected number of calls
+     * @returns {bigint | null} Discounted session cost, or null if bundle/tier not found
+     * @since 1.0.0
+     */
+    computeBundleSessionCost(bundleId: string, tierId: string, estimatedCalls: number): bigint | null;
+    /**
+     * @description Report a latency sample to update the rolling average.
+     * Used for congestion-based dynamic pricing.
+     * @param {number} ms - Latency in milliseconds
+     * @returns {void}
+     * @since 1.0.0
+     */
+    reportLatency(ms: number): void;
+    /**
+     * @description Get the current average latency (rounded).
+     * @returns {number} Average latency in milliseconds
+     * @since 1.0.0
+     */
+    getAvgLatency(): number;
+}
+//# sourceMappingURL=pricing.d.ts.map

package/dist/esm/ai/gateway/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../../../src/ai/gateway/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAgB,UAAU,EAAE,MAAM,SAAS,CAAC;AASrE;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EAqCtC,CAAC;AAMF;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,uCAAuC;IACvC,uBAAuB,EAAE,MAAM,CAAC;IAChC,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoD;IACpF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuB;IAErD,qEAAqE;IACrE,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,cAAc,CAAK;IAE3B;;;;;;OAMG;gBAED,YAAY,GAAE,WAAW,EAAkB,EAC3C,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,CAAM,EAC/C,aAAa,GAAE,OAAO,CAAC,oBAAoB,CAAM;IAiBnD;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IASjE;;;;OAIG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;;;OAIG;IACH,SAAS,IAAI,WAAW,EAAE;IAM1B;;;;;;OAMG;IACH,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM;IAkB3C;;;;;;;;OAQG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAS3F;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAIxC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI7C;;;;OAIG;IACH,WAAW,IAAI,UAAU,EAAE;IAI3B;;;;;;;;OAQG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAYjG;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAS/B;;;;OAIG;IACH,aAAa,IAAI,MAAM;CAGxB"}

package/dist/esm/ai/gateway/pricing.js

@@ -0,0 +1,252 @@
+/**
+ * @module ai/gateway/pricing
+ * @description PricingEngine — Dynamic pricing, tier management, and cost calculation.
+ *
+ * Supports:
+ * - Static per-method pricing
+ * - Dynamic pricing based on network congestion (slot-aware)
+ * - Bundle discounts
+ * - Free-tier with call limits
+ *
+ * @since 1.0.0
+ */
+/* ═══════════════════════════════════════════════════════════════
+ *  Pre-built pricing tiers
+ * ═══════════════════════════════════════════════════════════════ */
+const SOL = { type: 'SOL' };
+const USDC = { type: 'USDC' };
+/**
+ * @description Sensible default pricing tiers — providers override via GatewayConfig.
+ * Includes free, standard, premium (attested), and USDC tiers.
+ * @since 1.0.0
+ */
+export const DEFAULT_TIERS = [
+    {
+        id: 'free',
+        label: 'Free Tier',
+        pricePerCall: 0n,
+        maxCallsPerSession: 100,
+        rateLimit: 5,
+        token: SOL,
+        includesAttestation: false,
+    },
+    {
+        id: 'standard',
+        label: 'Standard',
+        pricePerCall: 1000n, // 0.000001 SOL per call
+        maxCallsPerSession: 10_000,
+        rateLimit: 50,
+        token: SOL,
+        includesAttestation: false,
+    },
+    {
+        id: 'premium',
+        label: 'Premium (Attested)',
+        pricePerCall: 5000n, // 0.000005 SOL per call
+        maxCallsPerSession: 0, // unlimited
+        rateLimit: 200,
+        token: SOL,
+        includesAttestation: true,
+    },
+    {
+        id: 'usdc-standard',
+        label: 'USDC Standard',
+        pricePerCall: 1n, // 0.000001 USDC per call
+        maxCallsPerSession: 50_000,
+        rateLimit: 100,
+        token: USDC,
+        includesAttestation: false,
+    },
+];
+const DEFAULT_DYNAMIC_CONFIG = {
+    baseMultiplier: 1.0,
+    congestionThresholdMs: 500,
+    congestionMaxMultiplier: 3.0,
+    bundleDiscount: 0.15,
+};
+/**
+ * @description Dynamic pricing engine for agent-to-agent RPC commerce.
+ *
+ * Manages pricing tiers, method-specific overrides, bundle discounts,
+ * and congestion-based dynamic pricing.
+ *
+ * @example
+ * ```ts
+ * const engine = new PricingEngine(DEFAULT_TIERS);
+ * const tier = engine.getTier('standard');
+ * const price = engine.computeCallPrice(tier);
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class PricingEngine {
+    tiers = new Map();
+    methodOverrides = new Map();
+    bundles = new Map();
+    dynamicConfig;
+    /** Rolling average latency (updated externally via reportLatency) */
+    avgLatencyMs = 0;
+    latencySamples = 0;
+    /**
+     * @description Create a new PricingEngine instance.
+     * @param {PricingTier[]} [defaultTiers=DEFAULT_TIERS] - Default pricing tiers
+     * @param {Record<string, PricingTier[]>} [methodTiers={}] - Per-method tier overrides
+     * @param {Partial<DynamicPricingConfig>} [dynamicConfig={}] - Dynamic pricing configuration
+     * @since 1.0.0
+     */
+    constructor(defaultTiers = DEFAULT_TIERS, methodTiers = {}, dynamicConfig = {}) {
+        this.dynamicConfig = { ...DEFAULT_DYNAMIC_CONFIG, ...dynamicConfig };
+        for (const tier of defaultTiers) {
+            this.tiers.set(tier.id, tier);
+        }
+        for (const [method, tiers] of Object.entries(methodTiers)) {
+            const m = new Map();
+            for (const t of tiers)
+                m.set(t.id, t);
+            this.methodOverrides.set(method, m);
+        }
+    }
+    /* ── Tier resolution ─────────────────────────────────────── */
+    /**
+     * @description Get the effective pricing tier for a method + tier ID.
+     * Method-specific overrides are checked first.
+     * @param {string} tierId - The tier identifier to look up
+     * @param {string} [method] - Optional method name for method-specific overrides
+     * @returns {PricingTier | undefined} The resolved pricing tier, or undefined
+     * @since 1.0.0
+     */
+    getTier(tierId, method) {
+        // Method-specific override first
+        if (method) {
+            const override = this.methodOverrides.get(method)?.get(tierId);
+            if (override)
+                return override;
+        }
+        return this.tiers.get(tierId);
+    }
+    /**
+     * @description List all available tier IDs.
+     * @returns {string[]} Array of tier ID strings
+     * @since 1.0.0
+     */
+    listTierIds() {
+        return [...this.tiers.keys()];
+    }
+    /**
+     * @description List all tiers as an array.
+     * @returns {PricingTier[]} Array of all configured pricing tiers
+     * @since 1.0.0
+     */
+    listTiers() {
+        return [...this.tiers.values()];
+    }
+    /* ── Dynamic price computation ──────────────────────────── */
+    /**
+     * @description Compute the effective price for a single call.
+     * Applies congestion multiplier if latency is above threshold.
+     * @param {PricingTier} tier - The pricing tier to compute the price for
+     * @returns {bigint} The price in smallest token unit (lamports / micro-USDC)
+     * @since 1.0.0
+     */
+    computeCallPrice(tier) {
+        if (tier.pricePerCall === 0n)
+            return 0n; // Free tier is always free
+        let multiplier = this.dynamicConfig.baseMultiplier;
+        // Congestion-based surge pricing
+        if (this.avgLatencyMs > this.dynamicConfig.congestionThresholdMs) {
+            const congestionRatio = Math.min(this.avgLatencyMs / this.dynamicConfig.congestionThresholdMs, this.dynamicConfig.congestionMaxMultiplier);
+            multiplier *= congestionRatio;
+        }
+        if (multiplier === 1.0)
+            return tier.pricePerCall;
+        return BigInt(Math.ceil(Number(tier.pricePerCall) * multiplier));
+    }
+    /**
+     * @description Estimate total cost for a session with a given number of calls.
+     * Useful for buyers to budget ahead of time.
+     * @param {string} tierId - The pricing tier to use for estimation
+     * @param {number} estimatedCalls - Expected number of calls
+     * @param {string} [method] - Optional method for method-specific pricing
+     * @returns {bigint | null} Estimated cost, or null if tier not found
+     * @since 1.0.0
+     */
+    estimateSessionCost(tierId, estimatedCalls, method) {
+        const tier = this.getTier(tierId, method);
+        if (!tier)
+            return null;
+        const perCall = this.computeCallPrice(tier);
+        return perCall * BigInt(estimatedCalls);
+    }
+    /* ── Bundles ─────────────────────────────────────────────── */
+    /**
+     * @description Register a tool bundle for bundle pricing.
+     * @param {ToolBundle} bundle - The tool bundle to register
+     * @returns {void}
+     * @since 1.0.0
+     */
+    registerBundle(bundle) {
+        this.bundles.set(bundle.id, bundle);
+    }
+    /**
+     * @description Get a registered bundle by ID.
+     * @param {string} id - The bundle identifier
+     * @returns {ToolBundle | undefined} The bundle, or undefined if not found
+     * @since 1.0.0
+     */
+    getBundle(id) {
+        return this.bundles.get(id);
+    }
+    /**
+     * @description List all registered bundles.
+     * @returns {ToolBundle[]} Array of all registered tool bundles
+     * @since 1.0.0
+     */
+    listBundles() {
+        return [...this.bundles.values()];
+    }
+    /**
+     * @description Compute bundle price for a session.
+     * Applies the bundle discount from the dynamic config.
+     * @param {string} bundleId - The bundle identifier
+     * @param {string} tierId - The pricing tier identifier
+     * @param {number} estimatedCalls - Expected number of calls
+     * @returns {bigint | null} Discounted session cost, or null if bundle/tier not found
+     * @since 1.0.0
+     */
+    computeBundleSessionCost(bundleId, tierId, estimatedCalls) {
+        const bundle = this.bundles.get(bundleId);
+        if (!bundle)
+            return null;
+        const tier = bundle.tiers.find(t => t.id === tierId);
+        if (!tier)
+            return null;
+        const baseCost = this.computeCallPrice(tier) * BigInt(estimatedCalls);
+        const discount = this.dynamicConfig.bundleDiscount;
+        return BigInt(Math.ceil(Number(baseCost) * (1 - discount)));
+    }
+    /* ── Latency tracking (for dynamic pricing) ─────────────── */
+    /**
+     * @description Report a latency sample to update the rolling average.
+     * Used for congestion-based dynamic pricing.
+     * @param {number} ms - Latency in milliseconds
+     * @returns {void}
+     * @since 1.0.0
+     */
+    reportLatency(ms) {
+        this.latencySamples++;
+        // Exponential moving average with warmup
+        const alpha = Math.min(0.1, 2 / (this.latencySamples + 1));
+        this.avgLatencyMs = this.avgLatencyMs === 0
+            ? ms
+            : this.avgLatencyMs * (1 - alpha) + ms * alpha;
+    }
+    /**
+     * @description Get the current average latency (rounded).
+     * @returns {number} Average latency in milliseconds
+     * @since 1.0.0
+     */
+    getAvgLatency() {
+        return Math.round(this.avgLatencyMs);
+    }
+}
+//# sourceMappingURL=pricing.js.map

package/dist/esm/ai/gateway/pricing.js.map

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

package/dist/esm/ai/gateway/session.d.ts

@@ -0,0 +1,191 @@
+/**
+ * @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
+ */
+import type { AgentId, SessionState, SessionStatus, PricingTier, PaymentIntent, GatewayEventHandler } from './types';
+/**
+ * @description Base error class for session-related errors.
+ * @since 1.0.0
+ */
+export declare class SessionError extends Error {
+    readonly code: string;
+    readonly sessionId?: string | undefined;
+    /**
+     * @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: string, code: string, sessionId?: string | undefined);
+}
+/**
+ * @description Error thrown when a session's budget has been fully consumed.
+ * @since 1.0.0
+ */
+export declare class BudgetExhaustedError extends SessionError {
+    /**
+     * @description Create a new BudgetExhaustedError.
+     * @param {string} sessionId - The exhausted session ID
+     * @since 1.0.0
+     */
+    constructor(sessionId: string);
+}
+/**
+ * @description Error thrown when a session exceeds its configured rate limit.
+ * @since 1.0.0
+ */
+export declare 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: string, retryAfterMs: number);
+    readonly retryAfterMs: number;
+}
+/**
+ * @description Error thrown when a session has exceeded its TTL.
+ * @since 1.0.0
+ */
+export declare class SessionExpiredError extends SessionError {
+    /**
+     * @description Create a new SessionExpiredError.
+     * @param {string} sessionId - The expired session ID
+     * @since 1.0.0
+     */
+    constructor(sessionId: string);
+}
+/**
+ * @description Error thrown when a session has exhausted its maximum call count.
+ * @since 1.0.0
+ */
+export declare 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: string);
+}
+/**
+ * @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
+ */
+export declare class AgentSession {
+    private state;
+    private readonly listeners;
+    /**
+     * @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: PaymentIntent, tier: PricingTier, sellerId: AgentId, ttl?: number);
+    /**
+     * @description Get the session ID.
+     * @returns {string} The unique session identifier
+     * @since 1.0.0
+     */
+    get id(): string;
+    /**
+     * @description Get the current session status.
+     * @returns {SessionStatus} The current lifecycle status
+     * @since 1.0.0
+     */
+    get status(): SessionStatus;
+    /**
+     * @description Get a frozen snapshot of the full session state.
+     * @returns {Readonly<SessionState>} Immutable copy of the session state
+     * @since 1.0.0
+     */
+    snapshot(): Readonly<SessionState>;
+    /**
+     * @description Activate the session (after payment verification).
+     * @throws {SessionError} If session is not in 'pending' state
+     * @returns {void}
+     * @since 1.0.0
+     */
+    activate(): void;
+    /**
+     * @description Pause the session (preserves budget). No-op if not active.
+     * @returns {void}
+     * @since 1.0.0
+     */
+    pause(): void;
+    /**
+     * @description Resume a paused session. No-op if not paused.
+     * @returns {void}
+     * @since 1.0.0
+     */
+    resume(): void;
+    /**
+     * @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: string): bigint;
+    /**
+     * @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: string, cost: bigint): void;
+    /**
+     * @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(): {
+        amountCharged: bigint;
+        callCount: number;
+        methodCounts: Record<string, number>;
+    };
+    /**
+     * @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: string, value: unknown): void;
+    on(event: string, handler: GatewayEventHandler): () => void;
+    private emit;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/esm/ai/gateway/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../src/ai/gateway/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EACV,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EACjD,aAAa,EAAgB,mBAAmB,EACjD,MAAM,SAAS,CAAC;AAMjB;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAUnB,IAAI,EAAE,MAAM;aACZ,SAAS,CAAC,EAAE,MAAM;IAVpC;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,YAAA;CAKrC;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD;;;;OAIG;gBACS,SAAS,EAAE,MAAM;CAG9B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACtD;;;;;OAKG;gBACS,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAInD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD;;;;OAIG;gBACS,SAAS,EAAE,MAAM;CAG9B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;IACtD;;;;OAIG;gBACS,SAAS,EAAE,MAAM;CAG9B;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoD;IAE9E;;;;;;;OAOG;gBAED,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,OAAO,EACjB,GAAG,SAAO;IA6BZ;;;;OAIG;IACH,IAAI,EAAE,IAAI,MAAM,CAA0B;IAE1C;;;;OAIG;IACH,IAAI,MAAM,IAAI,aAAa,CAA8B;IAEzD;;;;OAIG;IACH,QAAQ,IAAI,QAAQ,CAAC,YAAY,CAAC;IAElC;;;;;OAKG;IACH,QAAQ,IAAI,IAAI;IAQhB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAMd;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAiD/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IA8B5C;;;;;;OAMG;IACH,MAAM,IAAI;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE;IAe5F;;;;;;OAMG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAM9C,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,MAAM,IAAI;IAM3D,OAAO,CAAC,IAAI;CAab"}