thevoidforge 21.0.0

package/dist/wizard/lib/financial/billing/tiktok-billing.js

@@ -0,0 +1,260 @@
+/**
+ * TikTok Ads Billing Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements AdBillingSetup (interactive CLI) + AdBillingAdapter (daemon runtime)
+ * 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
+ *
+ * Billing model: TikTok uses prepaid (top-up wallet) or postpaid (auto-charge)
+ * billing. Neither supports programmatic settlement — all billing is managed
+ * through TikTok Ads Manager. Capability is always MONITORED_ONLY for
+ * prepaid/postpaid with auto-top-up, and UNSUPPORTED for unknown types.
+ *
+ * PRD Reference: $10.2, $11.1B, $12.3
+ * No Stubs Doctrine: every method makes a real API call or returns documented empty.
+ */
+import { request as httpsRequest } from 'node:https';
+import { randomUUID } from 'node:crypto';
+import { toCents } from './base.js';
+const TIKTOK_HOST = 'business-api.tiktok.com';
+// -- HTTP helpers -------------------------------------------------
+async function tiktokGet(path, accessToken, params) {
+    const query = params
+        ? '?' + new URLSearchParams(params).toString()
+        : '';
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: TIKTOK_HOST,
+            path: `/open_api/v1.3${path}${query}`,
+            method: 'GET',
+            headers: {
+                'Access-Token': accessToken,
+                '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('TikTok API timeout')); });
+        req.end();
+    });
+}
+async function tiktokPost(path, accessToken, body) {
+    const payload = JSON.stringify(body);
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: TIKTOK_HOST,
+            path: `/open_api/v1.3${path}`,
+            method: 'POST',
+            headers: {
+                'Access-Token': accessToken,
+                'Content-Type': 'application/json',
+                '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('TikTok API timeout')); });
+        req.write(payload);
+        req.end();
+    });
+}
+/** Parse JSON response body; on failure return a descriptive error object. */
+function safeParseJson(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return { error: { message: 'Non-JSON response from TikTok API' } };
+    }
+}
+// -- Setup Implementation -----------------------------------------
+export class TikTokBillingSetup {
+    async verifyBillingCapability(_platform, externalAccountId, tokens) {
+        const advertiserInfo = await this.fetchAdvertiserInfo(externalAccountId, tokens.accessToken);
+        const billingType = detectTikTokBillingType(advertiserInfo);
+        // TikTok doesn't support programmatic settlement — prepaid and postpaid are monitor-only
+        if (billingType === 'prepaid' || billingType === 'postpaid')
+            return 'MONITORED_ONLY';
+        return 'UNSUPPORTED';
+    }
+    async readBillingConfiguration(_platform, externalAccountId, tokens) {
+        const advertiserInfo = await this.fetchAdvertiserInfo(externalAccountId, tokens.accessToken);
+        const billingType = detectTikTokBillingType(advertiserInfo);
+        return {
+            billingMode: billingType === 'prepaid' ? 'manual_bank_transfer' : billingType === 'postpaid' ? 'direct_debit' : 'unknown',
+            accountIds: {
+                externalAccountId,
+            },
+        };
+    }
+    async detectBillingMode(_platform, externalAccountId, tokens) {
+        const advertiserInfo = await this.fetchAdvertiserInfo(externalAccountId, tokens.accessToken);
+        const billingType = detectTikTokBillingType(advertiserInfo);
+        // Map TikTok billing types to BillingMode union
+        if (billingType === 'prepaid')
+            return 'manual_bank_transfer';
+        if (billingType === 'postpaid')
+            return 'direct_debit';
+        return 'unknown';
+    }
+    /** Fetch advertiser info to determine billing type. */
+    async fetchAdvertiserInfo(advertiserId, accessToken) {
+        const { status, body } = await tiktokGet('/advertiser/info/', accessToken, { advertiser_ids: JSON.stringify([advertiserId]) });
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`TikTok fetchAdvertiserInfo failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        // TikTok wraps responses in { code: 0, data: { list: [...] } }
+        const data = parsed.data;
+        const list = data?.list ?? [];
+        if (list.length === 0) {
+            return { billing_type: 'unknown' };
+        }
+        return list[0];
+    }
+}
+// -- Runtime Adapter Implementation -------------------------------
+export class TikTokBillingAdapter {
+    config;
+    profile;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Set or update the billing profile (called by heartbeat after setup verification). */
+    setProfile(profile) {
+        this.profile = profile;
+    }
+    async getCapabilityState(_platform) {
+        return this.profile?.capabilityState ?? 'UNSUPPORTED';
+    }
+    async readInvoices(_platform, _dateRange) {
+        // TikTok does not expose a direct invoice API for programmatic access.
+        // Billing is managed entirely through TikTok Ads Manager.
+        return [];
+    }
+    async readExpectedDebits(_platform, dateRange) {
+        // Estimate upcoming debits from recent spend velocity via the reporting API.
+        // TikTok reporting endpoint returns spend data for the given date range.
+        const { status, body } = await tiktokPost('/report/integrated/get/', this.config.accessToken, {
+            advertiser_id: this.config.appId,
+            report_type: 'BASIC',
+            dimensions: ['stat_time_day'],
+            metrics: ['spend'],
+            data_level: 'AUCTION_ADVERTISER',
+            start_date: dateRange.start.slice(0, 10),
+            end_date: dateRange.end.slice(0, 10),
+            page_size: 365,
+        });
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`TikTok readExpectedDebits failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const data = parsed.data;
+        const list = data?.list ?? [];
+        if (list.length === 0)
+            return [];
+        // Calculate total spend in the date range
+        const totalSpendDollars = list.reduce((sum, row) => {
+            const metrics = row.metrics;
+            const spend = parseFloat(metrics?.spend ?? '0');
+            return sum + spend;
+        }, 0);
+        // Calculate days in range for daily rate
+        const rangeStart = new Date(dateRange.start);
+        const rangeEnd = new Date(dateRange.end);
+        const daySpan = Math.max(1, Math.ceil((rangeEnd.getTime() - rangeStart.getTime()) / (24 * 60 * 60 * 1000)));
+        const dailyRateDollars = totalSpendDollars / daySpan;
+        // Project: estimate next billing cycle as ~30 days of spend at current rate.
+        const estimatedMonthlyDollars = dailyRateDollars * 30;
+        if (estimatedMonthlyDollars < 1)
+            return []; // negligible spend
+        const nextDebitDate = new Date(rangeEnd.getTime() + 30 * 24 * 60 * 60 * 1000);
+        return [{
+                id: randomUUID(),
+                platform: 'tiktok',
+                externalAccountId: this.config.appId,
+                estimatedAmountCents: toCents(estimatedMonthlyDollars),
+                currency: 'USD',
+                expectedDate: nextDebitDate.toISOString().slice(0, 10),
+                status: 'expected',
+            }];
+    }
+    async generateSettlementInstructions(invoice) {
+        // TikTok billing is MONITORED_ONLY — no programmatic settlement.
+        // Return guidance directing users to TikTok Ads Manager.
+        return {
+            invoiceId: invoice.id,
+            platform: 'tiktok',
+            payeeName: 'TikTok / ByteDance',
+            paymentMethod: 'direct_debit',
+            amountCents: invoice.amountCents,
+            currency: 'USD',
+            dueDate: invoice.dueDate,
+            notes: 'TikTok billing is managed in TikTok Ads Manager — no programmatic settlement available',
+        };
+    }
+    async confirmSettlement(invoiceId, bankTransactionId) {
+        // Optimistic confirmation for monitoring purposes.
+        // TikTok handles billing internally; we track for reconciliation only.
+        void invoiceId;
+        void bankTransactionId; // recorded in audit log by caller
+        return {
+            confirmed: true,
+            reconciledAmountCents: 0,
+            varianceCents: 0,
+        };
+    }
+    async normalizeFundingState() {
+        if (!this.profile)
+            return [];
+        const warnings = [];
+        if (this.profile.status === 'degraded') {
+            warnings.push('TikTok billing degraded — check advertiser account status');
+        }
+        return [{
+                platform: 'tiktok',
+                capabilityState: this.profile.capabilityState,
+                billingMode: this.profile.billingMode,
+                outstandingCents: 0, // TikTok manages billing internally
+                nextPaymentDueDate: this.profile.nextDueDate,
+                daysUntilNextPayment: this.profile.nextDueDate
+                    ? Math.ceil((new Date(this.profile.nextDueDate).getTime() - Date.now()) / (24 * 60 * 60 * 1000))
+                    : undefined,
+                fundingHealthy: this.profile.status === 'active',
+                warnings,
+            }];
+    }
+}
+function detectTikTokBillingType(advertiserInfo) {
+    // TikTok returns billing_type or contacter_type to indicate billing model.
+    // Common values: "prepaid", "postpaid"
+    const billingType = (advertiserInfo.billing_type ?? '').toLowerCase();
+    if (billingType === 'prepaid')
+        return 'prepaid';
+    if (billingType === 'postpaid')
+        return 'postpaid';
+    return 'unknown';
+}

