voidforge-build 23.9.1

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/campaign-common.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared patterns across Google, TikTok, and Meta campaign adapters.
+ *
+ * Extracts: JSON parsing, error factory, objective mapping, spend aggregation.
+ * PRD Reference: SS9.5, SS9.19.10, SS9.20.4
+ */
+import type { CampaignConfig, PlatformError, Cents, AdPlatform } from './base.js';
+/** Platforms with full campaign adapter implementations. */
+export type CampaignPlatform = 'google' | 'tiktok' | 'meta';
+/** Safely parse JSON, returning an error-shaped object on failure. */
+export declare function safeParseJson(body: string): Record<string, unknown>;
+/** Create a typed PlatformError for a given ad platform. */
+export declare function makePlatformError(platform: AdPlatform, code: PlatformError['code'], originalCode: number, message: string, retryable?: boolean, retryAfter?: number): PlatformError;
+/** Map a CampaignConfig objective to a platform-specific objective string. */
+export declare function mapObjective(platform: CampaignPlatform, objective: CampaignConfig['objective']): string;
+/** Aggregate total spend from campaign rows. */
+export declare function aggregateSpend(campaigns: Array<{
+    spend: Cents;
+}>): Cents;
+/** Throw if campaign compliance has not passed. */
+export declare function requireCompliance(config: CampaignConfig, platform: AdPlatform): void;

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

