paygate-mcp 10.3.0 → 10.4.0

package/dist/spend-caps.d.ts

@@ -0,0 +1,105 @@
+/**
+ * SpendCapManager — Server-wide and per-key spend caps with auto-suspend.
+ *
+ * Prevents runaway agent spending by enforcing hard limits:
+ *   - Server-wide daily credit/call caps across ALL keys
+ *   - Per-key hourly credit/call caps (finer-grained than daily)
+ *   - Auto-suspend: keys that breach caps are automatically suspended
+ *   - Auto-resume: suspended keys can be auto-resumed after a cooldown period
+ *
+ * Unlike quotas (which just deny), spend caps can suspend keys to prevent
+ * further abuse until an admin reviews.
+ */
+import { QuotaConfig, SpendCapConfig } from './types';
+export type { SpendCapConfig } from './types';
+export interface SpendCapCheckResult {
+    allowed: boolean;
+    reason?: string;
+    /** Whether the key should be auto-suspended (only when breachAction = 'suspend'). */
+    shouldSuspend?: boolean;
+}
+export declare class SpendCapManager {
+    private config;
+    /** Server-wide daily counters (reset at UTC midnight). */
+    private serverDailyCalls;
+    private serverDailyCredits;
+    private serverDailyResetDay;
+    /** Per-key hourly buckets (keyed by API key prefix). */
+    private hourlyBuckets;
+    /** Auto-suspend timestamps (keyed by API key prefix → Unix ms when suspended). */
+    private suspendedAt;
+    /** Callback: notified when a key is auto-suspended. */
+    onAutoSuspend?: (apiKeyPrefix: string, reason: string) => void;
+    /** Callback: notified when a key is auto-resumed. */
+    onAutoResume?: (apiKeyPrefix: string) => void;
+    constructor(config: SpendCapConfig);
+    /**
+     * Update spend cap config at runtime (hot-reload).
+     */
+    updateConfig(config: SpendCapConfig): void;
+    /**
+     * Check server-wide spend caps.
+     * Call BEFORE per-key checks to fail fast on global limits.
+     */
+    checkServerCap(creditsRequired: number): SpendCapCheckResult;
+    /**
+     * Check per-key hourly spend caps.
+     */
+    checkHourlyCap(apiKeyPrefix: string, creditsRequired: number, quota?: QuotaConfig): SpendCapCheckResult;
+    /**
+     * Check if a key is auto-suspended and whether it should be auto-resumed.
+     * Returns true if the key is still suspended (should deny).
+     */
+    isAutoSuspended(apiKeyPrefix: string): boolean;
+    /**
+     * Auto-suspend a key (called when breachAction = 'suspend').
+     */
+    autoSuspendKey(apiKeyPrefix: string, reason: string): void;
+    /**
+     * Manually clear auto-suspend for a key (admin action).
+     */
+    clearAutoSuspend(apiKeyPrefix: string): boolean;
+    /**
+     * Record successful call against server-wide and hourly caps.
+     */
+    record(apiKeyPrefix: string, creditsCharged: number): void;
+    /**
+     * Record a batch of successful calls.
+     */
+    recordBatch(apiKeyPrefix: string, callCount: number, totalCreditsCharged: number): void;
+    /**
+     * Get server-wide daily stats.
+     */
+    getServerStats(): {
+        dailyCalls: number;
+        dailyCredits: number;
+        dailyCallCap: number;
+        dailyCreditCap: number;
+        resetDay: string;
+    };
+    /**
+     * Get per-key hourly stats.
+     */
+    getKeyHourlyStats(apiKeyPrefix: string): {
+        hourlyCalls: number;
+        hourlyCredits: number;
+        hour: string;
+    };
+    /**
+     * Get auto-suspend status for a key.
+     */
+    getAutoSuspendStatus(apiKeyPrefix: string): {
+        suspended: boolean;
+        suspendedAt?: number;
+        autoResumeIn?: number;
+    };
+    /** Get number of currently auto-suspended keys. */
+    get suspendedCount(): number;
+    /** Get the current config. */
+    get currentConfig(): SpendCapConfig;
+    private todayUTC;
+    private hourUTC;
+    private resetServerIfNeeded;
+    private getOrCreateHourlyBucket;
+}
+//# sourceMappingURL=spend-caps.d.ts.map

