thevoidforge 21.0.0

package/dist/wizard/lib/financial/campaign/meta-campaign.js

@@ -0,0 +1,311 @@
+/**
+ * Meta Marketing Campaign Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements AdPlatformAdapter for Meta Marketing API v19.0.
+ *
+ * Meta Marketing API v19.0:
+ *   Base URL: https://graph.facebook.com/v19.0
+ *   Auth: access_token query parameter
+ *   Campaign CRUD via Graph API
+ *   Reporting via insights endpoint
+ *   Rate limit: 200 calls/hr/ad account (sliding window)
+ *
+ * PRD Reference: §9.5, §9.19.10, §9.20.4
+ * No Stubs Doctrine: every method makes a real API call or returns documented empty.
+ */
+import { request as httpsRequest } from 'node:https';
+import { toCents, TokenBucketLimiter } from './base.js';
+const META_HOST = 'graph.facebook.com';
+// ── HTTP helpers ─────────────────────────────────────
+async function metaGet(path, accessToken, params) {
+    const queryParams = new URLSearchParams({ access_token: accessToken, ...params });
+    const query = '?' + queryParams.toString();
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: META_HOST,
+            path: `/v19.0${path}${query}`,
+            method: 'GET',
+            headers: { 'Accept': 'application/json' },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Meta API timeout')); });
+        req.end();
+    });
+}
+async function metaPost(path, accessToken, params) {
+    const payload = new URLSearchParams({ access_token: accessToken, ...params }).toString();
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: META_HOST,
+            path: `/v19.0${path}`,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                'Accept': 'application/json',
+            },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Meta API timeout')); });
+        req.write(payload);
+        req.end();
+    });
+}
+async function metaDelete(path, accessToken) {
+    const query = `?access_token=${encodeURIComponent(accessToken)}`;
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: META_HOST,
+            path: `/v19.0${path}${query}`,
+            method: 'DELETE',
+            headers: { 'Accept': 'application/json' },
+            timeout: 15000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve({ status: res.statusCode ?? 500, body: data }));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Meta API timeout')); });
+        req.end();
+    });
+}
+function safeParseJson(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return { error: { message: 'Non-JSON response from Meta API' } };
+    }
+}
+function makePlatformError(code, originalCode, message, retryable = false, retryAfter) {
+    return { platform: 'meta', code, originalCode, message, retryable, retryAfter };
+}
+function mapObjective(obj) {
+    const map = {
+        awareness: 'OUTCOME_AWARENESS',
+        traffic: 'OUTCOME_TRAFFIC',
+        conversions: 'OUTCOME_SALES',
+    };
+    return map[obj];
+}
+// ── Adapter Implementation ──────────────────────────
+export class MetaCampaignAdapter {
+    config;
+    rateLimiter;
+    constructor(config) {
+        this.config = config;
+        // Meta: 200 calls/hr/ad account
+        this.rateLimiter = new TokenBucketLimiter({ capacity: 200, refillRate: 200 / 3600 });
+    }
+    async refreshToken(token) {
+        // Meta long-lived tokens: exchange at 80% of 60-day TTL
+        await this.rateLimiter.acquire();
+        const { status, body } = await metaGet('/oauth/access_token', token.accessToken, {
+            grant_type: 'fb_exchange_token',
+            fb_exchange_token: token.accessToken,
+        });
+        if (status !== 200) {
+            throw makePlatformError('AUTH_EXPIRED', status, 'Meta token refresh failed');
+        }
+        const parsed = safeParseJson(body);
+        return {
+            ...token,
+            accessToken: parsed.access_token,
+            expiresAt: new Date(Date.now() + 60 * 24 * 60 * 60 * 1000).toISOString(),
+        };
+    }
+    async createCampaign(config) {
+        if (config.complianceStatus !== 'passed') {
+            throw makePlatformError('UNKNOWN', 400, 'Campaign compliance not passed — cannot create');
+        }
+        await this.rateLimiter.acquire();
+        const { status, body } = await metaPost(`/act_${this.config.adAccountId}/campaigns`, this.config.accessToken, {
+            name: config.name,
+            objective: mapObjective(config.objective),
+            status: 'PAUSED',
+            special_ad_categories: '[]',
+            // Idempotency per ADR-3: Meta uses request-level dedup via the key
+            idempotency_key: config.idempotencyKey,
+        });
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+        const parsed = safeParseJson(body);
+        const externalId = parsed.id;
+        return {
+            externalId,
+            platform: 'meta',
+            status: 'created',
+            dashboardUrl: `https://www.facebook.com/adsmanager/manage/campaigns?act=${this.config.adAccountId}&campaign_ids=${externalId}`,
+        };
+    }
+    async updateCampaign(id, changes) {
+        await this.rateLimiter.acquire();
+        const params = {};
+        if (changes.name !== undefined)
+            params.name = changes.name;
+        if (Object.keys(params).length === 0)
+            return;
+        const { status, body } = await metaPost(`/${id}`, this.config.accessToken, params);
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+    }
+    async pauseCampaign(id) {
+        await this.rateLimiter.acquire();
+        const { status, body } = await metaPost(`/${id}`, this.config.accessToken, {
+            status: 'PAUSED',
+        });
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+    }
+    async resumeCampaign(id) {
+        await this.rateLimiter.acquire();
+        const { status, body } = await metaPost(`/${id}`, this.config.accessToken, {
+            status: 'ACTIVE',
+        });
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+    }
+    async deleteCampaign(id) {
+        await this.rateLimiter.acquire();
+        const { status, body } = await metaDelete(`/${id}`, this.config.accessToken);
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+    }
+    async updateBudget(id, dailyBudget) {
+        await this.rateLimiter.acquire();
+        // Meta budgets are in the account's currency smallest unit (cents for USD)
+        const { status, body } = await metaPost(`/${id}`, this.config.accessToken, {
+            daily_budget: String(dailyBudget),
+        });
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+    }
+    async updateCreative(id, creative) {
+        await this.rateLimiter.acquire();
+        // Meta creative updates go through the ad object, not campaign
+        // Query the first ad under this campaign, then update it
+        const { status: queryStatus, body: queryBody } = await metaGet(`/${id}/ads`, this.config.accessToken, { fields: 'id', limit: '1' });
+        if (queryStatus !== 200) {
+            this.throwApiError(queryStatus, queryBody);
+        }
+        const queryParsed = safeParseJson(queryBody);
+        const ads = queryParsed.data ?? [];
+        if (ads.length === 0) {
+            throw makePlatformError('CREATIVE_REJECTED', 404, `No ads found for campaign ${id}`);
+        }
+        const adId = ads[0].id;
+        const params = {};
+        if (creative.landingUrl) {
+            params.creative = JSON.stringify({
+                object_story_spec: {
+                    link_data: {
+                        link: creative.landingUrl,
+                        message: creative.descriptions?.[0] ?? '',
+                        name: creative.headlines?.[0] ?? '',
+                        call_to_action: creative.callToAction
+                            ? { type: creative.callToAction }
+                            : undefined,
+                    },
+                },
+            });
+        }
+        if (Object.keys(params).length === 0)
+            return;
+        const { status, body } = await metaPost(`/${adId}`, this.config.accessToken, params);
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+    }
+    async getSpend(dateRange) {
+        await this.rateLimiter.acquire();
+        const { status, body } = await metaGet(`/act_${this.config.adAccountId}/insights`, this.config.accessToken, {
+            fields: 'campaign_id,spend,impressions,clicks,conversions',
+            time_range: JSON.stringify({ since: dateRange.start, until: dateRange.end }),
+            level: 'campaign',
+        });
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+        const parsed = safeParseJson(body);
+        const dataArray = parsed.data ?? [];
+        const campaigns = dataArray.map(r => ({
+            externalId: r.campaign_id,
+            spend: toCents(parseFloat(r.spend)),
+            impressions: parseInt(r.impressions),
+            clicks: parseInt(r.clicks),
+            conversions: parseInt(r.conversions || '0'),
+        }));
+        const totalSpend = campaigns.reduce((sum, c) => (sum + c.spend), 0);
+        return { platform: 'meta', dateRange, totalSpend, campaigns };
+    }
+    async getPerformance(campaignId) {
+        await this.rateLimiter.acquire();
+        const { status, body } = await metaGet(`/${campaignId}/insights`, this.config.accessToken, { fields: 'impressions,clicks,conversions,spend,ctr,cpc' });
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+        const parsed = safeParseJson(body);
+        const dataArray = parsed.data ?? [];
+        const d = dataArray[0] ?? {};
+        const spend = toCents(parseFloat(d.spend ?? '0'));
+        const conversions = parseInt(d.conversions || '0');
+        return {
+            campaignId,
+            impressions: parseInt(d.impressions ?? '0'),
+            clicks: parseInt(d.clicks ?? '0'),
+            conversions,
+            spend,
+            ctr: parseFloat(d.ctr ?? '0'),
+            cpc: toCents(parseFloat(d.cpc ?? '0')),
+            roas: (spend > 0 ? 0 : 0), // Revenue from Stripe, not ad platform
+        };
+    }
+    async getInsights(campaignId, metrics) {
+        await this.rateLimiter.acquire();
+        const { status, body } = await metaGet(`/${campaignId}/insights`, this.config.accessToken, { fields: metrics.join(',') });
+        if (status !== 200) {
+            this.throwApiError(status, body);
+        }
+        const parsed = safeParseJson(body);
+        const dataArray = parsed.data ?? [];
+        const row = dataArray[0] ?? {};
+        const result = {};
+        for (const metric of metrics) {
+            result[metric] = parseFloat(row[metric] ?? '0');
+        }
+        return { campaignId, metrics: result };
+    }
+    // ── Private helpers ─────────────────────────────────
+    throwApiError(status, body) {
+        const parsed = safeParseJson(body);
+        const errObj = parsed.error;
+        const errMsg = errObj?.message ?? `HTTP ${status}`;
+        const errCode = errObj?.code;
+        if (status === 429 || errCode === 32 || errCode === 4) {
+            throw makePlatformError('RATE_LIMITED', status, errMsg, true, 60);
+        }
+        if (status === 401 || status === 403 || errCode === 190) {
+            throw makePlatformError('AUTH_EXPIRED', status, errMsg);
+        }
+        if (errCode === 2635005 || errMsg.toLowerCase().includes('budget')) {
+            throw makePlatformError('BUDGET_EXCEEDED', status, errMsg);
+        }
+        throw makePlatformError('UNKNOWN', status, errMsg);
+    }
+}

