voidforge-build 23.9.1

package/dist/wizard/lib/kongo/analytics.js

@@ -0,0 +1,179 @@
+/**
+ * Kongo Analytics — Campaign analytics and computed growth signal.
+ *
+ * Kongo doesn't have a dedicated growth-signal endpoint, so we compute it
+ * client-side from the campaign analytics data using statistical analysis.
+ *
+ * Real Kongo API endpoint:
+ * - GET /engine/campaigns/:campaignId/analytics — per-variant breakdown
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.3
+ */
+// ── Analytics Operations ─────────────────────────────────
+/**
+ * Get campaign analytics with per-variant, per-source, and daily breakdown.
+ */
+export async function getCampaignAnalytics(client, campaignId, period) {
+    const query = {};
+    if (period)
+        query.period = period;
+    return client.get(`/engine/campaigns/${encodeURIComponent(campaignId)}/analytics`, query);
+}
+// ── Computed Growth Signal ───────────────────────────────
+// Minimum sample size per variant before making recommendations
+const MIN_SAMPLE_SIZE = 100;
+// Minimum total views before any signal is meaningful
+const MIN_TOTAL_VIEWS = 200;
+// Z-score threshold for 95% confidence
+const Z_95 = 1.96;
+/**
+ * Compute a growth signal from campaign analytics.
+ *
+ * This replaces the hypothetical /growth-signal endpoint from the PRD.
+ * Uses two-proportion z-test to determine if any variant significantly
+ * outperforms the control (first variant by order).
+ */
+export function computeGrowthSignal(campaignId, analytics) {
+    const timestamp = new Date().toISOString();
+    const variants = analytics.byVariant;
+    // Not enough data yet
+    if (analytics.summary.totalViews < MIN_TOTAL_VIEWS || variants.length < 2) {
+        return {
+            campaignId,
+            timestamp,
+            winningVariantId: null,
+            confidence: 0,
+            conversionRateDelta: 0,
+            recommendation: 'wait',
+            reasoning: variants.length < 2
+                ? 'Need at least 2 variants to evaluate'
+                : `Insufficient data: ${analytics.summary.totalViews} views (need ${MIN_TOTAL_VIEWS})`,
+            sampleSize: { control: variants[0]?.views ?? 0, variant: 0 },
+        };
+    }
+    // Control = first variant by creation order (the original, pre-variation baseline).
+    // NOT the worst performer — using worst inflates z-scores and causes false positives.
+    // Tiebreaker by variantId for deterministic selection across JS engines.
+    const control = [...variants].sort((a, b) => a.order - b.order || a.variantId.localeCompare(b.variantId))[0];
+    const challengers = variants.filter(v => v.variantId !== control.variantId);
+    if (challengers.length === 0) {
+        return {
+            campaignId,
+            timestamp,
+            winningVariantId: null,
+            confidence: 0,
+            conversionRateDelta: 0,
+            recommendation: 'wait',
+            reasoning: 'Only the control variant exists — need at least one challenger',
+            sampleSize: { control: control.views, variant: 0 },
+        };
+    }
+    // Find best challenger by CVR (guard against NaN from 0-view variants)
+    const best = challengers
+        .filter(v => v.views > 0)
+        .sort((a, b) => b.cvr - a.cvr)[0];
+    if (!best) {
+        return {
+            campaignId,
+            timestamp,
+            winningVariantId: null,
+            confidence: 0,
+            conversionRateDelta: 0,
+            recommendation: 'wait',
+            reasoning: 'No challengers with traffic data yet',
+            sampleSize: { control: control.views, variant: 0 },
+        };
+    }
+    // Check minimum sample sizes
+    if (best.views < MIN_SAMPLE_SIZE || control.views < MIN_SAMPLE_SIZE) {
+        return {
+            campaignId,
+            timestamp,
+            winningVariantId: null,
+            confidence: 0,
+            conversionRateDelta: 0,
+            recommendation: 'wait',
+            reasoning: `Insufficient per-variant data: best=${best.views}, control=${control.views} views (need ${MIN_SAMPLE_SIZE} each)`,
+            sampleSize: { control: control.views, variant: best.views },
+        };
+    }
+    // Two-proportion z-test (one-tailed: is best better than control?)
+    const { zScore, pValue } = twoProportionZTest(best.conversions, best.views, control.conversions, control.views);
+    // Confidence = 1 - p_value (one-tailed). For two-tailed 95%, need p < 0.025.
+    // We use one-tailed because we have a directional hypothesis (best > control).
+    const confidence = 1 - pValue;
+    const conversionRateDelta = best.cvr - control.cvr;
+    const recommendation = computeRecommendation(confidence, conversionRateDelta, analytics.summary.totalViews);
+    return {
+        campaignId,
+        timestamp,
+        winningVariantId: confidence >= 0.95 ? best.variantId : null,
+        confidence,
+        conversionRateDelta,
+        recommendation,
+        reasoning: formatReasoning(best, control, confidence, recommendation),
+        sampleSize: { control: control.views, variant: best.views },
+    };
+}
+/**
+ * Fetch analytics and compute growth signal in one call.
+ */
+export async function getGrowthSignal(client, campaignId, period) {
+    const analytics = await getCampaignAnalytics(client, campaignId, period);
+    return computeGrowthSignal(campaignId, analytics);
+}
+// ── Statistical Helpers ──────────────────────────────────
+function twoProportionZTest(successA, nA, successB, nB) {
+    const pA = successA / nA;
+    const pB = successB / nB;
+    const pPooled = (successA + successB) / (nA + nB);
+    const se = Math.sqrt(pPooled * (1 - pPooled) * (1 / nA + 1 / nB));
+    if (nA === 0 || nB === 0 || !(se > 0))
+        return { zScore: 0, pValue: 1 };
+    const zScore = (pA - pB) / se;
+    // One-tailed p-value: P(Z >= z) = 1 - CDF(z)
+    const pValue = 1 - normalCdf(zScore);
+    return { zScore, pValue };
+}
+/**
+ * Approximate normal CDF using Abramowitz and Stegun formula.
+ * Returns P(Z <= z) for standard normal distribution.
+ */
+function normalCdf(z) {
+    if (z < -6)
+        return 0;
+    if (z > 6)
+        return 1;
+    const absZ = Math.abs(z);
+    const t = 1 / (1 + 0.2316419 * absZ);
+    const d = 0.3989422804014327; // 1/sqrt(2*PI)
+    const p = d * Math.exp(-absZ * absZ / 2) *
+        (t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.8212560 + t * 1.3302744)))));
+    return z > 0 ? 1 - p : p;
+}
+function computeRecommendation(confidence, conversionRateDelta, totalViews) {
+    // High confidence winner
+    if (confidence >= 0.95 && conversionRateDelta > 0)
+        return 'scale';
+    // Moderate confidence, positive trend — keep iterating
+    if (confidence >= 0.80 && conversionRateDelta > 0)
+        return 'iterate';
+    // High confidence that all challengers underperform the control
+    if (confidence >= 0.95 && conversionRateDelta < 0 && totalViews > 500)
+        return 'kill';
+    // Not enough signal yet
+    return 'wait';
+}
+function formatReasoning(best, control, confidence, recommendation) {
+    const delta = (best.cvr - control.cvr).toFixed(2);
+    switch (recommendation) {
+        case 'scale':
+            return `Variant "${best.label}" outperforms control by ${delta}pp CVR with ${(confidence * 100).toFixed(1)}% confidence. Scale this variant.`;
+        case 'iterate':
+            return `Variant "${best.label}" shows +${delta}pp CVR lift at ${(confidence * 100).toFixed(1)}% confidence. Continue testing for stronger signal.`;
+        case 'kill':
+            return `No variant shows significant improvement. Consider killing this campaign.`;
+        case 'wait':
+            return `Insufficient data for recommendation. Current best: "${best.label}" at ${best.cvr.toFixed(2)}% CVR.`;
+    }
+}

