@appeeky/spec 0.0.0-stage → 0.1.0

package/dist/metrics.js

@@ -0,0 +1,250 @@
+/**
+ * Business outcomes of a change, beyond search ranks: conversion, downloads,
+ * revenue, trials and paid installs. They come from the store analytics,
+ * Apple Search Ads and RevenueCat data a user has connected in Appeeky
+ * (`GET /v1/user/apps/:appId/metrics`), so they need APPEEKY_API_KEY.
+ */
+export const METRICS = {
+    conversion: { label: "conversion", kind: "rate", better: "up" },
+    page_views: { label: "page views/day", kind: "count", better: "up" },
+    downloads: { label: "downloads/day", kind: "count", better: "up" },
+    proceeds: { label: "proceeds/day", kind: "money", better: "up" },
+    trials: { label: "trials/day", kind: "count", better: "up" },
+    revenue: { label: "revenue/day", kind: "money", better: "up" },
+    rc_trials: { label: "RevenueCat trials/day", kind: "count", better: "up" },
+    trial_conversion: { label: "trial conversion", kind: "rate", better: "up" },
+    ad_installs: { label: "ad installs/day", kind: "count", better: "up" },
+    cpa: { label: "cost per ad install", kind: "money", better: "down" },
+    rating: { label: "average rating", kind: "count", better: "up" },
+    organic_installs: { label: "organic installs/day", kind: "count", better: "up" },
+    organic_revenue: { label: "organic revenue/day", kind: "money", better: "up" },
+    organic_paid: { label: "organic installs that paid", kind: "rate", better: "up" },
+    link_clicks: { label: "clicks on the experiment's link", kind: "count", better: "up" },
+    link_installs: { label: "installs from the experiment's link", kind: "count", better: "up" },
+    link_revenue: { label: "revenue from the experiment's link", kind: "money", better: "up" },
+    low_ratings: { label: "1–2 star reviews", kind: "rate", better: "down" },
+    meta_spend: { label: "Meta spend/day", kind: "money", better: "down" },
+    meta_installs: { label: "Meta installs/day", kind: "count", better: "up" },
+    meta_cpi: { label: "Meta cost per install", kind: "money", better: "down" },
+    tiktok_spend: { label: "TikTok spend/day", kind: "money", better: "down" },
+    tiktok_conversions: { label: "TikTok conversions/day", kind: "count", better: "up" },
+    tiktok_cpa: { label: "TikTok cost per conversion", kind: "money", better: "down" },
+    ai_visibility: { label: "AI answers that name the app", kind: "rate", better: "up" },
+    category_rank: { label: "category rank", kind: "count", better: "down" },
+};
+export function isMetricName(name) {
+    return name in METRICS;
+}
+/** Below this many product page views in a window, a conversion rate is noise. */
+export const MIN_PAGE_VIEWS = 50;
+const sum = (xs) => xs.reduce((n, x) => n + (x ?? 0), 0);
+const known = (xs) => xs.filter((x) => x !== null && x !== undefined);
+/**
+ * Sum one API response into a window. RevenueCat numbers are only used when
+ * the RevenueCat project holds just this app; project-wide numbers would
+ * credit a listing change with another app's revenue.
+ */
+export function summarizeMetrics(data, from, to) {
+    const values = {};
+    const store = data.store?.days ?? [];
+    const days = Math.max(1, Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000));
+    if (store.length > 0) {
+        const pageViews = sum(store.map((d) => d.pageViews));
+        const downloads = sum(store.map((d) => d.downloads));
+        if (known(store.map((d) => d.pageViews)).length)
+            values.page_views = pageViews / days;
+        if (known(store.map((d) => d.downloads)).length)
+            values.downloads = downloads / days;
+        if (pageViews >= MIN_PAGE_VIEWS)
+            values.conversion = downloads / pageViews;
+        if (known(store.map((d) => d.proceeds)).length)
+            values.proceeds = sum(store.map((d) => d.proceeds)) / days;
+        if (known(store.map((d) => d.trials)).length)
+            values.trials = sum(store.map((d) => d.trials)) / days;
+    }
+    const ads = data.ads?.days ?? [];
+    if (ads.length > 0) {
+        const installs = sum(ads.map((d) => d.installs));
+        values.ad_installs = installs / days;
+        if (installs > 0)
+            values.cpa = sum(ads.map((d) => d.spend)) / installs;
+    }
+    const rc = data.revenuecat?.scope === "app" ? data.revenuecat.days : [];
+    if (rc.length > 0) {
+        if (known(rc.map((d) => d.revenue)).length)
+            values.revenue = sum(rc.map((d) => d.revenue)) / days;
+        if (known(rc.map((d) => d.trials)).length)
+            values.rc_trials = sum(rc.map((d) => d.trials)) / days;
+        const tc = known(rc.map((d) => d.trialConversion));
+        if (tc.length)
+            values.trial_conversion = tc.reduce((a, b) => a + b, 0) / tc.length;
+    }
+    const currency = data.revenuecat?.currency ?? data.ads?.currency ?? undefined;
+    return { from, to, days, values, ...(currency ? { currency } : {}) };
+}
+/** Changes smaller than this are noise. */
+export const FLAT_WITHIN = 0.05;
+export function outcomeOf(metric, change, noise = 0) {
+    if (Math.abs(change) < Math.max(FLAT_WITHIN, noise))
+        return "flat";
+    const up = change > 0;
+    return METRICS[metric].better === "up" ? (up ? "better" : "worse") : up ? "worse" : "better";
+}
+/**
+ * What a listing change is for: more people finding the app and paying. Organic numbers
+ * (from attribution) come first; without them, store conversion, then downloads, then
+ * the category rank (public, so it is there even without connected analytics).
+ */
+const LISTING_OUTCOMES = [["organic_installs", "organic_revenue"], ["conversion"], ["downloads"], ["category_rank"]];
+/**
+ * A verdict from outcomes, for a release whose ranks did not move (or that has no
+ * targets): won when the listing outcomes got better, lost when worse.
+ */
+export function outcomeVerdict(changes) {
+    for (const group of LISTING_OUTCOMES) {
+        const found = changes.filter((c) => group.includes(c.metric));
+        if (found.length === 0)
+            continue;
+        const better = found.filter((c) => c.outcome === "better").length;
+        const worse = found.filter((c) => c.outcome === "worse").length;
+        const verdict = better && !worse ? "won" : worse && !better ? "lost" : better && worse ? "mixed" : "flat";
+        return { verdict, by: found.map((c) => c.metric) };
+    }
+    return null;
+}
+/** Every metric present in both windows, with a usable before value. */
+export function compareWindows(before, after, noise = {}) {
+    const out = [];
+    for (const metric of Object.keys(METRICS)) {
+        const b = before.values[metric];
+        const a = after.values[metric];
+        if (b === undefined || a === undefined || b <= 0)
+            continue;
+        const change = a / b - 1;
+        const band = noise[metric];
+        out.push({ metric, before: b, after: a, change, outcome: outcomeOf(metric, change, band), ...(band !== undefined ? { noise: band } : {}) });
+    }
+    return out;
+}
+/** Past windows used to learn how much each metric moves on its own. */
+export const NOISE_WINDOWS = 4;
+/**
+ * Twice the spread of window-to-window changes over consecutive past windows, per metric:
+ * roughly the range a metric moves in with nothing changed. Needs three or more changes.
+ */
+export function noiseBands(windows) {
+    const out = {};
+    for (const metric of Object.keys(METRICS)) {
+        const changes = [];
+        for (let i = 1; i < windows.length; i++) {
+            const b = windows[i - 1].values[metric];
+            const a = windows[i].values[metric];
+            if (b !== undefined && a !== undefined && b > 0)
+                changes.push(a / b - 1);
+        }
+        if (changes.length < 3)
+            continue;
+        const mean = changes.reduce((s, x) => s + x, 0) / changes.length;
+        const sd = Math.sqrt(changes.reduce((s, x) => s + (x - mean) ** 2, 0) / (changes.length - 1));
+        out[metric] = Math.round(2 * sd * 1000) / 1000;
+    }
+    return out;
+}
+/** Meta counts an app install under one of these action types, depending on how the campaign is set up. */
+const META_INSTALL_ACTIONS = ["mobile_app_install", "app_install", "omni_app_install"];
+const num = (v) => {
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) ? n : 0;
+};
+/** Spend and installs of the given Meta campaigns' insights rows, per day. */
+export function summarizeMeta(rows, days) {
+    if (rows.length === 0)
+        return {};
+    const spend = rows.reduce((n, r) => n + num(r.spend), 0);
+    const installs = rows.reduce((n, r) => {
+        const actions = r.actions ?? [];
+        // Take the first install type present so one install is not counted twice.
+        const type = META_INSTALL_ACTIONS.find((t) => actions.some((a) => a.action_type === t));
+        return n + (type ? num(actions.find((a) => a.action_type === type)?.value) : 0);
+    }, 0);
+    const values = { meta_spend: spend / days, meta_installs: installs / days };
+    if (installs > 0)
+        values.meta_cpi = spend / installs;
+    return values;
+}
+/** Spend and conversions of the given TikTok campaigns, per day. Rows for other campaigns are left out. */
+export function summarizeTikTok(rows, campaigns, days) {
+    const mine = rows.filter((r) => r.dimensions?.campaign_id && campaigns.includes(String(r.dimensions.campaign_id)));
+    if (mine.length === 0)
+        return {};
+    const spend = mine.reduce((n, r) => n + num(r.metrics?.spend), 0);
+    const conversions = mine.reduce((n, r) => n + num(r.metrics?.conversion), 0);
+    const values = { tiktok_spend: spend / days, tiktok_conversions: conversions / days };
+    if (conversions > 0)
+        values.tiktok_cpa = spend / conversions;
+    return values;
+}
+/**
+ * Several sources as one: each window merges the values every source has.
+ * A source that fails or has no data is skipped, so one broken connection
+ * does not hide the others.
+ */
+export function combineSources(sources) {
+    return {
+        label: sources.map((s) => s.label).join(", "),
+        async window(store, appId, from, to) {
+            const windows = await Promise.all(sources.map((s) => s.window(store, appId, from, to).catch(() => null)));
+            const found = windows.filter((w) => w !== null);
+            if (found.length === 0)
+                return null;
+            const currency = found.find((w) => w.currency)?.currency;
+            return {
+                from,
+                to,
+                days: found[0].days,
+                values: Object.assign({}, ...found.map((w) => w.values)),
+                ...(currency ? { currency } : {}),
+            };
+        },
+    };
+}
+const iso = (ms) => new Date(ms).toISOString().slice(0, 10);
+/** Compare the `days` before a moment (a push, an experiment start) with the `days` after it. */
+export async function measureAround(source, store, appId, at, days) {
+    const t = Date.parse(at);
+    const span = Math.max(1, days) * 86_400_000;
+    // The day of the change itself is mixed, so it is in neither window.
+    const before = await source.window(store, appId, iso(t - span), iso(t));
+    const after = await source.window(store, appId, iso(t + 86_400_000), iso(t + 86_400_000 + span));
+    if (!before || !after)
+        return null;
+    // The windows before `before`, oldest first, to learn each metric's usual move.
+    const past = [];
+    for (let k = NOISE_WINDOWS; k >= 1; k--) {
+        const w = await source.window(store, appId, iso(t - (k + 1) * span), iso(t - k * span)).catch(() => null);
+        if (w)
+            past.push(w);
+    }
+    const changes = compareWindows(before, after, noiseBands([...past, before]));
+    return changes.length > 0 ? { source: source.label, before, after, changes } : null;
+}
+/** One metric's average over the `days` before a moment, for an experiment baseline. */
+export async function metricBefore(source, store, appId, metric, at, days) {
+    const t = Date.parse(at);
+    const window = await source.window(store, appId, iso(t - Math.max(1, days) * 86_400_000), iso(t));
+    return window?.values[metric];
+}
+/** One metric's average over the `days` from a moment on, for an experiment result. */
+export async function metricAfter(source, store, appId, metric, at, days) {
+    const t = Date.parse(at);
+    const window = await source.window(store, appId, iso(t), iso(t + Math.max(1, days) * 86_400_000));
+    return window?.values[metric];
+}
+/** "conversion 3.1% → 3.6% (+16%)", "revenue/day $41.20 → $47.90 (+16%)" */
+export function formatChange(c, currency) {
+    const { kind, label } = METRICS[c.metric];
+    const fmt = (v) => kind === "rate" ? `${(v * 100).toFixed(1)}%` : kind === "money" ? `${currency && currency !== "USD" ? `${currency} ` : "$"}${v.toFixed(2)}` : v >= 10 ? v.toFixed(0) : v.toFixed(1);
+    const pct = `${c.change >= 0 ? "+" : ""}${(c.change * 100).toFixed(0)}%`;
+    return `${label} ${fmt(c.before)} → ${fmt(c.after)} (${pct})`;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/output.d.ts

@@ -0,0 +1,21 @@
+import type { StorefrontCoverage } from "./coverage.js";
+import type { Issue } from "./lint.js";
+import type { FieldChange } from "./stores/types.js";
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    red: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    cyan: (s: string) => string;
+};
+export declare function printJson(value: unknown): void;
+declare const STORE_LABEL: {
+    readonly "app-store": "App Store";
+    readonly "google-play": "Google Play";
+};
+export declare const storeLabel: (s: keyof typeof STORE_LABEL) => "App Store" | "Google Play";
+export declare function formatIssues(issues: Issue[]): string;
+export declare function formatChanges(changes: FieldChange[]): string;
+export declare function formatCoverage(reports: StorefrontCoverage[]): string;
+export {};

