paygate-mcp 10.12.0 → 10.13.0

package/dist/dynamic-pricing.d.ts

@@ -0,0 +1,144 @@
+/**
+ * DynamicPricingEngine — Adjust tool pricing based on demand, time, and usage.
+ *
+ * Supports time-of-day multipliers, demand-based surge pricing,
+ * volume discounts, and per-key custom pricing. All pricing rules
+ * are composable and evaluated in priority order.
+ *
+ * @example
+ * ```ts
+ * const engine = new DynamicPricingEngine();
+ *
+ * engine.setBasePrice('search', 10);
+ *
+ * engine.addRule({
+ *   tool: 'search',
+ *   type: 'time_of_day',
+ *   config: { peakHours: [9,10,11,12,13,14,15,16,17], multiplier: 1.5 },
+ * });
+ *
+ * const price = engine.getPrice('search');
+ * // 15 during peak hours, 10 otherwise
+ * ```
+ */
+export type PricingRuleType = 'time_of_day' | 'demand' | 'volume_discount' | 'key_override' | 'custom';
+export interface TimeOfDayConfig {
+    /** Hours (0-23) considered peak. */
+    peakHours: number[];
+    /** Multiplier during peak hours. */
+    multiplier: number;
+}
+export interface DemandConfig {
+    /** Calls in the window that trigger surge. */
+    threshold: number;
+    /** Time window in seconds. */
+    windowSeconds: number;
+    /** Max multiplier at full surge. */
+    maxMultiplier: number;
+}
+export interface VolumeDiscountConfig {
+    /** Tiers: [{ minCalls, discount }] — discount is 0-1 (e.g., 0.2 = 20% off). */
+    tiers: {
+        minCalls: number;
+        discount: number;
+    }[];
+}
+export interface KeyOverrideConfig {
+    /** Key → fixed price. */
+    keyPrices: Map<string, number>;
+}
+export interface CustomRuleConfig {
+    /** Custom function: (basePrice, context) => adjustedPrice. */
+    fn: (basePrice: number, context: PricingContext) => number;
+}
+export type PricingRuleConfig = TimeOfDayConfig | DemandConfig | VolumeDiscountConfig | KeyOverrideConfig | CustomRuleConfig;
+export interface PricingRule {
+    id: string;
+    tool: string;
+    type: PricingRuleType;
+    config: PricingRuleConfig;
+    /** Higher priority rules evaluated first. Default 0. */
+    priority: number;
+    enabled: boolean;
+    createdAt: number;
+}
+export interface PricingRuleRegistration {
+    tool: string;
+    type: PricingRuleType;
+    config: PricingRuleConfig;
+    priority?: number;
+}
+export interface PricingContext {
+    tool: string;
+    key?: string;
+    timestamp: number;
+    recentCalls: number;
+    totalCalls: number;
+}
+export interface PriceResult {
+    tool: string;
+    basePrice: number;
+    finalPrice: number;
+    appliedRules: string[];
+    multiplier: number;
+}
+export interface DynamicPricingConfig {
+    /** Default base price for tools without explicit pricing. */
+    defaultBasePrice?: number;
+    /** Window for demand tracking in seconds. Default 300 (5 min). */
+    demandWindowSeconds?: number;
+}
+export interface DynamicPricingStats {
+    totalTools: number;
+    totalRules: number;
+    enabledRules: number;
+    totalPriceCalculations: number;
+    totalCallsTracked: number;
+}
+export declare class DynamicPricingEngine {
+    private basePrices;
+    private rules;
+    private ruleCounter;
+    private defaultBasePrice;
+    private demandWindowSeconds;
+    private callTimestamps;
+    private volumeTracker;
+    private totalCalculations;
+    private totalCallsTracked;
+    constructor(config?: DynamicPricingConfig);
+    /** Set the base credit price for a tool. */
+    setBasePrice(tool: string, price: number): void;
+    /** Get the base price for a tool. */
+    getBasePrice(tool: string): number;
+    /** Remove base price (falls back to default). */
+    removeBasePrice(tool: string): boolean;
+    /** Add a pricing rule. Returns the rule ID. */
+    addRule(reg: PricingRuleRegistration): string;
+    /** Remove a pricing rule. */
+    removeRule(id: string): boolean;
+    /** Enable or disable a rule. */
+    setRuleEnabled(id: string, enabled: boolean): boolean;
+    /** Get a specific rule. */
+    getRule(id: string): PricingRule | null;
+    /** List all rules for a tool. */
+    getToolRules(tool: string): PricingRule[];
+    /** Record a tool call for demand tracking. */
+    recordCall(tool: string, key?: string): void;
+    /** Get recent call count for a tool. */
+    getRecentCallCount(tool: string): number;
+    /** Get total calls for a key+tool combo. */
+    getKeyToolVolume(key: string, tool: string): number;
+    /** Calculate the current price for a tool call. */
+    getPrice(tool: string, key?: string): PriceResult;
+    getStats(): DynamicPricingStats;
+    /** Clear all data. */
+    destroy(): void;
+    private applyRule;
+    private applyTimeOfDay;
+    private applyDemand;
+    private applyVolumeDiscount;
+    private applyKeyOverride;
+    private applyCustom;
+    private pruneTimestamps;
+}
+//# sourceMappingURL=dynamic-pricing.d.ts.map