package/dist/wizard/lib/kongo/campaigns.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Kongo Campaigns — Campaign lifecycle operations.
+ *
+ * Create, list, update, publish/unpublish, and delete campaigns.
+ * Campaigns group pages + variants for A/B testing with rotation strategies.
+ *
+ * Real Kongo API endpoints:
+ * - POST /engine/campaigns — create
+ * - GET /engine/campaigns — list (cursor pagination)
+ * - GET /engine/campaigns/:campaignId — get detail
+ * - PUT /engine/campaigns/:campaignId — update
+ * - DELETE /engine/campaigns/:campaignId — archive (soft delete)
+ * - POST /engine/campaigns/:campaignId/publish — publish
+ * - DELETE /engine/campaigns/:campaignId/publish — unpublish
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.2
+ */
+import { KongoClient } from './client.js';
+import type { CreateCampaignRequest, CampaignDetail, UpdateCampaignRequest, PublishResult, ListCampaignsOptions, PaginatedResponse } from './types.js';
+/**
+ * Create a new campaign.
+ * Requires a templateId (page ID) to base variants on.
+ */
+export declare function createCampaign(client: KongoClient, config: CreateCampaignRequest): Promise<CampaignDetail>;
+/**
+ * Get a single campaign by ID.
+ * Returns full details including template info, variants, and stats.
+ */
+export declare function getCampaign(client: KongoClient, campaignId: string): Promise<CampaignDetail>;
+/**
+ * List campaigns with cursor-based pagination.
+ */
+export declare function listCampaigns(client: KongoClient, options?: ListCampaignsOptions): Promise<PaginatedResponse<CampaignDetail>>;
+/**
+ * Update a campaign's rotation strategy, tracking, access gate, or metadata.
+ * Slug and template cannot be changed after creation.
+ */
+export declare function updateCampaign(client: KongoClient, campaignId: string, updates: UpdateCampaignRequest): Promise<CampaignDetail>;
+/**
+ * Archive a campaign (soft delete). Unpublishes automatically.
+ */
+export declare function deleteCampaign(client: KongoClient, campaignId: string): Promise<void>;
+/**
+ * Publish a campaign — provisions DNS CNAME at {slug}.kongo.io.
+ * Requires at least 1 active variant. Idempotent.
+ */
+export declare function publishCampaign(client: KongoClient, campaignId: string): Promise<PublishResult>;
+/**
+ * Unpublish a campaign — removes DNS record.
+ */
+export declare function unpublishCampaign(client: KongoClient, campaignId: string): Promise<void>;
+export declare function batchGetCampaignStatuses(client: KongoClient): Promise<CampaignDetail[]>;