package/dist/output.js

@@ -0,0 +1,79 @@
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (useColor ? `\u001b[${code}m${s}\u001b[0m` : s);
+export const c = {
+    bold: wrap(1),
+    dim: wrap(2),
+    red: wrap(31),
+    green: wrap(32),
+    yellow: wrap(33),
+    cyan: wrap(36),
+};
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+const STORE_LABEL = { "app-store": "App Store", "google-play": "Google Play" };
+export const storeLabel = (s) => STORE_LABEL[s];
+export function formatIssues(issues) {
+    if (issues.length === 0)
+        return c.green("No issues.");
+    const icon = { error: c.red("error"), warning: c.yellow("warn "), info: c.cyan("info ") };
+    return issues
+        .map((i) => `${icon[i.severity]}  ${c.dim(`${storeLabel(i.store)} ${i.locale}${i.field ? ` ${i.field}` : ""}`)}  ${i.message} ${c.dim(`(${i.rule})`)}`)
+        .join("\n");
+}
+function preview(value, width = 70) {
+    if (value === undefined)
+        return c.dim("(empty)");
+    const flat = value.replace(/\n+/g, " ⏎ ");
+    return flat.length > width ? `${flat.slice(0, width - 1)}…` : flat;
+}
+export function formatChanges(changes) {
+    if (changes.length === 0)
+        return c.green("In sync with the store.");
+    const lines = [];
+    let last = "";
+    for (const ch of changes) {
+        const head = `${storeLabel(ch.store)} ${ch.locale}${ch.newLocale ? c.yellow(" (new locale)") : ""}`;
+        if (head !== last) {
+            lines.push(c.bold(head));
+            last = head;
+        }
+        lines.push(`  ${ch.field}`);
+        lines.push(`    ${c.red("-")} ${preview(ch.before)}`);
+        lines.push(`    ${c.green("+")} ${preview(ch.after)}`);
+        if (ch.blocked)
+            lines.push(`    ${c.yellow("blocked:")} ${ch.blocked}`);
+    }
+    return lines.join("\n");
+}
+const LEVEL_LABEL = {
+    title: "in title",
+    subtitle: "name+subtitle",
+    short: "short desc",
+    full: "indexed",
+    split: "split locales",
+    partial: "partial",
+    none: "missing",
+};
+export function formatCoverage(reports) {
+    if (reports.length === 0)
+        return c.dim("No targets yet. Add keywords under `targets:` in appeeky.spec.yaml.");
+    const out = [];
+    for (const r of reports) {
+        const weighted = r.weightedPercent !== undefined ? `, ${r.weightedPercent}% by popularity` : "";
+        out.push(c.bold(`${storeLabel(r.store)} ${r.country.toUpperCase()}`) +
+            c.dim(` (${r.locales.join(", ") || "no listing"})`) +
+            `  ${r.covered}/${r.total} covered (${r.percent}%${weighted})`);
+        const rows = [...r.keywords].sort((a, b) => (b.popularity ?? -1) - (a.popularity ?? -1));
+        for (const k of rows) {
+            const ok = ["title", "subtitle", "short", "full"].includes(k.level);
+            const mark = ok ? c.green("✓") : k.level === "none" ? c.red("✗") : c.yellow("~");
+            const pop = k.popularity !== undefined ? c.dim(` pop ${String(k.popularity).padStart(3)} diff ${String(k.difficulty ?? "-").padStart(3)}`) : "";
+            const missing = k.missing.length > 0 ? c.dim(`  missing: ${k.missing.join(", ")}`) : "";
+            out.push(`  ${mark} ${k.keyword.padEnd(28)} ${LEVEL_LABEL[k.level].padEnd(14)}${pop}${missing}`);
+        }
+        out.push("");
+    }
+    return out.join("\n").trimEnd();
+}
+//# sourceMappingURL=output.js.map

