@aicopycoders/exodus 2026.9.200 → 2026.9.1100-beta.1

package/dist/commands/winners.d.ts

@@ -1,3 +1,4 @@
+import { type AdAccountRef } from "../lib/meta-ads.js";
 export declare const helpText: string;
 export interface LocalValidation {
     ok: boolean;
@@ -8,3 +9,52 @@ export interface LocalValidation {
 export declare function validatePackageLocally(pkg: unknown): LocalValidation;
 export declare function contentTypeFor(filePath: string): string;
 export declare function run(flags: Record<string, string | boolean>): Promise<void>;
+export declare const VALUE_FLAGS: Set<string>;
+export declare function parsePositional(args?: string[]): string[];
+export interface WinnerDefinitionView {
+    accountId?: string | null;
+    campaignRoleMap?: Record<string, string> | null;
+    ruleVariant?: string | null;
+    otherDefinition?: string | null;
+    ignoredCampaignIds?: string[] | null;
+    defaults?: {
+        window?: string | null;
+        resultsFloor?: number | null;
+        contributionLine?: number | null;
+    } | null;
+    lastAppliedAt?: number | null;
+    setupCompletedAt?: number | null;
+    summary?: WinnerDefinitionSummary | null;
+}
+export interface WinnerDefinitionSummaryGroup {
+    resultLabel?: string | null;
+    objective?: string | null;
+    instanceCount?: number | null;
+    creativeCount?: number | null;
+    totalResults?: number | null;
+    winnerCount?: number | null;
+    winnerShare?: number | null;
+    videoWinners?: number | null;
+    imageWinners?: number | null;
+    flatCurve?: boolean | null;
+}
+export interface WinnerDefinitionSummary {
+    instanceCount?: number | null;
+    creativeCount?: number | null;
+    winnerCount?: number | null;
+    groups?: WinnerDefinitionSummaryGroup[] | null;
+    ignoredCampaignCount?: number | null;
+    computedAt?: number | null;
+}
+export interface WinnerDefinitionResponse {
+    account?: AdAccountRef | null;
+    definition?: WinnerDefinitionView | null;
+    accounts?: AdAccountRef[];
+}
+export declare function roleTally(map: Record<string, string> | null | undefined): {
+    total: number;
+    line: string;
+};
+export declare function sharePercent(value: unknown): string;
+export declare function summaryLines(summary: WinnerDefinitionSummary | null | undefined): string[];
+export declare function formatDefinition(data: WinnerDefinitionResponse): string[];

package/dist/commands/winners.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { apiGet, apiPost } from "../lib/client.js";
 import { displayRunStatus, formatError, tickerRunStatus } from "../lib/format.js";
 import { pollUntilDone } from "../lib/poll.js";
+import { accountLine, accountRequiredLines, count as formatCount, dateOrDash, errorCode, } from "../lib/meta-ads.js";
 export const helpText = `
 exodus winners — Import your own brand's winning ads as generative fuel
 
@@ -16,6 +17,14 @@ Usage:
   exodus winners import <file.json | ->        Push a winner package (- reads stdin)
   exodus winners status <importId>             Re-poll an import later
   exodus winners list                          Winners Exodus already holds
+  exodus winners definition [--account act_…]  What THIS brand means by "a winner"
+
+Definition flags:
+  --account <id>  Which connected ad account, e.g. act_1234567890. Required
+                  only when the brand has more than one connected — a
+                  definition read off the wrong account is a wrong answer that
+                  looks right.
+  --json          Machine-readable JSON output
 
 Import flags:
   --dry-run      Local schema check + server dry-run: reports would-create vs
@@ -25,6 +34,10 @@ Import flags:
 
 Notes:
   • Scopes to your active brand's workspace (exodus brand current).
+  • \`definition\` reads the answers a human already gave on the dashboard — it
+    never writes, and it never shows a machine guess nobody has confirmed. A
+    brand with a Meta integration keeps its definition there, not in a local
+    file. Its ads read back with \`exodus ads list\`.
   • Requires your Scrape Creators API key (Settings → Keys) — the own-page
     match scrape bills your account.
   • Re-pushing the same file is safe: no duplicate rows, the verdict snapshot
@@ -38,6 +51,8 @@ Examples:
   cat winners.json | exodus winners import -
   exodus winners status k97abc...
   exodus winners list
+  exodus winners definition
+  exodus winners definition --account act_1234567890 --json
 `.trim();
 export function validatePackageLocally(pkg) {
     const errors = [];
@@ -116,6 +131,8 @@ export async function run(flags) {
         return runStatus(rest, flags);
     if (sub === "list")
         return runList(flags);
+    if (sub === "definition")
+        return runDefinition(flags);
     if (!sub) {
         console.log(helpText);
         return;
@@ -124,8 +141,24 @@ export async function run(flags) {
     console.log(helpText);
     process.exit(1);
 }
-function parsePositional() {
-    return process.argv.slice(3).filter((a) => !a.startsWith("--"));
+export const VALUE_FLAGS = new Set(["account"]);
+export function parsePositional(args = process.argv.slice(3)) {
+    const out = [];
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2).split("=", 1)[0] ?? "";
+            if (!arg.includes("=") && VALUE_FLAGS.has(key))
+                i += 2;
+            else
+                i++;
+            continue;
+        }
+        out.push(arg);
+        i++;
+    }
+    return out;
 }
 async function runImport(positional, flags) {
     const json = !!flags["json"];
@@ -409,3 +442,143 @@ async function runList(flags) {
         console.log(`    ${w.verdictSentence}`);
     }
 }
+const RULE_VARIANTS = {
+    standard: "standard — the smallest set of creatives that together carry most of a result group's results",
+    efficiency: "efficiency — the creatives with the best cost per result in each group",
+    "ignore-campaigns": "standard, with some campaigns deliberately left out of the count",
+    other: "written out in the brand's own words (below)",
+};
+export function roleTally(map) {
+    const entries = map && typeof map === "object" ? Object.values(map) : [];
+    const counts = new Map();
+    for (const role of entries) {
+        if (typeof role !== "string" || !role.trim())
+            continue;
+        const key = role.trim();
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const order = ["testing", "scaling", "other"];
+    const parts = [...counts.entries()]
+        .sort((a, b) => {
+        const ai = order.indexOf(a[0]);
+        const bi = order.indexOf(b[0]);
+        return (ai === -1 ? order.length : ai) - (bi === -1 ? order.length : bi);
+    })
+        .map(([role, n]) => `${n} ${role}`);
+    return { total: entries.length, line: parts.join(" · ") || "none confirmed yet" };
+}
+export function sharePercent(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "—";
+    const pct = value <= 1 ? value * 100 : value;
+    return `${Math.round(pct)}%`;
+}
+export function summaryLines(summary) {
+    if (!summary) {
+        return ["Last run", "  (the rule has not been run over this account yet)"];
+    }
+    const lines = [`Last run — ${dateOrDash(summary.computedAt)}`];
+    lines.push(`  ${formatCount(summary.instanceCount)} ad instances → ${formatCount(summary.creativeCount)} distinct creatives · ${formatCount(summary.winnerCount)} winners`);
+    const groups = Array.isArray(summary.groups) ? summary.groups : [];
+    for (const group of groups) {
+        const label = group.resultLabel?.trim() || group.objective?.trim() || "(unlabelled group)";
+        lines.push(`  ${label}: ${formatCount(group.winnerCount)} of ${formatCount(group.creativeCount)} creatives carry ${sharePercent(group.winnerShare)} of ${formatCount(group.totalResults)} results (${formatCount(group.videoWinners)} video / ${formatCount(group.imageWinners)} image)`);
+        if (group.flatCurve) {
+            lines.push("    flat curve — results spread evenly, so there is no clean winner set here; treat these as top contributors, not outliers.");
+        }
+    }
+    if (typeof summary.ignoredCampaignCount === "number" && summary.ignoredCampaignCount > 0) {
+        lines.push(`  ${summary.ignoredCampaignCount} campaign(s) were left out of the count.`);
+    }
+    return lines;
+}
+export function formatDefinition(data) {
+    const accounts = Array.isArray(data.accounts) ? data.accounts : [];
+    const account = data.account ?? null;
+    const definition = data.definition ?? null;
+    if (!account) {
+        if (accounts.length === 0) {
+            return [
+                "No Meta ad account is connected to this brand.",
+                "Connect one on the dashboard (Settings → Meta) — then the daily sync fills in the ads and this definition.",
+            ];
+        }
+        const lines = ["Pick which ad account you mean:", ...accounts.map(accountLine)];
+        const first = accounts[0]?.accountId;
+        if (first) {
+            lines.push("");
+            lines.push(`  exodus winners definition --account ${first}`);
+        }
+        return lines;
+    }
+    const label = account.name?.trim()
+        ? `${account.name.trim()} (${account.accountId ?? "?"})`
+        : String(account.accountId ?? "?");
+    if (!definition) {
+        return [
+            `No winner definition for ${label} yet.`,
+            "Someone has to say what a winner means for this account before the rule can run — that happens on the dashboard (Settings → Meta → winner setup).",
+        ];
+    }
+    const lines = [];
+    lines.push(`Winner definition — ${label}`);
+    lines.push(`  setup:      ${definition.setupCompletedAt ? `confirmed ${dateOrDash(definition.setupCompletedAt)}` : "not finished yet"}`);
+    const variant = definition.ruleVariant?.trim() ?? "";
+    lines.push(`  rule:       ${RULE_VARIANTS[variant] ?? (variant || "—")}`);
+    const defaults = definition.defaults ?? {};
+    lines.push(`  dials:      window ${defaults.window ?? "—"} · results floor ${formatCount(defaults.resultsFloor)} · contribution line ${sharePercent(defaults.contributionLine)}`);
+    const roles = roleTally(definition.campaignRoleMap);
+    lines.push(`  campaigns:  ${roles.total} with a confirmed role — ${roles.line}`);
+    const ignored = Array.isArray(definition.ignoredCampaignIds) ? definition.ignoredCampaignIds : [];
+    if (ignored.length > 0) {
+        lines.push(`  ignored:    ${ignored.length} campaign(s) left out of the rule`);
+    }
+    if (definition.lastAppliedAt) {
+        lines.push(`  last run:   ${dateOrDash(definition.lastAppliedAt)}`);
+    }
+    if (definition.otherDefinition?.trim()) {
+        lines.push("");
+        lines.push("In the brand's own words");
+        for (const line of definition.otherDefinition.trim().split("\n"))
+            lines.push(`  ${line}`);
+    }
+    lines.push("");
+    lines.push(...summaryLines(definition.summary));
+    if (accounts.length > 1) {
+        lines.push("");
+        lines.push(`This brand has ${accounts.length} connected accounts — each keeps its own definition (--account).`);
+    }
+    return lines;
+}
+async function runDefinition(flags) {
+    const json = !!flags["json"];
+    const accountRaw = flags["account"];
+    if (accountRaw !== undefined && (typeof accountRaw !== "string" || !accountRaw.trim())) {
+        console.error("Error: --account needs an ad account id, e.g. act_1234567890");
+        console.log("Usage: exodus winners definition [--account act_…] [--json]");
+        process.exit(1);
+    }
+    const account = typeof accountRaw === "string" ? accountRaw.trim() : undefined;
+    const query = account ? `?account=${encodeURIComponent(account)}` : "";
+    const res = await apiGet(`/api/v2/winners/definition${query}`);
+    if (!res.ok) {
+        if (json) {
+            console.log(JSON.stringify({ ok: false, status: res.status, data: res.data }));
+            process.exit(1);
+        }
+        if (res.status === 400 && errorCode(res.data) === "ACCOUNT_REQUIRED") {
+            for (const line of accountRequiredLines(res, (id) => `exodus winners definition --account ${id}`)) {
+                console.log(line);
+            }
+            process.exit(1);
+        }
+        console.log(formatError(res));
+        process.exit(1);
+    }
+    if (json) {
+        console.log(JSON.stringify({ ok: true, ...res.data }));
+        return;
+    }
+    for (const line of formatDefinition(res.data))
+        console.log(line);
+}

package/dist/lib/meta-ads.d.ts

@@ -0,0 +1,108 @@
+import { type ApiResponse } from "./client.js";
+import { type Channel } from "./channel.js";
+export interface AdAccountRef {
+    accountId?: string | null;
+    name?: string | null;
+    currency?: string | null;
+}
+export interface AdMedia {
+    image?: string | null;
+    video?: string | null;
+    poster?: string | null;
+}
+export interface AdWindowStats {
+    resultType?: string | null;
+    results?: number | null;
+    costPerResult?: number | null;
+    costPerResultDisplay?: string | null;
+    ctr?: number | null;
+    ctrDisplay?: string | null;
+    cpc?: number | null;
+    cpcDisplay?: string | null;
+    spend?: number | null;
+    spendDisplay?: string | null;
+    impressions?: number | null;
+    clicks?: number | null;
+    currency?: string | null;
+}
+export interface AdSummary extends AdWindowStats {
+    adId?: string | null;
+    accountId?: string | null;
+    name?: string | null;
+    status?: string | null;
+    format?: string | null;
+    campaign?: {
+        id?: string | null;
+        name?: string | null;
+        objective?: string | null;
+    } | null;
+    adset?: {
+        id?: string | null;
+        name?: string | null;
+        optimizationGoal?: string | null;
+    } | null;
+    createdTime?: string | number | null;
+    headline?: string | null;
+    bodyText?: string | null;
+    winnerStatus?: string | null;
+    media?: AdMedia | null;
+    syncedAt?: string | number | null;
+}
+export interface AdsListResponse {
+    ads?: AdSummary[];
+    count?: number;
+    window?: string;
+    sort?: string;
+    accounts?: AdAccountRef[];
+}
+export interface AdShowResponse extends AdSummary {
+    lifetime?: AdWindowStats | null;
+    last90d?: AdWindowStats | null;
+    commentCounts?: {
+        facebook?: number | null;
+        instagram?: number | null;
+    } | null;
+}
+export interface AdComment {
+    id?: string | null;
+    adId?: string | null;
+    platform?: string | null;
+    text?: string | null;
+    createdAt?: string | number | null;
+    likeCount?: number | null;
+    parentId?: string | null;
+    syncedAt?: string | number | null;
+}
+export interface CommentsResponse {
+    adId?: string | null;
+    comments?: AdComment[];
+    count?: number;
+}
+export interface FlowResult {
+    code: number;
+    lines: string[];
+    warnings?: string[];
+}
+export interface MetaAdsDeps {
+    get: (path: string) => Promise<ApiResponse<unknown>>;
+    channel: Channel;
+    apiUrl: () => string;
+    now: () => number;
+}
+export declare const defaultMetaAdsDeps: MetaAdsDeps;
+export declare function displayOr(display: unknown, value: unknown, format: (n: number) => string): string;
+export declare function money(n: number, currency?: string | null): string;
+export declare function percent(n: number): string;
+export declare function count(n: unknown): string;
+export declare function sanitizeForTerminal(text: unknown): string;
+export declare function safeText(text: unknown): string;
+export declare function safeTextOr(text: unknown, fallback: string): string;
+export declare function truncate(text: unknown, max: number): string;
+export declare function dateOrDash(value: unknown): string;
+export declare function table(headers: string[], rows: string[][]): string;
+export declare function accountLine(account: AdAccountRef): string;
+export declare function mediaUrl(apiBase: string, relative: unknown): string | null;
+export declare function errorCode(data: unknown): string | undefined;
+export declare function accountsOf(data: unknown): AdAccountRef[];
+export declare function accountRequiredLines(res: ApiResponse<unknown>, example: (accountId: string) => string): string[];
+export declare function errorFor(res: ApiResponse<unknown>, verb: string, json: boolean, deps: MetaAdsDeps, example: (accountId: string) => string): FlowResult | undefined;

package/dist/lib/meta-ads.js

@@ -0,0 +1,156 @@
+import { apiGet, getApiUrl } from "./client.js";
+import { formatApiError } from "./format.js";
+import { auth401Hint } from "./backend-hint.js";
+import { getChannel } from "./channel.js";
+import { missingRouteLine } from "./route-support.js";
+export const defaultMetaAdsDeps = {
+    get: (path) => apiGet(path),
+    channel: getChannel(),
+    apiUrl: () => getApiUrl(),
+    now: () => Date.now(),
+};
+export function displayOr(display, value, format) {
+    if (typeof display === "string" && display.trim())
+        return safeTextOr(display, "—");
+    if (typeof value === "number" && Number.isFinite(value))
+        return format(value);
+    return "—";
+}
+export function money(n, currency) {
+    const body = n.toLocaleString("en-US", {
+        minimumFractionDigits: n < 100 ? 2 : 0,
+        maximumFractionDigits: 2,
+    });
+    return currency ? `${body} ${currency}` : body;
+}
+export function percent(n) {
+    return `${n.toFixed(2)}%`;
+}
+export function count(n) {
+    return typeof n === "number" && Number.isFinite(n) ? n.toLocaleString("en-US") : "—";
+}
+const ESC_STRING_SEQUENCE = /\x1b[\]PX^_][\s\S]*?(?:\x07|\x1b\\|$)/g;
+const ESC_CSI_SEQUENCE = /\x1b\[[0-?]*[ -\/]*[@-~]?/g;
+const ESC_SIMPLE_SEQUENCE = /\x1b[ -\/]*[0-~]?/g;
+const C0_AND_DEL = /[\x00-\x08\x0b-\x1f\x7f]/g;
+const C1_CONTROLS = /[\u0080-\u009f]/g;
+export function sanitizeForTerminal(text) {
+    if (typeof text !== "string" || text === "")
+        return "";
+    return text
+        .replace(ESC_STRING_SEQUENCE, "")
+        .replace(ESC_CSI_SEQUENCE, "")
+        .replace(ESC_SIMPLE_SEQUENCE, "")
+        .replace(C0_AND_DEL, "")
+        .replace(C1_CONTROLS, "");
+}
+export function safeText(text) {
+    return sanitizeForTerminal(text).trim();
+}
+export function safeTextOr(text, fallback) {
+    return safeText(text) || fallback;
+}
+export function truncate(text, max) {
+    if (typeof text !== "string")
+        return "";
+    const flat = sanitizeForTerminal(text).replace(/\s+/g, " ").trim();
+    if (flat.length <= max)
+        return flat;
+    const cut = flat.slice(0, max - 1);
+    const lastSpace = cut.lastIndexOf(" ");
+    const body = lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut;
+    return `${body}…`;
+}
+export function dateOrDash(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? "—" : d.toISOString().slice(0, 10);
+    }
+    if (typeof value === "string" && value.trim()) {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime())
+            ? safeText(value).slice(0, 10)
+            : d.toISOString().slice(0, 10);
+    }
+    return "—";
+}
+export function table(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((row) => row[i]?.length ?? 0)));
+    const fmt = (row) => row.map((cell, i) => (cell ?? "").padEnd(widths[i])).join("  ").trimEnd();
+    return [fmt(headers), fmt(headers.map((h) => "-".repeat(h.length))), ...rows.map(fmt)].join("\n");
+}
+export function accountLine(account) {
+    const id = safeTextOr(account.accountId, "(no id)");
+    const name = safeText(account.name);
+    const currency = safeText(account.currency);
+    const suffix = [name, currency ? `(${currency})` : ""].filter(Boolean).join(" ");
+    return suffix ? `  ${id}  ${suffix}` : `  ${id}`;
+}
+export function mediaUrl(apiBase, relative) {
+    const rel = safeText(relative);
+    if (!rel)
+        return null;
+    if (/^https?:\/\//i.test(rel))
+        return rel;
+    const base = (apiBase || "").replace(/\/$/, "");
+    return `${base}${rel.startsWith("/") ? "" : "/"}${rel}`;
+}
+export function errorCode(data) {
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const rec = data;
+    if (typeof rec.code === "string" && rec.code)
+        return rec.code;
+    const err = rec.error;
+    if (typeof err === "object" && err !== null) {
+        const nested = err.code;
+        if (typeof nested === "string" && nested)
+            return nested;
+    }
+    return undefined;
+}
+export function accountsOf(data) {
+    if (typeof data !== "object" || data === null)
+        return [];
+    const raw = data.accounts;
+    return Array.isArray(raw) ? raw : [];
+}
+export function accountRequiredLines(res, example) {
+    const accounts = accountsOf(res.data);
+    const lines = [formatApiError(res)];
+    if (accounts.length > 0) {
+        lines.push("");
+        lines.push("Connected ad accounts:");
+        for (const account of accounts)
+            lines.push(accountLine(account));
+        const first = accounts[0]?.accountId;
+        if (first) {
+            lines.push("");
+            lines.push("Re-run naming the one you mean:");
+            lines.push(`  ${example(first)}`);
+        }
+    }
+    return lines;
+}
+export function errorFor(res, verb, json, deps, example) {
+    if (res.ok)
+        return undefined;
+    if (json) {
+        return { code: 1, lines: [JSON.stringify({ ok: false, status: res.status, data: res.data })] };
+    }
+    const unsupported = missingRouteLine(res, verb, deps.channel);
+    if (unsupported)
+        return { code: 1, lines: [unsupported] };
+    if (res.status === 400 && errorCode(res.data) === "ACCOUNT_REQUIRED") {
+        return { code: 1, lines: accountRequiredLines(res, example) };
+    }
+    const lines = [formatApiError(res)];
+    if (res.status === 401) {
+        lines.push("");
+        lines.push(auth401Hint(deps.apiUrl()));
+    }
+    else if (res.status === 400 && errorCode(res.data) === "NO_BRAND") {
+        lines.push("Pick a brand first:  exodus brand use <slug>");
+    }
+    return { code: 1, lines };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicopycoders/exodus",
-  "version": "2026.9.200",
+  "version": "2026.9.1100-beta.1",
   "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
   "repository": {
     "type": "git",