package/dist/wizard/lib/financial/campaign/sandbox-campaign.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Sandbox Campaign Adapter — full implementation for development/demo.
+ *
+ * Returns realistic fake data matching the AdPlatformAdapter interface.
+ * Every method returns valid-shaped data. No throws (except invalid operations).
+ * This IS a full implementation for a sandbox provider (No Stubs Doctrine).
+ *
+ * Simulates campaign lifecycle: create → pending_review → (approveCampaign) →
+ * active → paused → resumed → completed. Realistic fake metrics: CTR 1.2-3.8%,
+ * CPC $0.45-$2.10, ROAS 1.5-4.2x. Idempotency key tracking prevents duplicate creates.
+ *
+ * PRD Reference: §9.5, §9.19.10, §9.20.4
+ */
+import type { AdPlatformAdapter, CampaignConfig, CampaignResult, CampaignUpdate, CreativeConfig, SpendReport, PerformanceMetrics, InsightData, OAuthTokens, AdPlatform, Cents } from './base.js';
+type SandboxCampaignStatus = 'pending_review' | 'active' | 'paused' | 'completed' | 'deleted';
+export declare class SandboxCampaignAdapter implements AdPlatformAdapter {
+    private readonly sandboxPlatform;
+    private campaigns;
+    private idempotencyKeys;
+    constructor(platform?: AdPlatform);
+    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>;
+    /** Manually advance campaign from pending_review to active (simulates platform approval). */
+    approveCampaign(id: string): void;
+    /** Get the current status of a sandbox campaign (for testing/integration). */
+    getCampaignStatus(id: string): SandboxCampaignStatus;
+    /** Get the count of tracked campaigns (for testing). */
+    getCampaignCount(): number;
+    private requireCampaign;
+    private requireNotDeleted;
+    private makePlatformError;
+}
+export {};