@@ -0,0 +1,58 @@
+/**
+ * Shared patterns across Google, TikTok, and Meta campaign adapters.
+ *
+ * Extracts: JSON parsing, error factory, objective mapping, spend aggregation.
+ * PRD Reference: SS9.5, SS9.19.10, SS9.20.4
+ */
+// ── JSON parsing ──────────────────────────────────────
+/** Safely parse JSON, returning an error-shaped object on failure. */
+export function safeParseJson(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return { error: { message: 'Non-JSON response' } };
+    }
+}
+// ── Error factory ─────────────────────────────────────
+/** Create a typed PlatformError for a given ad platform. */
+export function makePlatformError(platform, code, originalCode, message, retryable = false, retryAfter) {
+    return { platform, code, originalCode, message, retryable, retryAfter };
+}
+// ── Objective mapping ─────────────────────────────────
+const GOOGLE_OBJECTIVES = {
+    awareness: 'TARGET_IMPRESSION_SHARE',
+    traffic: 'MAXIMIZE_CLICKS',
+    conversions: 'MAXIMIZE_CONVERSIONS',
+};
+const TIKTOK_OBJECTIVES = {
+    awareness: 'REACH',
+    traffic: 'TRAFFIC',
+    conversions: 'CONVERSIONS',
+};
+const META_OBJECTIVES = {
+    awareness: 'OUTCOME_AWARENESS',
+    traffic: 'OUTCOME_TRAFFIC',
+    conversions: 'OUTCOME_SALES',
+};
+/** Map a CampaignConfig objective to a platform-specific objective string. */
+export function mapObjective(platform, objective) {
+    const maps = {
+        google: GOOGLE_OBJECTIVES,
+        tiktok: TIKTOK_OBJECTIVES,
+        meta: META_OBJECTIVES,
+    };
+    return maps[platform][objective];
+}
+// ── Spend aggregation ─────────────────────────────────
+/** Aggregate total spend from campaign rows. */
+export function aggregateSpend(campaigns) {
+    return campaigns.reduce((sum, c) => (sum + c.spend), 0);
+}
+// ── Compliance gate ───────────────────────────────────
+/** Throw if campaign compliance has not passed. */
+export function requireCompliance(config, platform) {
+    if (config.complianceStatus !== 'passed') {
+        throw makePlatformError(platform, 'UNKNOWN', 400, 'Campaign compliance not passed \u2014 cannot create');
+    }
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Google Ads API layer — raw HTTP calls via node:https (zero new dependencies).
+ *
+ * Google Ads API v17:
+ *   Base URL: https://googleads.googleapis.com/v17
+ *   Auth: Authorization: Bearer {accessToken} + developer-token header
+ *   Rate limit: 15,000 operations/day
+ *
+ * PRD Reference: SS9.5, SS9.19.10, SS9.20.4
+ */
+export declare const GOOGLE_ADS_HOST = "googleads.googleapis.com";
+export interface GoogleCampaignConfig {
+    customerId: string;
+    accessToken: string;
+    developerToken: string;
+}
+export declare function googleGet(path: string, accessToken: string, developerToken: string): Promise<{
+    status: number;
+    body: string;
+}>;
+export declare function googlePost(path: string, accessToken: string, developerToken: string, body: Record<string, unknown>): Promise<{
+    status: number;
+    body: string;
+}>;
+export declare function googleRefreshToken(refreshToken: string): Promise<{
+    status: number;
+    body: string;
+}>;
+/** Sanitize GAQL parameter — allow only alphanumeric, underscores, hyphens, dots. */
+export declare function sanitizeGaqlParam(value: string): string;
+/** Sanitize a date string for GAQL — must be YYYY-MM-DD. */
+export declare function sanitizeDate(value: string): string;
+/** Extract the first results array from a searchStream response. */
+export declare function extractSearchStreamRows(body: string): Array<Record<string, unknown>>;
+export declare function throwGoogleApiError(status: number, body: string): never;

package/dist/wizard/lib/financial/campaign/google-api.js

@@ -0,0 +1,118 @@
+/**
+ * Google Ads API layer — raw HTTP calls via node:https (zero new dependencies).
+ *
+ * Google Ads API v17:
+ *   Base URL: https://googleads.googleapis.com/v17
+ *   Auth: Authorization: Bearer {accessToken} + developer-token header
+ *   Rate limit: 15,000 operations/day
+ *
+ * PRD Reference: SS9.5, SS9.19.10, SS9.20.4
+ */
+import { request as httpsRequest } from 'node:https';
+import { safeParseJson, makePlatformError } from './campaign-common.js';
+export const GOOGLE_ADS_HOST = 'googleads.googleapis.com';
+// ── HTTP helpers ─────────────────────────────────────
+export async function googleGet(path, accessToken, developerToken) {
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: GOOGLE_ADS_HOST,
+            path: `/v17${path}`,
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${accessToken}`,
+                'developer-token': developerToken,
+                '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('Google Ads API timeout')); });
+        req.end();
+    });
+}
+export async function googlePost(path, accessToken, developerToken, body) {
+    const payload = JSON.stringify(body);
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: GOOGLE_ADS_HOST,
+            path: `/v17${path}`,
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${accessToken}`,
+                'developer-token': developerToken,
+                '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('Google Ads API timeout')); });
+        req.write(payload);
+        req.end();
+    });
+}
+// ── OAuth refresh ────────────────────────────────────
+export async function googleRefreshToken(refreshToken) {
+    const payload = JSON.stringify({
+        client_id: 'configured-in-vault',
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+    });
+    return new Promise((resolve, reject) => {
+        const req = httpsRequest({
+            hostname: 'oauth2.googleapis.com',
+            path: '/token',
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            timeout: 10000,
+        }, (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('Google OAuth timeout')); });
+        req.write(payload);
+        req.end();
+    });
+}
+// ── GAQL sanitisation ────────────────────────────────
+/** Sanitize GAQL parameter — allow only alphanumeric, underscores, hyphens, dots. */
+export function sanitizeGaqlParam(value) {
+    return value.replace(/[^a-zA-Z0-9_.\-]/g, '');
+}
+/** Sanitize a date string for GAQL — must be YYYY-MM-DD. */
+export function sanitizeDate(value) {
+    const match = value.match(/^(\d{4}-\d{2}-\d{2})/);
+    return match ? match[1] : new Date().toISOString().slice(0, 10);
+}
+// ── GAQL response extraction ─────────────────────────
+/** Extract the first results array from a searchStream response. */
+export function extractSearchStreamRows(body) {
+    const parsed = safeParseJson(body);
+    const batches = parsed;
+    return batches[0]?.results ?? [];
+}
+// ── Error classification ─────────────────────────────
+export function throwGoogleApiError(status, body) {
+    const parsed = safeParseJson(body);
+    const errMsg = parsed.error?.message ?? `HTTP ${status}`;
+    if (status === 429) {
+        throw makePlatformError('google', 'RATE_LIMITED', status, errMsg, true, 60);
+    }
+    if (status === 401 || status === 403) {
+        throw makePlatformError('google', 'AUTH_EXPIRED', status, errMsg);
+    }
+    if (errMsg.toLowerCase().includes('budget') || errMsg.includes('BudgetError')) {
+        throw makePlatformError('google', 'BUDGET_EXCEEDED', status, errMsg);
+    }
+    throw makePlatformError('google', 'UNKNOWN', status, errMsg);
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Google Ads Campaign Adapter — orchestration layer.
+ *
+ * Implements AdPlatformAdapter for Google Ads API v17.
+ * Raw API calls delegated to google-api.ts.
+ * Shared patterns from campaign-common.ts.
+ *
+ * PRD Reference: SS9.5, SS9.19.10, SS9.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';
+export type { GoogleCampaignConfig } from './google-api.js';
+export declare class GoogleCampaignAdapter implements AdPlatformAdapter {
+    private readonly config;
+    private readonly rateLimiter;
+    constructor(config: {
+        customerId: string;
+        accessToken: string;
+        developerToken: string;
+    });
+    private mutate;
+    private search;
+    private campaignResource;
+    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>;
+}