thevoidforge 21.0.0

package/dist/wizard/lib/patterns/oauth-token-lifecycle.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Pattern: OAuth Token Lifecycle
+ *
+ * Key principles:
+ * - Refresh at 80% of TTL (not at expiry — prevents race conditions)
+ * - Multi-grant-type support (authorization_code, refresh_token)
+ * - Vault integration — tokens encrypted at rest in financial vault
+ * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
+ * - Token stored as encrypted blob in vault, keyed by platform name
+ * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ *
+ * Agents: Breeze (platform relations), Dockson (vault)
+ *
+ * PRD Reference: §9.5 (token refresh strategy), §9.18 (vault session), §9.19.15
+ */
+type AdPlatform = 'meta' | 'google' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit';
+interface OAuthTokenSet {
+    platform: AdPlatform;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    tokenType: string;
+    scopes: string[];
+    grantedAt: string;
+    lastRefreshedAt: string;
+}
+type TokenHealth = 'healthy' | 'expiring_soon' | 'expired' | 'refresh_failed' | 'requires_reauth' | 'revoked';
+interface TokenStatus {
+    platform: AdPlatform;
+    health: TokenHealth;
+    expiresAt: string;
+    lastRefresh: string;
+    consecutiveFailures: number;
+    error?: string;
+}
+interface PlatformTokenConfig {
+    platform: AdPlatform;
+    accessTokenTtlHours: number;
+    refreshTokenTtlDays: number;
+    refreshEndpoint: string;
+    revokeEndpoint?: string;
+}
+declare const PLATFORM_CONFIGS: PlatformTokenConfig[];
+declare const REFRESH_AT_TTL_PERCENT = 0.8;
+declare const MAX_CONSECUTIVE_FAILURES = 3;
+/**
+ * Check if a token needs refresh.
+ * Returns true if the token is past 80% of its TTL.
+ */
+declare function needsRefresh(token: OAuthTokenSet): boolean;
+/**
+ * Determine the health status of a token.
+ */
+declare function getTokenHealth(token: OAuthTokenSet, failures: number): TokenHealth;
+interface RefreshResult {
+    success: boolean;
+    newTokens?: OAuthTokenSet;
+    error?: string;
+    requiresReauth?: boolean;
+}
+/**
+ * Handle a refresh failure. Implements the escalation:
+ * 1st failure: retry after 30s
+ * 2nd failure: retry after 60s
+ * 3rd failure: pause campaigns on this platform, set requires_reauth, alert
+ *
+ * The `invalid_grant` error means the refresh token itself is expired/revoked.
+ * This does NOT count toward the 3-failure pause trigger (§9.18) —
+ * it goes straight to requires_reauth.
+ */
+declare function handleRefreshFailure(platform: AdPlatform, error: string, consecutiveFailures: number): {
+    action: 'retry' | 'pause_and_alert' | 'reauth';
+    retryAfterMs?: number;
+};
+declare function tokenVaultKey(platform: AdPlatform): string;
+/**
+ * Serialize tokens for vault storage.
+ * The vault stores strings — tokens are JSON-serialized.
+ */
+declare function serializeTokens(tokens: OAuthTokenSet): string;
+declare function deserializeTokens(data: string): OAuthTokenSet;
+declare const SESSION_TOKEN_TTL_MS: number;
+declare const SESSION_TOKEN_GRACE_MS: number;
+interface SessionTokenState {
+    current: string;
+    previous?: string;
+    rotatedAt: number;
+    previousExpiresAt?: number;
+}
+declare function shouldRotateSessionToken(state: SessionTokenState): boolean;
+declare function rotateSessionToken(state: SessionTokenState, newToken: string): SessionTokenState;
+declare function validateSessionToken(provided: string, state: SessionTokenState): boolean;
+export type { OAuthTokenSet, TokenHealth, TokenStatus, PlatformTokenConfig, RefreshResult, SessionTokenState };
+export { PLATFORM_CONFIGS, REFRESH_AT_TTL_PERCENT, MAX_CONSECUTIVE_FAILURES, needsRefresh, getTokenHealth, handleRefreshFailure, tokenVaultKey, serializeTokens, deserializeTokens, SESSION_TOKEN_TTL_MS, SESSION_TOKEN_GRACE_MS, shouldRotateSessionToken, rotateSessionToken, validateSessionToken, };

package/dist/wizard/lib/patterns/oauth-token-lifecycle.js