package/dist/wizard/lib/kongo/campaigns.js

@@ -0,0 +1,91 @@
+/**
+ * Kongo Campaigns — Campaign lifecycle operations.
+ *
+ * Create, list, update, publish/unpublish, and delete campaigns.
+ * Campaigns group pages + variants for A/B testing with rotation strategies.
+ *
+ * Real Kongo API endpoints:
+ * - POST /engine/campaigns — create
+ * - GET /engine/campaigns — list (cursor pagination)
+ * - GET /engine/campaigns/:campaignId — get detail
+ * - PUT /engine/campaigns/:campaignId — update
+ * - DELETE /engine/campaigns/:campaignId — archive (soft delete)
+ * - POST /engine/campaigns/:campaignId/publish — publish
+ * - DELETE /engine/campaigns/:campaignId/publish — unpublish
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.2
+ */
+// ── Campaign Operations ──────────────────────────────────
+/**
+ * Create a new campaign.
+ * Requires a templateId (page ID) to base variants on.
+ */
+export async function createCampaign(client, config) {
+    return client.post('/engine/campaigns', config);
+}
+/**
+ * Get a single campaign by ID.
+ * Returns full details including template info, variants, and stats.
+ */
+export async function getCampaign(client, campaignId) {
+    return client.get(`/engine/campaigns/${encodeURIComponent(campaignId)}`);
+}
+/**
+ * List campaigns with cursor-based pagination.
+ */
+export async function listCampaigns(client, options) {
+    const query = {};
+    if (options?.cursor)
+        query.cursor = options.cursor;
+    if (options?.limit)
+        query.limit = options.limit;
+    if (options?.published !== undefined)
+        query.published = options.published;
+    if (options?.search)
+        query.search = options.search;
+    return client.get('/engine/campaigns', query);
+}
+/**
+ * Update a campaign's rotation strategy, tracking, access gate, or metadata.
+ * Slug and template cannot be changed after creation.
+ */
+export async function updateCampaign(client, campaignId, updates) {
+    return client.put(`/engine/campaigns/${encodeURIComponent(campaignId)}`, updates);
+}
+/**
+ * Archive a campaign (soft delete). Unpublishes automatically.
+ */
+export async function deleteCampaign(client, campaignId) {
+    await client.delete(`/engine/campaigns/${encodeURIComponent(campaignId)}`);
+}
+/**
+ * Publish a campaign — provisions DNS CNAME at {slug}.kongo.io.
+ * Requires at least 1 active variant. Idempotent.
+ */
+export async function publishCampaign(client, campaignId) {
+    return client.post(`/engine/campaigns/${encodeURIComponent(campaignId)}/publish`);
+}
+/**
+ * Unpublish a campaign — removes DNS record.
+ */
+export async function unpublishCampaign(client, campaignId) {
+    await client.delete(`/engine/campaigns/${encodeURIComponent(campaignId)}/publish`);
+}
+/**
+ * Get statuses for all active campaigns.
+ * Uses the list endpoint since Kongo doesn't have a batch-status endpoint.
+ */
+const MAX_BATCH_PAGES = 20;
+export async function batchGetCampaignStatuses(client) {
+    const results = [];
+    let cursor;
+    let pageCount = 0;
+    do {
+        if (++pageCount > MAX_BATCH_PAGES)
+            break;
+        const page = await listCampaigns(client, { cursor, limit: 100 });
+        results.push(...page.items);
+        cursor = page.hasMore ? page.cursor : undefined;
+    } while (cursor);
+    return results;
+}

