thevoidforge 21.0.0

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

@@ -0,0 +1,298 @@
+/**
+ * Google Ads Billing Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements AdBillingSetup (interactive CLI) + AdBillingAdapter (daemon runtime)
+ * for Google Ads API v17.
+ *
+ * Google Ads API v17:
+ *   Base URL: https://googleads.googleapis.com/v17
+ *   Auth: Authorization: Bearer {accessToken} (OAuth2)
+ *   Also requires developer-token header for API access.
+ *
+ * Billing model: Monthly invoicing accounts receive invoices that must be paid
+ * via wire/ACH. Non-invoicing accounts are monitor-only (card or manual bank).
+ *
+ * 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 { toCents } from './base.js';
+const GOOGLE_ADS_HOST = 'googleads.googleapis.com';
+// ── HTTP helpers ─────────────────────────────────────
+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();
+    });
+}
+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();
+    });
+}
+/** 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 Google Ads API' } };
+    }
+}
+// ── Setup Implementation ─────────────────────────────
+export class GoogleBillingSetup {
+    developerToken;
+    constructor(developerToken) {
+        this.developerToken = developerToken;
+    }
+    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) {
+        const billingSetup = await this.queryBillingSetup(externalAccountId, tokens.accessToken);
+        const mode = classifyGoogleBillingMode(billingSetup);
+        return {
+            billingMode: mode,
+            accountIds: {
+                externalAccountId,
+                billingSetupId: billingSetup.id,
+                paymentProfileId: billingSetup.paymentsProfile,
+                invoiceGroupId: billingSetup.invoiceGroup,
+            },
+        };
+    }
+    async detectBillingMode(_platform, externalAccountId, tokens) {
+        const billingSetup = await this.queryBillingSetup(externalAccountId, tokens.accessToken);
+        return classifyGoogleBillingMode(billingSetup);
+    }
+    /** Query billing_setup resource via Google Ads searchStream. */
+    async queryBillingSetup(customerId, accessToken) {
+        const { status, body } = await googlePost(`/customers/${customerId}/googleAds:searchStream`, accessToken, this.developerToken, {
+            query: [
+                'SELECT billing_setup.id, billing_setup.status,',
+                'billing_setup.payments_account, billing_setup.payments_profile',
+                'FROM billing_setup',
+                'WHERE billing_setup.status = "APPROVED"',
+                'LIMIT 1',
+            ].join(' '),
+        });
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Google Ads queryBillingSetup failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        // searchStream returns an array of result batches
+        const results = parsed;
+        const firstBatch = Array.isArray(results) ? results[0] : undefined;
+        const rows = firstBatch?.results ?? [];
+        if (rows.length === 0) {
+            return { status: 'NONE' };
+        }
+        const setup = rows[0].billingSetup ?? {};
+        return {
+            id: setup.id,
+            status: setup.status,
+            paymentsAccount: setup.paymentsAccount,
+            paymentsProfile: setup.paymentsProfile,
+            invoiceGroup: setup.invoiceGroup,
+        };
+    }
+}
+// ── Runtime Adapter Implementation ───────────────────
+export class GoogleBillingAdapter {
+    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) {
+        const { status, body } = await googleGet(`/customers/${this.config.customerId}/invoices?issueDate.start=${dateRange.start}&issueDate.end=${dateRange.end}`, this.config.accessToken, this.config.developerToken);
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Google Ads readInvoices failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const invoices = parsed.invoices ?? [];
+        return invoices.map(inv => {
+            // Google amounts are in micros (1/1,000,000 of currency unit)
+            // Divide by 10,000 to convert micros to cents
+            const totalMicros = inv.totalAmountMicros ?? 0;
+            const amountCents = toCents(totalMicros / 1_000_000);
+            const dueDateObj = inv.dueDate;
+            const dueDate = dueDateObj
+                ? `${dueDateObj.year}-${String(dueDateObj.month).padStart(2, '0')}-${String(dueDateObj.day).padStart(2, '0')}`
+                : new Date().toISOString().slice(0, 10);
+            const issueDateObj = inv.serviceDateRange;
+            const issueStart = issueDateObj?.startDate;
+            const issueDate = issueStart
+                ? `${issueStart.year}-${String(issueStart.month).padStart(2, '0')}-${String(issueStart.day).padStart(2, '0')}`
+                : new Date().toISOString().slice(0, 10);
+            return {
+                id: inv.id,
+                platform: 'google',
+                externalAccountId: this.config.customerId,
+                amountCents,
+                currency: 'USD',
+                issueDate,
+                dueDate,
+                status: mapGoogleInvoiceStatus(inv.type),
+                paymentReference: inv.paymentsAccountId,
+            };
+        });
+    }
+    async readExpectedDebits(_platform, _dateRange) {
+        // Google monthly invoicing does not use direct debit.
+        // Debits are a Meta concept. Return empty per the pattern.
+        return [];
+    }
+    async generateSettlementInstructions(invoice) {
+        // Google monthly invoicing: payment via wire/ACH to Google's bank account.
+        // Payment instructions are on the invoice itself.
+        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) {
+        // Read the invoice to get the expected amount, then match against bank transaction.
+        // In production the bank adapter provides the transaction amount.
+        // For now: confirm locally by reading invoices and marking the match.
+        const now = new Date();
+        const threeMonthsAgo = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1000);
+        const invoices = await this.readInvoices('google', {
+            start: threeMonthsAgo.toISOString().slice(0, 10),
+            end: now.toISOString().slice(0, 10),
+        });
+        const target = invoices.find(i => i.id === invoiceId);
+        if (!target) {
+            return {
+                confirmed: false,
+                reconciledAmountCents: 0,
+                varianceCents: 0,
+            };
+        }
+        // Bank transaction ID is stored for audit trail; amount reconciliation
+        // assumes exact match when no bank adapter is connected.
+        void bankTransactionId; // recorded in audit log by caller
+        return {
+            confirmed: true,
+            reconciledAmountCents: target.amountCents,
+            varianceCents: 0,
+        };
+    }
+    async normalizeFundingState() {
+        if (!this.profile)
+            return [];
+        const now = new Date();
+        const threeMonthsAgo = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1000);
+        const invoices = await this.readInvoices('google', {
+            start: threeMonthsAgo.toISOString().slice(0, 10),
+            end: now.toISOString().slice(0, 10),
+        });
+        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: this.profile.capabilityState,
+                billingMode: this.profile.billingMode,
+                outstandingCents,
+                nextPaymentDueDate: this.profile.nextDueDate,
+                daysUntilNextPayment: this.profile.nextDueDate
+                    ? Math.ceil((new Date(this.profile.nextDueDate).getTime() - Date.now()) / (24 * 60 * 60 * 1000))
+                    : undefined,
+                fundingHealthy: !overdue && this.profile.status === 'active',
+                warnings: overdue ? ['Overdue Google Ads invoice — settlement required'] : [],
+            }];
+    }
+}
+// ── Private helpers ──────────────────────────────────
+function classifyGoogleBillingMode(billingSetup) {
+    const status = billingSetup.status;
+    if (status === 'APPROVED')
+        return 'monthly_invoicing';
+    if (status === 'PENDING')
+        return 'unknown';
+    if (status === 'CANCELLED')
+        return 'unknown';
+    if (status === 'NONE')
+        return 'manual_bank_transfer';
+    return 'unknown';
+}
+function mapGoogleInvoiceStatus(invoiceType) {
+    // Google invoice types: INVOICE, CREDIT_MEMO, etc.
+    // Status mapping based on type and implicit state from API response.
+    // In production, cross-reference with payment records for accurate status.
+    switch (invoiceType) {
+        case 'INVOICE': return 'pending';
+        case 'CREDIT_MEMO': return 'paid';
+        default: return 'pending';
+    }
+}

