@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/ugc-local.js

@@ -0,0 +1,174 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative } from "node:path";
+import YAML from "yaml";
+import { SPEC_DIR } from "./files.js";
+/**
+ * Clips made on this machine with the user's own fal key (FAL_KEY), the same pipeline as Appeeky's
+ * hosted UGC and the desktop app's local mode: the persona's look → a still in the scene → a talking
+ * video with the script in the persona's voice. Planning, prompts and prices come from Appeeky's
+ * UGC core, bundled into dist/ugc-core.js and loaded only when this runs; fal bills the user directly.
+ *
+ * Personas come from either:
+ *   appeeky/ugc/personas/<name>.yaml   a persona kept in the repo, `looks:` pointing at its images
+ *   Appeeky UGC                         a persona made in Appeeky (APPEEKY_API_KEY), its cover as the look
+ */
+export const localPersonasDir = (root) => join(root, SPEC_DIR, "ugc", "personas");
+export const mediaDir = (root) => join(root, ".appeeky", "media");
+/** The UGC pipeline ships inside Spec as one minified file (dist/ugc-core.js, built by scripts/vendor-ugc-core.mjs). */
+export const CORE_FILE = "./ugc-core.js";
+export async function loadCore(load = (s) => import(s)) {
+    try {
+        return (await load(CORE_FILE));
+    }
+    catch {
+        throw new Error("This build of @appeeky/spec has no UGC pipeline (dist/ugc-core.js). Update it: npm install -g @appeeky/spec@latest");
+    }
+}
+function asUgcPersona(p) {
+    return {
+        ownerEmail: "",
+        appId: null,
+        status: "active",
+        bio: "",
+        story: "",
+        personality: "",
+        appearance: "",
+        voice: "",
+        voiceId: null,
+        style: {},
+        identity: {},
+        signatureDetails: [],
+        imperfections: [],
+        cameraHabits: {},
+        voiceProfile: {},
+        neverChange: [],
+        lane: "",
+        formats: [],
+        contentPillars: [],
+        platforms: [],
+        referenceAssetIds: p.looks,
+        folderId: null,
+        createdAt: "",
+        updatedAt: "",
+        ...p,
+    };
+}
+/** A persona kept in the repo (appeeky/ugc/personas/<name>.yaml), with its looks resolved to paths or URLs. */
+export async function readLocalPersona(root, name) {
+    const dir = localPersonasDir(root);
+    if (!existsSync(dir))
+        return undefined;
+    const slug = (n) => n.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+    const hit = (await readdir(dir)).find((f) => f.endsWith(".yaml") && slug(basename(f, ".yaml")) === slug(name));
+    if (!hit)
+        return undefined;
+    const file = join(dir, hit);
+    const raw = YAML.parse(await readFile(file, "utf8"));
+    if (!raw?.looks?.length)
+        throw new Error(`${relative(root, file)} needs looks: the persona's images (paths next to the file, or URLs).`);
+    return {
+        ...raw,
+        id: raw.id ?? basename(file, ".yaml"),
+        name: raw.name ?? basename(file, ".yaml"),
+        looks: raw.looks.map((l) => (/^https?:\/\//.test(l) || isAbsolute(l) ? l : join(dirname(file), l))),
+    };
+}
+/** A persona made in Appeeky UGC: its fields, with the cover image as its look. */
+export async function readAppeekyPersona(api, name) {
+    const res = await api.get("/ugc/personas");
+    const p = res?.personas?.find((x) => x.id === name || x.name.toLowerCase() === name.toLowerCase());
+    if (!p)
+        return undefined;
+    if (!p.coverUrl)
+        throw new Error(`${p.name} has no look in Appeeky yet: pick one in Appeeky UGC, or keep the persona in appeeky/ugc/personas/ with its images.`);
+    const { coverUrl, referenceAssetIds: _ids, ...rest } = p;
+    return { ...rest, looks: [coverUrl] };
+}
+/** The same two steps as the hosted clip render: a still of the persona in the scene, then a talking video. */
+export function planLocalClip(core, persona, brief, refs) {
+    const script = brief.script.trim();
+    if (script.length > core.MAX_SCRIPT_CHARS)
+        throw new Error(`The script is too long for one clip (max ${core.MAX_SCRIPT_CHARS} characters, about 8 seconds of speech).`);
+    const model = core.getMediaModel("veo-3.1-fast");
+    if (!model)
+        throw new Error("The video model veo-3.1-fast is missing from @appeeky/ugc-core: update it.");
+    const durationSec = core.fitDuration(model, brief.durationSec ?? 8);
+    const aspectRatio = brief.aspectRatio ?? "9:16";
+    const ugcPersona = asUgcPersona(persona);
+    const negativePrompt = core.negativesFor(core.buildCreatorLock(ugcPersona), { video: true }).join(", ");
+    const scene = (brief.scene ?? "").trim();
+    const still = core.prepareImageJob({
+        ownerEmail: "",
+        modelId: "nano-banana",
+        prompt: core.stillPrompt({ persona: ugcPersona, shot: {}, direction: scene || "talking to the camera at home" }),
+        imageUrls: refs,
+        count: 1,
+        aspectRatio,
+    });
+    const video = (stillUrl) => core.prepareVideoJob({
+        ownerEmail: "",
+        modelId: model.id,
+        prompt: core.talkingVideoPrompt({ persona: ugcPersona, shot: {}, direction: scene, script }),
+        imageUrl: stillUrl,
+        durationSec,
+        aspectRatio,
+        audio: true,
+        negativePrompt,
+    });
+    const costUsd = Math.round((still.costUsd + video(core.PLACEHOLDER_IMAGE).costUsd) * 10_000) / 10_000;
+    return { still, video, costUsd, clip: { durationSec, aspectRatio, videoModelId: model.id } };
+}
+const CONTENT_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp" };
+/** Local look images go to fal storage first, so the models can fetch them. */
+async function referenceUrls(fal, looks) {
+    const urls = [];
+    for (const look of looks.slice(0, 6)) {
+        if (/^https?:\/\//.test(look))
+            urls.push(look);
+        else
+            urls.push(await fal.upload({ data: await readFile(look), contentType: CONTENT_TYPES[extname(look).toLowerCase()] ?? "image/png", fileName: basename(look) }));
+    }
+    return urls;
+}
+async function runJob(core, fal, job, sleep, timeoutMs = 15 * 60_000) {
+    const submission = await fal.submit(job.model.endpoint, job.model.mapInput(job.request));
+    const started = Date.now();
+    for (;;) {
+        const s = await fal.status(submission.statusUrl);
+        if (s.state === "completed")
+            break;
+        if (s.state === "failed")
+            throw new Error(`fal: ${s.error}`);
+        if (Date.now() - started > timeoutMs)
+            throw new Error("fal: timed out after 15 minutes");
+        await sleep(4000);
+    }
+    const out = core.extractOutputUrls(await fal.result(submission.responseUrl));
+    if (!out[0])
+        throw new Error("fal returned no media");
+    return out[0].url;
+}
+/** Make the clip with the user's fal key, save it under .appeeky/media/ and record it in the brief. */
+export async function generateLocal(core, root, brief, persona, falKey, options = {}) {
+    const fal = core.createFalClient(falKey);
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const log = options.log ?? (() => { });
+    const refs = await referenceUrls(fal, persona.looks);
+    const plan = planLocalClip(core, persona, brief, refs);
+    log("still: the persona in the scene");
+    const stillUrl = await runJob(core, fal, plan.still, sleep);
+    log("video: the persona says the script");
+    const videoUrl = await runJob(core, fal, plan.video(stillUrl), sleep);
+    const res = await (options.fetcher ?? fetch)(videoUrl);
+    if (!res.ok)
+        throw new Error(`Could not download the clip: HTTP ${res.status}`);
+    await mkdir(mediaDir(root), { recursive: true });
+    const file = join(mediaDir(root), `${basename(brief.file, ".yaml")}.mp4`);
+    await writeFile(file, new Uint8Array(await res.arrayBuffer()));
+    const { file: briefFile, ...rest } = brief;
+    const record = { ...rest, status: "generated", clipFile: relative(root, file), videoUrl, costUsd: plan.costUsd, generatedAt: (options.now ?? new Date()).toISOString() };
+    await writeFile(briefFile, YAML.stringify(record, { lineWidth: 0 }));
+    return { file, videoUrl, stillUrl, costUsd: plan.costUsd };
+}
+//# sourceMappingURL=ugc-local.js.map

package/dist/ugc.d.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import type { AppeekyApi } from "./appeeky-api.js";
+/**
+ * UGC from Appeeky's creator personas, in the repo (APPEEKY_API_KEY):
+ *
+ *   appeeky/ugc/personas.yaml        the creator personas: who they are, their lane and platforms
+ *   appeeky/ugc/clips.jsonl          the clips made with them: script, caption, status, where posted
+ *   appeeky/ugc/briefs/<name>.yaml   a video to make: drafted, reviewed in a pull request, then generated
+ *
+ * Generating a clip uses Appeeky media credits, so it only runs when a person asks for it.
+ */
+export declare const ugcDir: (root: string) => string;
+export declare const briefsDir: (root: string) => string;
+export interface Persona {
+    id: string;
+    name: string;
+    status?: string;
+    bio?: string;
+    lane?: string;
+    platforms?: string[];
+    contentPillars?: string[];
+    /** Clips need a look (reference images) picked in Appeeky first. */
+    ready: boolean;
+}
+export interface Clip {
+    id: string;
+    persona: string;
+    status: string;
+    title?: string;
+    script?: string;
+    caption?: string;
+    durationSec?: number;
+    aspectRatio?: string;
+    scheduledFor?: string;
+    socialPostId?: string;
+    error?: string;
+    createdAt: string;
+}
+interface PersonaRow {
+    id: string;
+    name: string;
+    status?: string;
+    bio?: string;
+    lane?: string;
+    platforms?: string[];
+    contentPillars?: string[];
+    referenceAssetIds?: string[];
+}
+interface ClipRow {
+    id: string;
+    personaId: string;
+    status: string;
+    title?: string;
+    script?: string;
+    caption?: string;
+    durationSec?: number;
+    aspectRatio?: string;
+    scheduledFor?: string | null;
+    socialPostId?: string | null;
+    error?: string | null;
+    createdAt: string;
+}
+export declare function toPersona(r: PersonaRow): Persona;
+/** Signed media URLs expire within hours, so clips are stored without them. */
+export declare function toClip(r: ClipRow, personas: Persona[]): Clip;
+export declare function fetchUgc(api: AppeekyApi, options?: {
+    limit?: number;
+}): Promise<{
+    personas: Persona[];
+    clips: Clip[];
+}>;
+export declare function saveUgc(root: string, data: {
+    personas: Persona[];
+    clips: Clip[];
+}): Promise<void>;
+export declare function readPersonas(root: string): Promise<Persona[]>;
+export declare const briefSchema: z.ZodObject<{
+    /** A persona name or id from personas.yaml. */
+    persona: z.ZodString;
+    /** What the creator says, word for word. */
+    script: z.ZodString;
+    /** Where it is filmed and what is on screen. */
+    scene: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    durationSec: z.ZodOptional<z.ZodNumber>;
+    aspectRatio: z.ZodOptional<z.ZodEnum<["9:16", "16:9"]>>;
+    /** The hypothesis, for whoever reviews the pull request: which hook, for whom, measured how. */
+    why: z.ZodOptional<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<["draft", "generating", "generated"]>>;
+    clipId: z.ZodOptional<z.ZodString>;
+    credits: z.ZodOptional<z.ZodNumber>;
+    generatedAt: z.ZodOptional<z.ZodString>;
+    /** Made locally with --local: the file under .appeeky/media/, fal's URL for it and what fal charged. */
+    clipFile: z.ZodOptional<z.ZodString>;
+    videoUrl: z.ZodOptional<z.ZodString>;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    status: "draft" | "generating" | "generated";
+    persona: string;
+    script: string;
+    title?: string | undefined;
+    why?: string | undefined;
+    scene?: string | undefined;
+    caption?: string | undefined;
+    durationSec?: number | undefined;
+    aspectRatio?: "9:16" | "16:9" | undefined;
+    clipId?: string | undefined;
+    credits?: number | undefined;
+    generatedAt?: string | undefined;
+    clipFile?: string | undefined;
+    videoUrl?: string | undefined;
+    costUsd?: number | undefined;
+}, {
+    persona: string;
+    script: string;
+    status?: "draft" | "generating" | "generated" | undefined;
+    title?: string | undefined;
+    why?: string | undefined;
+    scene?: string | undefined;
+    caption?: string | undefined;
+    durationSec?: number | undefined;
+    aspectRatio?: "9:16" | "16:9" | undefined;
+    clipId?: string | undefined;
+    credits?: number | undefined;
+    generatedAt?: string | undefined;
+    clipFile?: string | undefined;
+    videoUrl?: string | undefined;
+    costUsd?: number | undefined;
+}>;
+export type Brief = z.infer<typeof briefSchema>;
+export declare function readBriefs(root: string): Promise<Array<Brief & {
+    file: string;
+}>>;
+export declare function findPersona(brief: Brief, personas: Persona[]): Persona | undefined;
+/** What the clip would cost in media credits, without making it. */
+export declare function quoteBrief(api: AppeekyApi, brief: Brief, persona: Persona): Promise<{
+    credits: number;
+    available: number;
+    affordable: boolean;
+}>;
+/** Start rendering the clip (uses media credits) and record it in the brief. */
+export declare function generateBrief(api: AppeekyApi, brief: Brief & {
+    file: string;
+}, persona: Persona, now?: Date): Promise<{
+    clipId: string;
+    credits: number;
+}>;
+export {};

package/dist/ugc.js

@@ -0,0 +1,111 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+import { SPEC_DIR, SpecError } from "./files.js";
+/**
+ * UGC from Appeeky's creator personas, in the repo (APPEEKY_API_KEY):
+ *
+ *   appeeky/ugc/personas.yaml        the creator personas: who they are, their lane and platforms
+ *   appeeky/ugc/clips.jsonl          the clips made with them: script, caption, status, where posted
+ *   appeeky/ugc/briefs/<name>.yaml   a video to make: drafted, reviewed in a pull request, then generated
+ *
+ * Generating a clip uses Appeeky media credits, so it only runs when a person asks for it.
+ */
+export const ugcDir = (root) => join(root, SPEC_DIR, "ugc");
+export const briefsDir = (root) => join(ugcDir(root), "briefs");
+const compact = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== "" && !(Array.isArray(v) && v.length === 0)));
+export function toPersona(r) {
+    return { ...compact({ id: r.id, name: r.name, status: r.status, bio: r.bio, lane: r.lane, platforms: r.platforms, contentPillars: r.contentPillars }), ready: (r.referenceAssetIds?.length ?? 0) > 0 };
+}
+/** Signed media URLs expire within hours, so clips are stored without them. */
+export function toClip(r, personas) {
+    return compact({
+        id: r.id,
+        persona: personas.find((p) => p.id === r.personaId)?.name ?? r.personaId,
+        status: r.status,
+        title: r.title,
+        script: r.script,
+        caption: r.caption,
+        durationSec: r.durationSec,
+        aspectRatio: r.aspectRatio,
+        scheduledFor: r.scheduledFor ?? undefined,
+        socialPostId: r.socialPostId ?? undefined,
+        error: r.error ?? undefined,
+        createdAt: r.createdAt,
+    });
+}
+export async function fetchUgc(api, options = {}) {
+    const personas = ((await api.get("/ugc/personas"))?.personas ?? []).map(toPersona);
+    const clips = ((await api.get("/ugc/clips", { limit: String(options.limit ?? 100) }))?.clips ?? []).map((c) => toClip(c, personas));
+    return { personas, clips };
+}
+export async function saveUgc(root, data) {
+    await mkdir(ugcDir(root), { recursive: true });
+    await writeFile(join(ugcDir(root), "personas.yaml"), YAML.stringify({ personas: data.personas }, { lineWidth: 0 }));
+    await writeFile(join(ugcDir(root), "clips.jsonl"), data.clips.map((c) => JSON.stringify(c)).join("\n") + (data.clips.length ? "\n" : ""));
+}
+export async function readPersonas(root) {
+    const file = join(ugcDir(root), "personas.yaml");
+    if (!existsSync(file))
+        return [];
+    return (YAML.parse(await readFile(file, "utf8"))?.personas ?? []);
+}
+// ── Briefs ──────────────────────────────────────────────────────────────────
+export const briefSchema = z
+    .object({
+    /** A persona name or id from personas.yaml. */
+    persona: z.string().min(1),
+    /** What the creator says, word for word. */
+    script: z.string().min(1),
+    /** Where it is filmed and what is on screen. */
+    scene: z.string().optional(),
+    caption: z.string().optional(),
+    title: z.string().optional(),
+    durationSec: z.number().int().positive().optional(),
+    aspectRatio: z.enum(["9:16", "16:9"]).optional(),
+    /** The hypothesis, for whoever reviews the pull request: which hook, for whom, measured how. */
+    why: z.string().optional(),
+    status: z.enum(["draft", "generating", "generated"]).default("draft"),
+    clipId: z.string().optional(),
+    credits: z.number().optional(),
+    generatedAt: z.string().optional(),
+    /** Made locally with --local: the file under .appeeky/media/, fal's URL for it and what fal charged. */
+    clipFile: z.string().optional(),
+    videoUrl: z.string().url().optional(),
+    costUsd: z.number().optional(),
+})
+    .strict();
+export async function readBriefs(root) {
+    const dir = briefsDir(root);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of (await readdir(dir)).filter((f) => f.endsWith(".yaml")).sort()) {
+        const parsed = briefSchema.safeParse(YAML.parse(await readFile(join(dir, f), "utf8")));
+        if (!parsed.success)
+            throw new SpecError(parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "), join(dir, f));
+        out.push({ ...parsed.data, file: join(dir, f) });
+    }
+    return out;
+}
+export function findPersona(brief, personas) {
+    const ref = brief.persona.toLowerCase();
+    return personas.find((p) => p.id === brief.persona || p.name.toLowerCase() === ref);
+}
+function clipBody(brief) {
+    return compact({ script: brief.script, scene: brief.scene, caption: brief.caption, title: brief.title, durationSec: brief.durationSec, aspectRatio: brief.aspectRatio });
+}
+/** What the clip would cost in media credits, without making it. */
+export async function quoteBrief(api, brief, persona) {
+    return api.post(`/ugc/personas/${encodeURIComponent(persona.id)}/clips`, { ...clipBody(brief), dryRun: true });
+}
+/** Start rendering the clip (uses media credits) and record it in the brief. */
+export async function generateBrief(api, brief, persona, now = new Date()) {
+    const res = await api.post(`/ugc/personas/${encodeURIComponent(persona.id)}/clips`, clipBody(brief));
+    const { file, ...rest } = brief;
+    await writeFile(file, YAML.stringify({ ...rest, status: "generating", clipId: res.clip.id, credits: res.credits, generatedAt: now.toISOString() }, { lineWidth: 0 }));
+    return { clipId: res.clip.id, credits: res.credits };
+}
+//# sourceMappingURL=ugc.js.map

package/dist/verify.d.ts

@@ -0,0 +1,70 @@
+import type { Project, StoreId } from "./schema.js";
+/** Where a store app's search rank for a keyword comes from. `null` = not in the results. */
+export interface RankSource {
+    readonly label: string;
+    /** Ranks for several keywords in one storefront. Missing keys mean "unknown". */
+    ranks(store: StoreId, appId: string, country: string, keywords: string[]): Promise<Record<string, number | null>>;
+}
+/** country → keyword → rank */
+export type RankSnapshot = Record<string, Record<string, number | null>>;
+export interface RankBaseline {
+    at: string;
+    source: string;
+    ranks: Partial<Record<StoreId, RankSnapshot>>;
+}
+/** Store ids for rank lookups: numeric App Store id, Google Play package name. */
+export declare function rankAppIds(project: Project): Partial<Record<StoreId, string>>;
+/** Ranks for every target of the given stores; failures leave that storefront out. */
+export declare function snapshotRanks(project: Project, source: RankSource, stores: StoreId[]): Promise<RankBaseline>;
+export interface RankMove {
+    country: string;
+    keyword: string;
+    before: number | null;
+    after: number | null;
+}
+export type Verdict = "won" | "lost" | "mixed" | "flat";
+export interface RankEvaluation {
+    improved: RankMove[];
+    dropped: RankMove[];
+    /** Top-20 terms that fell out of the top 20 by 10+ places, or stopped ranking. */
+    regressions: RankMove[];
+    verdict: Verdict;
+    /** Set when ranks did not move and the verdict came from these outcome metrics instead. */
+    decidedBy?: string[];
+    /** The changed storefronts against the unchanged ones over the same days. */
+    control?: import("./control.js").ControlComparison;
+    /** Why the verdict differs from the raw rank count, in words. */
+    note?: string;
+}
+/**
+ * Compare two snapshots of one store. A release "lost" when one top-10 term
+ * or two top-20 terms fell away (the rule the co-founder uses to propose a
+ * revert), "won" when more terms rose than fell, "mixed" or "flat" otherwise.
+ */
+export declare function evaluateRanks(before: RankSnapshot, after: RankSnapshot): RankEvaluation;
+/** App Store ranks from Apple's public search API: no key needed, top 200 results. */
+export declare function itunesRankSource(fetcher?: typeof fetch): RankSource;
+/** Combine sources: the first one that knows a keyword wins. */
+export declare function firstRankSource(...sources: RankSource[]): RankSource;
+/** Store-listing conversion over a date range, e.g. installs / product page visitors. */
+export interface ConversionWindow {
+    /** installs ÷ visitors, 0–1 */
+    rate: number;
+    visitors: number;
+    installs: number;
+    days: number;
+}
+/** Where conversion numbers come from (App Store Connect analytics, Play Console, a local cache). */
+export interface ConversionSource {
+    readonly label: string;
+    /** Conversion between two ISO dates (inclusive start, exclusive end); null when there is no data. */
+    conversion(store: StoreId, appId: string, from: string, to: string): Promise<ConversionWindow | null>;
+}
+export interface ConversionChange {
+    before: ConversionWindow;
+    after: ConversionWindow;
+    /** Relative change of the rate, e.g. 0.12 = +12%. */
+    change: number;
+}
+/** Compare the conversion of the `days` before a push with the `days` after it. */
+export declare function measureConversion(source: ConversionSource, store: StoreId, appId: string, pushedAt: string, days: number): Promise<ConversionChange | null>;

package/dist/verify.js

@@ -0,0 +1,134 @@
+import { normalize } from "./text.js";
+/** Store ids for rank lookups: numeric App Store id, Google Play package name. */
+export function rankAppIds(project) {
+    const ids = {};
+    const asc = project.spec.stores.appStore?.appId;
+    if (asc && /^\d+$/.test(asc))
+        ids["app-store"] = asc;
+    if (project.spec.stores.googlePlay)
+        ids["google-play"] = project.spec.stores.googlePlay.packageName;
+    return ids;
+}
+/** Ranks for every target of the given stores; failures leave that storefront out. */
+export async function snapshotRanks(project, source, stores) {
+    const ids = rankAppIds(project);
+    const baseline = { at: new Date().toISOString(), source: source.label, ranks: {} };
+    for (const store of stores) {
+        const appId = ids[store];
+        if (!appId)
+            continue;
+        const snap = {};
+        for (const [country, targets] of Object.entries(project.spec.targets)) {
+            const keywords = [...new Set(targets.map((k) => normalize(k).trim()))];
+            if (keywords.length === 0)
+                continue;
+            try {
+                snap[country] = await source.ranks(store, appId, country, keywords);
+            }
+            catch {
+                // A storefront that cannot be read now is simply not part of the baseline.
+            }
+        }
+        if (Object.keys(snap).length > 0)
+            baseline.ranks[store] = snap;
+    }
+    return baseline;
+}
+/** A move only counts when it is at least this many places. */
+const MIN_MOVE = 3;
+/** Same thresholds as the co-founder's ranking-term guard and auto-revert. */
+const TOP = 20;
+const DROP_PLACES = 10;
+/** Not ranked counts as just past the 200 results the stores return, so "out → out" is no move. */
+const UNRANKED = 201;
+const asRank = (r) => (r === null || r === undefined ? UNRANKED : r);
+/**
+ * Compare two snapshots of one store. A release "lost" when one top-10 term
+ * or two top-20 terms fell away (the rule the co-founder uses to propose a
+ * revert), "won" when more terms rose than fell, "mixed" or "flat" otherwise.
+ */
+export function evaluateRanks(before, after) {
+    const improved = [];
+    const dropped = [];
+    const regressions = [];
+    for (const [country, ranks] of Object.entries(before)) {
+        for (const [keyword, b] of Object.entries(ranks)) {
+            if (!(keyword in (after[country] ?? {})))
+                continue;
+            const a = after[country][keyword] ?? null;
+            const move = { country, keyword, before: b, after: a };
+            const from = asRank(b);
+            const to = asRank(a);
+            if (to + MIN_MOVE <= from)
+                improved.push(move);
+            else if (from + MIN_MOVE <= to)
+                dropped.push(move);
+            if (b !== null && b <= TOP && (a === null || (a > TOP && a - b >= DROP_PLACES)))
+                regressions.push(move);
+        }
+    }
+    const lost = regressions.length >= 2 || regressions.some((r) => (r.before ?? UNRANKED) <= 10);
+    const verdict = lost
+        ? "lost"
+        : improved.length > dropped.length
+            ? "won"
+            : improved.length === 0 && dropped.length === 0
+                ? "flat"
+                : "mixed";
+    return { improved, dropped, regressions, verdict };
+}
+/** App Store ranks from Apple's public search API: no key needed, top 200 results. */
+export function itunesRankSource(fetcher = fetch) {
+    return {
+        label: "App Store search",
+        async ranks(store, appId, country, keywords) {
+            if (store !== "app-store")
+                return {};
+            const out = {};
+            for (const keyword of keywords) {
+                const url = `https://itunes.apple.com/search?media=software&entity=software&limit=200&country=${encodeURIComponent(country)}&term=${encodeURIComponent(keyword)}`;
+                const res = await fetcher(url, { headers: { "User-Agent": "appeeky-spec" } });
+                if (!res.ok)
+                    continue;
+                const json = (await res.json());
+                const index = (json.results ?? []).findIndex((r) => String(r.trackId) === appId);
+                out[keyword] = index >= 0 ? index + 1 : null;
+            }
+            return out;
+        },
+    };
+}
+/** Combine sources: the first one that knows a keyword wins. */
+export function firstRankSource(...sources) {
+    return {
+        label: sources.map((s) => s.label).join(" + "),
+        async ranks(store, appId, country, keywords) {
+            const out = {};
+            let left = keywords;
+            for (const s of sources) {
+                if (left.length === 0)
+                    break;
+                try {
+                    Object.assign(out, await s.ranks(store, appId, country, left));
+                }
+                catch {
+                    // try the next source
+                }
+                left = keywords.filter((k) => !(k in out));
+            }
+            return out;
+        },
+    };
+}
+/** Compare the conversion of the `days` before a push with the `days` after it. */
+export async function measureConversion(source, store, appId, pushedAt, days) {
+    const t = Date.parse(pushedAt);
+    const iso = (ms) => new Date(ms).toISOString().slice(0, 10);
+    const span = Math.max(1, days) * 86_400_000;
+    const before = await source.conversion(store, appId, iso(t - span), iso(t));
+    const after = await source.conversion(store, appId, iso(t + 86_400_000), iso(t + 86_400_000 + span));
+    if (!before || !after || before.visitors === 0 || after.visitors === 0)
+        return null;
+    return { before, after, change: before.rate > 0 ? after.rate / before.rate - 1 : 0 };
+}
+//# sourceMappingURL=verify.js.map