package/dist/dynamic-pricing.d.ts.map

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

package/dist/dynamic-pricing.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * DynamicPricingEngine — Adjust tool pricing based on demand, time, and usage.
+ *
+ * Supports time-of-day multipliers, demand-based surge pricing,
+ * volume discounts, and per-key custom pricing. All pricing rules
+ * are composable and evaluated in priority order.
+ *
+ * @example
+ * ```ts
+ * const engine = new DynamicPricingEngine();
+ *
+ * engine.setBasePrice('search', 10);
+ *
+ * engine.addRule({
+ *   tool: 'search',
+ *   type: 'time_of_day',
+ *   config: { peakHours: [9,10,11,12,13,14,15,16,17], multiplier: 1.5 },
+ * });
+ *
+ * const price = engine.getPrice('search');
+ * // 15 during peak hours, 10 otherwise
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamicPricingEngine = void 0;
+// ── Implementation ───────────────────────────────────────────────────
+class DynamicPricingEngine {
+    // tool → base price
+    basePrices = new Map();
+    // ruleId → PricingRule
+    rules = new Map();
+    ruleCounter = 0;
+    defaultBasePrice;
+    demandWindowSeconds;
+    // Demand tracking: tool → timestamps of recent calls
+    callTimestamps = new Map();
+    // Volume tracking: key:tool → total calls
+    volumeTracker = new Map();
+    // Stats
+    totalCalculations = 0;
+    totalCallsTracked = 0;
+    constructor(config = {}) {
+        this.defaultBasePrice = config.defaultBasePrice ?? 1;
+        this.demandWindowSeconds = config.demandWindowSeconds ?? 300;
+    }
+    // ── Base Prices ───────────────────────────────────────────────────
+    /** Set the base credit price for a tool. */
+    setBasePrice(tool, price) {
+        if (price < 0)
+            throw new Error('Base price cannot be negative');
+        this.basePrices.set(tool, price);
+    }
+    /** Get the base price for a tool. */
+    getBasePrice(tool) {
+        return this.basePrices.get(tool) ?? this.defaultBasePrice;
+    }
+    /** Remove base price (falls back to default). */
+    removeBasePrice(tool) {
+        return this.basePrices.delete(tool);
+    }
+    // ── Rules ─────────────────────────────────────────────────────────
+    /** Add a pricing rule. Returns the rule ID. */
+    addRule(reg) {
+        const id = `rule_${++this.ruleCounter}`;
+        const rule = {
+            id,
+            tool: reg.tool,
+            type: reg.type,
+            config: reg.config,
+            priority: reg.priority ?? 0,
+            enabled: true,
+            createdAt: Date.now(),
+        };
+        this.rules.set(id, rule);
+        return id;
+    }
+    /** Remove a pricing rule. */
+    removeRule(id) {
+        return this.rules.delete(id);
+    }
+    /** Enable or disable a rule. */
+    setRuleEnabled(id, enabled) {
+        const rule = this.rules.get(id);
+        if (!rule)
+            return false;
+        rule.enabled = enabled;
+        return true;
+    }
+    /** Get a specific rule. */
+    getRule(id) {
+        return this.rules.get(id) ?? null;
+    }
+    /** List all rules for a tool. */
+    getToolRules(tool) {
+        return [...this.rules.values()]
+            .filter(r => r.tool === tool)
+            .sort((a, b) => b.priority - a.priority);
+    }
+    // ── Demand Tracking ────────────────────────────────────────────────
+    /** Record a tool call for demand tracking. */
+    recordCall(tool, key) {
+        // Track timestamps for demand pricing
+        if (!this.callTimestamps.has(tool)) {
+            this.callTimestamps.set(tool, []);
+        }
+        this.callTimestamps.get(tool).push(Date.now());
+        this.totalCallsTracked++;
+        // Track volume per key
+        if (key) {
+            const volumeKey = `${key}:${tool}`;
+            this.volumeTracker.set(volumeKey, (this.volumeTracker.get(volumeKey) ?? 0) + 1);
+        }
+        // Prune old timestamps
+        this.pruneTimestamps(tool);
+    }
+    /** Get recent call count for a tool. */
+    getRecentCallCount(tool) {
+        this.pruneTimestamps(tool);
+        return this.callTimestamps.get(tool)?.length ?? 0;
+    }
+    /** Get total calls for a key+tool combo. */
+    getKeyToolVolume(key, tool) {
+        return this.volumeTracker.get(`${key}:${tool}`) ?? 0;
+    }
+    // ── Price Calculation ─────────────────────────────────────────────
+    /** Calculate the current price for a tool call. */
+    getPrice(tool, key) {
+        this.totalCalculations++;
+        const basePrice = this.getBasePrice(tool);
+        const context = {
+            tool,
+            key,
+            timestamp: Date.now(),
+            recentCalls: this.getRecentCallCount(tool),
+            totalCalls: key ? this.getKeyToolVolume(key, tool) : 0,
+        };
+        // Get enabled rules for this tool, sorted by priority (highest first)
+        const rules = [...this.rules.values()]
+            .filter(r => r.tool === tool && r.enabled)
+            .sort((a, b) => b.priority - a.priority);
+        let price = basePrice;
+        const appliedRules = [];
+        for (const rule of rules) {
+            const newPrice = this.applyRule(rule, price, context);
+            if (newPrice !== price) {
+                price = newPrice;
+                appliedRules.push(rule.id);
+            }
+        }
+        // Ensure price is non-negative
+        price = Math.max(0, Math.round(price));
+        return {
+            tool,
+            basePrice,
+            finalPrice: price,
+            appliedRules,
+            multiplier: basePrice > 0 ? price / basePrice : 1,
+        };
+    }
+    // ── Stats ─────────────────────────────────────────────────────────
+    getStats() {
+        const enabledRules = [...this.rules.values()].filter(r => r.enabled).length;
+        return {
+            totalTools: this.basePrices.size,
+            totalRules: this.rules.size,
+            enabledRules,
+            totalPriceCalculations: this.totalCalculations,
+            totalCallsTracked: this.totalCallsTracked,
+        };
+    }
+    /** Clear all data. */
+    destroy() {
+        this.basePrices.clear();
+        this.rules.clear();
+        this.callTimestamps.clear();
+        this.volumeTracker.clear();
+        this.totalCalculations = 0;
+        this.totalCallsTracked = 0;
+        this.ruleCounter = 0;
+    }
+    // ── Private ───────────────────────────────────────────────────────
+    applyRule(rule, currentPrice, ctx) {
+        switch (rule.type) {
+            case 'time_of_day':
+                return this.applyTimeOfDay(rule.config, currentPrice, ctx);
+            case 'demand':
+                return this.applyDemand(rule.config, currentPrice, ctx);
+            case 'volume_discount':
+                return this.applyVolumeDiscount(rule.config, currentPrice, ctx);
+            case 'key_override':
+                return this.applyKeyOverride(rule.config, currentPrice, ctx);
+            case 'custom':
+                return this.applyCustom(rule.config, currentPrice, ctx);
+            default:
+                return currentPrice;
+        }
+    }
+    applyTimeOfDay(config, price, ctx) {
+        const hour = new Date(ctx.timestamp).getHours();
+        if (config.peakHours.includes(hour)) {
+            return price * config.multiplier;
+        }
+        return price;
+    }
+    applyDemand(config, price, ctx) {
+        if (ctx.recentCalls < config.threshold)
+            return price;
+        // Linear surge: 1x at threshold, maxMultiplier at 2x threshold
+        const ratio = Math.min((ctx.recentCalls - config.threshold) / config.threshold, 1);
+        const multiplier = 1 + ratio * (config.maxMultiplier - 1);
+        return price * multiplier;
+    }
+    applyVolumeDiscount(config, price, ctx) {
+        if (!ctx.key)
+            return price;
+        // Sort tiers descending by minCalls, find the highest qualifying tier
+        const sorted = [...config.tiers].sort((a, b) => b.minCalls - a.minCalls);
+        for (const tier of sorted) {
+            if (ctx.totalCalls >= tier.minCalls) {
+                return price * (1 - tier.discount);
+            }
+        }
+        return price;
+    }
+    applyKeyOverride(config, _price, ctx) {
+        if (!ctx.key)
+            return _price;
+        const override = config.keyPrices.get(ctx.key);
+        return override !== undefined ? override : _price;
+    }
+    applyCustom(config, price, ctx) {
+        try {
+            return config.fn(price, ctx);
+        }
+        catch {
+            return price; // Fail-safe: return original price
+        }
+    }
+    pruneTimestamps(tool) {
+        const timestamps = this.callTimestamps.get(tool);
+        if (!timestamps)
+            return;
+        const cutoff = Date.now() - this.demandWindowSeconds * 1000;
+        const pruned = timestamps.filter(t => t >= cutoff);
+        this.callTimestamps.set(tool, pruned);
+    }
+}
+exports.DynamicPricingEngine = DynamicPricingEngine;
+//# sourceMappingURL=dynamic-pricing.js.map

package/dist/dynamic-pricing.js.map

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

package/dist/event-ledger.d.ts

@@ -0,0 +1,116 @@
+/**
+ * EventLedger — Immutable event sourcing for full audit trail.
+ *
+ * Records every state change as an immutable event. Supports replay,
+ * projection, and time-travel queries for compliance and debugging.
+ *
+ * @example
+ * ```ts
+ * const ledger = new EventLedger();
+ *
+ * ledger.append({
+ *   type: 'credit.deducted',
+ *   aggregateId: 'key_abc',
+ *   payload: { amount: 50, tool: 'search', balance: 950 },
+ * });
+ *
+ * const events = ledger.query({ aggregateId: 'key_abc' });
+ * ```
+ */
+export interface LedgerEvent {
+    id: string;
+    sequence: number;
+    type: string;
+    aggregateId: string;
+    aggregateType?: string;
+    payload: Record<string, unknown>;
+    metadata?: Record<string, string>;
+    timestamp: number;
+    version: number;
+}
+export interface AppendParams {
+    type: string;
+    aggregateId: string;
+    aggregateType?: string;
+    payload: Record<string, unknown>;
+    metadata?: Record<string, string>;
+    expectedVersion?: number;
+}
+export interface LedgerQuery {
+    aggregateId?: string;
+    aggregateType?: string;
+    type?: string;
+    types?: string[];
+    startTime?: number;
+    endTime?: number;
+    afterSequence?: number;
+    limit?: number;
+    offset?: number;
+}
+export interface LedgerQueryResult {
+    events: LedgerEvent[];
+    total: number;
+    hasMore: boolean;
+}
+export interface AggregateSnapshot {
+    aggregateId: string;
+    version: number;
+    eventCount: number;
+    firstEvent: number;
+    lastEvent: number;
+    types: string[];
+}
+export interface EventLedgerConfig {
+    maxEvents?: number;
+    enableConcurrencyCheck?: boolean;
+}
+export interface EventLedgerStats {
+    totalEvents: number;
+    totalAggregates: number;
+    eventTypes: number;
+    oldestEvent: number | null;
+    newestEvent: number | null;
+}
+export declare class EventLedger {
+    private events;
+    private sequence;
+    private maxEvents;
+    private enableConcurrencyCheck;
+    private aggregateVersions;
+    constructor(config?: EventLedgerConfig);
+    /** Append an event to the ledger. Returns the event ID. */
+    append(params: AppendParams): string;
+    /** Append multiple events atomically. */
+    appendBatch(params: AppendParams[]): string[];
+    /** Query events with filters. */
+    query(q?: LedgerQuery): LedgerQueryResult;
+    /** Get a single event by ID. */
+    getEvent(id: string): LedgerEvent | null;
+    /** Get all events for an aggregate in order. */
+    getAggregateEvents(aggregateId: string): LedgerEvent[];
+    /** Get the current version of an aggregate. */
+    getAggregateVersion(aggregateId: string): number;
+    /** Get a snapshot summary of an aggregate. */
+    getAggregateSnapshot(aggregateId: string): AggregateSnapshot | null;
+    /** List all aggregate IDs. */
+    listAggregates(): string[];
+    /**
+     * Replay events for an aggregate through a reducer function.
+     * Returns the final state.
+     */
+    replay<T>(aggregateId: string, reducer: (state: T, event: LedgerEvent) => T, initialState: T): T;
+    /**
+     * Replay all events through a reducer (not scoped to aggregate).
+     * Useful for rebuilding read models / projections.
+     */
+    replayAll<T>(reducer: (state: T, event: LedgerEvent) => T, initialState: T): T;
+    /** Get the state of an aggregate at a specific point in time. */
+    getEventsAsOf(aggregateId: string, asOfTimestamp: number): LedgerEvent[];
+    /** Get event count by type. */
+    getEventTypeCounts(): Map<string, number>;
+    getStats(): EventLedgerStats;
+    /** Clear all data. */
+    destroy(): void;
+    private applyFilters;
+}
+//# sourceMappingURL=event-ledger.d.ts.map

package/dist/event-ledger.d.ts.map

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