@appeeky/spec 0.0.0-stage → 0.1.0

package/dist/data.js

@@ -0,0 +1,298 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { SPEC_DIR } from "./files.js";
+import { rankAppIds } from "./verify.js";
+/**
+ * Your app's numbers as plain CSV files an agent can read: the same sources Appeeky
+ * Desktop keeps locally (App Store Connect and Google Play analytics, Apple Search Ads,
+ * RevenueCat, Meta and TikTok), pulled through the connections in Appeeky.
+ *
+ * They are private business data, so they go to .appeeky/data/ (gitignored) unless the
+ * spec says `data: { commit: true }`, which writes them to appeeky/data/ instead.
+ * Pulling again merges by date, so a scheduled pull keeps one growing file per source.
+ */
+export function dataDir(project) {
+    return project.spec.data.commit ? join(project.root, SPEC_DIR, "data") : join(project.root, ".appeeky", "data");
+}
+function cell(v) {
+    if (v === null || v === undefined)
+        return "";
+    const s = typeof v === "number" ? String(Math.round(v * 10_000) / 10_000) : v;
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+function parseCsv(text) {
+    const [head, ...lines] = text.trim().split("\n");
+    if (!head)
+        return [];
+    const cols = head.split(",");
+    return lines.map((line) => {
+        const vals = [];
+        let cur = "";
+        let quoted = false;
+        for (let i = 0; i < line.length; i++) {
+            const ch = line[i];
+            if (quoted) {
+                if (ch === '"' && line[i + 1] === '"') {
+                    cur += '"';
+                    i++;
+                }
+                else if (ch === '"')
+                    quoted = false;
+                else
+                    cur += ch;
+            }
+            else if (ch === '"')
+                quoted = true;
+            else if (ch === ",") {
+                vals.push(cur);
+                cur = "";
+            }
+            else
+                cur += ch;
+        }
+        vals.push(cur);
+        return Object.fromEntries(cols.map((c, i) => [c, vals[i] ?? ""]));
+    });
+}
+/** Merge rows into a CSV file by key: new rows replace old ones with the same key. */
+export async function mergeCsv(dir, file) {
+    const path = join(dir, `${file.name}.csv`);
+    const keyOf = (r) => file.key.map((k) => String(r[k] ?? "")).join("|");
+    const merged = new Map();
+    if (existsSync(path))
+        for (const r of parseCsv(await readFile(path, "utf8")))
+            merged.set(keyOf(r), r);
+    for (const r of file.rows)
+        merged.set(keyOf(r), r);
+    const rows = [...merged.values()].sort((a, b) => keyOf(a).localeCompare(keyOf(b)));
+    await mkdir(dir, { recursive: true });
+    await writeFile(path, [file.columns.join(","), ...rows.map((r) => file.columns.map((c) => cell(r[c])).join(","))].join("\n") + "\n");
+    const dates = rows.map((r) => String(r.date ?? "")).filter(Boolean).sort();
+    return { path, rows: rows.length, from: dates[0], to: dates[dates.length - 1] };
+}
+const iso = (ms) => new Date(ms).toISOString().slice(0, 10);
+/** [from, to] inclusive, split into chunks the API accepts. */
+export function dateChunks(from, to, maxDays = 180) {
+    const out = [];
+    let start = Date.parse(from);
+    const end = Date.parse(to);
+    while (start <= end) {
+        const stop = Math.min(end, start + (maxDays - 1) * 86_400_000);
+        out.push([iso(start), iso(stop)]);
+        start = stop + 86_400_000;
+    }
+    return out;
+}
+/** Every source this spec can read, over the `days` up to yesterday. */
+export async function pullData(api, project, days, now = new Date(), attributionIn) {
+    const to = iso(now.getTime() - 86_400_000);
+    const from = iso(Date.parse(to) - (Math.max(1, days) - 1) * 86_400_000);
+    const ids = rankAppIds(project);
+    const files = [];
+    const errors = [];
+    const attempt = async (source, run) => {
+        try {
+            await run();
+        }
+        catch (e) {
+            errors.push({ source, message: e.message });
+        }
+    };
+    for (const store of (api ? Object.keys(ids) : [])) {
+        if (!api)
+            break;
+        const appId = ids[store];
+        const label = store === "app-store" ? "App Store Connect" : "Google Play";
+        await attempt(`${label} analytics`, async () => {
+            const storeRows = [];
+            const adRows = [];
+            const rcRows = [];
+            let sources = null;
+            let rcScope;
+            for (const [a, b] of dateChunks(from, to)) {
+                const m = await api.get(`/user/apps/${encodeURIComponent(appId)}/metrics`, { from: a, to: b });
+                for (const d of m?.store?.days ?? [])
+                    storeRows.push({ ...d, date: String(d.date) });
+                for (const d of m?.ads?.days ?? [])
+                    adRows.push({ ...d, currency: m?.ads?.currency });
+                for (const d of m?.revenuecat?.days ?? [])
+                    rcRows.push({ ...d, date: String(d.date) });
+                if (m?.sources)
+                    sources = m.sources;
+                rcScope = m?.revenuecat?.scope ?? rcScope;
+            }
+            if (storeRows.length)
+                files.push({
+                    name: `${store}-analytics`,
+                    about: `${label}: impressions, product page views, downloads, conversion, proceeds, trials and subscriptions per day`,
+                    key: ["date"],
+                    columns: ["date", "impressions", "pageViews", "downloads", "conversionRate", "proceeds", "trials", "subscriptions"],
+                    rows: storeRows,
+                });
+            if (sources?.length)
+                files.push({
+                    name: `${store}-traffic-sources`,
+                    about: `${label}: where product page views came from, ${from} to ${to} (replaced on every pull)`,
+                    key: ["source"],
+                    columns: ["source", "impressions", "pageViews", "share"],
+                    rows: sources,
+                });
+            if (adRows.length && store === "app-store")
+                files.push({
+                    name: "apple-search-ads",
+                    about: "Apple Search Ads: spend, impressions, taps and installs per day",
+                    key: ["date"],
+                    columns: ["date", "spend", "impressions", "taps", "installs", "currency"],
+                    rows: adRows,
+                });
+            if (rcRows.length && !files.some((f) => f.name === "revenuecat"))
+                files.push({
+                    name: "revenuecat",
+                    about: `RevenueCat: revenue, MRR, trials, new customers, trial conversion, churn and actives per day${rcScope === "project" ? " (the RevenueCat project holds other apps too, so these include them)" : ""}`,
+                    key: ["date"],
+                    columns: ["date", "revenue", "mrr", "trials", "newCustomers", "trialConversion", "churn", "actives"],
+                    rows: rcRows,
+                });
+        });
+    }
+    if (api && ids["app-store"]) {
+        await attempt("App Store Connect sales", async () => {
+            const m = await api.get(`/connect/metrics/apps/${encodeURIComponent(ids["app-store"])}`, { from, to });
+            if (m?.daily?.length)
+                files.push({
+                    name: "app-store-sales",
+                    about: "App Store Connect sales reports: units, revenue, subscriptions, trials and in-app purchases per day",
+                    key: ["date"],
+                    columns: ["date", "downloads", "revenue", "subscriptions", "trials", "iap_count"],
+                    rows: m.daily.map((d) => ({ ...d, date: String(d.metric_date) })),
+                });
+            if (m?.countries?.length)
+                files.push({
+                    name: "app-store-countries",
+                    about: `App Store Connect: downloads and revenue by country, ${from} to ${to} (replaced on every pull)`,
+                    key: ["country"],
+                    columns: ["country", "downloads", "revenue"],
+                    rows: m.countries,
+                });
+        });
+    }
+    // One set of files per Appeeky Analytics app; with an app per store, the store is in the name.
+    const attributionByStore = !attributionIn
+        ? []
+        : "get" in attributionIn
+            ? [["", attributionIn]]
+            : [...new Map(Object.entries(attributionIn).map(([store, client]) => [client, store])).entries()].map(([client, store]) => [store, client]);
+    for (const [store, attribution] of attributionByStore) {
+        const suffix = attributionByStore.length > 1 ? `-${store}` : "";
+        await attempt(attribution.label, async () => {
+            const summary = await attribution.get("summary", { days: String(Math.min(180, Math.max(1, days))) });
+            if (summary?.bySource?.length)
+                files.push({
+                    name: `attribution-sources${suffix}`,
+                    about: `Installs, trials, payers and revenue by source and campaign, for installs in the last ${summary.days} days (replaced on every pull)`,
+                    key: ["source", "campaign"],
+                    columns: ["source", "campaign", "installs", "trials", "payers", "revenueUsd"],
+                    rows: summary.bySource.map((r) => ({ ...r })),
+                });
+            for (const dim of ["keyword", "campaign", "country"]) {
+                const rows = await attribution.get("breakdown", { dim, range: "30d" });
+                const list = Array.isArray(rows) ? rows : (rows?.rows ?? []);
+                // Apple Search Ads reports keyword ids, not the words; the words are in your Search Ads account.
+                const column = dim === "keyword" ? "keywordId" : dim;
+                if (list.length)
+                    files.push({
+                        name: `attribution-${dim === "country" ? "countries" : `${dim}s`}${suffix}`,
+                        about: `Installs, payers and revenue by ${dim === "keyword" ? "Apple Search Ads keyword id" : dim === "campaign" ? "campaign ((none) is organic and other installs without one)" : dim}, last 30 days (replaced on every pull)`,
+                        key: [column],
+                        columns: [column, "installs", "payers", "revenueUsd"],
+                        rows: list.map((r) => ({ [column]: r.key ?? "(none)", installs: r.count, payers: r.payers, revenueUsd: r.revenueUsd })),
+                    });
+            }
+            const links = await attribution.get("links", { range: "30d" });
+            if (links?.links?.length)
+                files.push({
+                    name: `smart-links${suffix}`,
+                    about: "Smart links: clicks, installs and revenue per link, last 30 days (replaced on every pull)",
+                    key: ["slug"],
+                    columns: ["slug", "name", "campaign", "channel", "clicks", "installs", "revenueUsd"],
+                    rows: links.links.map((l) => ({ slug: l.link.slug, name: l.link.name, campaign: l.link.campaign, channel: l.link.channel, clicks: l.clicks.total, installs: l.installs, revenueUsd: l.revenueUsd })),
+                });
+        });
+    }
+    const meta = project.spec.ads.meta;
+    if (api && meta) {
+        await attempt("Meta Ads", async () => {
+            const rows = [];
+            for (const campaign of meta.campaigns) {
+                const data = await api.get("/connect/meta-ads/insights", {
+                    targetType: "campaign",
+                    targetId: campaign,
+                    since: from,
+                    until: to,
+                    timeIncrement: "1",
+                    fields: "spend,impressions,clicks,actions,date_start",
+                    ...(meta.adAccount ? { adAccountId: meta.adAccount } : {}),
+                });
+                for (const r of data?.data ?? []) {
+                    const installs = (r.actions ?? []).find((a) => ["mobile_app_install", "app_install", "omni_app_install"].includes(a.action_type));
+                    rows.push({ date: r.date_start, campaign, spend: Number(r.spend ?? 0), impressions: Number(r.impressions ?? 0), clicks: Number(r.clicks ?? 0), installs: Number(installs?.value ?? 0) });
+                }
+            }
+            if (rows.length)
+                files.push({ name: "meta-ads", about: "Meta Ads: spend, impressions, clicks and installs per campaign per day", key: ["date", "campaign"], columns: ["date", "campaign", "spend", "impressions", "clicks", "installs"], rows });
+        });
+    }
+    const tiktok = project.spec.ads.tiktok;
+    if (api && tiktok) {
+        await attempt("TikTok Ads", async () => {
+            const data = await api.get("/connect/tiktok-ads/report", {
+                dataLevel: "AUCTION_CAMPAIGN",
+                dimensions: "campaign_id,stat_time_day",
+                metrics: "spend,impressions,clicks,conversion",
+                startDate: from,
+                endDate: to,
+                pageSize: "1000",
+                ...(tiktok.advertiser ? { advertiserId: tiktok.advertiser } : {}),
+            });
+            const rows = (data?.list ?? [])
+                .filter((r) => r.dimensions?.campaign_id && tiktok.campaigns.includes(String(r.dimensions.campaign_id)))
+                .map((r) => ({
+                date: String(r.dimensions?.stat_time_day ?? "").slice(0, 10),
+                campaign: String(r.dimensions?.campaign_id),
+                spend: Number(r.metrics?.spend ?? 0),
+                impressions: Number(r.metrics?.impressions ?? 0),
+                clicks: Number(r.metrics?.clicks ?? 0),
+                conversions: Number(r.metrics?.conversion ?? 0),
+            }));
+            if (rows.length)
+                files.push({ name: "tiktok-ads", about: "TikTok Ads: spend, impressions, clicks and conversions per campaign per day", key: ["date", "campaign"], columns: ["date", "campaign", "spend", "impressions", "clicks", "conversions"], rows });
+        });
+    }
+    const dir = dataDir(project);
+    const written = [];
+    for (const f of files) {
+        // Range snapshots are replaced, daily series are merged.
+        if (!f.key.includes("date") && existsSync(join(dir, `${f.name}.csv`)))
+            await writeFile(join(dir, `${f.name}.csv`), "");
+        written.push({ name: f.name, about: f.about, ...(await mergeCsv(dir, f)) });
+    }
+    if (written.length)
+        await writeIndex(dir, written, now);
+    return { files: written, errors };
+}
+/** README.md next to the files: what each one holds, so an agent knows where to look. */
+async function writeIndex(dir, files, now) {
+    const lines = [
+        "# App data",
+        "",
+        `Pulled ${now.toISOString().slice(0, 10)} by \`appeeky-spec data pull\`. Daily files are merged by date on every pull. Do not edit by hand.`,
+        "",
+        "| file | rows | dates | what it holds |",
+        "| --- | --- | --- | --- |",
+        ...files.map((f) => `| ${f.name}.csv | ${f.rows} | ${f.from && f.to ? `${f.from} → ${f.to}` : "—"} | ${f.about} |`),
+        "",
+    ];
+    await writeFile(join(dir, "README.md"), lines.join("\n"));
+}
+//# sourceMappingURL=data.js.map

package/dist/diff.d.ts

@@ -0,0 +1,11 @@
+import { type Listing, type StoreId, type StoreListings } from "./schema.js";
+import type { FieldChange } from "./stores/types.js";
+/** Stores trim trailing whitespace and normalize line endings, so compare the same way. */
+export declare function normalizeValue(value: string | undefined | null): string | undefined;
+/**
+ * Field-level differences for the fields the spec manages. A locale or field
+ * that is only in the store is left alone: the spec owns what it lists.
+ */
+export declare function diffListings<L extends Listing>(store: StoreId, local: StoreListings<L>, remote: StoreListings<L>): FieldChange[];
+/** The inverse of a set of applied changes: what to push to go back. A field that was empty goes back to "" (cleared). */
+export declare function invertChanges(changes: FieldChange[]): FieldChange[];

package/dist/diff.js

@@ -0,0 +1,33 @@
+import { fieldsFor } from "./schema.js";
+/** Stores trim trailing whitespace and normalize line endings, so compare the same way. */
+export function normalizeValue(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    return value.replace(/\r\n?/g, "\n").replace(/[ \t]+$/gm, "").trimEnd();
+}
+/**
+ * Field-level differences for the fields the spec manages. A locale or field
+ * that is only in the store is left alone: the spec owns what it lists.
+ */
+export function diffListings(store, local, remote) {
+    const changes = [];
+    for (const [locale, listing] of Object.entries(local)) {
+        const live = remote[locale];
+        for (const field of fieldsFor(store)) {
+            const after = normalizeValue(listing[field]);
+            if (after === undefined)
+                continue;
+            const before = normalizeValue(live?.[field]);
+            // "" in the spec clears the field; empty and missing are the same.
+            if ((before ?? "") === after)
+                continue;
+            changes.push({ store, locale, field, before, after, newLocale: live === undefined });
+        }
+    }
+    return changes;
+}
+/** The inverse of a set of applied changes: what to push to go back. A field that was empty goes back to "" (cleared). */
+export function invertChanges(changes) {
+    return changes.map((c) => ({ ...c, before: c.after, after: c.before ?? "", newLocale: false, blocked: undefined }));
+}
+//# sourceMappingURL=diff.js.map

package/dist/experiments.d.ts

@@ -0,0 +1,115 @@
+import { z } from "zod";
+/**
+ * Anything you try to grow the app that is not a listing push: screenshots,
+ * a UGC hook, an ad creative, a price. Same shape as a release: a hypothesis,
+ * one metric, a baseline, a date to check, and a result.
+ * Listing pushes are experiments already (their release file holds the result).
+ */
+export declare const experimentSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<["screenshots", "ugc", "ads", "pricing", "other"]>;
+    hypothesis: z.ZodString;
+    /** Persona id from `personas:` in appeeky.spec.yaml. */
+    persona: z.ZodOptional<z.ZodString>;
+    store: z.ZodOptional<z.ZodEnum<["app-store", "google-play"]>>;
+    country: z.ZodOptional<z.ZodString>;
+    metric: z.ZodString;
+    baseline: z.ZodOptional<z.ZodNumber>;
+    /** Value that counts as a win, e.g. 2.5 for "install_per_1k_views > 2.5". */
+    target: z.ZodOptional<z.ZodNumber>;
+    startedAt: z.ZodString;
+    checkAfterDays: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodDefault<z.ZodEnum<["running", "won", "lost", "inconclusive"]>>;
+    result: z.ZodOptional<z.ZodObject<{
+        value: z.ZodOptional<z.ZodNumber>;
+        note: z.ZodOptional<z.ZodString>;
+        closedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        closedAt: string;
+        value?: number | undefined;
+        note?: string | undefined;
+    }, {
+        closedAt: string;
+        value?: number | undefined;
+        note?: string | undefined;
+    }>>;
+    /** The smart link that carries the experiment's traffic, so its installs and revenue are counted exactly. */
+    link: z.ZodOptional<z.ZodObject<{
+        slug: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+        store: z.ZodOptional<z.ZodEnum<["app-store", "google-play"]>>;
+    }, "strict", z.ZodTypeAny, {
+        slug: string;
+        url?: string | undefined;
+        store?: "app-store" | "google-play" | undefined;
+    }, {
+        slug: string;
+        url?: string | undefined;
+        store?: "app-store" | "google-play" | undefined;
+    }>>;
+    /** Links, file paths, ad ids: whatever ran. */
+    assets: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    type: "ads" | "screenshots" | "ugc" | "pricing" | "other";
+    status: "won" | "lost" | "running" | "inconclusive";
+    id: string;
+    hypothesis: string;
+    metric: string;
+    startedAt: string;
+    checkAfterDays: number;
+    assets: string[];
+    store?: "app-store" | "google-play" | undefined;
+    link?: {
+        slug: string;
+        url?: string | undefined;
+        store?: "app-store" | "google-play" | undefined;
+    } | undefined;
+    country?: string | undefined;
+    result?: {
+        closedAt: string;
+        value?: number | undefined;
+        note?: string | undefined;
+    } | undefined;
+    persona?: string | undefined;
+    baseline?: number | undefined;
+    target?: number | undefined;
+}, {
+    type: "ads" | "screenshots" | "ugc" | "pricing" | "other";
+    id: string;
+    hypothesis: string;
+    metric: string;
+    startedAt: string;
+    status?: "won" | "lost" | "running" | "inconclusive" | undefined;
+    store?: "app-store" | "google-play" | undefined;
+    link?: {
+        slug: string;
+        url?: string | undefined;
+        store?: "app-store" | "google-play" | undefined;
+    } | undefined;
+    country?: string | undefined;
+    result?: {
+        closedAt: string;
+        value?: number | undefined;
+        note?: string | undefined;
+    } | undefined;
+    persona?: string | undefined;
+    baseline?: number | undefined;
+    target?: number | undefined;
+    checkAfterDays?: number | undefined;
+    assets?: string[] | undefined;
+}>;
+export type Experiment = z.infer<typeof experimentSchema>;
+export type ExperimentInput = z.input<typeof experimentSchema>;
+export declare function experimentsDir(root: string): string;
+export declare function readExperiments(root: string): Promise<Experiment[]>;
+export declare function writeExperiment(root: string, input: ExperimentInput): Promise<Experiment>;
+export declare function experimentId(date: Date, hypothesis: string): string;
+/** Experiments whose check date has passed and that have no result yet. */
+export declare function dueExperiments(experiments: Experiment[], now?: Date): Experiment[];
+/**
+ * Close with a measured value. With a `target`, reaching it wins. Without
+ * one, a known metric (conversion, revenue, cpa, ...) is judged against the
+ * baseline: a 5% move the right way wins, the wrong way loses. Anything else
+ * is inconclusive.
+ */
+export declare function closeExperiment(e: Experiment, value: number | undefined, note: string | undefined, now?: Date): Experiment;

