dotdo 0.0.1 → 0.1.0

package/dist/workflows/context/rate-limit.js

@@ -0,0 +1,358 @@
+/**
+ * Rate Limit Context API for $.rateLimit() and $.rateLimits
+ *
+ * Provides a workflow context API for rate limiting with support for:
+ * - $.rateLimit(key).check(opts?) - Check if request is allowed, consumes quota
+ * - $.rateLimit(key).isAllowed(opts?) - Boolean check WITHOUT consuming quota
+ * - $.rateLimit(key).remaining(opts?) - Get remaining WITHOUT consuming quota
+ * - $.rateLimit(key).consume(cost, opts?) - Consume tokens after the fact
+ * - $.rateLimit(key).reset(opts?) - Reset rate limit for key
+ * - $.rateLimit(key).status(opts?) - Get status without modifying
+ * - $.rateLimits.configure(name, config) - Configure named limits
+ * - $.rateLimits.getConfig() - Get all limit configs
+ * - $.rateLimits.get(name) - Get specific limit config
+ *
+ * Supports cost-based limiting (AI tokens, uploads, etc.) and named limits.
+ *
+ * @module workflows/context/rate-limit
+ */
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/**
+ * Default limit when using $.rateLimit without a named config
+ */
+const DEFAULT_LIMIT = 100;
+/**
+ * Default window when using $.rateLimit without a named config (1 minute)
+ */
+const DEFAULT_WINDOW = '1m';
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+/**
+ * Parses a window string into milliseconds.
+ * Format: number + unit (m = minutes, h = hours, d = days)
+ *
+ * @param window - Window string like '1m', '1h', '1d', '15m'
+ * @returns Window duration in milliseconds
+ * @throws Error if format is invalid
+ */
+export function parseWindow(window) {
+    const match = window.match(/^(\d+)([mhd])$/);
+    if (!match) {
+        throw new Error(`Invalid window format: ${window}. Expected format: '1m', '1h', '1d'`);
+    }
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    if (value === 0) {
+        throw new Error(`Invalid window value: ${window}. Window must be greater than 0`);
+    }
+    switch (unit) {
+        case 'm':
+            return value * 60 * 1000; // minutes to ms
+        case 'h':
+            return value * 60 * 60 * 1000; // hours to ms
+        case 'd':
+            return value * 24 * 60 * 60 * 1000; // days to ms
+        default:
+            throw new Error(`Unknown unit: ${unit}`);
+    }
+}
+/**
+ * Create a composite key for rate limit storage.
+ * Combines the user key with the named limit to allow separate tracking.
+ */
+function makeCompositeKey(key, name) {
+    return `${name}:${key}`;
+}
+/**
+ * Prune expired entries from the entry list
+ */
+function pruneExpiredEntries(entries, cutoff) {
+    return entries.filter((e) => e.timestamp > cutoff);
+}
+/**
+ * Calculate total cost from entries
+ */
+function calculateTotalCost(entries) {
+    return entries.reduce((sum, e) => sum + e.cost, 0);
+}
+// ============================================================================
+// CONTEXT FACTORY
+// ============================================================================
+/**
+ * Creates a mock workflow context ($) with rate limit support for testing
+ *
+ * This factory creates a context object with:
+ * - $.rateLimit(key) - Returns a RateLimitContextInstance for per-key operations
+ * - $.rateLimits - Collection-level operations (configure, get, getConfig)
+ * - $._storage - Internal storage for test setup
+ * - $._now - Time provider for testing (can be overridden for fake timers)
+ *
+ * @returns A RateLimitContext object with rate limit API methods
+ */
+export function createMockContext() {
+    // Internal storage
+    const storage = {
+        entries: new Map(),
+        configs: new Map(),
+    };
+    // Time provider - can be patched for testing
+    let nowFn = () => Date.now();
+    /**
+     * Get config for a named limit, or throw if not found
+     */
+    function getConfigOrThrow(name) {
+        const config = storage.configs.get(name);
+        if (!config) {
+            throw new Error(`Rate limit '${name}' is not configured. Use $.rateLimits.configure('${name}', { limit, window }) first.`);
+        }
+        return config;
+    }
+    /**
+     * Get config for a named limit, or return defaults
+     */
+    function getConfigOrDefault(name) {
+        if (name) {
+            return getConfigOrThrow(name);
+        }
+        return { limit: DEFAULT_LIMIT, window: DEFAULT_WINDOW };
+    }
+    /**
+     * Create a RateLimitContextInstance for a specific key
+     */
+    function createRateLimitInstance(key) {
+        return {
+            /**
+             * Check if request is allowed and consume quota
+             */
+            async check(options) {
+                const name = options?.name;
+                const cost = options?.cost ?? 1;
+                // Validate cost
+                if (cost < 0) {
+                    throw new Error(`Invalid cost: ${cost}. Cost must be non-negative`);
+                }
+                // Get config (throws if named limit not found)
+                const config = name ? getConfigOrThrow(name) : getConfigOrDefault();
+                const { limit, window } = config;
+                // Parse window
+                const windowMs = parseWindow(window);
+                const now = nowFn();
+                const cutoff = now - windowMs;
+                // Get composite key for tracking
+                const compositeKey = makeCompositeKey(key, name ?? '_default');
+                // Get and prune entries
+                let entries = storage.entries.get(compositeKey) ?? [];
+                entries = pruneExpiredEntries(entries, cutoff);
+                // Calculate current usage
+                const currentCost = calculateTotalCost(entries);
+                // Handle zero cost (peek/check without consuming)
+                if (cost === 0) {
+                    const remaining = Math.max(0, limit - currentCost);
+                    storage.entries.set(compositeKey, entries);
+                    return {
+                        success: remaining > 0 || limit === 0 ? limit > 0 : true,
+                        remaining,
+                        resetAt: entries.length > 0 ? Math.min(...entries.map((e) => e.timestamp)) + windowMs : now + windowMs,
+                        limit,
+                        cost: 0,
+                    };
+                }
+                // Check if we can accommodate this request
+                if (currentCost + cost > limit) {
+                    storage.entries.set(compositeKey, entries);
+                    return {
+                        success: false,
+                        remaining: Math.max(0, limit - currentCost),
+                        resetAt: entries.length > 0 ? Math.min(...entries.map((e) => e.timestamp)) + windowMs : now + windowMs,
+                        limit,
+                        cost,
+                    };
+                }
+                // Add new entry
+                entries.push({ timestamp: now, cost });
+                storage.entries.set(compositeKey, entries);
+                return {
+                    success: true,
+                    remaining: Math.max(0, limit - currentCost - cost),
+                    resetAt: now + windowMs,
+                    limit,
+                    cost,
+                };
+            },
+            /**
+             * Boolean check if request would be allowed (does not consume quota)
+             */
+            async isAllowed(options) {
+                const name = options?.name;
+                const cost = options?.cost ?? 1;
+                // Get config
+                const config = name ? getConfigOrThrow(name) : getConfigOrDefault();
+                const { limit, window } = config;
+                // Parse window
+                const windowMs = parseWindow(window);
+                const now = nowFn();
+                const cutoff = now - windowMs;
+                // Get composite key
+                const compositeKey = makeCompositeKey(key, name ?? '_default');
+                // Get and prune entries (don't save - read-only)
+                let entries = storage.entries.get(compositeKey) ?? [];
+                entries = pruneExpiredEntries(entries, cutoff);
+                // Calculate current usage
+                const currentCost = calculateTotalCost(entries);
+                // Check if we could accommodate this request
+                return currentCost + cost <= limit;
+            },
+            /**
+             * Get remaining quota without consuming
+             */
+            async remaining(options) {
+                const name = options?.name;
+                // Get config
+                const config = name ? getConfigOrThrow(name) : getConfigOrDefault();
+                const { limit, window } = config;
+                // Parse window
+                const windowMs = parseWindow(window);
+                const now = nowFn();
+                const cutoff = now - windowMs;
+                // Get composite key
+                const compositeKey = makeCompositeKey(key, name ?? '_default');
+                // Get and prune entries (don't save - read-only)
+                let entries = storage.entries.get(compositeKey) ?? [];
+                entries = pruneExpiredEntries(entries, cutoff);
+                // Calculate remaining
+                const currentCost = calculateTotalCost(entries);
+                return Math.max(0, limit - currentCost);
+            },
+            /**
+             * Consume specific cost from quota (for post-facto consumption)
+             */
+            async consume(cost, options) {
+                const name = options?.name;
+                // Get config
+                const config = name ? getConfigOrThrow(name) : getConfigOrDefault();
+                const { limit, window } = config;
+                // Parse window
+                const windowMs = parseWindow(window);
+                const now = nowFn();
+                const cutoff = now - windowMs;
+                // Get composite key
+                const compositeKey = makeCompositeKey(key, name ?? '_default');
+                // Get and prune entries
+                let entries = storage.entries.get(compositeKey) ?? [];
+                entries = pruneExpiredEntries(entries, cutoff);
+                // Calculate current usage before consuming
+                const currentCost = calculateTotalCost(entries);
+                // Add new entry (consume always adds, even if over limit)
+                entries.push({ timestamp: now, cost });
+                storage.entries.set(compositeKey, entries);
+                // Calculate new remaining (can be negative for over-consumption scenario)
+                const newTotal = currentCost + cost;
+                const remaining = limit - newTotal;
+                return {
+                    success: remaining >= 0,
+                    remaining: Math.max(0, remaining),
+                    resetAt: now + windowMs,
+                    limit,
+                    cost,
+                };
+            },
+            /**
+             * Reset the rate limit for this key
+             */
+            async reset(options) {
+                const name = options?.name;
+                const compositeKey = makeCompositeKey(key, name ?? '_default');
+                storage.entries.delete(compositeKey);
+            },
+            /**
+             * Get status without modifying quota
+             */
+            async status(options) {
+                const name = options?.name;
+                // Get config
+                const config = name ? getConfigOrThrow(name) : getConfigOrDefault();
+                const { limit, window } = config;
+                // Parse window
+                const windowMs = parseWindow(window);
+                const now = nowFn();
+                const cutoff = now - windowMs;
+                // Get composite key
+                const compositeKey = makeCompositeKey(key, name ?? '_default');
+                // Get and prune entries (don't save - read-only)
+                let entries = storage.entries.get(compositeKey) ?? [];
+                entries = pruneExpiredEntries(entries, cutoff);
+                // Calculate remaining
+                const currentCost = calculateTotalCost(entries);
+                const remaining = Math.max(0, limit - currentCost);
+                return {
+                    success: remaining > 0,
+                    remaining,
+                    resetAt: entries.length > 0 ? Math.min(...entries.map((e) => e.timestamp)) + windowMs : now + windowMs,
+                    limit,
+                };
+            },
+        };
+    }
+    /**
+     * Rate limits collection API
+     */
+    const rateLimitsCollection = {
+        /**
+         * Configure a named rate limit
+         */
+        configure(name, config) {
+            // Validate config
+            if (config.limit < 0) {
+                throw new Error(`Invalid limit: ${config.limit}. Limit must be non-negative`);
+            }
+            // Validate window format (will throw if invalid)
+            parseWindow(config.window);
+            // Store config (deep copy to prevent mutations)
+            storage.configs.set(name, {
+                limit: config.limit,
+                window: config.window,
+                ...(config.description && { description: config.description }),
+            });
+        },
+        /**
+         * Get all configured named limits
+         * Returns a deep copy to prevent mutations
+         */
+        getConfig() {
+            const result = {};
+            for (const [key, config] of storage.configs.entries()) {
+                result[key] = {
+                    limit: config.limit,
+                    window: config.window,
+                    ...(config.description && { description: config.description }),
+                };
+            }
+            return result;
+        },
+        /**
+         * Get configuration for a specific named limit
+         * Returns a copy to prevent mutations
+         */
+        get(name) {
+            const config = storage.configs.get(name);
+            if (!config) {
+                return undefined;
+            }
+            return {
+                limit: config.limit,
+                window: config.window,
+                ...(config.description && { description: config.description }),
+            };
+        },
+    };
+    return {
+        rateLimit: createRateLimitInstance,
+        rateLimits: rateLimitsCollection,
+        _storage: storage,
+        _now: () => nowFn(),
+    };
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/workflows/context/rate-limit.js.map

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

package/dist/workflows/context/user.js

@@ -0,0 +1,117 @@
+/**
+ * User Proxy Context API for $.user.*
+ *
+ * Provides a workflow context API for user interactions:
+ * - $.user.confirm(message) - Ask user for confirmation (returns boolean)
+ * - $.user.prompt(question) - Get text input from user (returns string)
+ * - $.user.select(question, options) - Show options to user (returns selected option)
+ * - $.user.notify(message) - Send notification to user (fire-and-forget)
+ * - $.user.chat(message) - Open chat interface for conversation
+ *
+ * Unlike $.human.*, which routes to specific roles (CEO, Legal, etc.),
+ * $.user.* interacts directly with the end user of the application.
+ *
+ * @module workflows/context/user
+ */
+import { DEFAULT_TIMEOUT, getDOStub as getDOStubBase, makeRequest as makeRequestBase, } from './human-base';
+// ============================================================================
+// FACTORY FUNCTION
+// ============================================================================
+/**
+ * Creates a user proxy context for user interactions in workflows
+ *
+ * @param config - Configuration options
+ * @returns UserProxyContext with user methods
+ */
+export function createUserProxy(config) {
+    const { env, defaultTimeout = DEFAULT_TIMEOUT, userId = 'default' } = config;
+    /**
+     * Get DO stub for user
+     */
+    function getDOStub() {
+        return getDOStubBase({
+            namespace: env.USER_DO,
+            name: userId,
+        });
+    }
+    /**
+     * Make a request to User DO
+     */
+    async function makeRequest(path, method, body) {
+        const stub = getDOStub();
+        return makeRequestBase({
+            stub,
+            baseUrl: 'https://user.do',
+            path,
+            method,
+            body,
+        });
+    }
+    return {
+        user: {
+            /**
+             * Ask user for confirmation
+             */
+            async confirm(message, options = {}) {
+                const response = await makeRequest('/confirm', 'POST', {
+                    message,
+                    timeout: options.timeout ?? defaultTimeout,
+                    default: options.default,
+                });
+                const result = (await response.json());
+                return result.confirmed;
+            },
+            /**
+             * Get text input from user
+             */
+            async prompt(question, options = {}) {
+                const response = await makeRequest('/prompt', 'POST', {
+                    question,
+                    timeout: options.timeout ?? defaultTimeout,
+                    placeholder: options.placeholder,
+                    hasValidation: !!options.validate,
+                });
+                const result = (await response.json());
+                const answer = result.answer ?? '';
+                // Validate if validation function provided
+                if (options.validate && !options.validate(answer)) {
+                    // In real implementation, would retry
+                    return answer;
+                }
+                return answer;
+            },
+            /**
+             * Show options to user
+             */
+            async select(question, selectOptions, options = {}) {
+                const response = await makeRequest('/select', 'POST', {
+                    question,
+                    options: selectOptions,
+                    timeout: options.timeout ?? defaultTimeout,
+                });
+                const result = (await response.json());
+                return result.selected ?? selectOptions[0];
+            },
+            /**
+             * Send notification to user (fire-and-forget)
+             */
+            async notify(message) {
+                await makeRequest('/notify', 'POST', { message });
+            },
+            /**
+             * Open chat interface for conversation
+             */
+            async chat(message) {
+                const response = await makeRequest('/chat', 'POST', { message });
+                const result = (await response.json());
+                return {
+                    messages: [{ role: 'assistant', content: message }],
+                    close: async () => {
+                        await makeRequest(`/chat/${result.conversationId}/close`, 'POST');
+                    },
+                };
+            },
+        },
+    };
+}
+//# sourceMappingURL=user.js.map

package/dist/workflows/context/user.js.map

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