package/dist/wizard/lib/financial/campaign/base.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Campaign adapter types — re-exports from the pattern file.
+ * ARCH-R2-012: Production code should not import from docs/patterns/ directly.
+ *
+ * The AdPlatformAdapter interface defines campaign CRUD operations:
+ * create, pause, resume, delete, updateBudget, updateCreative,
+ * plus reporting (getSpend, getPerformance, getInsights).
+ *
+ * Split interface: AdPlatformSetup (interactive CLI) + AdPlatformAdapter (daemon runtime).
+ * ReadOnlyAdapter restricts daemon Tier 1 jobs to safe operations only.
+ */
+export type { AdPlatformSetup, AdPlatformAdapter, ReadOnlyAdapter, CampaignConfig, CampaignResult, CampaignUpdate, CreativeConfig, SpendReport, PerformanceMetrics, InsightData, OAuthTokens, ConnectionStatus, PlatformError, Cents, Percentage, Ratio, AdPlatform, } from '../../patterns/ad-platform-adapter.js';
+export { toCents, toDollars, TokenBucketLimiter } from '../../patterns/ad-platform-adapter.js';

package/dist/wizard/lib/financial/campaign/base.js

@@ -0,0 +1 @@
+export { toCents, toDollars, TokenBucketLimiter } from '../../patterns/ad-platform-adapter.js';

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

@@ -0,0 +1,42 @@
+/**
+ * Google Ads Campaign Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements AdPlatformAdapter for Google Ads API v17.
+ *
+ * Google Ads API v17:
+ *   Base URL: https://googleads.googleapis.com/v17
+ *   Auth: Authorization: Bearer {accessToken} + developer-token header
+ *   Campaign CRUD via mutate endpoints
+ *   Reporting via searchStream
+ *   Rate limit: 15,000 operations/day
+ *
+ * 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 GoogleCampaignConfig {
+    customerId: string;
+    accessToken: string;
+    developerToken: string;
+}
+export declare class GoogleCampaignAdapter implements AdPlatformAdapter {
+    private readonly config;
+    private readonly rateLimiter;
+    constructor(config: GoogleCampaignConfig);
+    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>;
+    private throwApiError;
+}
+export {};