package/dist/wizard/lib/financial/campaign/sandbox-campaign.js

@@ -0,0 +1,261 @@
+/**
+ * Sandbox Campaign Adapter — full implementation for development/demo.
+ *
+ * Returns realistic fake data matching the AdPlatformAdapter interface.
+ * Every method returns valid-shaped data. No throws (except invalid operations).
+ * This IS a full implementation for a sandbox provider (No Stubs Doctrine).
+ *
+ * Simulates campaign lifecycle: create → pending_review → (approveCampaign) →
+ * active → paused → resumed → completed. Realistic fake metrics: CTR 1.2-3.8%,
+ * CPC $0.45-$2.10, ROAS 1.5-4.2x. Idempotency key tracking prevents duplicate creates.
+ *
+ * PRD Reference: §9.5, §9.19.10, §9.20.4
+ */
+import { randomUUID } from 'node:crypto';
+// ── Deterministic Fake Metrics ──────────────────────
+function fakeCtr() {
+    // CTR 1.2% - 3.8%
+    return (1.2 + Math.random() * 2.6);
+}
+function fakeRoas() {
+    // ROAS 1.5x - 4.2x
+    return (1.5 + Math.random() * 2.7);
+}
+function fakeDailySpend(dailyBudget) {
+    // Spend 60-95% of daily budget
+    const factor = 0.6 + Math.random() * 0.35;
+    return Math.round(dailyBudget * factor);
+}
+// ── Sandbox Adapter Implementation ──────────────────
+export class SandboxCampaignAdapter {
+    sandboxPlatform;
+    campaigns = new Map();
+    idempotencyKeys = new Map(); // key → externalId
+    constructor(platform = 'meta') {
+        this.sandboxPlatform = platform;
+    }
+    async refreshToken(token) {
+        // Sandbox tokens never expire — return same token with extended expiry
+        return {
+            ...token,
+            expiresAt: new Date(Date.now() + 60 * 24 * 60 * 60 * 1000).toISOString(),
+        };
+    }
+    async createCampaign(config) {
+        // Idempotency: return existing result for duplicate key
+        const existing = this.idempotencyKeys.get(config.idempotencyKey);
+        if (existing) {
+            const campaign = this.campaigns.get(existing);
+            if (campaign) {
+                return {
+                    externalId: campaign.externalId,
+                    platform: config.platform,
+                    status: campaign.status === 'pending_review' ? 'pending_review' : 'created',
+                    dashboardUrl: `https://sandbox.ads.example.com/campaigns/${campaign.externalId}`,
+                };
+            }
+        }
+        const externalId = `sandbox_campaign_${randomUUID().slice(0, 12)}`;
+        const now = new Date().toISOString();
+        const state = {
+            externalId,
+            name: config.name,
+            platform: config.platform,
+            objective: config.objective,
+            status: 'pending_review',
+            dailyBudget: config.dailyBudget,
+            targeting: { ...config.targeting },
+            creative: {
+                headlines: config.creative.headlines,
+                descriptions: config.creative.descriptions,
+                callToAction: config.creative.callToAction,
+                landingUrl: config.creative.landingUrl,
+                imageUrls: config.creative.imageUrls,
+            },
+            schedule: config.schedule,
+            createdAt: now,
+            totalSpendCents: 0,
+            impressions: 0,
+            clicks: 0,
+            conversions: 0,
+            pollCount: 0,
+        };
+        this.campaigns.set(externalId, state);
+        this.idempotencyKeys.set(config.idempotencyKey, externalId);
+        return {
+            externalId,
+            platform: config.platform,
+            status: 'pending_review',
+            dashboardUrl: `https://sandbox.ads.example.com/campaigns/${externalId}`,
+        };
+    }
+    async updateCampaign(id, changes) {
+        const campaign = this.requireCampaign(id);
+        this.requireNotDeleted(campaign);
+        if (changes.name !== undefined)
+            campaign.name = changes.name;
+        if (changes.dailyBudget !== undefined)
+            campaign.dailyBudget = changes.dailyBudget;
+        if (changes.targeting !== undefined) {
+            campaign.targeting = { ...campaign.targeting, ...changes.targeting };
+        }
+        if (changes.schedule !== undefined)
+            campaign.schedule = changes.schedule;
+    }
+    async pauseCampaign(id) {
+        const campaign = this.requireCampaign(id);
+        if (campaign.status !== 'active') {
+            throw this.makePlatformError(id, `Cannot pause campaign in status: ${campaign.status}`, campaign.status === 'deleted' ? 'UNKNOWN' : 'UNKNOWN', campaign.status === 'deleted' ? 410 : 400);
+        }
+        campaign.status = 'paused';
+    }
+    async resumeCampaign(id) {
+        const campaign = this.requireCampaign(id);
+        if (campaign.status !== 'paused') {
+            throw this.makePlatformError(id, `Cannot resume campaign in status: ${campaign.status}`, 'UNKNOWN', campaign.status === 'deleted' ? 410 : 400);
+        }
+        campaign.status = 'active';
+    }
+    async deleteCampaign(id) {
+        const campaign = this.requireCampaign(id);
+        campaign.status = 'deleted';
+    }
+    async updateBudget(id, dailyBudget) {
+        const campaign = this.requireCampaign(id);
+        this.requireNotDeleted(campaign);
+        campaign.dailyBudget = dailyBudget;
+    }
+    async updateCreative(id, creative) {
+        const campaign = this.requireCampaign(id);
+        this.requireNotDeleted(campaign);
+        if (creative.headlines !== undefined)
+            campaign.creative.headlines = creative.headlines;
+        if (creative.descriptions !== undefined)
+            campaign.creative.descriptions = creative.descriptions;
+        if (creative.callToAction !== undefined)
+            campaign.creative.callToAction = creative.callToAction;
+        if (creative.landingUrl !== undefined)
+            campaign.creative.landingUrl = creative.landingUrl;
+        if (creative.imageUrls !== undefined)
+            campaign.creative.imageUrls = creative.imageUrls;
+    }
+    async getSpend(dateRange) {
+        const campaignSpends = Array.from(this.campaigns.values())
+            .filter(c => c.status === 'active' || c.status === 'paused' || c.status === 'completed')
+            .map(c => ({
+            externalId: c.externalId,
+            spend: c.totalSpendCents,
+            impressions: c.impressions,
+            clicks: c.clicks,
+            conversions: c.conversions,
+        }));
+        const totalSpend = campaignSpends.reduce((sum, c) => (sum + c.spend), 0);
+        return {
+            platform: this.sandboxPlatform,
+            dateRange,
+            totalSpend,
+            campaigns: campaignSpends,
+        };
+    }
+    async getPerformance(campaignId) {
+        const campaign = this.requireCampaign(campaignId);
+        this.requireNotDeleted(campaign);
+        // Advance metrics on each poll for active campaigns
+        if (campaign.status === 'active') {
+            campaign.pollCount += 1;
+            const daySpend = fakeDailySpend(campaign.dailyBudget);
+            campaign.totalSpendCents = (campaign.totalSpendCents + daySpend);
+            const newImpressions = Math.floor(1000 + Math.random() * 9000);
+            campaign.impressions += newImpressions;
+            campaign.clicks += Math.floor(newImpressions * (fakeCtr() / 100));
+            campaign.conversions += Math.floor(campaign.clicks * (0.02 + Math.random() * 0.08));
+        }
+        const ctr = campaign.impressions > 0
+            ? (campaign.clicks / campaign.impressions * 100)
+            : 0;
+        const cpc = campaign.clicks > 0
+            ? Math.round(campaign.totalSpendCents / campaign.clicks)
+            : 0;
+        return {
+            campaignId,
+            impressions: campaign.impressions,
+            clicks: campaign.clicks,
+            conversions: campaign.conversions,
+            spend: campaign.totalSpendCents,
+            ctr,
+            cpc,
+            roas: fakeRoas(),
+        };
+    }
+    async getInsights(campaignId, metrics) {
+        const campaign = this.requireCampaign(campaignId);
+        this.requireNotDeleted(campaign);
+        const result = {};
+        for (const metric of metrics) {
+            switch (metric) {
+                case 'impressions':
+                    result[metric] = campaign.impressions;
+                    break;
+                case 'clicks':
+                    result[metric] = campaign.clicks;
+                    break;
+                case 'conversions':
+                    result[metric] = campaign.conversions;
+                    break;
+                case 'spend':
+                    result[metric] = campaign.totalSpendCents;
+                    break;
+                case 'ctr':
+                    result[metric] = campaign.impressions > 0
+                        ? campaign.clicks / campaign.impressions * 100 : 0;
+                    break;
+                default: result[metric] = 0;
+            }
+        }
+        return {
+            campaignId,
+            metrics: result,
+            recommendations: campaign.status === 'active'
+                ? ['Consider increasing budget — ROAS is healthy']
+                : undefined,
+        };
+    }
+    // ── Sandbox-Specific Methods ────────────────────────
+    /** Manually advance campaign from pending_review to active (simulates platform approval). */
+    approveCampaign(id) {
+        const campaign = this.requireCampaign(id);
+        if (campaign.status === 'pending_review') {
+            campaign.status = 'active';
+        }
+    }
+    /** Get the current status of a sandbox campaign (for testing/integration). */
+    getCampaignStatus(id) {
+        return this.requireCampaign(id).status;
+    }
+    /** Get the count of tracked campaigns (for testing). */
+    getCampaignCount() {
+        return this.campaigns.size;
+    }
+    // ── Private Helpers ─────────────────────────────────
+    requireCampaign(id) {
+        const campaign = this.campaigns.get(id);
+        if (!campaign) {
+            throw this.makePlatformError(id, 'Campaign not found', 'UNKNOWN', 404);
+        }
+        return campaign;
+    }
+    requireNotDeleted(campaign) {
+        if (campaign.status === 'deleted') {
+            throw this.makePlatformError(campaign.externalId, 'Campaign is deleted', 'UNKNOWN', 410);
+        }
+    }
+    makePlatformError(campaignId, message, code = 'UNKNOWN', originalCode = 400) {
+        return {
+            platform: this.sandboxPlatform,
+            code,
+            originalCode,
+            message: `Sandbox: ${message} (campaign: ${campaignId})`,
+            retryable: false,
+        };
+    }
+}

package/dist/wizard/lib/financial/campaign/tiktok-campaign.d.ts

@@ -0,0 +1,40 @@
+/**
+ * TikTok Marketing Campaign Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements AdPlatformAdapter for TikTok Marketing API v1.3.
+ *
+ * TikTok Marketing API v1.3:
+ *   Base URL: https://business-api.tiktok.com/open_api/v1.3
+ *   Auth: Access-Token header
+ *   Campaign CRUD via campaign/create, campaign/update
+ *   Reporting via report/integrated/get
+ *   Rate limit: 10 calls/sec
+ *
+ * PRD Reference: §9.5, §9.19.10, §9.20.4
+ * No Stubs Doctrine: every method makes a real API call or returns documented empty.
+ */
+import type { AdPlatformAdapter, CampaignConfig, CampaignResult, CampaignUpdate, CreativeConfig, SpendReport, PerformanceMetrics, InsightData, OAuthTokens, Cents } from './base.js';
+interface TikTokCampaignConfig {
+    appId: string;
+    accessToken: string;
+}
+export declare class TikTokCampaignAdapter implements AdPlatformAdapter {
+    private readonly config;
+    private readonly rateLimiter;
+    constructor(config: TikTokCampaignConfig);
+    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>;
+}
+export {};