thevoidforge 21.0.0

package/dist/wizard/lib/patterns/ad-billing-adapter.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Pattern: Ad Billing Adapter (Split Interface)
+ *
+ * Key principles:
+ * - Billing is SEPARATE from campaign CRUD. This adapter handles how ad platforms
+ *   get paid (invoices, direct debits, settlements), not how campaigns are managed.
+ *   Campaign operations live in ad-platform-adapter.ts.
+ * - Three capability states determine what Treasury can automate:
+ *     FULLY_FUNDABLE   — Treasury manages settlement lifecycle end-to-end
+ *     MONITORED_ONLY   — spend and billing are observed, but funding is not automated
+ *     UNSUPPORTED      — billing configuration blocks any automation
+ * - Split interface: AdBillingSetup (interactive) + AdBillingAdapter (runtime)
+ * - Single-writer: only Heartbeat daemon calls the runtime adapter
+ * - All amounts in branded integer cents (Cents type from financial-transaction.ts)
+ *
+ * Agents: Dockson (treasury), Wax (paid ads), Heartbeat daemon
+ *
+ * PRD Reference: §10.2, §11.1B, §12.3
+ *
+ * Google Ads Billing API reference:
+ *   Billing setup: managed via Google Ads UI — no API for enabling monthly invoicing.
+ *   Read-only API paths (Ads API v16+):
+ *     BillingSetup resource   → billingSetup.status, paymentsAccount, paymentsProfile
+ *     Invoice resource        → GET /customers/{id}/invoices (monthly invoicing accounts only)
+ *       Fields: invoice.id, invoice.type, invoice.due_date, invoice.total_amount_micros
+ *       Note: amounts in micros (1/1,000,000 of currency unit). Divide by 10,000 for cents.
+ *   payments_account_id identifies the payments profile linked to billing.
+ *   monthly_invoicing must be enabled by Google — not programmatically toggleable.
+ *
+ * Meta Ads Billing reference:
+ *   No first-party invoice API. Billing is managed via:
+ *     GET /act_{id}?fields=funding_source,funding_source_details → funding method classification
+ *     funding_source_details.type: 1=credit_card, 2=debit_card, 4=direct_debit,
+ *       5=paypal, 8=extended_credit, 11=invoice
+ *   Direct debit: Meta pulls from linked bank. No settlement instruction needed.
+ *   Extended credit / invoicing: available to qualifying business accounts.
+ *   For direct debit accounts, Treasury maintains a buffer; for invoiced accounts,
+ *   Treasury tracks due dates and settlement instructions.
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+declare function toCents(dollars: number): Cents;
+type CapabilityState = 'FULLY_FUNDABLE' | 'MONITORED_ONLY' | 'UNSUPPORTED';
+type BillingMode = 'monthly_invoicing' | 'direct_debit' | 'extended_credit' | 'manual_bank_transfer' | 'card_only' | 'unknown';
+type AdPlatform = 'google' | 'meta' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit' | 'snap';
+interface Invoice {
+    id: string;
+    platform: AdPlatform;
+    externalAccountId: string;
+    amountCents: Cents;
+    currency: 'USD';
+    issueDate: string;
+    dueDate: string;
+    status: 'pending' | 'paid' | 'overdue' | 'cancelled';
+    lineItems?: InvoiceLineItem[];
+    paymentReference?: string;
+}
+interface InvoiceLineItem {
+    description: string;
+    amountCents: Cents;
+    campaignId?: string;
+}
+interface ExpectedDebit {
+    id: string;
+    platform: AdPlatform;
+    externalAccountId: string;
+    estimatedAmountCents: Cents;
+    currency: 'USD';
+    expectedDate: string;
+    status: 'expected' | 'detected' | 'confirmed' | 'failed';
+    bankTransactionId?: string;
+}
+interface SettlementInstruction {
+    invoiceId: string;
+    platform: AdPlatform;
+    payeeName: string;
+    paymentMethod: 'wire' | 'ach' | 'direct_debit';
+    amountCents: Cents;
+    currency: 'USD';
+    dueDate: string;
+    bankReference?: string;
+    routingNumber?: string;
+    accountNumber?: string;
+    notes: string;
+}
+interface PlatformBillingProfile {
+    platform: AdPlatform;
+    capabilityState: CapabilityState;
+    billingMode: BillingMode;
+    externalAccountId: string;
+    billingSetupId?: string;
+    invoiceGroupId?: string;
+    paymentProfileId?: string;
+    fundingSourceId?: string;
+    currency: 'USD';
+    nextDueDate?: string;
+    status: 'active' | 'degraded' | 'suspended' | 'unconfigured';
+    lastVerifiedAt: string;
+}
+interface BillingConfiguration {
+    billingMode: BillingMode;
+    accountIds: {
+        externalAccountId: string;
+        billingSetupId?: string;
+        invoiceGroupId?: string;
+        paymentProfileId?: string;
+        fundingSourceId?: string;
+    };
+    nextDueDate?: string;
+    estimatedMonthlySpendCents?: Cents;
+}
+interface NormalizedFundingState {
+    platform: AdPlatform;
+    capabilityState: CapabilityState;
+    billingMode: BillingMode;
+    outstandingCents: Cents;
+    nextPaymentDueDate?: string;
+    daysUntilNextPayment?: number;
+    fundingHealthy: boolean;
+    warnings: string[];
+}
+interface DateRange {
+    start: string;
+    end: string;
+}
+interface AdBillingSetup {
+    /** Determine what level of funding automation this platform supports */
+    verifyBillingCapability(platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<CapabilityState>;
+    /** Read the billing configuration details for storage in vault */
+    readBillingConfiguration(platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingConfiguration>;
+    /** Auto-detect the billing mode from platform API responses */
+    detectBillingMode(platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingMode>;
+}
+interface AdBillingAdapter {
+    /** Current capability state — may degrade at runtime if billing config changes */
+    getCapabilityState(platform: AdPlatform): Promise<CapabilityState>;
+    /** List pending and paid invoices in date range (Google monthly invoicing) */
+    readInvoices(platform: AdPlatform, dateRange: DateRange): Promise<Invoice[]>;
+    /** List expected bank debits in date range (Meta direct debit) */
+    readExpectedDebits(platform: AdPlatform, dateRange: DateRange): Promise<ExpectedDebit[]>;
+    /** Generate a settlement instruction for a specific invoice */
+    generateSettlementInstructions(invoice: Invoice): Promise<SettlementInstruction>;
+    /** Confirm that an invoice was settled by linking to a bank transaction */
+    confirmSettlement(invoiceId: string, bankTransactionId: string): Promise<{
+        confirmed: boolean;
+        reconciledAmountCents: Cents;
+        varianceCents: Cents;
+    }>;
+    /** Unified funding view across all connected platforms */
+    normalizeFundingState(): Promise<NormalizedFundingState[]>;
+}
+declare class GoogleBillingAdapter implements AdBillingSetup, AdBillingAdapter {
+    private readonly adsApiUrl;
+    private profiles;
+    verifyBillingCapability(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<CapabilityState>;
+    readBillingConfiguration(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingConfiguration>;
+    detectBillingMode(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingMode>;
+    getCapabilityState(_platform: AdPlatform): Promise<CapabilityState>;
+    readInvoices(_platform: AdPlatform, dateRange: DateRange): Promise<Invoice[]>;
+    readExpectedDebits(_platform: AdPlatform, _dateRange: DateRange): Promise<ExpectedDebit[]>;
+    generateSettlementInstructions(invoice: Invoice): Promise<SettlementInstruction>;
+    confirmSettlement(invoiceId: string, bankTransactionId: string): Promise<{
+        confirmed: boolean;
+        reconciledAmountCents: Cents;
+        varianceCents: Cents;
+    }>;
+    normalizeFundingState(): Promise<NormalizedFundingState[]>;
+    private queryBillingSetup;
+    private classifyGoogleBillingMode;
+}
+declare class MetaBillingAdapter implements AdBillingSetup, AdBillingAdapter {
+    private readonly baseUrl;
+    private profiles;
+    verifyBillingCapability(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<CapabilityState>;
+    readBillingConfiguration(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingConfiguration>;
+    detectBillingMode(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingMode>;
+    getCapabilityState(_platform: AdPlatform): Promise<CapabilityState>;
+    readInvoices(_platform: AdPlatform, _dateRange: DateRange): Promise<Invoice[]>;
+    readExpectedDebits(_platform: AdPlatform, dateRange: DateRange): Promise<ExpectedDebit[]>;
+    generateSettlementInstructions(invoice: Invoice): Promise<SettlementInstruction>;
+    confirmSettlement(invoiceId: string, bankTransactionId: string): Promise<{
+        confirmed: boolean;
+        reconciledAmountCents: Cents;
+        varianceCents: Cents;
+    }>;
+    normalizeFundingState(): Promise<NormalizedFundingState[]>;
+    private apiCall;
+}
+export type { AdBillingSetup, AdBillingAdapter, CapabilityState, BillingMode, AdPlatform, Invoice, InvoiceLineItem, ExpectedDebit, SettlementInstruction, PlatformBillingProfile, BillingConfiguration, NormalizedFundingState, DateRange, Cents, };
+export { toCents, GoogleBillingAdapter, MetaBillingAdapter };

package/dist/wizard/lib/patterns/ad-billing-adapter.js

@@ -0,0 +1,269 @@
+/**
+ * Pattern: Ad Billing Adapter (Split Interface)
+ *
+ * Key principles:
+ * - Billing is SEPARATE from campaign CRUD. This adapter handles how ad platforms
+ *   get paid (invoices, direct debits, settlements), not how campaigns are managed.
+ *   Campaign operations live in ad-platform-adapter.ts.
+ * - Three capability states determine what Treasury can automate:
+ *     FULLY_FUNDABLE   — Treasury manages settlement lifecycle end-to-end
+ *     MONITORED_ONLY   — spend and billing are observed, but funding is not automated
+ *     UNSUPPORTED      — billing configuration blocks any automation
+ * - Split interface: AdBillingSetup (interactive) + AdBillingAdapter (runtime)
+ * - Single-writer: only Heartbeat daemon calls the runtime adapter
+ * - All amounts in branded integer cents (Cents type from financial-transaction.ts)
+ *
+ * Agents: Dockson (treasury), Wax (paid ads), Heartbeat daemon
+ *
+ * PRD Reference: §10.2, §11.1B, §12.3
+ *
+ * Google Ads Billing API reference:
+ *   Billing setup: managed via Google Ads UI — no API for enabling monthly invoicing.
+ *   Read-only API paths (Ads API v16+):
+ *     BillingSetup resource   → billingSetup.status, paymentsAccount, paymentsProfile
+ *     Invoice resource        → GET /customers/{id}/invoices (monthly invoicing accounts only)
+ *       Fields: invoice.id, invoice.type, invoice.due_date, invoice.total_amount_micros
+ *       Note: amounts in micros (1/1,000,000 of currency unit). Divide by 10,000 for cents.
+ *   payments_account_id identifies the payments profile linked to billing.
+ *   monthly_invoicing must be enabled by Google — not programmatically toggleable.
+ *
+ * Meta Ads Billing reference:
+ *   No first-party invoice API. Billing is managed via:
+ *     GET /act_{id}?fields=funding_source,funding_source_details → funding method classification
+ *     funding_source_details.type: 1=credit_card, 2=debit_card, 4=direct_debit,
+ *       5=paypal, 8=extended_credit, 11=invoice
+ *   Direct debit: Meta pulls from linked bank. No settlement instruction needed.
+ *   Extended credit / invoicing: available to qualifying business accounts.
+ *   For direct debit accounts, Treasury maintains a buffer; for invoiced accounts,
+ *   Treasury tracks due dates and settlement instructions.
+ */
+function toCents(dollars) {
+    return Math.round(dollars * 100);
+}
+// ── Reference Implementation: Google Billing ─────────
+// Production implementation would live in wizard/lib/financial/billing/google-billing.ts
+class GoogleBillingAdapter {
+    adsApiUrl = 'https://googleads.googleapis.com/v16';
+    profiles = new Map();
+    // ── Setup (interactive) ──────────
+    async verifyBillingCapability(_platform, externalAccountId, tokens) {
+        const mode = await this.detectBillingMode('google', externalAccountId, tokens);
+        if (mode === 'monthly_invoicing')
+            return 'FULLY_FUNDABLE';
+        if (mode === 'manual_bank_transfer')
+            return 'MONITORED_ONLY';
+        if (mode === 'unknown' || mode === 'card_only')
+            return 'UNSUPPORTED';
+        return 'MONITORED_ONLY';
+    }
+    async readBillingConfiguration(_platform, externalAccountId, tokens) {
+        // Google Ads API: query billing_setup resource
+        // SELECT billing_setup.id, billing_setup.status, billing_setup.payments_account,
+        //        billing_setup.payments_profile
+        // FROM billing_setup
+        const billingSetup = await this.queryBillingSetup(externalAccountId, tokens);
+        const mode = this.classifyGoogleBillingMode(billingSetup);
+        return {
+            billingMode: mode,
+            accountIds: {
+                externalAccountId,
+                billingSetupId: billingSetup.id,
+                paymentProfileId: billingSetup.paymentsProfile,
+            },
+        };
+    }
+    async detectBillingMode(_platform, externalAccountId, tokens) {
+        const billingSetup = await this.queryBillingSetup(externalAccountId, tokens);
+        return this.classifyGoogleBillingMode(billingSetup);
+    }
+    // ── Runtime (daemon) ──────────
+    async getCapabilityState(_platform) {
+        // Re-verify from cached profile — full re-check happens on scheduled interval
+        const profile = this.profiles.get('google');
+        return profile?.capabilityState ?? 'UNSUPPORTED';
+    }
+    async readInvoices(_platform, dateRange) {
+        // Google Ads API: query invoice resource
+        // SELECT invoice.id, invoice.type, invoice.due_date,
+        //        invoice.service_date_range, invoice.total_amount_micros,
+        //        invoice.payments_account_id
+        // FROM invoice
+        // WHERE invoice.issue_date >= '{dateRange.start}'
+        //   AND invoice.issue_date <= '{dateRange.end}'
+        //
+        // Amounts are in micros: divide by 10,000 to get cents
+        // e.g., 1,500,000,000 micros = $1,500.00 = 150,000 cents
+        throw new Error('HTTP implementation — use node:https with Google Ads REST API');
+    }
+    async readExpectedDebits(_platform, _dateRange) {
+        // Google does not use direct debit in the monthly invoicing flow.
+        // This method returns empty for Google — debits are a Meta concept.
+        return [];
+    }
+    async generateSettlementInstructions(invoice) {
+        // Google monthly invoicing: payment via wire/ACH to Google's bank account
+        // Payment instructions are on the invoice itself.
+        // Reference number must be included for matching.
+        return {
+            invoiceId: invoice.id,
+            platform: 'google',
+            payeeName: 'Google Ads',
+            paymentMethod: 'wire',
+            amountCents: invoice.amountCents,
+            currency: 'USD',
+            dueDate: invoice.dueDate,
+            bankReference: invoice.paymentReference,
+            notes: `Google monthly invoice ${invoice.id} — wire payment with reference ${invoice.paymentReference ?? 'see invoice'}`,
+        };
+    }
+    async confirmSettlement(invoiceId, bankTransactionId) {
+        // Match bank transaction amount against invoice amount.
+        // In production: read from bank adapter + invoice store.
+        // Variance threshold: configurable, default 0 cents for exact match.
+        throw new Error('Implementation requires invoice store + bank adapter integration');
+    }
+    async normalizeFundingState() {
+        const profile = this.profiles.get('google');
+        if (!profile)
+            return [];
+        const invoices = await this.readInvoices('google', {
+            start: new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString(),
+            end: new Date().toISOString(),
+        });
+        const pending = invoices.filter(i => i.status === 'pending' || i.status === 'overdue');
+        const outstandingCents = pending.reduce((sum, i) => (sum + i.amountCents), 0);
+        const overdue = pending.some(i => i.status === 'overdue');
+        return [{
+                platform: 'google',
+                capabilityState: profile.capabilityState,
+                billingMode: profile.billingMode,
+                outstandingCents,
+                nextPaymentDueDate: profile.nextDueDate,
+                daysUntilNextPayment: profile.nextDueDate
+                    ? Math.ceil((new Date(profile.nextDueDate).getTime() - Date.now()) / (24 * 60 * 60 * 1000))
+                    : undefined,
+                fundingHealthy: !overdue && profile.status === 'active',
+                warnings: overdue ? ['Overdue Google Ads invoice — settlement required'] : [],
+            }];
+    }
+    // ── Private helpers ──────────
+    async queryBillingSetup(_externalAccountId, _tokens) {
+        // POST {adsApiUrl}/customers/{id}/googleAds:searchStream
+        // Body: { query: "SELECT billing_setup.id, ..." }
+        // Headers: Authorization: Bearer {accessToken}, developer-token: {devToken}
+        throw new Error('HTTP implementation — use node:https with Google Ads REST API');
+    }
+    classifyGoogleBillingMode(billingSetup) {
+        const status = billingSetup.status;
+        if (status === 'APPROVED')
+            return 'monthly_invoicing';
+        if (status === 'PENDING')
+            return 'unknown';
+        if (status === 'CANCELLED')
+            return 'unknown';
+        return 'unknown';
+    }
+}
+// ── Reference Implementation: Meta Billing ───────────
+// Production implementation would live in wizard/lib/financial/billing/meta-billing.ts
+class MetaBillingAdapter {
+    baseUrl = 'https://graph.facebook.com/v19.0';
+    profiles = new Map();
+    // ── Setup (interactive) ──────────
+    async verifyBillingCapability(_platform, externalAccountId, tokens) {
+        const mode = await this.detectBillingMode('meta', externalAccountId, tokens);
+        if (mode === 'direct_debit' || mode === 'extended_credit')
+            return 'FULLY_FUNDABLE';
+        if (mode === 'card_only')
+            return 'UNSUPPORTED';
+        return 'MONITORED_ONLY';
+    }
+    async readBillingConfiguration(_platform, externalAccountId, tokens) {
+        const mode = await this.detectBillingMode('meta', externalAccountId, tokens);
+        return {
+            billingMode: mode,
+            accountIds: {
+                externalAccountId,
+            },
+        };
+    }
+    async detectBillingMode(_platform, externalAccountId, tokens) {
+        // GET /act_{id}?fields=funding_source_details&access_token={token}
+        // Response: { funding_source_details: { id, type, display_string } }
+        // type values: 1=credit_card, 2=debit_card, 4=direct_debit,
+        //              5=paypal, 8=extended_credit, 11=invoice
+        const res = await this.apiCall('GET', `/act_${externalAccountId}`, tokens.accessToken, { fields: 'funding_source_details' });
+        const details = res.funding_source_details;
+        const fundingType = details?.type;
+        switch (fundingType) {
+            case 4: return 'direct_debit';
+            case 8: return 'extended_credit';
+            case 11: return 'monthly_invoicing';
+            case 1:
+            case 2: return 'card_only';
+            default: return 'unknown';
+        }
+    }
+    // ── Runtime (daemon) ──────────
+    async getCapabilityState(_platform) {
+        const profile = this.profiles.get('meta');
+        return profile?.capabilityState ?? 'UNSUPPORTED';
+    }
+    async readInvoices(_platform, _dateRange) {
+        // Meta does not expose a first-party invoice API for most account types.
+        // For extended_credit accounts: invoices may be available via Business Manager.
+        // In V1: return empty — Meta billing is tracked via expected debits.
+        return [];
+    }
+    async readExpectedDebits(_platform, dateRange) {
+        // For direct debit accounts: estimate upcoming debits from recent spend.
+        // Meta typically debits when spend threshold is reached or on billing date.
+        // This is a forecast based on spend velocity, not a platform API call.
+        // The actual debit is detected when it appears in the bank account.
+        throw new Error('Implementation requires spend history + bank transaction detection');
+    }
+    async generateSettlementInstructions(invoice) {
+        // Meta direct debit: no manual settlement needed — Meta pulls from bank.
+        // Meta extended credit / invoicing: payment instructions on invoice.
+        return {
+            invoiceId: invoice.id,
+            platform: 'meta',
+            payeeName: 'Meta Platforms Inc',
+            paymentMethod: 'direct_debit',
+            amountCents: invoice.amountCents,
+            currency: 'USD',
+            dueDate: invoice.dueDate,
+            notes: 'Meta direct debit — ensure sufficient bank balance before debit date',
+        };
+    }
+    async confirmSettlement(invoiceId, bankTransactionId) {
+        throw new Error('Implementation requires invoice store + bank adapter integration');
+    }
+    async normalizeFundingState() {
+        const profile = this.profiles.get('meta');
+        if (!profile)
+            return [];
+        return [{
+                platform: 'meta',
+                capabilityState: profile.capabilityState,
+                billingMode: profile.billingMode,
+                outstandingCents: 0, // Meta direct debit is pulled, not pushed
+                nextPaymentDueDate: profile.nextDueDate,
+                daysUntilNextPayment: profile.nextDueDate
+                    ? Math.ceil((new Date(profile.nextDueDate).getTime() - Date.now()) / (24 * 60 * 60 * 1000))
+                    : undefined,
+                fundingHealthy: profile.status === 'active',
+                warnings: profile.status === 'degraded'
+                    ? ['Meta billing degraded — check funding source status']
+                    : [],
+            }];
+    }
+    // ── Private helpers ──────────
+    async apiCall(method, path, accessToken, params) {
+        // Implementation: raw HTTPS (no SDK — zero dependency principle)
+        // Headers: Authorization: Bearer {accessToken}
+        // Sanitize response strings per §9.19.16 before returning
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+}
+export { toCents, GoogleBillingAdapter, MetaBillingAdapter };

package/dist/wizard/lib/patterns/ad-platform-adapter.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Pattern: Ad Platform Adapter (Split Interface)
+ *
+ * Key principles:
+ * - Separate interactive setup (browser OAuth) from runtime operations (daemon)
+ * - AdPlatformSetup runs in CLI/Danger Room (interactive, user-present)
+ * - AdPlatformAdapter runs in heartbeat daemon (non-interactive, autonomous)
+ * - All amounts in integer cents (Cents branded type) — never float
+ * - Rate limiting per-platform with token bucket
+ * - Errors normalized to common PlatformError format
+ * - Idempotency keys on all write operations (WAL pattern per ADR-3)
+ *
+ * Agents: Breeze (platform relations), Wax (paid ads), Dockson (treasury)
+ *
+ * PRD Reference: §9.5, §9.19.10, §9.20.4
+ *
+ * Authorization Guard (§9.20.4):
+ *   Daemon Tier 1 jobs receive ReadOnlyAdapter (pause, read operations only).
+ *   Authenticated external commands receive full AdPlatformAdapter.
+ *   See financial-transaction.ts for the Cents branded type.
+ */
+type Cents = number & {
+    readonly __brand: 'Cents';
+};
+type Percentage = number & {
+    readonly __brand: 'Percentage';
+};
+type Ratio = number & {
+    readonly __brand: 'Ratio';
+};
+declare function toCents(dollars: number): Cents;
+declare function toDollars(cents: Cents): number;
+type AdPlatform = 'meta' | 'google' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit' | 'snap';
+interface OAuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    platform: AdPlatform;
+    scopes: string[];
+}
+interface ConnectionStatus {
+    connected: boolean;
+    accountId?: string;
+    accountName?: string;
+    currency?: string;
+    error?: string;
+}
+interface PlatformError {
+    platform: AdPlatform;
+    code: 'RATE_LIMITED' | 'AUTH_EXPIRED' | 'BUDGET_EXCEEDED' | 'CREATIVE_REJECTED' | 'UNKNOWN';
+    originalCode: number;
+    message: string;
+    retryable: boolean;
+    retryAfter?: number;
+}
+interface CampaignConfig {
+    name: string;
+    platform: AdPlatform;
+    objective: 'awareness' | 'traffic' | 'conversions';
+    dailyBudget: Cents;
+    targeting: {
+        audiences: string[];
+        locations: string[];
+        ageRange?: [number, number];
+        interests?: string[];
+    };
+    creative: {
+        headlines: string[];
+        descriptions: string[];
+        callToAction: string;
+        landingUrl: string;
+        imageUrls?: string[];
+    };
+    testGroupId?: string;
+    testVariant?: string;
+    schedule?: {
+        startDate?: string;
+        endDate?: string;
+    };
+    idempotencyKey: string;
+    complianceStatus: 'passed' | 'pending';
+}
+interface CampaignResult {
+    externalId: string;
+    platform: AdPlatform;
+    status: 'created' | 'pending_review';
+    dashboardUrl: string;
+}
+interface CampaignUpdate {
+    name?: string;
+    dailyBudget?: Cents;
+    targeting?: Partial<CampaignConfig['targeting']>;
+    schedule?: CampaignConfig['schedule'];
+}
+interface CreativeConfig {
+    headlines?: string[];
+    descriptions?: string[];
+    callToAction?: string;
+    landingUrl?: string;
+    imageUrls?: string[];
+}
+interface SpendReport {
+    platform: AdPlatform;
+    dateRange: {
+        start: string;
+        end: string;
+    };
+    totalSpend: Cents;
+    campaigns: Array<{
+        externalId: string;
+        spend: Cents;
+        impressions: number;
+        clicks: number;
+        conversions: number;
+    }>;
+}
+interface PerformanceMetrics {
+    campaignId: string;
+    impressions: number;
+    clicks: number;
+    conversions: number;
+    spend: Cents;
+    ctr: Percentage;
+    cpc: Cents;
+    roas: Ratio;
+}
+interface InsightData {
+    campaignId: string;
+    metrics: Record<string, number>;
+    recommendations?: string[];
+}
+interface AdPlatformSetup {
+    /** Interactive OAuth flow — opens browser for authorization */
+    authenticate(): Promise<OAuthTokens>;
+    /** Verify the connection works and return account info */
+    verifyConnection(tokens: OAuthTokens): Promise<ConnectionStatus>;
+    /** Detect account currency for ADR-6 enforcement */
+    detectCurrency(tokens: OAuthTokens): Promise<string>;
+}
+interface AdPlatformAdapter {
+    refreshToken(token: OAuthTokens): Promise<OAuthTokens>;
+    createCampaign(config: CampaignConfig): Promise<CampaignResult>;
+    updateCampaign(id: string, changes: CampaignUpdate): Promise<void>;
+    pauseCampaign(id: string): Promise<void>;
+    resumeCampaign(id: string): Promise<void>;
+    deleteCampaign(id: string): Promise<void>;
+    updateBudget(id: string, dailyBudget: Cents): Promise<void>;
+    updateCreative(id: string, creative: CreativeConfig): Promise<void>;
+    getSpend(dateRange: {
+        start: string;
+        end: string;
+    }): Promise<SpendReport>;
+    getPerformance(campaignId: string): Promise<PerformanceMetrics>;
+    getInsights(campaignId: string, metrics: string[]): Promise<InsightData>;
+    handleWebhook?(payload: unknown): Promise<{
+        processed: boolean;
+    }>;
+    verifyWebhookSignature?(payload: Buffer, signature: string): boolean;
+}
+type ReadOnlyAdapter = Pick<AdPlatformAdapter, 'pauseCampaign' | // Protective — stopping spend is always safe
+'getSpend' | 'getPerformance' | 'getInsights' | 'refreshToken'>;
+declare class MetaAdapter implements AdPlatformSetup, AdPlatformAdapter {
+    private adAccountId;
+    private readonly baseUrl;
+    private rateLimiter;
+    constructor(adAccountId: string);
+    authenticate(): Promise<OAuthTokens>;
+    verifyConnection(tokens: OAuthTokens): Promise<ConnectionStatus>;
+    detectCurrency(tokens: OAuthTokens): Promise<string>;
+    refreshToken(token: OAuthTokens): Promise<OAuthTokens>;
+    createCampaign(config: CampaignConfig): Promise<CampaignResult>;
+    pauseCampaign(id: string): Promise<void>;
+    resumeCampaign(id: string): Promise<void>;
+    deleteCampaign(id: string): Promise<void>;
+    updateCampaign(id: string, changes: CampaignUpdate): Promise<void>;
+    updateBudget(id: string, dailyBudget: Cents): Promise<void>;
+    updateCreative(id: string, creative: CreativeConfig): Promise<void>;
+    getSpend(dateRange: {
+        start: string;
+        end: string;
+    }): Promise<SpendReport>;
+    getPerformance(campaignId: string): Promise<PerformanceMetrics>;
+    getInsights(campaignId: string, metrics: string[]): Promise<InsightData>;
+    private mapObjective;
+    private apiCall;
+}
+declare class TokenBucketLimiter {
+    private tokens;
+    private lastRefill;
+    private readonly capacity;
+    private readonly refillRate;
+    constructor(opts: {
+        capacity: number;
+        refillRate: number;
+    });
+    acquire(): Promise<void>;
+    private refill;
+}
+export type { AdPlatformSetup, AdPlatformAdapter, ReadOnlyAdapter, CampaignConfig, CampaignResult, CampaignUpdate, CreativeConfig, SpendReport, PerformanceMetrics, InsightData, OAuthTokens, ConnectionStatus, PlatformError, Cents, Percentage, Ratio, AdPlatform, };
+export { toCents, toDollars, MetaAdapter, TokenBucketLimiter };