package/dist/experiments.js

@@ -0,0 +1,85 @@
+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";
+import { isMetricName, outcomeOf } from "./metrics.js";
+/**
+ * Anything you try to grow the app that is not a listing push: screenshots,
+ * a UGC hook, an ad creative, a price. Same shape as a release: a hypothesis,
+ * one metric, a baseline, a date to check, and a result.
+ * Listing pushes are experiments already (their release file holds the result).
+ */
+export const experimentSchema = z
+    .object({
+    id: z.string().regex(/^[a-z0-9-]+$/),
+    type: z.enum(["screenshots", "ugc", "ads", "pricing", "other"]),
+    hypothesis: z.string().min(1),
+    /** Persona id from `personas:` in appeeky.spec.yaml. */
+    persona: z.string().optional(),
+    store: z.enum(["app-store", "google-play"]).optional(),
+    country: z.string().optional(),
+    metric: z.string().min(1),
+    baseline: z.number().optional(),
+    /** Value that counts as a win, e.g. 2.5 for "install_per_1k_views > 2.5". */
+    target: z.number().optional(),
+    startedAt: z.string(),
+    checkAfterDays: z.number().int().positive().default(14),
+    status: z.enum(["running", "won", "lost", "inconclusive"]).default("running"),
+    result: z.object({ value: z.number().optional(), note: z.string().optional(), closedAt: z.string() }).optional(),
+    /** The smart link that carries the experiment's traffic, so its installs and revenue are counted exactly. */
+    link: z.object({ slug: z.string(), url: z.string().optional(), store: z.enum(["app-store", "google-play"]).optional() }).strict().optional(),
+    /** Links, file paths, ad ids: whatever ran. */
+    assets: z.array(z.string()).default([]),
+})
+    .strict();
+export function experimentsDir(root) {
+    return join(root, SPEC_DIR, "experiments");
+}
+export async function readExperiments(root) {
+    const dir = experimentsDir(root);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of (await readdir(dir)).filter((f) => f.endsWith(".yaml")).sort().reverse()) {
+        const parsed = experimentSchema.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);
+    }
+    return out;
+}
+export async function writeExperiment(root, input) {
+    const experiment = experimentSchema.parse(input);
+    await mkdir(experimentsDir(root), { recursive: true });
+    await writeFile(join(experimentsDir(root), `${experiment.id}.yaml`), YAML.stringify(experiment, { lineWidth: 0 }));
+    return experiment;
+}
+export function experimentId(date, hypothesis) {
+    const slug = hypothesis.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "experiment";
+    return `${date.toISOString().slice(0, 10)}-${slug}`;
+}
+/** Experiments whose check date has passed and that have no result yet. */
+export function dueExperiments(experiments, now = new Date()) {
+    return experiments.filter((e) => e.status === "running" && Date.parse(e.startedAt) + e.checkAfterDays * 86_400_000 <= now.getTime());
+}
+/**
+ * Close with a measured value. With a `target`, reaching it wins. Without
+ * one, a known metric (conversion, revenue, cpa, ...) is judged against the
+ * baseline: a 5% move the right way wins, the wrong way loses. Anything else
+ * is inconclusive.
+ */
+export function closeExperiment(e, value, note, now = new Date()) {
+    let status = "inconclusive";
+    if (value !== undefined && e.target !== undefined) {
+        const lowerIsBetter = isMetricName(e.metric) && outcomeOf(e.metric, -1) === "better";
+        status = (lowerIsBetter ? value <= e.target : value >= e.target) ? "won" : "lost";
+    }
+    else if (value !== undefined && e.baseline !== undefined && e.baseline > 0 && isMetricName(e.metric)) {
+        const outcome = outcomeOf(e.metric, value / e.baseline - 1);
+        status = outcome === "better" ? "won" : outcome === "worse" ? "lost" : "inconclusive";
+    }
+    return { ...e, status, result: { value, note, closedAt: now.toISOString() } };
+}
+//# sourceMappingURL=experiments.js.map