package/dist/wizard/lib/kongo/client.d.ts

@@ -0,0 +1,58 @@
+/**
+ * KongoClient — Authenticated HTTP client for the Kongo Engine API.
+ *
+ * First-party integration (ADR-036): Kongo is owned by the same user.
+ * No adapter abstraction — direct typed client.
+ *
+ * Credentials: API key (ke_live_ prefix) stored in financial vault.
+ * Rate limiting: 60 requests/minute sliding window (client-side safety).
+ * Retries: Exponential backoff on 429, 3 attempts max.
+ * No external dependencies: uses node:https only.
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.1, §8
+ */
+import type { KongoClientConfig, KongoErrorCode } from './types.js';
+export declare class KongoApiError extends Error {
+    readonly code: KongoErrorCode | string;
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    constructor(code: KongoErrorCode | string, message: string, status: number, retryable?: boolean, retryAfterMs?: number);
+}
+export declare class SlidingWindowLimiter {
+    private readonly timestamps;
+    private readonly windowMs;
+    private readonly maxRequests;
+    constructor(maxRequestsPerMinute: number);
+    acquire(): void;
+    getStatus(): {
+        available: number;
+        total: number;
+        windowMs: number;
+    };
+}
+export declare class KongoClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly limiter;
+    constructor(config: KongoClientConfig);
+    /** GET request */
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    /** POST request */
+    post<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /** PUT request */
+    put<T>(path: string, body?: unknown): Promise<T>;
+    /** PATCH request */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /** DELETE request */
+    delete<T>(path: string): Promise<T>;
+    /** Rate limiter status for monitoring */
+    getRateLimitStatus(): {
+        available: number;
+        total: number;
+        windowMs: number;
+    };
+    private requestWithRetry;
+    private rawRequest;
+}

package/dist/wizard/lib/kongo/client.js

