paygate-mcp 10.18.0 → 10.19.0

package/dist/error-classifier.d.ts

@@ -0,0 +1,109 @@
+/**
+ * ErrorClassifier — Classify and categorize errors for analytics and routing.
+ *
+ * Register error patterns, classify incoming errors by matching,
+ * and track error frequency for prioritization.
+ *
+ * @example
+ * ```ts
+ * const classifier = new ErrorClassifier();
+ *
+ * classifier.registerPattern({
+ *   category: 'rate_limit',
+ *   pattern: /rate limit|too many requests|429/i,
+ *   severity: 'warning',
+ *   retryable: true,
+ * });
+ *
+ * const result = classifier.classify(new Error('Rate limit exceeded'));
+ * // { category: 'rate_limit', severity: 'warning', retryable: true, ... }
+ * ```
+ */
+export type ErrorSeverity = 'info' | 'warning' | 'error' | 'critical';
+export interface ErrorPattern {
+    id: string;
+    category: string;
+    pattern: RegExp;
+    severity: ErrorSeverity;
+    retryable: boolean;
+    description: string;
+}
+export interface PatternRegistration {
+    category: string;
+    pattern: RegExp;
+    severity?: ErrorSeverity;
+    retryable?: boolean;
+    description?: string;
+}
+export interface ClassifyResult {
+    classified: boolean;
+    category: string;
+    severity: ErrorSeverity;
+    retryable: boolean;
+    patternId: string | null;
+    description: string;
+    message: string;
+    timestamp: number;
+}
+export interface ErrorFrequency {
+    category: string;
+    count: number;
+    lastSeen: number;
+    firstSeen: number;
+}
+export interface ErrorClassifierConfig {
+    /** Max classification history. Default 10000. */
+    maxHistory?: number;
+    /** Max registered patterns. Default 500. */
+    maxPatterns?: number;
+    /** Default severity for unclassified errors. Default 'error'. */
+    defaultSeverity?: ErrorSeverity;
+}
+export interface ErrorClassifierStats {
+    totalPatterns: number;
+    totalClassified: number;
+    totalUnclassified: number;
+    categories: number;
+    topCategories: ErrorFrequency[];
+}
+export declare class ErrorClassifier {
+    private patterns;
+    private history;
+    private frequency;
+    private nextId;
+    private maxHistory;
+    private maxPatterns;
+    private defaultSeverity;
+    private totalClassified;
+    private totalUnclassified;
+    constructor(config?: ErrorClassifierConfig);
+    /** Register an error pattern. */
+    registerPattern(reg: PatternRegistration): ErrorPattern;
+    /** Remove a pattern by ID. */
+    removePattern(id: string): boolean;
+    /** Get a pattern by ID. */
+    getPattern(id: string): ErrorPattern | null;
+    /** List all patterns. */
+    listPatterns(): ErrorPattern[];
+    /** Classify an error. */
+    classify(error: Error | string): ClassifyResult;
+    /** Classify and return just the category name. */
+    categorize(error: Error | string): string;
+    /** Check if an error is retryable. */
+    isRetryable(error: Error | string): boolean;
+    /** Get classification history. */
+    getHistory(options?: {
+        category?: string;
+        severity?: ErrorSeverity;
+        limit?: number;
+    }): ClassifyResult[];
+    /** Get error frequency by category. */
+    getFrequency(): ErrorFrequency[];
+    /** Get frequency for a specific category. */
+    getCategoryFrequency(category: string): ErrorFrequency | null;
+    getStats(): ErrorClassifierStats;
+    /** Clear all data. */
+    destroy(): void;
+    private recordResult;
+}
+//# sourceMappingURL=error-classifier.d.ts.map

package/dist/error-classifier.d.ts.map

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

