@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/dataforseo.js

@@ -0,0 +1,354 @@
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { seoDir } from "./seo.js";
+import { rankAppIds } from "./verify.js";
+export function readDataForSeo(env) {
+    const login = env.DATAFORSEO_LOGIN?.trim();
+    const password = env.DATAFORSEO_PASSWORD?.trim();
+    if (!login && !password)
+        return null;
+    if (!login || !password)
+        throw new Error("DataForSEO needs both DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD (from app.dataforseo.com → API access).");
+    return { login, password };
+}
+/** Rough prices for the quote, in USD; the real cost of every call is added up from the responses. */
+export const DFS_PRICE = { serp: 0.02, keywordOverview: 0.0101, related: 0.0135, domain: 0.0505 };
+const ISO_NUMERIC = {
+    ar: 32, at: 40, au: 36, be: 56, bg: 100, br: 76, ca: 124, ch: 756, cl: 152, cn: 156, co: 170, cz: 203, de: 276, dk: 208, ee: 233,
+    eg: 818, es: 724, fi: 246, fr: 250, gb: 826, gr: 300, hk: 344, hr: 191, hu: 348, id: 360, ie: 372, il: 376, in: 356, it: 380,
+    jp: 392, kr: 410, lt: 440, lv: 428, ma: 504, mx: 484, my: 458, ng: 566, nl: 528, no: 578, nz: 554, pe: 604, ph: 608, pk: 586,
+    pl: 616, pt: 620, ro: 642, rs: 688, ru: 643, sa: 682, se: 752, sg: 702, sk: 703, th: 764, tr: 792, tw: 158, ua: 804, us: 840,
+    vn: 704, za: 710,
+};
+const LANGUAGE = {
+    ar: "es", at: "de", br: "pt", ch: "de", cl: "es", cn: "zh-CN", co: "es", cz: "cs", de: "de", dk: "da", eg: "ar", es: "es", fi: "fi",
+    fr: "fr", gr: "el", hk: "zh-TW", hr: "hr", hu: "hu", id: "id", il: "he", it: "it", jp: "ja", kr: "ko", lt: "lt", lv: "lv", ma: "ar",
+    mx: "es", nl: "nl", no: "no", pe: "es", pl: "pl", pt: "pt", ro: "ro", rs: "sr", ru: "ru", sa: "ar", se: "sv", sk: "sk", th: "th",
+    tr: "tr", tw: "zh-TW", ua: "uk", vn: "vi",
+};
+/** Country-level location codes are 2000 + the ISO 3166-1 numeric code. */
+export const locationCode = (country) => 2000 + (ISO_NUMERIC[country.toLowerCase()] ?? 840);
+export const languageCode = (country) => LANGUAGE[country.toLowerCase()] ?? "en";
+/** POST one task to a DataForSEO live endpoint. HTTP 200 can still carry a failed task, so both are checked. */
+export async function dfsPost(auth, path, task, fetcher = fetch) {
+    const res = await fetcher(`https://api.dataforseo.com${path}`, {
+        method: "POST",
+        headers: { authorization: `Basic ${Buffer.from(`${auth.login}:${auth.password}`).toString("base64")}`, "content-type": "application/json" },
+        body: JSON.stringify([task]),
+        signal: AbortSignal.timeout(90_000),
+    });
+    if (res.status === 401)
+        throw new Error("DataForSEO: wrong login or password (DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD).");
+    const json = (await res.json().catch(() => null));
+    if (!res.ok || !json)
+        throw new Error(`DataForSEO: HTTP ${res.status}`);
+    const t = json.tasks?.[0];
+    if (!t)
+        throw new Error(`DataForSEO: ${json.status_code} ${json.status_message}`);
+    if (t.status_code !== 20000 && t.status_code !== 20100) {
+        if (t.status_code === 40200 || /payment|balance|funds/i.test(t.status_message))
+            throw new Error(`DataForSEO: ${t.status_message.replace(/\.$/, "")}. Add funds at app.dataforseo.com.`);
+        throw new Error(`DataForSEO: ${t.status_code} ${t.status_message}`);
+    }
+    return { results: t.result ?? [], cost: json.cost ?? 0 };
+}
+const r2 = (n) => Math.round(n * 100) / 100;
+const r4 = (n) => Math.round(n * 10_000) / 10_000;
+const day = (d) => d.toISOString().slice(0, 10);
+const cell = (v) => (v === null || v === undefined ? "" : typeof v === "string" && /[",\n]/.test(v) ? `"${v.replace(/"/g, '""')}"` : String(v));
+const pipe = (s) => s.replace(/\|/g, "\\|");
+export function bareDomain(hostOrUrl) {
+    let host = hostOrUrl.trim().toLowerCase();
+    try {
+        if (/^[a-z]+:\/\//.test(host))
+            host = new URL(host).hostname;
+    }
+    catch {
+        // keep as is
+    }
+    return host.replace(/^www\./, "").replace(/\/.*$/, "");
+}
+const sameSite = (domain, own) => domain === own || domain.endsWith(`.${own}`);
+/** The keywords to watch per storefront: web.keywords, else the store targets. */
+export function webKeywords(project) {
+    const own = project.spec.web?.keywords;
+    const out = {};
+    const countries = project.spec.web?.countries ?? Object.keys(own ?? {}).concat(Object.keys(project.spec.targets)).filter((c, i, a) => a.indexOf(c) === i).slice(0, 1);
+    for (const cc of countries) {
+        const list = own?.[cc] ?? project.spec.targets[cc] ?? [];
+        if (list.length)
+            out[cc] = [...new Set(list.map((k) => k.trim().toLowerCase()).filter(Boolean))];
+    }
+    return out;
+}
+export function siteDomain(project) {
+    const url = project.spec.web?.url;
+    if (!url)
+        throw new Error("Set web.url in appeeky.spec.yaml first.");
+    return bareDomain(url);
+}
+export function readSerp(items, own, storePatterns) {
+    const organic = items.filter((i) => i.type === "organic" && i.url);
+    const pos = (i) => i.rank_group ?? i.rank_absolute ?? 999;
+    const mine = organic.filter((i) => sameSite(bareDomain(i.domain ?? i.url), own)).sort((a, b) => pos(a) - pos(b))[0];
+    const store = organic.filter((i) => storePatterns.some((p) => p.test(i.url))).sort((a, b) => pos(a) - pos(b))[0];
+    const block = items.find((i) => i.type === "ai_overview");
+    const cited = new Set();
+    for (const ref of [...(block?.references ?? []), ...(block?.items ?? []).flatMap((x) => x.references ?? [])]) {
+        const d = ref.domain ?? ref.url;
+        if (d)
+            cited.add(bareDomain(d));
+    }
+    const top = [...new Set(organic.sort((a, b) => pos(a) - pos(b)).map((i) => bareDomain(i.domain ?? i.url)))].slice(0, 3);
+    return {
+        position: mine ? pos(mine) : null,
+        ...(mine?.url ? { url: mine.url } : {}),
+        storePosition: store ? pos(store) : null,
+        aiOverview: Boolean(block),
+        aiCitesYou: [...cited].some((d) => sameSite(d, own)),
+        aiCited: [...cited].slice(0, 8),
+        top,
+    };
+}
+export const ranksFile = (root) => join(seoDir(root), "ranks.csv");
+const RANKS_HEADER = "date,country,keyword,position,url,store_position,ai_overview,ai_cites_you\n";
+async function readRanks(root) {
+    if (!existsSync(ranksFile(root)))
+        return [];
+    return (await readFile(ranksFile(root), "utf8"))
+        .split("\n")
+        .slice(1)
+        .filter(Boolean)
+        .map((l) => {
+        const parts = l.match(/("([^"]|"")*"|[^,]*)(,|$)/g).map((p) => p.replace(/,$/, "").replace(/^"|"$/g, "").replace(/""/g, '"'));
+        return { date: parts[0], country: parts[1], keyword: parts[2], position: parts[3] ? Number(parts[3]) : null, aiOverview: parts[6] === "yes", aiCitesYou: parts[7] === "yes" };
+    });
+}
+export async function daysSinceRanks(root, now = new Date()) {
+    const last = (await readRanks(root)).map((r) => r.date).sort().at(-1);
+    return last ? Math.floor((now.getTime() - Date.parse(last)) / 86_400_000) : null;
+}
+/** One Google results page per keyword and storefront, read like a person on a phone sees it. */
+export async function pullRanks(project, auth, options = {}) {
+    const own = siteDomain(project);
+    const ids = rankAppIds(project);
+    const storePatterns = [
+        ...(ids["app-store"] ? [new RegExp(`apps\\.apple\\.com/.*id${ids["app-store"]}`)] : []),
+        ...(ids["google-play"] ? [new RegExp(`play\\.google\\.com/store/apps/details\\?id=${ids["google-play"].replace(/\./g, "\\.")}`)] : []),
+    ];
+    const device = project.spec.web?.device ?? "mobile";
+    const now = options.now ?? new Date();
+    const date = day(now);
+    const ranks = [];
+    const errors = [];
+    let cost = 0;
+    for (const [country, keywords] of Object.entries(webKeywords(project))) {
+        for (const keyword of keywords) {
+            try {
+                const { results, cost: c } = await dfsPost(auth, "/v3/serp/google/organic/live/advanced", { keyword, location_code: locationCode(country), language_code: languageCode(country), device, os: device === "mobile" ? "ios" : "macos", depth: 100, load_async_ai_overview: true, group_organic_results: true }, options.fetcher);
+                cost += c;
+                ranks.push({ country, keyword, ...readSerp(results[0]?.items ?? [], own, storePatterns) });
+            }
+            catch (e) {
+                errors.push(`${country.toUpperCase()} "${keyword}": ${e.message}`);
+                if (/wrong login|Add funds/.test(e.message))
+                    break;
+            }
+            options.log?.(`${ranks.length + errors.length} keywords`);
+        }
+    }
+    const dir = seoDir(project.root);
+    await mkdir(dir, { recursive: true });
+    const prev = await readRanks(project.root);
+    const lastDate = prev.map((r) => r.date).filter((d) => d < date).sort().at(-1);
+    const before = new Map(prev.filter((r) => r.date === lastDate).map((r) => [`${r.country}\u0000${r.keyword}`, r]));
+    const changes = [];
+    for (const r of ranks) {
+        const was = before.get(`${r.country}\u0000${r.keyword}`);
+        if (!was)
+            continue;
+        const label = `${r.country.toUpperCase()} "${r.keyword}"`;
+        const top10 = (p) => p !== null && p <= 10;
+        if (top10(r.position) && !top10(was.position))
+            changes.push(`${label}: into the top 10 (${was.position ?? "not ranked"} → ${r.position})`);
+        if (!top10(r.position) && top10(was.position))
+            changes.push(`${label}: out of the top 10 (${was.position} → ${r.position ?? "not ranked"})`);
+        if (r.aiCitesYou && !was.aiCitesYou)
+            changes.push(`${label}: Google's AI Overview now cites the site`);
+        if (!r.aiCitesYou && was.aiCitesYou)
+            changes.push(`${label}: Google's AI Overview stopped citing the site`);
+    }
+    if (!existsSync(ranksFile(project.root)))
+        await writeFile(ranksFile(project.root), RANKS_HEADER);
+    // One snapshot a day: a second run the same day replaces the first.
+    if (prev.some((r) => r.date === date)) {
+        const kept = (await readFile(ranksFile(project.root), "utf8")).split("\n").filter((l, i) => i === 0 || (l && !l.startsWith(`${date},`)));
+        await writeFile(ranksFile(project.root), kept.join("\n") + "\n");
+    }
+    const yes = (b) => (b ? "yes" : "no");
+    if (ranks.length)
+        await appendFile(ranksFile(project.root), ranks.map((r) => [date, r.country, cell(r.keyword), r.position ?? "", cell(r.url ?? ""), r.storePosition ?? "", yes(r.aiOverview), yes(r.aiCitesYou)].join(",")).join("\n") + "\n");
+    const ranked = ranks.filter((r) => r.position !== null);
+    const md = [
+        "# Google ranks",
+        "",
+        `Written by \`seo ranks\` from DataForSEO, ${date}, ${device}. ${own}: ${ranked.length} of ${ranks.length} keywords in the top 100, ${ranks.filter((r) => r.position !== null && r.position <= 10).length} in the top 10. Google's AI Overview shows for ${ranks.filter((r) => r.aiOverview).length} and cites the site for ${ranks.filter((r) => r.aiCitesYou).length}.`,
+        "",
+        "| keyword | site | store page | AI Overview | top 3 |",
+        "| --- | --- | --- | --- | --- |",
+        ...ranks.map((r) => `| ${r.country.toUpperCase()} ${pipe(r.keyword)} | ${r.position ?? "—"} | ${r.storePosition ?? "—"} | ${r.aiOverview ? (r.aiCitesYou ? "cites you" : `cites ${r.aiCited.slice(0, 3).join(", ") || "no one"}`) : "—"} | ${r.top.join(", ")} |`),
+        "",
+        "`site` is the best position of a page on the site, `store page` is where the app's App Store or Google Play page ranks on Google.",
+        "",
+    ].join("\n");
+    await writeFile(join(dir, "ranks.md"), md);
+    if (changes.length) {
+        const file = join(dir, "changes.md");
+        const old = existsSync(file) ? await readFile(file, "utf8") : "# Google changes\n\nWritten by `seo ranks`: keywords that entered or left the top 10, and AI Overview citations.\n";
+        const [head, ...rest] = old.split(/\n(?=- )/);
+        await writeFile(file, [head.trimEnd(), "", ...changes.map((c) => `- ${date} · ${c}`), ...rest.map((r) => r.trimEnd())].join("\n") + "\n");
+    }
+    return { ranks, costUsd: r4(cost), changes, errors };
+}
+/** `web_rank` (average position, 101 for not ranked) and `ai_overview_citations` (share of keywords) per scan day. */
+export function webRankMetricSource(root) {
+    if (!existsSync(ranksFile(root)))
+        return null;
+    let rows;
+    return {
+        label: "Google ranks in the repo",
+        async window(_store, _appId, from, to) {
+            rows ??= readRanks(root);
+            const inside = (await rows).filter((r) => r.date >= from && r.date < to);
+            if (inside.length === 0)
+                return null;
+            const days = Math.max(1, Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000));
+            const values = {
+                web_rank: inside.reduce((n, r) => n + (r.position ?? 101), 0) / inside.length,
+                ai_overview_citations: inside.filter((r) => r.aiCitesYou).length / inside.length,
+            };
+            return { from, to, days, values };
+        },
+    };
+}
+function flat(item) {
+    const n = item.keyword_data;
+    return {
+        keyword: (n?.keyword ?? item.keyword ?? "").toLowerCase(),
+        volume: n?.keyword_info?.search_volume ?? item.keyword_info?.search_volume ?? null,
+        cpc: n?.keyword_info?.cpc ?? item.keyword_info?.cpc ?? null,
+        difficulty: n?.keyword_properties?.keyword_difficulty ?? item.keyword_properties?.keyword_difficulty ?? null,
+        intent: n?.search_intent_info?.main_intent ?? item.search_intent_info?.main_intent ?? null,
+        position: item.ranked_serp_element?.serp_item?.rank_group ?? null,
+        url: item.ranked_serp_element?.serp_item?.url ?? null,
+        traffic: item.ranked_serp_element?.serp_item?.etv ?? null,
+    };
+}
+/** Volume, difficulty, CPC and intent for the watched keywords, and related ideas from the first few. */
+export async function pullKeywords(project, auth, options = {}) {
+    const rows = [];
+    let cost = 0;
+    for (const [country, keywords] of Object.entries(webKeywords(project))) {
+        const base = { location_code: locationCode(country), language_code: languageCode(country) };
+        const overview = await dfsPost(auth, "/v3/dataforseo_labs/google/keyword_overview/live", { ...base, keywords: keywords.slice(0, 700) }, options.fetcher);
+        cost += overview.cost;
+        const seen = new Set();
+        const got = new Map((overview.results[0]?.items ?? []).map((i) => [flat(i).keyword, flat(i)]));
+        for (const k of keywords) {
+            const f = got.get(k);
+            seen.add(k);
+            rows.push({ country, keyword: k, volume: f?.volume ?? null, difficulty: f?.difficulty ?? null, cpc: f?.cpc ?? null, intent: f?.intent ?? null, tracked: true });
+        }
+        for (const seed of keywords.slice(0, options.seeds ?? 3)) {
+            const related = await dfsPost(auth, "/v3/dataforseo_labs/google/related_keywords/live", { ...base, keyword: seed, depth: 1, limit: 50, order_by: ["keyword_data.keyword_info.search_volume,desc"] }, options.fetcher);
+            cost += related.cost;
+            for (const i of related.results[0]?.items ?? []) {
+                const f = flat(i);
+                if (!f.keyword || seen.has(f.keyword))
+                    continue;
+                seen.add(f.keyword);
+                rows.push({ country, keyword: f.keyword, volume: f.volume, difficulty: f.difficulty, cpc: f.cpc, intent: f.intent, tracked: false });
+            }
+        }
+    }
+    const dir = seoDir(project.root);
+    await mkdir(dir, { recursive: true });
+    const sorted = [...rows].sort((a, b) => Number(b.tracked) - Number(a.tracked) || (b.volume ?? -1) - (a.volume ?? -1));
+    await writeFile(join(dir, "keywords.csv"), `country,keyword,volume,difficulty,cpc,intent,tracked\n${sorted.map((r) => [r.country, cell(r.keyword), r.volume ?? "", r.difficulty ?? "", r.cpc ?? "", r.intent ?? "", r.tracked ? "yes" : "no"].join(",")).join("\n")}\n`);
+    return { rows: sorted, costUsd: r4(cost) };
+}
+const PLATFORMS = /(^|\.)(google\.|apple\.com$|youtube\.com$|wikipedia\.org$|facebook\.com$|reddit\.com$|amazon\.|linkedin\.com$|twitter\.com$|x\.com$|instagram\.com$|tiktok\.com$|medium\.com$|github\.com$)/;
+/** What the site ranks for in the first storefront, and the sites that rank for the same searches. */
+export async function pullDomain(project, auth, options = {}) {
+    const domain = siteDomain(project);
+    const country = Object.keys(webKeywords(project))[0] ?? Object.keys(project.spec.targets)[0] ?? "us";
+    const target = { target: domain, location_code: locationCode(country), language_code: languageCode(country) };
+    let cost = 0;
+    const overview = await dfsPost(auth, "/v3/dataforseo_labs/google/domain_rank_overview/live", target, options.fetcher);
+    cost += overview.cost;
+    const o = overview.results[0]?.items?.[0]?.metrics?.organic ?? {};
+    const ranked = await dfsPost(auth, "/v3/dataforseo_labs/google/ranked_keywords/live", { ...target, limit: 100, order_by: ["ranked_serp_element.serp_item.etv,desc"] }, options.fetcher);
+    cost += ranked.cost;
+    const competitors = await dfsPost(auth, "/v3/dataforseo_labs/google/competitors_domain/live", { ...target, limit: 30 }, options.fetcher);
+    cost += competitors.cost;
+    const report = {
+        domain,
+        country,
+        keywords: o.count ?? 0,
+        traffic: Math.round(o.etv ?? 0),
+        top3: (o.pos_1 ?? 0) + (o.pos_2_3 ?? 0),
+        top10: (o.pos_1 ?? 0) + (o.pos_2_3 ?? 0) + (o.pos_4_10 ?? 0),
+        ranked: (ranked.results[0]?.items ?? []).map((i) => {
+            const f = flat(i);
+            return { keyword: f.keyword, position: f.position, volume: f.volume, url: f.url, traffic: f.traffic === null ? null : Math.round(f.traffic) };
+        }),
+        competitors: (competitors.results[0]?.items ?? [])
+            .filter((c) => c.domain && bareDomain(c.domain) !== domain && !PLATFORMS.test(bareDomain(c.domain)))
+            .slice(0, 10)
+            .map((c) => ({ domain: bareDomain(c.domain), common: c.intersections ?? 0, avgPosition: c.avg_position === undefined ? null : r2(c.avg_position) })),
+    };
+    const dir = seoDir(project.root);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "ranked-keywords.csv"), `keyword,position,volume,traffic,url\n${report.ranked.map((r) => [cell(r.keyword), r.position ?? "", r.volume ?? "", r.traffic ?? "", cell(r.url ?? "")].join(",")).join("\n")}${report.ranked.length ? "\n" : ""}`);
+    const targets = new Set(Object.values(project.spec.targets).flat().map((t) => t.toLowerCase()));
+    const md = [
+        "# The site in Google",
+        "",
+        `Written by \`seo domain\` from DataForSEO for ${domain} in ${country.toUpperCase()}.`,
+        "",
+        `- Ranks for ${report.keywords} keywords: ${report.top3} in the top 3, ${report.top10} in the top 10`,
+        `- Estimated organic visits a month: ${report.traffic}`,
+        "",
+        "## Top keywords",
+        "",
+        "| keyword | position | volume | store target |",
+        "| --- | --- | --- | --- |",
+        ...(report.ranked.length ? report.ranked.slice(0, 20).map((r) => `| ${pipe(r.keyword)} | ${r.position ?? "—"} | ${r.volume ?? "—"} | ${targets.has(r.keyword) ? "yes" : ""} |`) : ["| none yet | | | |"]),
+        "",
+        "## Sites that rank for the same searches",
+        "",
+        "| domain | shared keywords | their average position |",
+        "| --- | --- | --- |",
+        ...(report.competitors.length ? report.competitors.map((c) => `| ${c.domain} | ${c.common} | ${c.avgPosition ?? "—"} |`) : ["| none found | | |"]),
+        "",
+    ].join("\n");
+    await writeFile(join(dir, "domain.md"), md);
+    return { report, costUsd: r4(cost) };
+}
+/** USD before anything is asked. */
+export function quoteSeo(project, what, seeds = 3) {
+    const sets = Object.values(webKeywords(project));
+    if (what === "ranks")
+        return r2(sets.reduce((n, k) => n + k.length, 0) * DFS_PRICE.serp);
+    if (what === "keywords")
+        return r2(sets.reduce((n, k) => n + DFS_PRICE.keywordOverview + Math.min(seeds, k.length) * DFS_PRICE.related, 0));
+    return r2(DFS_PRICE.domain);
+}
+/** For tests and callers that only want the latest snapshot. */
+export async function latestRanks(root) {
+    const rows = await readRanks(root);
+    const last = rows.map((r) => r.date).sort().at(-1);
+    return rows.filter((r) => r.date === last);
+}
+//# sourceMappingURL=dataforseo.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" | "ugc" | "screenshots" | "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;
+    target?: number | undefined;
+    baseline?: number | undefined;
+}, {
+    type: "ads" | "ugc" | "screenshots" | "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;
+    target?: number | undefined;
+    baseline?: 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>;