package/dist/wizard/lib/financial/billing/meta-billing.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Meta Ads Billing Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements AdBillingSetup (interactive CLI) + AdBillingAdapter (daemon runtime)
+ * for Meta Marketing API v19.0.
+ *
+ * Meta Marketing API v19.0:
+ *   Base URL: https://graph.facebook.com/v19.0
+ *   Auth: access_token query parameter
+ *
+ * Billing model: Meta uses direct debit (bank-backed autopay) or extended credit.
+ * No first-party invoice API — billing is tracked via funding source details
+ * and spend velocity estimates. Direct debit accounts have Meta pull from the
+ * linked bank; extended credit accounts receive invoices.
+ *
+ * PRD Reference: $10.2, $11.1B, $12.3
+ * No Stubs Doctrine: every method makes a real API call or returns documented empty.
+ */
+import type { AdBillingSetup, AdBillingAdapter, CapabilityState, BillingMode, AdPlatform, Invoice, ExpectedDebit, SettlementInstruction, PlatformBillingProfile, BillingConfiguration, NormalizedFundingState, DateRange, Cents } from './base.js';
+interface MetaBillingConfig {
+    adAccountId: string;
+    accessToken: string;
+}
+export declare class MetaBillingSetup implements AdBillingSetup {
+    verifyBillingCapability(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<CapabilityState>;
+    readBillingConfiguration(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingConfiguration>;
+    detectBillingMode(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingMode>;
+    /** Fetch funding_source_details for an ad account. */
+    private fetchFundingDetails;
+}
+export declare class MetaBillingAdapter implements AdBillingAdapter {
+    private readonly config;
+    private profile;
+    constructor(config: MetaBillingConfig);
+    /** Set or update the billing profile (called by heartbeat after setup verification). */
+    setProfile(profile: PlatformBillingProfile): void;
+    getCapabilityState(_platform: AdPlatform): Promise<CapabilityState>;
+    readInvoices(_platform: AdPlatform, _dateRange: DateRange): Promise<Invoice[]>;
+    readExpectedDebits(_platform: AdPlatform, dateRange: DateRange): Promise<ExpectedDebit[]>;
+    generateSettlementInstructions(invoice: Invoice): Promise<SettlementInstruction>;
+    confirmSettlement(invoiceId: string, bankTransactionId: string): Promise<{
+        confirmed: boolean;
+        reconciledAmountCents: Cents;
+        varianceCents: Cents;
+    }>;
+    normalizeFundingState(): Promise<NormalizedFundingState[]>;
+}
+export {};

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

@@ -0,0 +1,243 @@
+/**
+ * Meta Ads Billing Adapter — real implementation via node:https (zero new dependencies).
+ *
+ * Implements AdBillingSetup (interactive CLI) + AdBillingAdapter (daemon runtime)
+ * for Meta Marketing API v19.0.
+ *
+ * Meta Marketing API v19.0:
+ *   Base URL: https://graph.facebook.com/v19.0
+ *   Auth: access_token query parameter
+ *
+ * Billing model: Meta uses direct debit (bank-backed autopay) or extended credit.
+ * No first-party invoice API — billing is tracked via funding source details
+ * and spend velocity estimates. Direct debit accounts have Meta pull from the
+ * linked bank; extended credit accounts receive invoices.
+ *
+ * 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 META_HOST = 'graph.facebook.com';
+// ── HTTP helper ──────────────────────────────────────
+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();
+    });
+}
+/** 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 Meta API' } };
+    }
+}
+// ── Meta funding type constants ─────────────────────
+const META_FUNDING_TYPE = {
+    CREDIT_CARD: 1,
+    DEBIT_CARD: 2,
+    DIRECT_DEBIT: 4,
+    PAYPAL: 5,
+    EXTENDED_CREDIT: 8,
+    INVOICE: 11,
+};
+// ── Setup Implementation ─────────────────────────────
+export class MetaBillingSetup {
+    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';
+        if (mode === 'unknown')
+            return 'UNSUPPORTED';
+        return 'MONITORED_ONLY';
+    }
+    async readBillingConfiguration(_platform, externalAccountId, tokens) {
+        const fundingDetails = await this.fetchFundingDetails(externalAccountId, tokens.accessToken);
+        const mode = classifyMetaBillingMode(fundingDetails);
+        return {
+            billingMode: mode,
+            accountIds: {
+                externalAccountId,
+                fundingSourceId: fundingDetails.id,
+            },
+        };
+    }
+    async detectBillingMode(_platform, externalAccountId, tokens) {
+        const fundingDetails = await this.fetchFundingDetails(externalAccountId, tokens.accessToken);
+        return classifyMetaBillingMode(fundingDetails);
+    }
+    /** Fetch funding_source_details for an ad account. */
+    async fetchFundingDetails(adAccountId, accessToken) {
+        const { status, body } = await metaGet(`/act_${adAccountId}`, accessToken, { fields: 'funding_source_details,funding_source' });
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Meta fetchFundingDetails failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const details = parsed.funding_source_details;
+        return details ?? { type: -1 };
+    }
+}
+// ── Runtime Adapter Implementation ───────────────────
+export class MetaBillingAdapter {
+    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) {
+        // Meta does not expose a first-party invoice API for most account types.
+        // For extended_credit accounts, invoices may be available via Business Manager,
+        // but that API is not publicly documented for programmatic access.
+        // In V1: return empty — Meta billing is tracked via expected debits.
+        return [];
+    }
+    async readExpectedDebits(_platform, dateRange) {
+        // Estimate upcoming debits from recent spend velocity.
+        // Meta debits when spend threshold is reached or on billing date.
+        // Fetch recent insights to calculate spend rate, then project next debit.
+        const { status, body } = await metaGet(`/act_${this.config.adAccountId}/insights`, this.config.accessToken, {
+            fields: 'spend',
+            time_range: JSON.stringify({
+                since: dateRange.start.slice(0, 10),
+                until: dateRange.end.slice(0, 10),
+            }),
+            level: 'account',
+        });
+        if (status !== 200) {
+            let errorMsg = `HTTP ${status}`;
+            try {
+                const e = JSON.parse(body);
+                errorMsg = e.error?.message ?? errorMsg;
+            }
+            catch { /* non-JSON */ }
+            throw new Error(`Meta readExpectedDebits failed: ${errorMsg}`);
+        }
+        const parsed = safeParseJson(body);
+        const dataArray = parsed.data ?? [];
+        if (dataArray.length === 0)
+            return [];
+        // Calculate total spend in the date range
+        const totalSpendDollars = dataArray.reduce((sum, row) => {
+            const spend = parseFloat(row.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: Meta typically debits monthly for direct debit accounts.
+        // Estimate next debit 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: 'meta',
+                externalAccountId: this.config.adAccountId,
+                estimatedAmountCents: toCents(estimatedMonthlyDollars),
+                currency: 'USD',
+                expectedDate: nextDebitDate.toISOString().slice(0, 10),
+                status: 'expected',
+            }];
+    }
+    async generateSettlementInstructions(invoice) {
+        // Meta direct debit: no manual settlement needed — Meta pulls from bank.
+        // For extended credit / invoicing: payment instructions are on the invoice.
+        // Treasury's role: ensure sufficient bank balance before debit date.
+        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) {
+        // For Meta direct debit: the bank transaction is the debit Meta pulled.
+        // Match by looking at expected debits and comparing amounts.
+        // In production, the bank adapter detects the Meta debit and we reconcile here.
+        void invoiceId; // the debit ID from readExpectedDebits
+        void bankTransactionId; // recorded in audit log by caller
+        // Without a connected bank adapter, confirm optimistically.
+        // The heartbeat daemon will detect mismatches on subsequent runs.
+        return {
+            confirmed: true,
+            reconciledAmountCents: 0,
+            varianceCents: 0,
+        };
+    }
+    async normalizeFundingState() {
+        if (!this.profile)
+            return [];
+        // For direct debit: outstanding is 0 since Meta pulls automatically.
+        // For extended credit: would need invoice tracking (V2).
+        const warnings = [];
+        if (this.profile.status === 'degraded') {
+            warnings.push('Meta billing degraded — check funding source status');
+        }
+        return [{
+                platform: 'meta',
+                capabilityState: this.profile.capabilityState,
+                billingMode: this.profile.billingMode,
+                outstandingCents: 0,
+                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,
+            }];
+    }
+}
+// ── Private helpers ──────────────────────────────────
+function classifyMetaBillingMode(fundingDetails) {
+    const fundingType = fundingDetails.type;
+    switch (fundingType) {
+        case META_FUNDING_TYPE.DIRECT_DEBIT: return 'direct_debit';
+        case META_FUNDING_TYPE.EXTENDED_CREDIT: return 'extended_credit';
+        case META_FUNDING_TYPE.INVOICE: return 'monthly_invoicing';
+        case META_FUNDING_TYPE.CREDIT_CARD:
+        case META_FUNDING_TYPE.DEBIT_CARD: return 'card_only';
+        default: return 'unknown';
+    }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * 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 type { AdBillingSetup, AdBillingAdapter, CapabilityState, BillingMode, AdPlatform, Invoice, ExpectedDebit, SettlementInstruction, PlatformBillingProfile, BillingConfiguration, NormalizedFundingState, DateRange, Cents } from './base.js';
+interface TikTokBillingConfig {
+    appId: string;
+    accessToken: string;
+}
+export declare class TikTokBillingSetup implements AdBillingSetup {
+    verifyBillingCapability(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<CapabilityState>;
+    readBillingConfiguration(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingConfiguration>;
+    detectBillingMode(_platform: AdPlatform, externalAccountId: string, tokens: {
+        accessToken: string;
+    }): Promise<BillingMode>;
+    /** Fetch advertiser info to determine billing type. */
+    private fetchAdvertiserInfo;
+}
+export declare class TikTokBillingAdapter implements AdBillingAdapter {
+    private readonly config;
+    private profile;
+    constructor(config: TikTokBillingConfig);
+    /** Set or update the billing profile (called by heartbeat after setup verification). */
+    setProfile(profile: PlatformBillingProfile): void;
+    getCapabilityState(_platform: AdPlatform): Promise<CapabilityState>;
+    readInvoices(_platform: AdPlatform, _dateRange: DateRange): Promise<Invoice[]>;
+    readExpectedDebits(_platform: AdPlatform, dateRange: DateRange): Promise<ExpectedDebit[]>;
+    generateSettlementInstructions(invoice: Invoice): Promise<SettlementInstruction>;
+    confirmSettlement(invoiceId: string, bankTransactionId: string): Promise<{
+        confirmed: boolean;
+        reconciledAmountCents: Cents;
+        varianceCents: Cents;
+    }>;
+    normalizeFundingState(): Promise<NormalizedFundingState[]>;
+}
+export {};