package/dist/project.d.ts

@@ -0,0 +1,19 @@
+import type { Project, StoreId } from "./schema.js";
+import type { FieldChange, RemoteState, StoreAdapter } from "./stores/types.js";
+import { type OpsTransport, type TransportOptions } from "./transport.js";
+export interface StoreHandle {
+    store: StoreId;
+    adapter: StoreAdapter;
+    transport: OpsTransport;
+}
+/** Stores configured in the spec, optionally narrowed to one. */
+export declare function configuredStores(project: Project, only?: StoreId): StoreId[];
+export declare function storeHandle(project: Project, store: StoreId, overrides?: Partial<TransportOptions>, transportOverride?: OpsTransport): StoreHandle;
+export interface StorePlan {
+    store: StoreId;
+    via: string;
+    state: RemoteState;
+    changes: FieldChange[];
+}
+/** Pull the store, diff it with the spec and mark what cannot be pushed yet. */
+export declare function planStore(project: Project, handle: StoreHandle): Promise<StorePlan>;

package/dist/project.js

@@ -0,0 +1,35 @@
+import { diffListings } from "./diff.js";
+import { AppStoreAdapter } from "./stores/app-store.js";
+import { GooglePlayAdapter } from "./stores/google-play.js";
+import { createTransport } from "./transport.js";
+/** Stores configured in the spec, optionally narrowed to one. */
+export function configuredStores(project, only) {
+    const stores = [];
+    if (project.spec.stores.appStore)
+        stores.push("app-store");
+    if (project.spec.stores.googlePlay)
+        stores.push("google-play");
+    return only ? stores.filter((s) => s === only) : stores;
+}
+export function storeHandle(project, store, overrides = {}, transportOverride) {
+    if (store === "app-store") {
+        const cfg = project.spec.stores.appStore;
+        if (!cfg)
+            throw new Error("The spec has no stores.appStore section.");
+        const transport = transportOverride ?? createTransport(store, { via: cfg.via, account: cfg.account, ...overrides });
+        return { store, transport, adapter: new AppStoreAdapter(transport, cfg.appId, cfg.platform) };
+    }
+    const cfg = project.spec.stores.googlePlay;
+    if (!cfg)
+        throw new Error("The spec has no stores.googlePlay section.");
+    const transport = transportOverride ?? createTransport(store, { via: cfg.via, account: cfg.account ?? cfg.profile, ...overrides });
+    return { store, transport, adapter: new GooglePlayAdapter(transport, cfg.packageName) };
+}
+/** Pull the store, diff it with the spec and mark what cannot be pushed yet. */
+export async function planStore(project, handle) {
+    const state = await handle.adapter.pull();
+    const local = project.listings[handle.store];
+    const changes = handle.adapter.annotate(diffListings(handle.store, local, state.listings), state, local);
+    return { store: handle.store, via: handle.transport.label, state, changes };
+}
+//# sourceMappingURL=project.js.map