package/dist/files.d.ts

@@ -0,0 +1,27 @@
+import { type Listing, type Project, type SpecFile, type SpecFileInput, type StoreId } from "./schema.js";
+export declare const SPEC_FILE = "appeeky.spec.yaml";
+export declare const SPEC_DIR = "appeeky";
+export declare class SpecError extends Error {
+    readonly file?: string | undefined;
+    constructor(message: string, file?: string | undefined);
+}
+export declare function listingsDir(root: string, store: StoreId): string;
+export declare function listingPath(root: string, store: StoreId, locale: string): string;
+/** Walk up from `start` to the folder that holds `appeeky.spec.yaml`. */
+export declare function findRoot(start?: string): string | undefined;
+export declare function parseSpec(raw: unknown, file?: string): SpecFile;
+export declare function parseListing(store: StoreId, raw: unknown, file: string): Listing;
+/** Load the spec and every listing file under `appeeky/store/`. */
+export declare function loadProject(start?: string): Promise<Project>;
+/** Keep the store's field order and use block scalars for multi-line text so diffs stay readable. */
+export declare function stringifyListing(store: StoreId, listing: Listing): string;
+export declare function writeListing(root: string, store: StoreId, locale: string, listing: Listing): Promise<string>;
+export declare function stringifySpec(spec: SpecFileInput): string;
+export declare function writeSpec(root: string, spec: SpecFileInput): Promise<string>;
+/** Where each store's listing files were last pulled from, e.g. "version 3.0.1 (prepare for submission)". */
+export type PullState = Partial<Record<StoreId, {
+    target: string;
+    at: string;
+}>>;
+export declare function readPullState(root: string): Promise<PullState>;
+export declare function recordPull(root: string, store: StoreId, target: string): Promise<void>;