package/dist/error-classifier.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * ErrorClassifier — Classify and categorize errors for analytics and routing.
+ *
+ * Register error patterns, classify incoming errors by matching,
+ * and track error frequency for prioritization.
+ *
+ * @example
+ * ```ts
+ * const classifier = new ErrorClassifier();
+ *
+ * classifier.registerPattern({
+ *   category: 'rate_limit',
+ *   pattern: /rate limit|too many requests|429/i,
+ *   severity: 'warning',
+ *   retryable: true,
+ * });
+ *
+ * const result = classifier.classify(new Error('Rate limit exceeded'));
+ * // { category: 'rate_limit', severity: 'warning', retryable: true, ... }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorClassifier = void 0;
+// ── Implementation ───────────────────────────────────────────────────
+class ErrorClassifier {
+    patterns = new Map();
+    history = [];
+    frequency = new Map();
+    nextId = 1;
+    maxHistory;
+    maxPatterns;
+    defaultSeverity;
+    // Stats
+    totalClassified = 0;
+    totalUnclassified = 0;
+    constructor(config = {}) {
+        this.maxHistory = config.maxHistory ?? 10_000;
+        this.maxPatterns = config.maxPatterns ?? 500;
+        this.defaultSeverity = config.defaultSeverity ?? 'error';
+    }
+    // ── Pattern Management ────────────────────────────────────────
+    /** Register an error pattern. */
+    registerPattern(reg) {
+        if (!reg.category)
+            throw new Error('Category is required');
+        if (!reg.pattern)
+            throw new Error('Pattern is required');
+        if (this.patterns.size >= this.maxPatterns) {
+            throw new Error(`Maximum ${this.maxPatterns} patterns reached`);
+        }
+        const pattern = {
+            id: `ep_${this.nextId++}`,
+            category: reg.category,
+            pattern: reg.pattern,
+            severity: reg.severity ?? this.defaultSeverity,
+            retryable: reg.retryable ?? false,
+            description: reg.description ?? '',
+        };
+        this.patterns.set(pattern.id, pattern);
+        return pattern;
+    }
+    /** Remove a pattern by ID. */
+    removePattern(id) {
+        return this.patterns.delete(id);
+    }
+    /** Get a pattern by ID. */
+    getPattern(id) {
+        return this.patterns.get(id) ?? null;
+    }
+    /** List all patterns. */
+    listPatterns() {
+        return [...this.patterns.values()];
+    }
+    // ── Classification ─────────────────────────────────────────────
+    /** Classify an error. */
+    classify(error) {
+        const message = typeof error === 'string' ? error : error.message;
+        const now = Date.now();
+        // Try to match against registered patterns
+        for (const pattern of this.patterns.values()) {
+            if (pattern.pattern.test(message)) {
+                const result = {
+                    classified: true,
+                    category: pattern.category,
+                    severity: pattern.severity,
+                    retryable: pattern.retryable,
+                    patternId: pattern.id,
+                    description: pattern.description,
+                    message,
+                    timestamp: now,
+                };
+                this.recordResult(result);
+                this.totalClassified++;
+                return result;
+            }
+        }
+        // Unclassified
+        const result = {
+            classified: false,
+            category: 'unknown',
+            severity: this.defaultSeverity,
+            retryable: false,
+            patternId: null,
+            description: 'No matching pattern found',
+            message,
+            timestamp: now,
+        };
+        this.recordResult(result);
+        this.totalUnclassified++;
+        return result;
+    }
+    /** Classify and return just the category name. */
+    categorize(error) {
+        return this.classify(error).category;
+    }
+    /** Check if an error is retryable. */
+    isRetryable(error) {
+        return this.classify(error).retryable;
+    }
+    // ── Query ──────────────────────────────────────────────────────
+    /** Get classification history. */
+    getHistory(options) {
+        let results = [...this.history];
+        if (options?.category)
+            results = results.filter(r => r.category === options.category);
+        if (options?.severity)
+            results = results.filter(r => r.severity === options.severity);
+        const limit = options?.limit ?? 50;
+        return results.slice(-limit);
+    }
+    /** Get error frequency by category. */
+    getFrequency() {
+        return [...this.frequency.values()].sort((a, b) => b.count - a.count);
+    }
+    /** Get frequency for a specific category. */
+    getCategoryFrequency(category) {
+        return this.frequency.get(category) ?? null;
+    }
+    // ── Stats ──────────────────────────────────────────────────────
+    getStats() {
+        const topCategories = this.getFrequency().slice(0, 5);
+        return {
+            totalPatterns: this.patterns.size,
+            totalClassified: this.totalClassified,
+            totalUnclassified: this.totalUnclassified,
+            categories: this.frequency.size,
+            topCategories,
+        };
+    }
+    /** Clear all data. */
+    destroy() {
+        this.patterns.clear();
+        this.history = [];
+        this.frequency.clear();
+        this.totalClassified = 0;
+        this.totalUnclassified = 0;
+    }
+    // ── Private ───────────────────────────────────────────────────
+    recordResult(result) {
+        this.history.push(result);
+        if (this.history.length > this.maxHistory) {
+            this.history.splice(0, this.history.length - this.maxHistory);
+        }
+        const existing = this.frequency.get(result.category);
+        if (existing) {
+            existing.count++;
+            existing.lastSeen = result.timestamp;
+        }
+        else {
+            this.frequency.set(result.category, {
+                category: result.category,
+                count: 1,
+                lastSeen: result.timestamp,
+                firstSeen: result.timestamp,
+            });
+        }
+    }
+}
+exports.ErrorClassifier = ErrorClassifier;
+//# sourceMappingURL=error-classifier.js.map

package/dist/error-classifier.js.map

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

package/dist/grace-period.d.ts

@@ -0,0 +1,113 @@
+/**
+ * GracePeriodManager — Grace periods for key expiry, quota overages, and payment failures.
+ *
+ * Define grace period policies, apply them to keys, and check
+ * whether a key is within its grace period before hard enforcement.
+ *
+ * @example
+ * ```ts
+ * const mgr = new GracePeriodManager();
+ *
+ * mgr.definePolicy({
+ *   name: 'payment_failure',
+ *   durationMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+ *   reason: 'Payment failed',
+ *   maxExtensions: 1,
+ * });
+ *
+ * mgr.startGracePeriod('key_abc', 'payment_failure');
+ *
+ * const check = mgr.check('key_abc');
+ * // { inGracePeriod: true, expiresAt: ..., remaining: ... }
+ * ```
+ */
+export interface GracePolicy {
+    id: string;
+    name: string;
+    durationMs: number;
+    reason: string;
+    maxExtensions: number;
+}
+export interface PolicyDefineParams {
+    name: string;
+    durationMs: number;
+    reason?: string;
+    maxExtensions?: number;
+}
+export interface GracePeriod {
+    id: string;
+    key: string;
+    policyId: string;
+    policyName: string;
+    reason: string;
+    startedAt: number;
+    expiresAt: number;
+    extensions: number;
+    maxExtensions: number;
+    active: boolean;
+    expiredAt: number | null;
+    cancelledAt: number | null;
+}
+export interface GraceCheckResult {
+    inGracePeriod: boolean;
+    gracePeriod: GracePeriod | null;
+    remainingMs: number;
+    expired: boolean;
+}
+export interface GracePeriodConfig {
+    /** Max active grace periods. Default 10000. */
+    maxActivePeriods?: number;
+    /** Max policies. Default 100. */
+    maxPolicies?: number;
+}
+export interface GracePeriodStats {
+    totalPolicies: number;
+    activePeriods: number;
+    expiredPeriods: number;
+    cancelledPeriods: number;
+    totalStarted: number;
+    totalExpired: number;
+    totalCancelled: number;
+    totalExtended: number;
+}
+export declare class GracePeriodManager {
+    private policies;
+    private periods;
+    private keyPeriods;
+    private nextPolicyId;
+    private nextPeriodId;
+    private maxActivePeriods;
+    private maxPolicies;
+    private totalStarted;
+    private totalExpired;
+    private totalCancelled;
+    private totalExtended;
+    constructor(config?: GracePeriodConfig);
+    /** Define a grace period policy. */
+    definePolicy(params: PolicyDefineParams): GracePolicy;
+    /** Get a policy by ID or name. */
+    getPolicy(idOrName: string): GracePolicy | null;
+    /** List all policies. */
+    listPolicies(): GracePolicy[];
+    /** Remove a policy. */
+    removePolicy(id: string): boolean;
+    /** Start a grace period for a key. */
+    startGracePeriod(key: string, policyIdOrName: string): GracePeriod;
+    /** Check a key's grace period status. */
+    check(key: string): GraceCheckResult;
+    /** Extend a key's grace period. */
+    extend(key: string, additionalMs?: number): GracePeriod;
+    /** Cancel a key's grace period. */
+    cancel(key: string): GracePeriod;
+    /** Get a grace period by key. */
+    getByKey(key: string): GracePeriod | null;
+    /** List all active grace periods. */
+    listActive(): GracePeriod[];
+    /** List expiring grace periods (within given ms). */
+    listExpiring(withinMs: number): GracePeriod[];
+    getStats(): GracePeriodStats;
+    /** Clear all data. */
+    destroy(): void;
+    private getActivePeriodCount;
+}
+//# sourceMappingURL=grace-period.d.ts.map

package/dist/grace-period.d.ts.map

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

package/dist/grace-period.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * GracePeriodManager — Grace periods for key expiry, quota overages, and payment failures.
+ *
+ * Define grace period policies, apply them to keys, and check
+ * whether a key is within its grace period before hard enforcement.
+ *
+ * @example
+ * ```ts
+ * const mgr = new GracePeriodManager();
+ *
+ * mgr.definePolicy({
+ *   name: 'payment_failure',
+ *   durationMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+ *   reason: 'Payment failed',
+ *   maxExtensions: 1,
+ * });
+ *
+ * mgr.startGracePeriod('key_abc', 'payment_failure');
+ *
+ * const check = mgr.check('key_abc');
+ * // { inGracePeriod: true, expiresAt: ..., remaining: ... }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GracePeriodManager = void 0;
+// ── Implementation ───────────────────────────────────────────────────
+class GracePeriodManager {
+    policies = new Map();
+    periods = new Map();
+    keyPeriods = new Map(); // key → periodId
+    nextPolicyId = 1;
+    nextPeriodId = 1;
+    maxActivePeriods;
+    maxPolicies;
+    // Stats
+    totalStarted = 0;
+    totalExpired = 0;
+    totalCancelled = 0;
+    totalExtended = 0;
+    constructor(config = {}) {
+        this.maxActivePeriods = config.maxActivePeriods ?? 10_000;
+        this.maxPolicies = config.maxPolicies ?? 100;
+    }
+    // ── Policy Management ──────────────────────────────────────────
+    /** Define a grace period policy. */
+    definePolicy(params) {
+        if (!params.name)
+            throw new Error('Policy name is required');
+        if (params.durationMs <= 0)
+            throw new Error('Duration must be positive');
+        if (this.policies.size >= this.maxPolicies) {
+            throw new Error(`Maximum ${this.maxPolicies} policies reached`);
+        }
+        // Check for duplicate names
+        for (const p of this.policies.values()) {
+            if (p.name === params.name)
+                throw new Error(`Policy '${params.name}' already exists`);
+        }
+        const policy = {
+            id: `gp_${this.nextPolicyId++}`,
+            name: params.name,
+            durationMs: params.durationMs,
+            reason: params.reason ?? '',
+            maxExtensions: params.maxExtensions ?? 0,
+        };
+        this.policies.set(policy.id, policy);
+        return policy;
+    }
+    /** Get a policy by ID or name. */
+    getPolicy(idOrName) {
+        const byId = this.policies.get(idOrName);
+        if (byId)
+            return byId;
+        for (const p of this.policies.values()) {
+            if (p.name === idOrName)
+                return p;
+        }
+        return null;
+    }
+    /** List all policies. */
+    listPolicies() {
+        return [...this.policies.values()];
+    }
+    /** Remove a policy. */
+    removePolicy(id) {
+        return this.policies.delete(id);
+    }
+    // ── Grace Period Lifecycle ─────────────────────────────────────
+    /** Start a grace period for a key. */
+    startGracePeriod(key, policyIdOrName) {
+        if (!key)
+            throw new Error('Key is required');
+        const policy = this.getPolicy(policyIdOrName);
+        if (!policy)
+            throw new Error(`Policy '${policyIdOrName}' not found`);
+        // Check if key already has an active grace period
+        const existingId = this.keyPeriods.get(key);
+        if (existingId) {
+            const existing = this.periods.get(existingId);
+            if (existing && existing.active) {
+                throw new Error(`Key '${key}' already has an active grace period`);
+            }
+        }
+        if (this.getActivePeriodCount() >= this.maxActivePeriods) {
+            throw new Error(`Maximum ${this.maxActivePeriods} active periods reached`);
+        }
+        const now = Date.now();
+        const period = {
+            id: `gpr_${this.nextPeriodId++}`,
+            key,
+            policyId: policy.id,
+            policyName: policy.name,
+            reason: policy.reason,
+            startedAt: now,
+            expiresAt: now + policy.durationMs,
+            extensions: 0,
+            maxExtensions: policy.maxExtensions,
+            active: true,
+            expiredAt: null,
+            cancelledAt: null,
+        };
+        this.periods.set(period.id, period);
+        this.keyPeriods.set(key, period.id);
+        this.totalStarted++;
+        return period;
+    }
+    /** Check a key's grace period status. */
+    check(key) {
+        const periodId = this.keyPeriods.get(key);
+        if (!periodId) {
+            return { inGracePeriod: false, gracePeriod: null, remainingMs: 0, expired: false };
+        }
+        const period = this.periods.get(periodId);
+        if (!period || !period.active) {
+            return { inGracePeriod: false, gracePeriod: period ?? null, remainingMs: 0, expired: !!period };
+        }
+        const now = Date.now();
+        if (now >= period.expiresAt) {
+            // Grace period expired
+            period.active = false;
+            period.expiredAt = now;
+            this.totalExpired++;
+            return { inGracePeriod: false, gracePeriod: period, remainingMs: 0, expired: true };
+        }
+        return {
+            inGracePeriod: true,
+            gracePeriod: period,
+            remainingMs: period.expiresAt - now,
+            expired: false,
+        };
+    }
+    /** Extend a key's grace period. */
+    extend(key, additionalMs) {
+        const periodId = this.keyPeriods.get(key);
+        if (!periodId)
+            throw new Error(`No grace period for key '${key}'`);
+        const period = this.periods.get(periodId);
+        if (!period)
+            throw new Error(`Grace period not found`);
+        if (!period.active)
+            throw new Error(`Grace period for key '${key}' is not active`);
+        if (period.extensions >= period.maxExtensions) {
+            throw new Error(`Maximum extensions (${period.maxExtensions}) reached for key '${key}'`);
+        }
+        const policy = this.policies.get(period.policyId);
+        const extensionMs = additionalMs ?? policy?.durationMs ?? period.expiresAt - period.startedAt;
+        period.expiresAt += extensionMs;
+        period.extensions++;
+        this.totalExtended++;
+        return period;
+    }
+    /** Cancel a key's grace period. */
+    cancel(key) {
+        const periodId = this.keyPeriods.get(key);
+        if (!periodId)
+            throw new Error(`No grace period for key '${key}'`);
+        const period = this.periods.get(periodId);
+        if (!period)
+            throw new Error(`Grace period not found`);
+        if (!period.active)
+            throw new Error(`Grace period for key '${key}' is not active`);
+        period.active = false;
+        period.cancelledAt = Date.now();
+        this.totalCancelled++;
+        return period;
+    }
+    // ── Query ──────────────────────────────────────────────────────
+    /** Get a grace period by key. */
+    getByKey(key) {
+        const id = this.keyPeriods.get(key);
+        return id ? (this.periods.get(id) ?? null) : null;
+    }
+    /** List all active grace periods. */
+    listActive() {
+        return [...this.periods.values()].filter(p => p.active && Date.now() < p.expiresAt);
+    }
+    /** List expiring grace periods (within given ms). */
+    listExpiring(withinMs) {
+        const deadline = Date.now() + withinMs;
+        return [...this.periods.values()]
+            .filter(p => p.active && p.expiresAt <= deadline && p.expiresAt > Date.now())
+            .sort((a, b) => a.expiresAt - b.expiresAt);
+    }
+    // ── Stats ──────────────────────────────────────────────────────
+    getStats() {
+        let active = 0, expired = 0, cancelled = 0;
+        const now = Date.now();
+        for (const p of this.periods.values()) {
+            if (p.active && now < p.expiresAt)
+                active++;
+            else if (p.expiredAt)
+                expired++;
+            else if (p.cancelledAt)
+                cancelled++;
+        }
+        return {
+            totalPolicies: this.policies.size,
+            activePeriods: active,
+            expiredPeriods: expired,
+            cancelledPeriods: cancelled,
+            totalStarted: this.totalStarted,
+            totalExpired: this.totalExpired,
+            totalCancelled: this.totalCancelled,
+            totalExtended: this.totalExtended,
+        };
+    }
+    /** Clear all data. */
+    destroy() {
+        this.policies.clear();
+        this.periods.clear();
+        this.keyPeriods.clear();
+        this.totalStarted = 0;
+        this.totalExpired = 0;
+        this.totalCancelled = 0;
+        this.totalExtended = 0;
+    }
+    // ── Private ───────────────────────────────────────────────────
+    getActivePeriodCount() {
+        let count = 0;
+        const now = Date.now();
+        for (const p of this.periods.values()) {
+            if (p.active && now < p.expiresAt)
+                count++;
+        }
+        return count;
+    }
+}
+exports.GracePeriodManager = GracePeriodManager;
+//# sourceMappingURL=grace-period.js.map