voidforge-build 23.9.1

package/dist/wizard/lib/patterns/outbound-rate-limiter.js

@@ -0,0 +1,216 @@
+/**
+ * Pattern: Outbound Rate Limiter
+ *
+ * Key principles:
+ * - Token bucket per-platform with configurable capacity and refill rate
+ * - Safety margin reservation: hold back 10% of capacity for health checks
+ * - Queue overflow handling: reject with RATE_LIMITED error, don't block forever
+ * - Per-platform configuration (Meta: 200/hr, Google: 15000/day, etc.)
+ * - Exponential backoff on 429 responses from platforms
+ * - Daily quota tracking for platforms with daily limits (Google, LinkedIn)
+ *
+ * Agents: Breeze (platform relations), Wax (paid ads)
+ *
+ * PRD Reference: §9.5 (rate limit strategy), §9.17 (outbound-rate-limiter.ts)
+ */
+const PLATFORM_RATES = {
+    meta: {
+        platform: 'meta',
+        capacity: 200, // 200 calls/hr/ad account
+        refillRate: 200 / 3600, // ~0.056 tokens/sec
+        burstAllowed: true,
+        safetyMargin: 0.10,
+        backoffBase: 1000,
+        maxRetries: 5,
+    },
+    google: {
+        platform: 'google',
+        capacity: 100, // Batch operations — 15000/day but bursty
+        refillRate: 15000 / 86400, // ~0.174 tokens/sec
+        dailyQuota: 15000, // Mutate operations/day
+        burstAllowed: true,
+        safetyMargin: 0.10,
+        backoffBase: 1000,
+        maxRetries: 5,
+    },
+    tiktok: {
+        platform: 'tiktok',
+        capacity: 10, // 10 req/sec
+        refillRate: 10, // 10 tokens/sec
+        burstAllowed: false, // Strict per-second
+        safetyMargin: 0.10,
+        backoffBase: 500,
+        maxRetries: 5,
+    },
+    linkedin: {
+        platform: 'linkedin',
+        capacity: 100, // 100 calls/day — very restrictive
+        refillRate: 100 / 86400, // ~0.0012 tokens/sec
+        dailyQuota: 100,
+        burstAllowed: false,
+        safetyMargin: 0.20, // Higher margin — can't afford waste
+        backoffBase: 5000,
+        maxRetries: 3, // Fewer retries — each costs a daily call
+    },
+    twitter: {
+        platform: 'twitter',
+        capacity: 450, // 450 req/15min
+        refillRate: 450 / 900, // 0.5 tokens/sec
+        burstAllowed: true,
+        safetyMargin: 0.10,
+        backoffBase: 1000,
+        maxRetries: 5,
+    },
+    reddit: {
+        platform: 'reddit',
+        capacity: 60, // Conservative: 60 req/min (not documented)
+        refillRate: 1, // 1 token/sec
+        burstAllowed: false,
+        safetyMargin: 0.15,
+        backoffBase: 2000,
+        maxRetries: 3,
+    },
+};
+// ── Token Bucket Implementation ───────────────────────
+class OutboundRateLimiter {
+    tokens;
+    lastRefill;
+    dailyUsed = 0;
+    dailyResetAt;
+    config;
+    effectiveCapacity;
+    constructor(platform) {
+        this.config = PLATFORM_RATES[platform];
+        this.effectiveCapacity = Math.floor(this.config.capacity * (1 - this.config.safetyMargin));
+        this.tokens = this.effectiveCapacity;
+        this.lastRefill = Date.now();
+        this.dailyResetAt = this.nextMidnightUTC();
+    }
+    /**
+     * Acquire a token. Resolves when a token is available.
+     * Throws if the daily quota is exhausted.
+     */
+    async acquire() {
+        this.checkDailyReset();
+        // Daily quota check
+        if (this.config.dailyQuota && this.dailyUsed >= this.config.dailyQuota) {
+            const hoursUntilReset = (this.dailyResetAt - Date.now()) / 3600000;
+            throw new RateLimitError(this.config.platform, `Daily quota exhausted (${this.dailyUsed}/${this.config.dailyQuota}). Resets in ${hoursUntilReset.toFixed(1)} hours.`, this.dailyResetAt - Date.now());
+        }
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            this.dailyUsed += 1;
+            return;
+        }
+        // Wait for a token
+        const waitMs = Math.ceil((1 / this.config.refillRate) * 1000);
+        if (waitMs > 30000) {
+            // Don't wait more than 30 seconds — reject instead
+            throw new RateLimitError(this.config.platform, 'Rate limited — next token available in ' + (waitMs / 1000).toFixed(1) + 's', waitMs);
+        }
+        await new Promise(resolve => setTimeout(resolve, waitMs));
+        this.refill();
+        this.tokens -= 1;
+        this.dailyUsed += 1;
+    }
+    /**
+     * Execute a request with automatic retry on 429 responses.
+     * Uses exponential backoff with platform-specific base delay.
+     */
+    async executeWithRetry(fn) {
+        let attempt = 0;
+        while (attempt < this.config.maxRetries) {
+            await this.acquire();
+            try {
+                return await fn();
+            }
+            catch (err) {
+                if (isRateLimitResponse(err) && attempt < this.config.maxRetries - 1) {
+                    const delay = this.config.backoffBase * Math.pow(2, attempt);
+                    const retryAfter = extractRetryAfter(err);
+                    const waitMs = retryAfter ? retryAfter * 1000 : delay;
+                    await new Promise(resolve => setTimeout(resolve, waitMs));
+                    attempt++;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw new RateLimitError(this.config.platform, `Max retries (${this.config.maxRetries}) exceeded`, 0);
+    }
+    /** Get current rate limiter status for monitoring */
+    getStatus() {
+        this.refill();
+        return {
+            tokens: Math.floor(this.tokens),
+            capacity: this.effectiveCapacity,
+            dailyUsed: this.dailyUsed,
+            dailyQuota: this.config.dailyQuota,
+        };
+    }
+    /** Reserve N tokens for a batch operation. Returns false if insufficient. */
+    canReserve(count) {
+        this.refill();
+        return this.tokens >= count;
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000;
+        this.tokens = Math.min(this.effectiveCapacity, this.tokens + elapsed * this.config.refillRate);
+        this.lastRefill = now;
+    }
+    checkDailyReset() {
+        if (Date.now() >= this.dailyResetAt) {
+            this.dailyUsed = 0;
+            this.dailyResetAt = this.nextMidnightUTC();
+        }
+    }
+    nextMidnightUTC() {
+        const d = new Date();
+        d.setUTCDate(d.getUTCDate() + 1);
+        d.setUTCHours(0, 0, 0, 0);
+        return d.getTime();
+    }
+}
+// ── Error Types ───────────────────────────────────────
+class RateLimitError extends Error {
+    platform;
+    retryAfterMs;
+    constructor(platform, message, retryAfterMs) {
+        super(`[${platform}] Rate limited: ${message}`);
+        this.platform = platform;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+function isRateLimitResponse(err) {
+    if (err instanceof RateLimitError)
+        return true;
+    // Check for HTTP 429 in various error shapes
+    const e = err;
+    if (e.status === 429 || e.statusCode === 429)
+        return true;
+    if (typeof e.code === 'string' && e.code === 'RATE_LIMITED')
+        return true;
+    return false;
+}
+function extractRetryAfter(err) {
+    const e = err;
+    if (typeof e.retryAfter === 'number')
+        return e.retryAfter;
+    if (e.headers && typeof e.headers['retry-after'] === 'string') {
+        return parseInt(e.headers['retry-after']);
+    }
+    return null;
+}
+// ── Limiter Registry ──────────────────────────────────
+const limiters = new Map();
+function getLimiter(platform) {
+    let limiter = limiters.get(platform);
+    if (!limiter) {
+        limiter = new OutboundRateLimiter(platform);
+        limiters.set(platform, limiter);
+    }
+    return limiter;
+}
+export { OutboundRateLimiter, RateLimitError, PLATFORM_RATES, getLimiter, isRateLimitResponse };

package/dist/wizard/lib/patterns/revenue-source-adapter.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pattern: Revenue Source Adapter (Read-Only)
+ *
+ * Key principles:
+ * - Read-only interface — VoidForge never processes payments directly
+ * - Separate from AdPlatformAdapter — revenue in, ad spend out
+ * - Polling with overlapping windows for gap-free coverage (ADR-5)
+ * - Dedup by externalId to prevent double-counting
+ * - Webhook signature verification mandatory when webhooks are implemented
+ * - USD-only enforcement (ADR-6) at connection time
+ *
+ * Agents: Dockson (treasury), Vin (analytics)
+ *
+ * PRD Reference: §9.4, §9.9, §9.17 (polling improvements), ADR-5/ADR-6
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+type RevenueSource = 'stripe' | 'paddle';
+interface RevenueSourceAdapter {
+    /** Establish connection and verify credentials work */
+    connect(credentials: RevenueCredentials): Promise<ConnectionResult>;
+    /** Detect the account's currency for ADR-6 enforcement */
+    detectCurrency(credentials: RevenueCredentials): Promise<string>;
+    /**
+     * Fetch transactions in a date range.
+     * Uses overlapping windows: fetch from (lastPollTime - 5 minutes) to now.
+     * Dedup by externalId at the caller.
+     */
+    getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage>;
+    /** Get current account balance (optional — not all sources support this) */
+    getBalance?(): Promise<BalanceResult>;
+    /**
+     * Verify webhook signature (mandatory when webhooks are implemented).
+     * Deferred to remote mode per ADR-5 — not called in v11.x polling mode.
+     */
+    verifyWebhookSignature?(payload: Buffer, signature: string, secret: string): boolean;
+}
+interface RevenueCredentials {
+    source: RevenueSource;
+    apiKey?: string;
+    accessToken?: string;
+}
+interface ConnectionResult {
+    connected: boolean;
+    accountId?: string;
+    accountName?: string;
+    currency?: string;
+    error?: string;
+}
+interface DateRange {
+    start: string;
+    end: string;
+}
+interface TransactionPage {
+    transactions: RevenueTransaction[];
+    hasMore: boolean;
+    cursor?: string;
+}
+interface RevenueTransaction {
+    externalId: string;
+    type: 'charge' | 'subscription' | 'refund' | 'dispute';
+    amount: Cents;
+    currency: 'USD';
+    description: string;
+    customerId?: string;
+    subscriptionId?: string;
+    metadata: Record<string, string>;
+    createdAt: string;
+}
+interface BalanceResult {
+    available: Cents;
+    pending: Cents;
+    currency: 'USD';
+}
+declare class StripeAdapter implements RevenueSourceAdapter {
+    private apiKey;
+    private readonly baseUrl;
+    connect(credentials: RevenueCredentials): Promise<ConnectionResult>;
+    detectCurrency(credentials: RevenueCredentials): Promise<string>;
+    getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage>;
+    getBalance(): Promise<BalanceResult>;
+    verifyWebhookSignature(payload: Buffer, signature: string, secret: string): boolean;
+    private apiCall;
+}
+declare class PaddleAdapter implements RevenueSourceAdapter {
+    private apiKey;
+    private readonly baseUrl;
+    connect(credentials: RevenueCredentials): Promise<ConnectionResult>;
+    detectCurrency(credentials: RevenueCredentials): Promise<string>;
+    getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage>;
+    private apiCall;
+}
+declare function hashCustomerId(customerId: string): string;
+export type { RevenueSourceAdapter, RevenueCredentials, ConnectionResult, TransactionPage, RevenueTransaction, BalanceResult, DateRange };
+export { StripeAdapter, PaddleAdapter, hashCustomerId };

package/dist/wizard/lib/patterns/revenue-source-adapter.js

@@ -0,0 +1,182 @@
+/**
+ * Pattern: Revenue Source Adapter (Read-Only)
+ *
+ * Key principles:
+ * - Read-only interface — VoidForge never processes payments directly
+ * - Separate from AdPlatformAdapter — revenue in, ad spend out
+ * - Polling with overlapping windows for gap-free coverage (ADR-5)
+ * - Dedup by externalId to prevent double-counting
+ * - Webhook signature verification mandatory when webhooks are implemented
+ * - USD-only enforcement (ADR-6) at connection time
+ *
+ * Agents: Dockson (treasury), Vin (analytics)
+ *
+ * PRD Reference: §9.4, §9.9, §9.17 (polling improvements), ADR-5/ADR-6
+ */
+// ── Reference Implementation: Stripe ──────────────────
+class StripeAdapter {
+    apiKey = '';
+    baseUrl = 'https://api.stripe.com/v1';
+    async connect(credentials) {
+        this.apiKey = credentials.apiKey || '';
+        try {
+            const account = await this.apiCall('GET', '/account');
+            return {
+                connected: true,
+                accountId: account.id,
+                accountName: account.business_profile?.name || account.email,
+                currency: account.default_currency?.toUpperCase(),
+            };
+        }
+        catch (err) {
+            return { connected: false, error: err.message };
+        }
+    }
+    async detectCurrency(credentials) {
+        const result = await this.connect(credentials);
+        return result.currency || 'USD';
+    }
+    async getTransactions(range, cursor) {
+        // Use Stripe Events API for sequential, immutable event log (§9.18)
+        const params = {
+            type: 'charge.succeeded',
+            'created[gte]': String(Math.floor(new Date(range.start).getTime() / 1000)),
+            'created[lte]': String(Math.floor(new Date(range.end).getTime() / 1000)),
+            limit: '100',
+        };
+        if (cursor)
+            params.starting_after = cursor;
+        const data = await this.apiCall('GET', '/events', params);
+        const transactions = data.data.map((event) => {
+            const charge = event.data?.object;
+            return {
+                externalId: event.id,
+                type: 'charge',
+                amount: (charge?.amount || 0), // Stripe amounts are already in cents
+                currency: 'USD',
+                description: charge?.description || '',
+                customerId: charge?.customer ? hashCustomerId(charge.customer) : undefined,
+                subscriptionId: charge?.subscription,
+                metadata: charge?.metadata || {},
+                createdAt: new Date(event.created * 1000).toISOString(),
+            };
+        });
+        return {
+            transactions,
+            hasMore: data.has_more,
+            cursor: data.data.length > 0 ? data.data[data.data.length - 1].id : undefined,
+        };
+    }
+    async getBalance() {
+        const data = await this.apiCall('GET', '/balance');
+        const usd = data.available.find((b) => b.currency === 'usd');
+        const pending = data.pending.find((b) => b.currency === 'usd');
+        return {
+            available: (usd?.amount || 0),
+            pending: (pending?.amount || 0),
+            currency: 'USD',
+        };
+    }
+    verifyWebhookSignature(payload, signature, secret) {
+        // Stripe uses HMAC-SHA256 for webhook signatures
+        const { createHmac } = require('node:crypto');
+        const parts = signature.split(',').reduce((acc, part) => {
+            const [key, value] = part.split('=');
+            acc[key] = value;
+            return acc;
+        }, {});
+        const timestamp = parts['t'];
+        const expected = parts['v1'];
+        if (!timestamp || !expected)
+            return false;
+        const signed = createHmac('sha256', secret)
+            .update(`${timestamp}.${payload.toString()}`)
+            .digest('hex');
+        // VG-006: Use timing-safe comparison to prevent timing attacks on signature
+        const { timingSafeEqual } = require('node:crypto');
+        if (signed.length !== expected.length)
+            return false;
+        return timingSafeEqual(Buffer.from(signed), Buffer.from(expected));
+    }
+    async apiCall(method, path, params) {
+        // Implementation: raw HTTPS (no Stripe SDK — zero dependency principle)
+        // Headers: Authorization: Bearer {apiKey}, Content-Type: application/x-www-form-urlencoded
+        // Sanitize response strings per §9.19.16 before returning
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+}
+// ── Paddle Adapter ────────────────────────────────────
+class PaddleAdapter {
+    apiKey = '';
+    baseUrl = 'https://api.paddle.com';
+    async connect(credentials) {
+        this.apiKey = credentials.apiKey || '';
+        try {
+            const data = await this.apiCall('GET', '/businesses');
+            const biz = data.data?.[0];
+            return {
+                connected: true,
+                accountId: biz?.id,
+                accountName: biz?.name,
+                currency: biz?.currency_code,
+            };
+        }
+        catch (err) {
+            return { connected: false, error: err.message };
+        }
+    }
+    async detectCurrency(credentials) {
+        const result = await this.connect(credentials);
+        return result.currency || 'USD';
+    }
+    async getTransactions(range, cursor) {
+        const params = {
+            'created_at[gte]': range.start,
+            'created_at[lte]': range.end,
+            per_page: '100',
+        };
+        if (cursor)
+            params.after = cursor;
+        const data = await this.apiCall('GET', '/transactions', params);
+        const transactions = data.data.map((txn) => {
+            const details = txn.details;
+            const totals = details?.totals;
+            const items = txn.items;
+            const firstItemPrice = items?.[0]?.price;
+            return {
+                externalId: txn.id,
+                type: mapPaddleStatus(txn.status),
+                amount: Math.round(parseFloat(totals?.total || '0') * 100),
+                currency: 'USD',
+                description: firstItemPrice?.description || '',
+                customerId: txn.customer_id ? hashCustomerId(txn.customer_id) : undefined,
+                subscriptionId: txn.subscription_id,
+                metadata: txn.custom_data || {},
+                createdAt: txn.created_at,
+            };
+        });
+        return {
+            transactions,
+            hasMore: !!data.meta?.pagination?.next,
+            cursor: data.meta?.pagination?.next,
+        };
+    }
+    async apiCall(method, path, params) {
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+}
+// ── Helpers ───────────────────────────────────────────
+function hashCustomerId(customerId) {
+    const { createHash } = require('node:crypto');
+    return createHash('sha256').update(customerId).digest('hex').substring(0, 16);
+}
+function mapPaddleStatus(status) {
+    if (status === 'completed' || status === 'paid')
+        return 'charge';
+    if (status === 'refunded' || status === 'partially_refunded')
+        return 'refund';
+    if (status === 'disputed')
+        return 'dispute';
+    return 'charge';
+}
+export { StripeAdapter, PaddleAdapter, hashCustomerId };