package/dist/spend-caps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-caps.d.ts","sourceRoot":"","sources":["../src/spend-caps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAgB,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGpE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAI9C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAYD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiB;IAC/B,0DAA0D;IAC1D,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,mBAAmB,CAAM;IACjC,wDAAwD;IACxD,OAAO,CAAC,aAAa,CAAmC;IACxD,kFAAkF;IAClF,OAAO,CAAC,WAAW,CAA6B;IAChD,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/D,qDAAqD;IACrD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;gBAElC,MAAM,EAAE,cAAc;IAKlC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAI1C;;;OAGG;IACH,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,mBAAmB;IA0B5D;;OAEG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,mBAAmB;IA2BvG;;;OAGG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAiB9C;;OAEG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAK1D;;OAEG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAI/C;;OAEG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IAU1D;;OAEG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,IAAI;IAUvF;;OAEG;IACH,cAAc,IAAI;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAW9H;;OAEG;IACH,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IASrG;;OAEG;IACH,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAiB/G,mDAAmD;IACnD,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,8BAA8B;IAC9B,IAAI,aAAa,IAAI,cAAc,CAElC;IAID,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,uBAAuB;CAahC"}

package/dist/spend-caps.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * SpendCapManager — Server-wide and per-key spend caps with auto-suspend.
+ *
+ * Prevents runaway agent spending by enforcing hard limits:
+ *   - Server-wide daily credit/call caps across ALL keys
+ *   - Per-key hourly credit/call caps (finer-grained than daily)
+ *   - Auto-suspend: keys that breach caps are automatically suspended
+ *   - Auto-resume: suspended keys can be auto-resumed after a cooldown period
+ *
+ * Unlike quotas (which just deny), spend caps can suspend keys to prevent
+ * further abuse until an admin reviews.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpendCapManager = void 0;
+// ─── SpendCapManager ─────────────────────────────────────────────────────────
+class SpendCapManager {
+    config;
+    /** Server-wide daily counters (reset at UTC midnight). */
+    serverDailyCalls = 0;
+    serverDailyCredits = 0;
+    serverDailyResetDay = '';
+    /** Per-key hourly buckets (keyed by API key prefix). */
+    hourlyBuckets = new Map();
+    /** Auto-suspend timestamps (keyed by API key prefix → Unix ms when suspended). */
+    suspendedAt = new Map();
+    /** Callback: notified when a key is auto-suspended. */
+    onAutoSuspend;
+    /** Callback: notified when a key is auto-resumed. */
+    onAutoResume;
+    constructor(config) {
+        this.config = config;
+        this.serverDailyResetDay = this.todayUTC();
+    }
+    /**
+     * Update spend cap config at runtime (hot-reload).
+     */
+    updateConfig(config) {
+        this.config = config;
+    }
+    /**
+     * Check server-wide spend caps.
+     * Call BEFORE per-key checks to fail fast on global limits.
+     */
+    checkServerCap(creditsRequired) {
+        this.resetServerIfNeeded();
+        // Server-wide daily credit cap
+        if (this.config.serverDailyCreditCap > 0) {
+            if (this.serverDailyCredits + creditsRequired > this.config.serverDailyCreditCap) {
+                return {
+                    allowed: false,
+                    reason: `server_daily_credit_cap: ${this.serverDailyCredits}+${creditsRequired} would exceed ${this.config.serverDailyCreditCap} credits/day (server-wide)`,
+                };
+            }
+        }
+        // Server-wide daily call cap
+        if (this.config.serverDailyCallCap > 0) {
+            if (this.serverDailyCalls + 1 > this.config.serverDailyCallCap) {
+                return {
+                    allowed: false,
+                    reason: `server_daily_call_cap: ${this.serverDailyCalls}+1 would exceed ${this.config.serverDailyCallCap} calls/day (server-wide)`,
+                };
+            }
+        }
+        return { allowed: true };
+    }
+    /**
+     * Check per-key hourly spend caps.
+     */
+    checkHourlyCap(apiKeyPrefix, creditsRequired, quota) {
+        if (!quota)
+            return { allowed: true };
+        const hourlyCallLimit = quota.hourlyCallLimit || 0;
+        const hourlyCreditLimit = quota.hourlyCreditLimit || 0;
+        if (hourlyCallLimit === 0 && hourlyCreditLimit === 0)
+            return { allowed: true };
+        const bucket = this.getOrCreateHourlyBucket(apiKeyPrefix);
+        if (hourlyCallLimit > 0 && bucket.calls + 1 > hourlyCallLimit) {
+            return {
+                allowed: false,
+                reason: `hourly_call_cap: ${bucket.calls}+1 would exceed ${hourlyCallLimit} calls/hour`,
+                shouldSuspend: this.config.breachAction === 'suspend',
+            };
+        }
+        if (hourlyCreditLimit > 0 && bucket.credits + creditsRequired > hourlyCreditLimit) {
+            return {
+                allowed: false,
+                reason: `hourly_credit_cap: ${bucket.credits}+${creditsRequired} would exceed ${hourlyCreditLimit} credits/hour`,
+                shouldSuspend: this.config.breachAction === 'suspend',
+            };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Check if a key is auto-suspended and whether it should be auto-resumed.
+     * Returns true if the key is still suspended (should deny).
+     */
+    isAutoSuspended(apiKeyPrefix) {
+        const suspendTime = this.suspendedAt.get(apiKeyPrefix);
+        if (!suspendTime)
+            return false;
+        // Check auto-resume
+        if (this.config.autoResumeAfterSeconds > 0) {
+            const elapsed = (Date.now() - suspendTime) / 1000;
+            if (elapsed >= this.config.autoResumeAfterSeconds) {
+                this.suspendedAt.delete(apiKeyPrefix);
+                this.onAutoResume?.(apiKeyPrefix);
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Auto-suspend a key (called when breachAction = 'suspend').
+     */
+    autoSuspendKey(apiKeyPrefix, reason) {
+        this.suspendedAt.set(apiKeyPrefix, Date.now());
+        this.onAutoSuspend?.(apiKeyPrefix, reason);
+    }
+    /**
+     * Manually clear auto-suspend for a key (admin action).
+     */
+    clearAutoSuspend(apiKeyPrefix) {
+        return this.suspendedAt.delete(apiKeyPrefix);
+    }
+    /**
+     * Record successful call against server-wide and hourly caps.
+     */
+    record(apiKeyPrefix, creditsCharged) {
+        this.resetServerIfNeeded();
+        this.serverDailyCalls++;
+        this.serverDailyCredits += creditsCharged;
+        const bucket = this.getOrCreateHourlyBucket(apiKeyPrefix);
+        bucket.calls++;
+        bucket.credits += creditsCharged;
+    }
+    /**
+     * Record a batch of successful calls.
+     */
+    recordBatch(apiKeyPrefix, callCount, totalCreditsCharged) {
+        this.resetServerIfNeeded();
+        this.serverDailyCalls += callCount;
+        this.serverDailyCredits += totalCreditsCharged;
+        const bucket = this.getOrCreateHourlyBucket(apiKeyPrefix);
+        bucket.calls += callCount;
+        bucket.credits += totalCreditsCharged;
+    }
+    /**
+     * Get server-wide daily stats.
+     */
+    getServerStats() {
+        this.resetServerIfNeeded();
+        return {
+            dailyCalls: this.serverDailyCalls,
+            dailyCredits: this.serverDailyCredits,
+            dailyCallCap: this.config.serverDailyCreditCap,
+            dailyCreditCap: this.config.serverDailyCreditCap,
+            resetDay: this.serverDailyResetDay,
+        };
+    }
+    /**
+     * Get per-key hourly stats.
+     */
+    getKeyHourlyStats(apiKeyPrefix) {
+        const bucket = this.getOrCreateHourlyBucket(apiKeyPrefix);
+        return {
+            hourlyCalls: bucket.calls,
+            hourlyCredits: bucket.credits,
+            hour: bucket.hour,
+        };
+    }
+    /**
+     * Get auto-suspend status for a key.
+     */
+    getAutoSuspendStatus(apiKeyPrefix) {
+        const suspendTime = this.suspendedAt.get(apiKeyPrefix);
+        if (!suspendTime)
+            return { suspended: false };
+        const result = {
+            suspended: true,
+            suspendedAt: suspendTime,
+        };
+        if (this.config.autoResumeAfterSeconds > 0) {
+            const elapsed = (Date.now() - suspendTime) / 1000;
+            result.autoResumeIn = Math.max(0, Math.ceil(this.config.autoResumeAfterSeconds - elapsed));
+        }
+        return result;
+    }
+    /** Get number of currently auto-suspended keys. */
+    get suspendedCount() {
+        return this.suspendedAt.size;
+    }
+    /** Get the current config. */
+    get currentConfig() {
+        return { ...this.config };
+    }
+    // ─── Internals ─────────────────────────────────────────────────────────────
+    todayUTC() {
+        return new Date().toISOString().slice(0, 10);
+    }
+    hourUTC() {
+        return new Date().toISOString().slice(0, 13); // YYYY-MM-DDTHH
+    }
+    resetServerIfNeeded() {
+        const today = this.todayUTC();
+        if (this.serverDailyResetDay !== today) {
+            this.serverDailyCalls = 0;
+            this.serverDailyCredits = 0;
+            this.serverDailyResetDay = today;
+        }
+    }
+    getOrCreateHourlyBucket(apiKeyPrefix) {
+        const currentHour = this.hourUTC();
+        const existing = this.hourlyBuckets.get(apiKeyPrefix);
+        if (existing && existing.hour === currentHour) {
+            return existing;
+        }
+        // New hour — reset bucket
+        const bucket = { hour: currentHour, calls: 0, credits: 0 };
+        this.hourlyBuckets.set(apiKeyPrefix, bucket);
+        return bucket;
+    }
+}
+exports.SpendCapManager = SpendCapManager;
+//# sourceMappingURL=spend-caps.js.map

package/dist/spend-caps.js.map

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

package/dist/task-manager.d.ts

@@ -0,0 +1,158 @@
+/**
+ * TaskManager — MCP Tasks primitive (MCP 2025-11-25 spec).
+ *
+ * Manages async task lifecycle for long-running tool calls:
+ *   - tasks/send   — Create a task wrapping a tool call
+ *   - tasks/get    — Get task status and progress
+ *   - tasks/result — Get task result (completed or error)
+ *   - tasks/list   — List tasks for a session
+ *   - tasks/cancel — Cancel a running task
+ *
+ * Task states: pending → running → completed | failed | cancelled
+ *
+ * Billing integration:
+ *   - Pre-charge: credits deducted at task creation (tasks/send)
+ *   - Refund: if task fails and refundOnFailure is enabled
+ *   - Outcome billing: additional credits charged on completion if output pricing is configured
+ */
+export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+export interface TaskRecord {
+    /** Unique task ID. */
+    id: string;
+    /** Current task status. */
+    status: TaskStatus;
+    /** Tool name being called. */
+    toolName: string;
+    /** Tool call arguments. */
+    arguments?: Record<string, unknown>;
+    /** API key that created this task (prefix only). */
+    apiKeyPrefix: string;
+    /** Session ID this task belongs to. */
+    sessionId: string;
+    /** ISO timestamp when task was created. */
+    createdAt: string;
+    /** ISO timestamp when task started running. */
+    startedAt?: string;
+    /** ISO timestamp when task completed/failed/was cancelled. */
+    completedAt?: string;
+    /** Progress percentage (0-100). Updated by the backend. */
+    progress?: number;
+    /** Human-readable progress message. */
+    message?: string;
+    /** Credits charged at task creation. */
+    creditsCharged: number;
+    /** Additional credits charged post-completion (outcome billing). */
+    outcomeCredits?: number;
+    /** Task result (populated on completion). */
+    result?: unknown;
+    /** Error message (populated on failure). */
+    error?: string;
+    /** Duration in milliseconds. */
+    durationMs?: number;
+}
+export interface TaskListQuery {
+    /** Filter by session ID. */
+    sessionId?: string;
+    /** Filter by status. */
+    status?: TaskStatus;
+    /** Filter by API key prefix. */
+    apiKeyPrefix?: string;
+    /** Pagination cursor. */
+    cursor?: string;
+    /** Page size. Default: 50. Max: 200. */
+    pageSize?: number;
+}
+export interface TaskListResult {
+    tasks: TaskRecord[];
+    total: number;
+    nextCursor?: string;
+}
+export declare class TaskManager {
+    /** All tasks, keyed by task ID. */
+    private tasks;
+    /** Max tasks to retain. Oldest completed tasks are evicted first. Default: 10000. */
+    private maxTasks;
+    /** Task timeout in ms. 0 = no timeout. Default: 300000 (5 min). */
+    private taskTimeoutMs;
+    /** Cleanup interval handle. */
+    private cleanupInterval;
+    constructor(options?: {
+        maxTasks?: number;
+        taskTimeoutMs?: number;
+    });
+    /**
+     * Create a new task (tasks/send).
+     * Returns the task record in pending state.
+     */
+    createTask(params: {
+        toolName: string;
+        arguments?: Record<string, unknown>;
+        apiKeyPrefix: string;
+        sessionId: string;
+        creditsCharged: number;
+    }): TaskRecord;
+    /**
+     * Transition task to 'running'.
+     */
+    startTask(taskId: string): TaskRecord | null;
+    /**
+     * Update task progress.
+     */
+    updateProgress(taskId: string, progress: number, message?: string): TaskRecord | null;
+    /**
+     * Complete a task with result.
+     */
+    completeTask(taskId: string, result: unknown, outcomeCredits?: number): TaskRecord | null;
+    /**
+     * Fail a task with error.
+     */
+    failTask(taskId: string, error: string): TaskRecord | null;
+    /**
+     * Cancel a task.
+     */
+    cancelTask(taskId: string): TaskRecord | null;
+    /**
+     * Get a task by ID.
+     */
+    getTask(taskId: string): TaskRecord | null;
+    /**
+     * List tasks with optional filters.
+     */
+    listTasks(query?: TaskListQuery): TaskListResult;
+    /**
+     * Get summary stats.
+     */
+    getStats(): {
+        total: number;
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+        cancelled: number;
+    };
+    /** Get total task count. */
+    get taskCount(): number;
+    /**
+     * Handle a tasks/* JSON-RPC method.
+     * Returns the response content or null if not a tasks method.
+     */
+    handleTasksMethod(method: string, params: Record<string, unknown>, apiKeyPrefix: string, sessionId: string): {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    } | null;
+    destroy(): void;
+    private taskToResponse;
+    private jsonResult;
+    private errorResult;
+    /**
+     * Evict oldest completed tasks if at capacity.
+     */
+    private evictIfNeeded;
+    /**
+     * Cleanup timed-out tasks.
+     */
+    private cleanup;
+}
+//# sourceMappingURL=task-manager.d.ts.map

package/dist/task-manager.d.ts.map

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