package/dist/report.d.ts

@@ -0,0 +1,5 @@
+import { type Project } from "./schema.js";
+/** Load the spec as it was at a git ref (e.g. `origin/main`), or null when it did not exist there. */
+export declare function loadProjectAtRef(root: string, ref: string): Promise<Project | null>;
+/** Markdown for a pull request: listing changes, check results and coverage before → after. */
+export declare function specReport(base: Project | null, head: Project): string;

package/dist/report.js

@@ -0,0 +1,71 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { promisify } from "node:util";
+import { projectCoverage } from "./coverage.js";
+import { diffListings } from "./diff.js";
+import { loadProject, SPEC_DIR, SPEC_FILE } from "./files.js";
+import { lintProject } from "./lint.js";
+import { STORES } from "./schema.js";
+const run = promisify(execFile);
+/** Load the spec as it was at a git ref (e.g. `origin/main`), or null when it did not exist there. */
+export async function loadProjectAtRef(root, ref) {
+    const { stdout: top } = await run("git", ["rev-parse", "--show-toplevel"], { cwd: root });
+    const prefix = relative(await realpath(top.trim()), await realpath(root));
+    const paths = [SPEC_FILE, SPEC_DIR].map((p) => (prefix ? `${prefix}/${p}` : p));
+    const dir = await mkdtemp(join(tmpdir(), "appeeky-spec-base-"));
+    try {
+        const archive = await run("git", ["archive", "--format=tar", ref, "--", ...paths], { cwd: top.trim(), encoding: "buffer", maxBuffer: 64 * 1024 * 1024 }).catch(() => null);
+        if (!archive)
+            return null;
+        await new Promise((resolve, reject) => {
+            const tar = execFile("tar", ["-x", "-C", dir], (err) => (err ? reject(err) : resolve()));
+            tar.stdin.end(archive.stdout);
+        });
+        return await loadProject(join(dir, prefix));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        // loadProject read everything into memory; the copy is no longer needed.
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+const key = (r) => `${r.store}:${r.country}`;
+const label = (r) => `${r.store === "app-store" ? "App Store" : "Google Play"} ${r.country.toUpperCase()}`;
+/** Markdown for a pull request: listing changes, check results and coverage before → after. */
+export function specReport(base, head) {
+    const out = ["## Appeeky Spec"];
+    const changes = STORES.flatMap((store) => diffListings(store, head.listings[store], (base?.listings[store] ?? {})));
+    out.push("", `**${changes.length} listing field${changes.length === 1 ? "" : "s"} changed**`);
+    if (changes.length > 0) {
+        out.push("", "| Store | Locale | Field | After |", "| --- | --- | --- | --- |");
+        for (const c of changes.slice(0, 40)) {
+            out.push(`| ${c.store} | ${c.locale} | ${c.field} | ${c.after.replace(/\n+/g, " ").replace(/\|/g, "\\|").slice(0, 90)} |`);
+        }
+    }
+    const issues = lintProject(head).filter((i) => i.severity !== "info");
+    const errors = issues.filter((i) => i.severity === "error").length;
+    out.push("", `**Check:** ${errors} error${errors === 1 ? "" : "s"}, ${issues.length - errors} warning${issues.length - errors === 1 ? "" : "s"}`);
+    for (const i of issues.slice(0, 20))
+        out.push(`- ${i.severity === "error" ? "❌" : "⚠️"} ${i.store} ${i.locale}${i.field ? ` ${i.field}` : ""}: ${i.message}`);
+    const before = new Map((base ? projectCoverage(base) : []).map((r) => [key(r), r]));
+    const after = projectCoverage(head);
+    if (after.length > 0) {
+        out.push("", "| Storefront | Coverage | Gained | Lost |", "| --- | --- | --- | --- |");
+        for (const r of after) {
+            const b = before.get(key(r));
+            const covered = (x) => new Set((x?.keywords ?? []).filter((k) => ["title", "subtitle", "short", "full"].includes(k.level)).map((k) => k.keyword));
+            const was = covered(b);
+            const now = covered(r);
+            const gained = [...now].filter((k) => !was.has(k));
+            const lost = [...was].filter((k) => !now.has(k));
+            const pct = b ? `${b.percent}% → ${r.percent}%` : `${r.percent}%`;
+            out.push(`| ${label(r)} | ${pct} | ${gained.join(", ") || "—"} | ${lost.length > 0 ? `**${lost.join(", ")}**` : "—"} |`);
+        }
+    }
+    return out.join("\n");
+}
+//# sourceMappingURL=report.js.map

package/dist/reviews.d.ts

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { MetricSource } from "./metrics.js";
+import type { StoreId } from "./schema.js";
+/**
+ * Customer reviews in the repo, so an agent can read what users say next to the
+ * listing, and answer them through a pull request like any other change.
+ *
+ *   appeeky/reviews/<store>/<YYYY-MM>.jsonl   one review per line, newest first
+ *   appeeky/reviews/summary.md                ratings, replies, versions, last 30 days
+ *   appeeky/reviews/replies/<id>.yaml         a reply: drafted, reviewed in a PR, then sent
+ *
+ * Reviews come from the store connections in Appeeky (APPEEKY_API_KEY).
+ */
+export interface Review {
+    id: string;
+    store: StoreId;
+    rating: number;
+    title?: string;
+    body: string;
+    author?: string;
+    /** App Store territory (US) or Google Play language (en). */
+    where?: string;
+    version?: string;
+    date: string;
+    reply?: {
+        body: string;
+        date?: string;
+    };
+}
+export declare function reviewsDir(root: string): string;
+interface AscReviewRow {
+    id: string;
+    rating: number;
+    title: string | null;
+    body: string | null;
+    reviewer_nickname: string | null;
+    territory: string | null;
+    app_version: string | null;
+    review_created_at: string;
+    response_body: string | null;
+    response_last_modified: string | null;
+}
+interface PlayReviewRow {
+    review_id: string;
+    author_name: string | null;
+    reviewer_language: string | null;
+    star_rating: number;
+    review_text: string | null;
+    review_last_modified_at: string;
+    app_version_name: string | null;
+    developer_reply_text: string | null;
+    developer_reply_last_modified_at: string | null;
+}
+export declare function fromAsc(r: AscReviewRow): Review;
+export declare function fromPlay(r: PlayReviewRow): Review;
+/** Newest reviews first, paging back until `since` (or `max` reviews). */
+export declare function fetchReviews(api: AppeekyApi, store: StoreId, appId: string, options?: {
+    since?: string;
+    max?: number;
+}): Promise<Review[]>;
+export declare function readReviews(root: string, store?: StoreId): Promise<Review[]>;
+/**
+ * Merge fetched reviews into the monthly files: a review that changed (edited,
+ * answered) replaces the old line. Returns how many were new and how many changed.
+ */
+export declare function saveReviews(root: string, fetched: Review[]): Promise<{
+    added: number;
+    updated: number;
+}>;
+export interface ReviewStats {
+    count: number;
+    average: number | null;
+    /** Share of 1- and 2-star reviews. */
+    low: number | null;
+    unanswered: number;
+    distribution: Record<1 | 2 | 3 | 4 | 5, number>;
+}
+export declare function reviewStats(reviews: Review[]): ReviewStats;
+/**
+ * What users ask for in their own words: words and two-word phrases that come up in three or
+ * more reviews and appear nowhere in your listing. Candidates for targets, or for the product.
+ * English stop words only, so other languages show more noise.
+ */
+export declare function reviewPhrases(reviews: Review[], listingText: string, limit?: number): Array<{
+    phrase: string;
+    reviews: number;
+    low: number;
+}>;
+export declare function summaryMarkdown(reviews: Review[], now?: Date, listingText?: string): string;
+export declare function writeSummary(root: string, now?: Date, listingText?: string): Promise<string>;
+export declare const replySchema: z.ZodObject<{
+    id: z.ZodString;
+    store: z.ZodEnum<["app-store", "google-play"]>;
+    /** The review being answered, for whoever reviews the pull request. */
+    review: z.ZodOptional<z.ZodString>;
+    text: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<["draft", "sent"]>>;
+    sentAt: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "draft" | "sent";
+    store: "app-store" | "google-play";
+    id: string;
+    text: string;
+    review?: string | undefined;
+    sentAt?: string | undefined;
+}, {
+    store: "app-store" | "google-play";
+    id: string;
+    text: string;
+    status?: "draft" | "sent" | undefined;
+    review?: string | undefined;
+    sentAt?: string | undefined;
+}>;
+export type Reply = z.infer<typeof replySchema>;
+export declare const repliesDir: (root: string) => string;
+export declare function writeReply(root: string, reply: z.input<typeof replySchema>): Promise<string>;
+export declare function readReplies(root: string): Promise<Array<Reply & {
+    file: string;
+}>>;
+/** Store limits for a developer reply. */
+export declare const REPLY_LIMIT: Record<StoreId, number>;
+export declare function replyIssues(reply: Reply): string[];
+/** Send one draft reply to the store and mark it sent. */
+export declare function sendReply(api: AppeekyApi, reply: Reply & {
+    file: string;
+}, packageName: string | undefined, now?: Date): Promise<void>;
+/** Ratings around a push, from the pulled review files: no API call. */
+export declare function reviewMetricSource(root: string): MetricSource;
+export {};