@@ -0,0 +1,139 @@
+/**
+ * Pattern: OAuth Token Lifecycle
+ *
+ * Key principles:
+ * - Refresh at 80% of TTL (not at expiry — prevents race conditions)
+ * - Multi-grant-type support (authorization_code, refresh_token)
+ * - Vault integration — tokens encrypted at rest in financial vault
+ * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
+ * - Token stored as encrypted blob in vault, keyed by platform name
+ * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ *
+ * Agents: Breeze (platform relations), Dockson (vault)
+ *
+ * PRD Reference: §9.5 (token refresh strategy), §9.18 (vault session), §9.19.15
+ */
+const PLATFORM_CONFIGS = [
+    { platform: 'meta', accessTokenTtlHours: 1440, refreshTokenTtlDays: 0, refreshEndpoint: 'https://graph.facebook.com/v19.0/oauth/access_token' },
+    { platform: 'google', accessTokenTtlHours: 1, refreshTokenTtlDays: 0, refreshEndpoint: 'https://oauth2.googleapis.com/token' },
+    { platform: 'tiktok', accessTokenTtlHours: 24, refreshTokenTtlDays: 365, refreshEndpoint: 'https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/' },
+    { platform: 'linkedin', accessTokenTtlHours: 1440, refreshTokenTtlDays: 365, refreshEndpoint: 'https://www.linkedin.com/oauth/v2/accessToken' },
+    { platform: 'twitter', accessTokenTtlHours: 0, refreshTokenTtlDays: 0, refreshEndpoint: '' }, // OAuth 1.0a — tokens don't expire
+    { platform: 'reddit', accessTokenTtlHours: 1, refreshTokenTtlDays: 0, refreshEndpoint: 'https://www.reddit.com/api/v1/access_token' },
+];
+// ── Refresh Logic ─────────────────────────────────────
+const REFRESH_AT_TTL_PERCENT = 0.80; // Refresh at 80% of TTL
+const MAX_CONSECUTIVE_FAILURES = 3;
+/**
+ * Check if a token needs refresh.
+ * Returns true if the token is past 80% of its TTL.
+ */
+function needsRefresh(token) {
+    const config = PLATFORM_CONFIGS.find(c => c.platform === token.platform);
+    if (!config || config.accessTokenTtlHours === 0)
+        return false; // Never expires (Twitter OAuth 1.0a)
+    const expiresAt = new Date(token.expiresAt).getTime();
+    const lastRefresh = new Date(token.lastRefreshedAt).getTime();
+    const ttlMs = config.accessTokenTtlHours * 60 * 60 * 1000;
+    const refreshAt = lastRefresh + (ttlMs * REFRESH_AT_TTL_PERCENT);
+    return Date.now() >= refreshAt;
+}
+/**
+ * Determine the health status of a token.
+ */
+function getTokenHealth(token, failures) {
+    if (failures >= MAX_CONSECUTIVE_FAILURES)
+        return 'requires_reauth';
+    const now = Date.now();
+    const expiresAt = new Date(token.expiresAt).getTime();
+    if (expiresAt < now)
+        return 'expired';
+    const config = PLATFORM_CONFIGS.find(c => c.platform === token.platform);
+    if (!config || config.accessTokenTtlHours === 0)
+        return 'healthy'; // Never expires
+    const ttlMs = config.accessTokenTtlHours * 60 * 60 * 1000;
+    const warningAt = expiresAt - (ttlMs * 0.2); // Warn at 80% consumed
+    if (now >= warningAt)
+        return 'expiring_soon';
+    if (failures > 0)
+        return 'refresh_failed';
+    return 'healthy';
+}
+/**
+ * Handle a refresh failure. Implements the escalation:
+ * 1st failure: retry after 30s
+ * 2nd failure: retry after 60s
+ * 3rd failure: pause campaigns on this platform, set requires_reauth, alert
+ *
+ * The `invalid_grant` error means the refresh token itself is expired/revoked.
+ * This does NOT count toward the 3-failure pause trigger (§9.18) —
+ * it goes straight to requires_reauth.
+ */
+function handleRefreshFailure(platform, error, consecutiveFailures) {
+    // invalid_grant = refresh token revoked/expired — immediate reauth
+    if (error.includes('invalid_grant') || error.includes('revoked')) {
+        return { action: 'reauth' };
+    }
+    const newCount = consecutiveFailures + 1;
+    if (newCount >= MAX_CONSECUTIVE_FAILURES) {
+        return { action: 'pause_and_alert' };
+    }
+    // Exponential backoff: 30s, 60s
+    const retryAfterMs = 30000 * Math.pow(2, consecutiveFailures);
+    return { action: 'retry', retryAfterMs };
+}
+// ── Vault Integration ─────────────────────────────────
+// Tokens are stored in the financial vault, keyed by platform name.
+// The daemon reads them at startup and holds them in memory.
+// On refresh, the daemon writes the updated token back to the vault.
+const TOKEN_VAULT_KEY_PREFIX = 'growth/tokens/';
+function tokenVaultKey(platform) {
+    return TOKEN_VAULT_KEY_PREFIX + platform;
+}
+/**
+ * Serialize tokens for vault storage.
+ * The vault stores strings — tokens are JSON-serialized.
+ */
+function serializeTokens(tokens) {
+    return JSON.stringify(tokens);
+}
+function deserializeTokens(data) {
+    return JSON.parse(data);
+}
+// ── Session Token Rotation (§9.19.15) ─────────────────
+// The daemon session token (heartbeat.token) rotates every 24 hours.
+// During rotation, accept both old and new tokens for 30-second grace period.
+const SESSION_TOKEN_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const SESSION_TOKEN_GRACE_MS = 30 * 1000; // 30 seconds
+function shouldRotateSessionToken(state) {
+    return Date.now() - state.rotatedAt >= SESSION_TOKEN_TTL_MS;
+}
+function rotateSessionToken(state, newToken) {
+    return {
+        current: newToken,
+        previous: state.current,
+        rotatedAt: Date.now(),
+        previousExpiresAt: Date.now() + SESSION_TOKEN_GRACE_MS,
+    };
+}
+function validateSessionToken(provided, state) {
+    const { timingSafeEqual } = require('node:crypto');
+    // Check current token
+    if (provided.length === state.current.length) {
+        const a = Buffer.from(provided);
+        const b = Buffer.from(state.current);
+        if (timingSafeEqual(a, b))
+            return true;
+    }
+    // Check previous token during grace period
+    if (state.previous && state.previousExpiresAt && Date.now() < state.previousExpiresAt) {
+        if (provided.length === state.previous.length) {
+            const a = Buffer.from(provided);
+            const b = Buffer.from(state.previous);
+            if (timingSafeEqual(a, b))
+                return true;
+        }
+    }
+    return false;
+}
+export { PLATFORM_CONFIGS, REFRESH_AT_TTL_PERCENT, MAX_CONSECUTIVE_FAILURES, needsRefresh, getTokenHealth, handleRefreshFailure, tokenVaultKey, serializeTokens, deserializeTokens, SESSION_TOKEN_TTL_MS, SESSION_TOKEN_GRACE_MS, shouldRotateSessionToken, rotateSessionToken, validateSessionToken, };