@@ -0,0 +1,221 @@
+/**
+ * KongoClient — Authenticated HTTP client for the Kongo Engine API.
+ *
+ * First-party integration (ADR-036): Kongo is owned by the same user.
+ * No adapter abstraction — direct typed client.
+ *
+ * Credentials: API key (ke_live_ prefix) stored in financial vault.
+ * Rate limiting: 60 requests/minute sliding window (client-side safety).
+ * Retries: Exponential backoff on 429, 3 attempts max.
+ * No external dependencies: uses node:https only.
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.1, §8
+ */
+import { request as httpsRequest } from 'node:https';
+import { URL } from 'node:url';
+// ── KongoApiError ────────────────────────────────────────
+export class KongoApiError extends Error {
+    code;
+    status;
+    retryable;
+    retryAfterMs;
+    constructor(code, message, status, retryable = false, retryAfterMs) {
+        super(message);
+        this.name = 'KongoApiError';
+        this.code = code;
+        this.status = status;
+        this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+// ── Sliding Window Rate Limiter ──────────────────────────
+export class SlidingWindowLimiter {
+    timestamps = [];
+    windowMs;
+    maxRequests;
+    constructor(maxRequestsPerMinute) {
+        this.windowMs = 60_000;
+        this.maxRequests = maxRequestsPerMinute;
+    }
+    acquire() {
+        const now = Date.now();
+        // Evict timestamps outside the window
+        while (this.timestamps.length > 0 && this.timestamps[0] <= now - this.windowMs) {
+            this.timestamps.shift();
+        }
+        if (this.timestamps.length >= this.maxRequests) {
+            const waitMs = this.timestamps[0] + this.windowMs - now;
+            throw new KongoApiError('RATE_LIMITED', `Client-side rate limit exceeded. Retry in ${Math.ceil(waitMs / 1000)}s.`, 429, true, waitMs);
+        }
+        this.timestamps.push(now);
+    }
+    getStatus() {
+        const now = Date.now();
+        while (this.timestamps.length > 0 && this.timestamps[0] <= now - this.windowMs) {
+            this.timestamps.shift();
+        }
+        return {
+            available: this.maxRequests - this.timestamps.length,
+            total: this.maxRequests,
+            windowMs: this.windowMs,
+        };
+    }
+}
+// ── KongoClient ──────────────────────────────────────────
+const DEFAULT_BASE_URL = 'https://kongo.io/api/v1';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RATE_LIMIT = 60;
+const MAX_RETRIES = 3;
+const BACKOFF_BASE_MS = 1_000;
+export class KongoClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    limiter;
+    constructor(config) {
+        if (!config.apiKey || !config.apiKey.startsWith('ke_live_')) {
+            throw new KongoApiError('UNAUTHORIZED', 'Invalid API key format. Kongo keys use the ke_live_ prefix.', 401);
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.limiter = new SlidingWindowLimiter(config.rateLimitPerMinute ?? DEFAULT_RATE_LIMIT);
+    }
+    /** GET request */
+    async get(path, query) {
+        return this.requestWithRetry('GET', path, undefined, query);
+    }
+    /** POST request */
+    async post(path, body, headers) {
+        return this.requestWithRetry('POST', path, body, undefined, headers);
+    }
+    /** PUT request */
+    async put(path, body) {
+        return this.requestWithRetry('PUT', path, body);
+    }
+    /** PATCH request */
+    async patch(path, body) {
+        return this.requestWithRetry('PATCH', path, body);
+    }
+    /** DELETE request */
+    async delete(path) {
+        return this.requestWithRetry('DELETE', path);
+    }
+    /** Rate limiter status for monitoring */
+    getRateLimitStatus() {
+        return this.limiter.getStatus();
+    }
+    // ── Internal ─────────────────────────────────────────
+    async requestWithRetry(method, path, body, query, extraHeaders) {
+        let lastError;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            try {
+                this.limiter.acquire();
+                return await this.rawRequest(method, path, body, query, extraHeaders);
+            }
+            catch (err) {
+                if (!(err instanceof KongoApiError))
+                    throw err;
+                lastError = err;
+                if (!err.retryable || attempt === MAX_RETRIES - 1)
+                    throw err;
+                const backoffMs = err.retryAfterMs ?? BACKOFF_BASE_MS * Math.pow(2, attempt);
+                await sleep(backoffMs);
+            }
+        }
+        throw lastError ?? new KongoApiError('UNKNOWN', 'Request failed', 500);
+    }
+    rawRequest(method, path, body, query, extraHeaders) {
+        return new Promise((resolve, reject) => {
+            // Concatenate base URL path with request path (URL constructor replaces path on leading /)
+            const base = this.baseUrl.replace(/\/$/, '');
+            const cleanPath = path.startsWith('/') ? path : `/${path}`;
+            const url = new URL(`${base}${cleanPath}`);
+            if (query) {
+                for (const [key, val] of Object.entries(query)) {
+                    if (val !== undefined)
+                        url.searchParams.set(key, String(val));
+                }
+            }
+            const payload = body ? JSON.stringify(body) : undefined;
+            // Sanitize extraHeaders: strip any auth-related keys (case-insensitive)
+            const safeExtra = {};
+            if (extraHeaders) {
+                for (const [key, val] of Object.entries(extraHeaders)) {
+                    if (key.toLowerCase() !== 'authorization') {
+                        safeExtra[key] = val;
+                    }
+                }
+            }
+            const headers = {
+                ...safeExtra,
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Accept': 'application/json',
+            };
+            if (payload) {
+                headers['Content-Type'] = 'application/json';
+                headers['Content-Length'] = String(Buffer.byteLength(payload));
+            }
+            const MAX_RESPONSE_BYTES = 10 * 1024 * 1024; // 10 MB
+            const req = httpsRequest(url, { method, headers, timeout: this.timeoutMs }, (res) => {
+                const chunks = [];
+                let totalBytes = 0;
+                let settled = false;
+                res.on('data', (chunk) => {
+                    if (settled)
+                        return;
+                    totalBytes += chunk.length;
+                    if (totalBytes > MAX_RESPONSE_BYTES) {
+                        settled = true;
+                        req.destroy();
+                        reject(new KongoApiError('RESPONSE_TOO_LARGE', 'Response exceeded 10 MB limit', 502));
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                res.on('end', () => {
+                    if (settled)
+                        return;
+                    const raw = Buffer.concat(chunks).toString('utf-8');
+                    // HTML endpoint returns raw HTML, not JSON
+                    if (res.headers['content-type']?.includes('text/html')) {
+                        resolve(raw);
+                        return;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(raw);
+                    }
+                    catch {
+                        reject(new KongoApiError('UNKNOWN', `Failed to parse Kongo response (status=${res.statusCode}, content-type=${res.headers['content-type'] ?? 'unknown'})`, res.statusCode ?? 500));
+                        return;
+                    }
+                    if (!parsed.success) {
+                        const status = res.statusCode ?? 500;
+                        const retryable = status === 429 || status === 503;
+                        const retryAfterMs = res.headers['retry-after']
+                            ? parseInt(res.headers['retry-after'], 10) * 1000
+                            : undefined;
+                        reject(new KongoApiError(parsed.error.code, parsed.error.message, status, retryable, retryAfterMs));
+                        return;
+                    }
+                    resolve(parsed.data);
+                });
+            });
+            req.on('error', (err) => {
+                reject(new KongoApiError('NETWORK_ERROR', err.message, 0, true));
+            });
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new KongoApiError('TIMEOUT', `Request timed out after ${this.timeoutMs}ms`, 408, true));
+            });
+            if (payload)
+                req.write(payload);
+            req.end();
+        });
+    }
+}
+// ── Helpers ──────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/wizard/lib/kongo/jobs.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Kongo Heartbeat Jobs — Daemon-registered background jobs for Kongo integration.
+ *
+ * Three jobs that run when Kongo is connected:
+ * - kongo-signal: Hourly poll of growth signal for all active campaigns
+ * - kongo-seed: Triggered when a variant wins — pushes winning copy back
+ * - kongo-webhook: Event-driven handler for Kongo webhook events
+ *
+ * Jobs are only registered when Kongo is connected (API key in vault).
+ * All jobs skip cleanly when Kongo is not connected.
+ *
+ * PRD Reference: PRD-kongo-integration.md §4.6
+ */
+import { KongoClient } from './client.js';
+import type { ComputedGrowthSignal } from './types.js';
+export interface KongoJobContext {
+    readonly client: KongoClient;
+    readonly webhookSecret: string | null;
+    readonly logger: (msg: string) => void;
+    readonly onSignal?: (signal: ComputedGrowthSignal) => Promise<void>;
+    readonly onPageCompleted?: (pageId: string) => Promise<void>;
+    readonly onPageFailed?: (pageId: string, error?: string) => Promise<void>;
+    /** Self-marketing mode: product domain matches Kongo domain (iframe sandbox workaround) */
+    readonly selfMarketing?: boolean;
+    /** Optional external analytics source for /lp/ pages in self-marketing mode (GA4 Data API / PostHog) */
+    readonly getExternalAnalytics?: (pageSlug: string, period: string) => Promise<{
+        views: number;
+        conversions: number;
+    } | null>;
+}
+export interface KongoJobHandlers {
+    readonly signalPoll: () => Promise<KongoSignalResult>;
+    readonly seedPush: (campaignId: string, winningVariantId: string) => Promise<Record<string, string> | null>;
+    readonly webhookHandle: (rawBody: string, signature: string) => Promise<void>;
+}
+export interface KongoSignalResult {
+    readonly signals: ComputedGrowthSignal[];
+    readonly polledAt: string;
+}
+/**
+ * Create Kongo job handlers for the heartbeat daemon.
+ *
+ * Usage in heartbeat.ts:
+ * ```
+ * const kongoJobs = createKongoJobs(context);
+ * scheduler.add('kongo-signal', 3_600_000, kongoJobs.signalPoll);  // 1 hour
+ * ```
+ */
+export declare function createKongoJobs(ctx: KongoJobContext): KongoJobHandlers;
+export interface JobScheduler {
+    add(name: string, intervalMs: number, handler: () => Promise<void>): void;
+}
+/**
+ * Register Kongo jobs with the daemon's scheduler.
+ * Only registers when Kongo is connected.
+ */
+export declare function registerKongoJobs(scheduler: JobScheduler, jobs: KongoJobHandlers): void;