voidforge-build 23.9.1

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

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

@@ -0,0 +1,212 @@
+/**
+ * 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.
+ */
+function toCents(dollars) {
+    return Math.round(dollars * 100);
+}
+function toDollars(cents) {
+    return cents / 100;
+}
+// Authenticated external commands receive the full AdPlatformAdapter
+//
+// ── Adapter Caching Rule (field report #258) ────────────
+// Stateful adapters (in-memory campaign store, e.g. sandbox) MUST be cached
+// per platform — one instance per platform key. Creating a new instance per
+// call loses state between operations (campaigns created become invisible).
+// Stateless adapters (HTTP clients calling external APIs) can be created per
+// call since they hold no local state. Use a module-level Map<string, Adapter>
+// for caching when the adapter's constructor initializes mutable collections.
+// ── Reference Implementation: Meta Marketing API ──────
+class MetaAdapter {
+    adAccountId;
+    baseUrl = 'https://graph.facebook.com/v19.0';
+    rateLimiter;
+    constructor(adAccountId) {
+        this.adAccountId = adAccountId;
+        // Meta: 200 calls/hr/ad account (sliding window)
+        this.rateLimiter = new TokenBucketLimiter({ capacity: 200, refillRate: 200 / 3600 });
+    }
+    // ── Setup (interactive) ──────────
+    async authenticate() {
+        // 1. Open browser to Facebook Login
+        // 2. User authorizes → callback with short-lived token
+        // 3. Exchange for long-lived token (60 days)
+        // 4. Return OAuthTokens
+        throw new Error('Interactive OAuth — implement per platform');
+    }
+    async verifyConnection(tokens) {
+        const res = await this.apiCall('GET', `/act_${this.adAccountId}`, tokens, {
+            fields: 'name,currency,account_status'
+        });
+        return {
+            connected: true,
+            accountId: this.adAccountId,
+            accountName: res.name,
+            currency: res.currency,
+        };
+    }
+    async detectCurrency(tokens) {
+        const status = await this.verifyConnection(tokens);
+        return status.currency ?? 'USD';
+    }
+    // ── Runtime (daemon) ─────────────
+    async refreshToken(token) {
+        // Meta long-lived tokens: exchange at 80% of 60-day TTL
+        const res = await this.apiCall('GET', '/oauth/access_token', token, {
+            grant_type: 'fb_exchange_token',
+            fb_exchange_token: token.accessToken,
+        });
+        return { ...token, accessToken: res.access_token, expiresAt: res.expires_at };
+    }
+    async createCampaign(config) {
+        await this.rateLimiter.acquire();
+        const res = await this.apiCall('POST', `/act_${this.adAccountId}/campaigns`, undefined, {
+            name: config.name,
+            objective: this.mapObjective(config.objective),
+            status: 'PAUSED', // Create paused, activate after ad set + ad creation
+            special_ad_categories: [],
+        });
+        return {
+            externalId: res.id,
+            platform: 'meta',
+            status: 'created',
+            dashboardUrl: `https://www.facebook.com/adsmanager/manage/campaigns?act=${this.adAccountId}&campaign_ids=${res.id}`,
+        };
+    }
+    async pauseCampaign(id) {
+        await this.rateLimiter.acquire();
+        await this.apiCall('POST', `/${id}`, undefined, { status: 'PAUSED' });
+    }
+    async resumeCampaign(id) {
+        await this.rateLimiter.acquire();
+        await this.apiCall('POST', `/${id}`, undefined, { status: 'ACTIVE' });
+    }
+    async deleteCampaign(id) {
+        await this.rateLimiter.acquire();
+        await this.apiCall('DELETE', `/${id}`, undefined, {});
+    }
+    async updateCampaign(id, changes) {
+        await this.rateLimiter.acquire();
+        const params = {};
+        if (changes.name)
+            params.name = changes.name;
+        // Budget changes go through ad set, not campaign on Meta
+        await this.apiCall('POST', `/${id}`, undefined, params);
+    }
+    async updateBudget(id, dailyBudget) {
+        await this.rateLimiter.acquire();
+        // Meta budgets are in the account's currency smallest unit (cents for USD)
+        await this.apiCall('POST', `/${id}`, undefined, { daily_budget: dailyBudget });
+    }
+    async updateCreative(id, creative) {
+        await this.rateLimiter.acquire();
+        // Creative updates go through the ad object, not campaign
+        throw new Error('Creative update requires ad-level API call — implement per ad structure');
+    }
+    async getSpend(dateRange) {
+        await this.rateLimiter.acquire();
+        const res = await this.apiCall('GET', `/act_${this.adAccountId}/insights`, undefined, {
+            fields: 'campaign_id,spend,impressions,clicks,conversions',
+            time_range: JSON.stringify({ since: dateRange.start, until: dateRange.end }),
+            level: 'campaign',
+        });
+        const resData = res.data;
+        return {
+            platform: 'meta',
+            dateRange,
+            totalSpend: toCents(resData.reduce((sum, r) => sum + parseFloat(r.spend), 0)),
+            campaigns: resData.map((r) => ({
+                externalId: r.campaign_id,
+                spend: toCents(parseFloat(r.spend)),
+                impressions: parseInt(r.impressions),
+                clicks: parseInt(r.clicks),
+                conversions: parseInt(r.conversions || '0'),
+            })),
+        };
+    }
+    async getPerformance(campaignId) {
+        await this.rateLimiter.acquire();
+        const res = await this.apiCall('GET', `/${campaignId}/insights`, undefined, {
+            fields: 'impressions,clicks,conversions,spend,ctr,cpc',
+        });
+        const d = res.data[0];
+        const spend = toCents(parseFloat(d.spend));
+        const conversions = parseInt(d.conversions || '0');
+        const revenue = 0; // Revenue comes from Stripe, not the ad platform
+        return {
+            campaignId,
+            impressions: parseInt(d.impressions),
+            clicks: parseInt(d.clicks),
+            conversions,
+            spend,
+            ctr: parseFloat(d.ctr),
+            cpc: toCents(parseFloat(d.cpc)),
+            roas: (revenue > 0 ? toDollars(revenue) / toDollars(spend) : 0),
+        };
+    }
+    async getInsights(campaignId, metrics) {
+        await this.rateLimiter.acquire();
+        const res = await this.apiCall('GET', `/${campaignId}/insights`, undefined, {
+            fields: metrics.join(','),
+        });
+        return { campaignId, metrics: res.data[0] ?? {} };
+    }
+    // ── Helpers ──────────────────────
+    mapObjective(obj) {
+        const map = { awareness: 'OUTCOME_AWARENESS', traffic: 'OUTCOME_TRAFFIC', conversions: 'OUTCOME_SALES' };
+        return map[obj];
+    }
+    async apiCall(method, path, tokens, params) {
+        // Sanitize platform response data per §9.19.16
+        // All string fields: strip HTML tags, escape <>&"', truncate to 500 chars
+        // Use idempotency key for POST/DELETE per ADR-3
+        throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+    }
+}
+// ── Token Bucket Rate Limiter ─────────────────────────
+class TokenBucketLimiter {
+    tokens;
+    lastRefill;
+    capacity;
+    refillRate; // tokens per second
+    constructor(opts) {
+        this.capacity = opts.capacity;
+        this.refillRate = opts.refillRate;
+        this.tokens = opts.capacity;
+        this.lastRefill = Date.now();
+    }
+    async acquire() {
+        this.refill();
+        if (this.tokens < 1) {
+            const waitMs = (1 / this.refillRate) * 1000;
+            await new Promise(resolve => setTimeout(resolve, waitMs));
+            this.refill();
+        }
+        this.tokens -= 1;
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000;
+        this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate);
+        this.lastRefill = now;
+    }
+}
+export { toCents, toDollars, MetaAdapter, TokenBucketLimiter };