package/dist/wizard/lib/patterns/outbound-rate-limiter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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)
+ */
+type AdPlatform = 'meta' | 'google' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit';
+interface PlatformRateConfig {
+    platform: AdPlatform;
+    capacity: number;
+    refillRate: number;
+    dailyQuota?: number;
+    burstAllowed: boolean;
+    safetyMargin: number;
+    backoffBase: number;
+    maxRetries: number;
+}
+declare const PLATFORM_RATES: Record<AdPlatform, PlatformRateConfig>;
+declare class OutboundRateLimiter {
+    private tokens;
+    private lastRefill;
+    private dailyUsed;
+    private dailyResetAt;
+    private readonly config;
+    private readonly effectiveCapacity;
+    constructor(platform: AdPlatform);
+    /**
+     * Acquire a token. Resolves when a token is available.
+     * Throws if the daily quota is exhausted.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Execute a request with automatic retry on 429 responses.
+     * Uses exponential backoff with platform-specific base delay.
+     */
+    executeWithRetry<T>(fn: () => Promise<T>): Promise<T>;
+    /** Get current rate limiter status for monitoring */
+    getStatus(): {
+        tokens: number;
+        capacity: number;
+        dailyUsed: number;
+        dailyQuota: number | undefined;
+    };
+    /** Reserve N tokens for a batch operation. Returns false if insufficient. */
+    canReserve(count: number): boolean;
+    private refill;
+    private checkDailyReset;
+    private nextMidnightUTC;
+}
+declare class RateLimitError extends Error {
+    readonly platform: string;
+    readonly retryAfterMs: number;
+    constructor(platform: string, message: string, retryAfterMs: number);
+}
+declare function isRateLimitResponse(err: unknown): boolean;
+declare function getLimiter(platform: AdPlatform): OutboundRateLimiter;
+export { OutboundRateLimiter, RateLimitError, PLATFORM_RATES, getLimiter, isRateLimitResponse };
+export type { PlatformRateConfig };

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 };