ezthrottle 1.0.0 → 1.1.1

package/README.md

@@ -1,28 +1,280 @@
 # EZThrottle Node.js SDK
 
-The World's First API Aqueduct.
+The API Dam for rate-limited services. Queue and execute HTTP requests with smart retry logic, multi-region racing, and webhook delivery.
 
 ## Installation
 
 ```bash
-npm install @tracktags/ezthrottle
+npm install ezthrottle
 ```
 
 ## Quick Start
 
 ```javascript
-const { EZThrottle } = require('@tracktags/ezthrottle');
+const { EZThrottle, Step, StepType } = require('ezthrottle');
 
-const client = new EZThrottle({
-  apiKey: 'ck_live_cust_XXX_YYY',
-});
+const client = new EZThrottle({ apiKey: 'your_api_key' });
+
+// Simple job submission
+const result = await new Step(client)
+  .url('https://api.example.com/endpoint')
+  .method('POST')
+  .type(StepType.PERFORMANCE)
+  .webhooks([{ url: 'https://your-app.com/webhook' }])
+  .execute();
+
+console.log(`Job ID: ${result.job_id}`);
+```
+
+## Step Types
+
+### StepType.PERFORMANCE (Server-side execution)
+
+Submit jobs to EZThrottle for distributed execution with multi-region racing and webhook delivery.
+
+```javascript
+await new Step(client)
+  .url('https://api.stripe.com/charges')
+  .type(StepType.PERFORMANCE)
+  .webhooks([{ url: 'https://app.com/webhook' }])
+  .regions(['iad', 'lax', 'ord'])  // Multi-region racing
+  .executionMode('race')  // First completion wins
+  .execute();
+```
+
+### StepType.FRUGAL (Client-side first)
+
+Execute locally first, only forward to EZThrottle on specific error codes. Saves money!
+
+```javascript
+await new Step(client)
+  .url('https://api.example.com')
+  .type(StepType.FRUGAL)
+  .fallbackOnError([429, 500, 503])  // Forward to EZThrottle on these codes
+  .execute();
+```
+
+## Idempotent Key Strategies
+
+**Critical concept:** Idempotent keys prevent duplicate job execution. Choose the right strategy for your use case.
+
+### IdempotentStrategy.HASH (Default)
+
+Backend generates deterministic hash of (url, method, body, customer_id). **Prevents duplicates.**
+
+**Use when:**
+- Payment processing (don't charge twice!)
+- Critical operations (create user, send notification)
+- You want automatic deduplication
+
+**Example:**
+```javascript
+const { IdempotentStrategy } = require('ezthrottle');
+
+// Prevents duplicate charges - same request = rejected as duplicate
+await new Step(client)
+  .url('https://api.stripe.com/charges')
+  .body(JSON.stringify({ amount: 1000, currency: 'usd' }))
+  .idempotentStrategy(IdempotentStrategy.HASH)  // Default
+  .execute();
+```
+
+### IdempotentStrategy.UNIQUE
+
+SDK generates unique UUID per request. **Allows duplicates.**
+
+**Use when:**
+- Polling endpoints (same URL, different data each time)
+- Webhooks (want to send every time)
+- Scheduled jobs (run every minute/hour)
+- GET requests that return changing data
+
+**Example:**
+```javascript
+// Poll API every minute - each request gets unique UUID
+setInterval(async () => {
+  await new Step(client)
+    .url('https://api.example.com/status')
+    .idempotentStrategy(IdempotentStrategy.UNIQUE)  // New UUID each time
+    .execute();
+}, 60000);
+```
+
+## Workflow Chaining
+
+Chain steps together with `.onSuccess()`, `.onFailure()`, and `.fallback()`:
+
+```javascript
+// Analytics step (cheap)
+const analytics = new Step(client)
+  .url('https://analytics.com/track')
+  .type(StepType.FRUGAL);
+
+// Notification (fast, distributed)
+const notification = new Step(client)
+  .url('https://notify.com')
+  .type(StepType.PERFORMANCE)
+  .webhooks([{ url: 'https://app.com/webhook' }])
+  .regions(['iad', 'lax'])
+  .onSuccess(analytics);
+
+// Primary API call (cheap local execution)
+await new Step(client)
+  .url('https://api.example.com')
+  .type(StepType.FRUGAL)
+  .fallbackOnError([429, 500])
+  .onSuccess(notification)
+  .execute();
+```
+
+## Fallback Chains
+
+Handle failures with automatic fallback execution:
+
+```javascript
+const backupApi = new Step().url('https://backup-api.com');
+
+await new Step(client)
+  .url('https://primary-api.com')
+  .fallback(backupApi, { triggerOnError: [500, 502, 503] })
+  .execute();
+```
+
+## Multi-Region Racing
 
-const result = await client.queueRequest({
-  url: 'https://api.example.com/data',
-  webhookUrl: 'https://myapp.com/webhook',
+Submit jobs to multiple regions, fastest wins:
+
+```javascript
+await new Step(client)
+  .url('https://api.example.com')
+  .regions(['iad', 'lax', 'ord'])  // Try all 3 regions
+  .regionPolicy('fallback')  // Auto-route if region down
+  .executionMode('race')  // First completion wins
+  .webhooks([{ url: 'https://app.com/webhook' }])
+  .execute();
+```
+
+## Webhook Fanout (Multiple Webhooks)
+
+Deliver job results to multiple services simultaneously:
+
+```javascript
+await new Step(client)
+  .url('https://api.stripe.com/charges')
+  .method('POST')
+  .webhooks([
+    // Primary webhook (must succeed)
+    { url: 'https://app.com/payment-complete', has_quorum_vote: true },
+
+    // Analytics webhook (optional)
+    { url: 'https://analytics.com/track', has_quorum_vote: false },
+
+    // Notification service (must succeed)
+    { url: 'https://notify.com/alert', has_quorum_vote: true },
+
+    // Multi-region webhook racing
+    { url: 'https://backup.com/webhook', regions: ['iad', 'lax'], has_quorum_vote: true }
+  ])
+  .webhookQuorum(2)  // At least 2 webhooks with has_quorum_vote=true must succeed
+  .execute();
+```
+
+## Retry Policies
+
+Customize retry behavior:
+
+```javascript
+await new Step(client)
+  .url('https://api.example.com')
+  .retryPolicy({
+    max_retries: 5,
+    max_reroutes: 3,
+    retry_codes: [429, 503],  // Retry in same region
+    reroute_codes: [500, 502, 504]  // Try different region
+  })
+  .execute();
+```
+
+## Production Ready ✅
+
+This SDK is production-ready with **working examples validated in CI on every push**.
+
+### Reference Implementation: test-app/
+
+The `test-app/` directory contains **real, working code** you can learn from. Not toy examples - this is production code we run in automated tests against live EZThrottle backend.
+
+**Multi-Region Racing** ([test-app/app.js:104-122](test-app/app.js#L104-L122))
+```javascript
+await new Step(client)
+  .url('https://httpbin.org/delay/1')
+  .type(StepType.PERFORMANCE)
+  .webhooks([{ url: `${APP_URL}/webhook` }])
+  .regions(['iad', 'lax', 'ord'])  // Race across 3 regions
+  .executionMode('race')  // First completion wins
+  .execute();
+```
+
+**Idempotent HASH (Deduplication)** ([test-app/app.js:181-203](test-app/app.js#L181-L203))
+```javascript
+// Same request twice = same job_id (deduplicated)
+await new Step(client)
+  .url(`https://httpbin.org/get?run=${runId}`)
+  .idempotentStrategy(IdempotentStrategy.HASH)
+  .execute();
+```
+
+**Fallback Chain** ([test-app/app.js:125-154](test-app/app.js#L125-L154))
+```javascript
+await new Step(client)
+  .url('https://httpbin.org/status/500')
+  .fallback(
+    new Step().url('https://httpbin.org/status/200'),
+    { triggerOnError: [500, 502, 503] }
+  )
+  .execute();
+```
+
+**On-Success Workflow** ([test-app/app.js:157-178](test-app/app.js#L157-L178))
+```javascript
+await new Step(client)
+  .url('https://httpbin.org/status/200')
+  .onSuccess(
+    new Step().url('https://httpbin.org/delay/1')
+  )
+  .execute();
+```
+
+**FRUGAL Local Execution** ([test-app/app.js:247-260](test-app/app.js#L247-L260))
+```javascript
+await new Step(client)
+  .url('https://httpbin.org/status/200')
+  .type(StepType.FRUGAL)
+  .execute();
+```
+
+**Validated in CI:**
+- ✅ GitHub Actions runs these examples against live backend on every push
+- ✅ 7 integration tests covering all SDK features
+- ✅ Proves the code actually works, not just documentation
+
+## Legacy API (Deprecated)
+
+For backward compatibility, the old `queueRequest()` method is still available:
+
+```javascript
+await client.queueRequest({
+  url: 'https://api.example.com',
+  webhookUrl: 'https://your-app.com/webhook',  // Note: singular
+  method: 'POST'
 });
+```
+
+**Prefer the new `Step` builder API for all new code!**
 
-console.log('Job queued:', result.job_id);
+## Environment Variables
+
+```bash
+EZTHROTTLE_API_KEY=your_api_key_here
 ```
 
 ## License

package/dist/client.d.ts

@@ -0,0 +1,58 @@
+import { EZThrottleConfig, SubmitJobParams } from './types';
+interface QueueRequestParams {
+    url: string;
+    webhookUrl?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    metadata?: Record<string, any>;
+    retryAt?: number;
+}
+interface QueueAndWaitParams extends QueueRequestParams {
+    timeout?: number;
+    pollInterval?: number;
+}
+interface RequestParams {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+export declare class EZThrottle {
+    private apiKey;
+    private tracktagsUrl;
+    private ezthrottleUrl;
+    constructor({ apiKey, tracktagsUrl, ezthrottleUrl }: EZThrottleConfig);
+    /**
+     * Submit a job through TracktTags proxy → EZThrottle (NEW API with full features)
+     *
+     * @param {Object} options - Job configuration
+     * @param {string} options.url - Target URL to request
+     * @param {string} [options.method='GET'] - HTTP method
+     * @param {Object} [options.headers] - Request headers
+     * @param {string} [options.body] - Request body
+     * @param {Object} [options.metadata] - Custom metadata
+     * @param {Array} [options.webhooks] - Array of webhook configs: [{url, regions, hasQuorumVote}]
+     * @param {number} [options.webhookQuorum=1] - Minimum webhooks that must succeed
+     * @param {Array<string>} [options.regions] - Regions to execute in (e.g., ['iad', 'lax', 'ord'])
+     * @param {string} [options.regionPolicy='fallback'] - 'fallback' or 'strict'
+     * @param {string} [options.executionMode='race'] - 'race' or 'fanout'
+     * @param {Object} [options.retryPolicy] - Retry configuration
+     * @param {Object} [options.fallbackJob] - Recursive fallback configuration
+     * @param {Object} [options.onSuccess] - Job to spawn on success
+     * @param {Object} [options.onFailure] - Job to spawn on failure
+     * @param {number} [options.onFailureTimeoutMs] - Timeout before triggering onFailure
+     * @param {string} [options.idempotentKey] - Deduplication key
+     * @param {number} [options.retryAt] - Timestamp (ms) when job can be retried
+     * @returns {Promise<Object>} - {job_id, status, ...}
+     */
+    submitJob({ url, method, headers, body, metadata, webhooks, webhookQuorum, regions, regionPolicy, executionMode, retryPolicy, fallbackJob, onSuccess, onFailure, onFailureTimeoutMs, idempotentKey, retryAt, }: SubmitJobParams): Promise<any>;
+    /**
+     * DEPRECATED: Use submitJob() instead
+     * Legacy method for backward compatibility
+     */
+    queueRequest({ url, webhookUrl, method, headers, body, metadata, retryAt }: QueueRequestParams): Promise<any>;
+    request({ url, method, headers, body }: RequestParams): Promise<any>;
+    queueAndWait({ url, webhookUrl, method, headers, body, metadata, retryAt, timeout, pollInterval, }: QueueAndWaitParams): Promise<any>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,177 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EZThrottle = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const errors_1 = require("./errors");
+class EZThrottle {
+    constructor({ apiKey, tracktagsUrl, ezthrottleUrl }) {
+        if (!apiKey) {
+            throw new Error('apiKey is required');
+        }
+        this.apiKey = apiKey;
+        this.tracktagsUrl = tracktagsUrl || 'https://tracktags.fly.dev';
+        this.ezthrottleUrl = ezthrottleUrl || 'https://ezthrottle.fly.dev';
+    }
+    /**
+     * Submit a job through TracktTags proxy → EZThrottle (NEW API with full features)
+     *
+     * @param {Object} options - Job configuration
+     * @param {string} options.url - Target URL to request
+     * @param {string} [options.method='GET'] - HTTP method
+     * @param {Object} [options.headers] - Request headers
+     * @param {string} [options.body] - Request body
+     * @param {Object} [options.metadata] - Custom metadata
+     * @param {Array} [options.webhooks] - Array of webhook configs: [{url, regions, hasQuorumVote}]
+     * @param {number} [options.webhookQuorum=1] - Minimum webhooks that must succeed
+     * @param {Array<string>} [options.regions] - Regions to execute in (e.g., ['iad', 'lax', 'ord'])
+     * @param {string} [options.regionPolicy='fallback'] - 'fallback' or 'strict'
+     * @param {string} [options.executionMode='race'] - 'race' or 'fanout'
+     * @param {Object} [options.retryPolicy] - Retry configuration
+     * @param {Object} [options.fallbackJob] - Recursive fallback configuration
+     * @param {Object} [options.onSuccess] - Job to spawn on success
+     * @param {Object} [options.onFailure] - Job to spawn on failure
+     * @param {number} [options.onFailureTimeoutMs] - Timeout before triggering onFailure
+     * @param {string} [options.idempotentKey] - Deduplication key
+     * @param {number} [options.retryAt] - Timestamp (ms) when job can be retried
+     * @returns {Promise<Object>} - {job_id, status, ...}
+     */
+    async submitJob({ url, method = 'GET', headers, body, metadata, webhooks, webhookQuorum = 1, regions, regionPolicy = 'fallback', executionMode = 'race', retryPolicy, fallbackJob, onSuccess, onFailure, onFailureTimeoutMs, idempotentKey, retryAt, }) {
+        // Build EZThrottle job payload
+        const jobPayload = {
+            url,
+            method: method.toUpperCase(),
+        };
+        // Add optional parameters
+        if (headers)
+            jobPayload.headers = headers;
+        if (body)
+            jobPayload.body = body;
+        if (metadata)
+            jobPayload.metadata = metadata;
+        if (webhooks)
+            jobPayload.webhooks = webhooks;
+        if (webhookQuorum !== 1)
+            jobPayload.webhook_quorum = webhookQuorum;
+        if (regions)
+            jobPayload.regions = regions;
+        if (regionPolicy !== 'fallback')
+            jobPayload.region_policy = regionPolicy;
+        if (executionMode !== 'race')
+            jobPayload.execution_mode = executionMode;
+        if (retryPolicy)
+            jobPayload.retry_policy = retryPolicy;
+        if (fallbackJob)
+            jobPayload.fallback_job = fallbackJob;
+        if (onSuccess)
+            jobPayload.on_success = onSuccess;
+        if (onFailure)
+            jobPayload.on_failure = onFailure;
+        if (onFailureTimeoutMs !== undefined)
+            jobPayload.on_failure_timeout_ms = onFailureTimeoutMs;
+        if (idempotentKey)
+            jobPayload.idempotent_key = idempotentKey;
+        if (retryAt !== undefined)
+            jobPayload.retry_at = retryAt;
+        console.log('[SDK] Sending jobPayload with idempotent_key:', jobPayload.idempotent_key);
+        // Build proxy request
+        const proxyPayload = {
+            scope: 'customer',
+            metric_name: '',
+            target_url: `${this.ezthrottleUrl}/api/v1/jobs`,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(jobPayload),
+        };
+        const response = await (0, node_fetch_1.default)(`${this.tracktagsUrl}/api/v1/proxy`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(proxyPayload),
+        });
+        // Handle proxy responses
+        if (response.status === 429) {
+            const errorData = await response.json();
+            const retryAfterSeconds = response.headers.get('retry-after');
+            let calculatedRetryAt = errorData.retry_at;
+            if (retryAfterSeconds && !calculatedRetryAt) {
+                calculatedRetryAt = Date.now() + (parseInt(retryAfterSeconds) * 1000);
+            }
+            throw new errors_1.RateLimitError(`Rate limited: ${errorData.error || 'Unknown error'}`, calculatedRetryAt);
+        }
+        if (response.status !== 200) {
+            const text = await response.text();
+            throw new errors_1.EZThrottleError(`Proxy request failed: ${text}`);
+        }
+        const proxyResponse = await response.json();
+        if (proxyResponse.status !== 'allowed') {
+            throw new errors_1.EZThrottleError(`Request denied: ${proxyResponse.error || 'Unknown error'}`);
+        }
+        const forwarded = proxyResponse.forwarded_response || {};
+        const statusCode = forwarded.status_code || 0;
+        if (statusCode < 200 || statusCode >= 300) {
+            throw new errors_1.EZThrottleError(`EZThrottle job creation failed: ${forwarded.body || 'Unknown error'}`);
+        }
+        const ezthrottleResponse = JSON.parse(forwarded.body || '{}');
+        return ezthrottleResponse;
+    }
+    /**
+     * DEPRECATED: Use submitJob() instead
+     * Legacy method for backward compatibility
+     */
+    async queueRequest({ url, webhookUrl, method = 'GET', headers, body, metadata, retryAt }) {
+        // Convert singular webhookUrl to webhooks array
+        const webhooks = webhookUrl
+            ? [{ url: webhookUrl, has_quorum_vote: true }]
+            : undefined;
+        return this.submitJob({
+            url,
+            method,
+            headers,
+            body,
+            metadata,
+            webhooks,
+            retryAt,
+        });
+    }
+    async request({ url, method = 'GET', headers, body }) {
+        return (0, node_fetch_1.default)(url, {
+            method,
+            headers,
+            body,
+        });
+    }
+    async queueAndWait({ url, webhookUrl, method = 'GET', headers, body, metadata, retryAt, timeout = 300000, pollInterval = 2000, }) {
+        const result = await this.queueRequest({
+            url,
+            webhookUrl,
+            method,
+            headers,
+            body,
+            metadata,
+            retryAt,
+        });
+        const jobId = result.job_id;
+        if (!jobId) {
+            throw new errors_1.EZThrottleError('No job_id in response');
+        }
+        const startTime = Date.now();
+        return new Promise((resolve, reject) => {
+            const checkResult = async () => {
+                if (Date.now() - startTime > timeout) {
+                    reject(new errors_1.TimeoutError(`Timeout waiting for job ${jobId}`));
+                    return;
+                }
+                setTimeout(checkResult, pollInterval);
+            };
+            checkResult();
+        });
+    }
+}
+exports.EZThrottle = EZThrottle;

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+export declare class EZThrottleError extends Error {
+    retryAt: number | null;
+    constructor(message: string, retryAt?: number | null);
+}
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+export declare class RateLimitError extends EZThrottleError {
+    constructor(message: string, retryAt: number);
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = exports.TimeoutError = exports.EZThrottleError = void 0;
+class EZThrottleError extends Error {
+    constructor(message, retryAt = null) {
+        super(message);
+        this.name = 'EZThrottleError';
+        this.retryAt = retryAt;
+    }
+}
+exports.EZThrottleError = EZThrottleError;
+class TimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+class RateLimitError extends EZThrottleError {
+    constructor(message, retryAt) {
+        super(message, retryAt);
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;

package/dist/idempotentStrategy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Idempotent key generation strategy
+ */
+export declare enum IdempotentStrategy {
+    /** Backend generates deterministic hash - prevents duplicates (DEFAULT) */
+    HASH = "hash",
+    /** SDK generates UUID - allows duplicates (polling, webhooks, scheduled jobs) */
+    UNIQUE = "unique"
+}

package/dist/idempotentStrategy.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotentStrategy = void 0;
+/**
+ * Idempotent key generation strategy
+ */
+var IdempotentStrategy;
+(function (IdempotentStrategy) {
+    /** Backend generates deterministic hash - prevents duplicates (DEFAULT) */
+    IdempotentStrategy["HASH"] = "hash";
+    /** SDK generates UUID - allows duplicates (polling, webhooks, scheduled jobs) */
+    IdempotentStrategy["UNIQUE"] = "unique";
+})(IdempotentStrategy || (exports.IdempotentStrategy = IdempotentStrategy = {}));

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { EZThrottle } from './client';
+export { EZThrottleError, TimeoutError, RateLimitError } from './errors';
+export { Step } from './step';
+export { StepType } from './stepType';
+export { IdempotentStrategy } from './idempotentStrategy';
+export * from './types';
+import { EZThrottle } from './client';
+export default EZThrottle;

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdempotentStrategy = exports.StepType = exports.Step = exports.RateLimitError = exports.TimeoutError = exports.EZThrottleError = exports.EZThrottle = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "EZThrottle", { enumerable: true, get: function () { return client_1.EZThrottle; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "EZThrottleError", { enumerable: true, get: function () { return errors_1.EZThrottleError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_1.TimeoutError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+var step_1 = require("./step");
+Object.defineProperty(exports, "Step", { enumerable: true, get: function () { return step_1.Step; } });
+var stepType_1 = require("./stepType");
+Object.defineProperty(exports, "StepType", { enumerable: true, get: function () { return stepType_1.StepType; } });
+var idempotentStrategy_1 = require("./idempotentStrategy");
+Object.defineProperty(exports, "IdempotentStrategy", { enumerable: true, get: function () { return idempotentStrategy_1.IdempotentStrategy; } });
+__exportStar(require("./types"), exports);
+// Default export for CommonJS compatibility
+const client_2 = require("./client");
+exports.default = client_2.EZThrottle;