@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/competitors.d.ts

@@ -0,0 +1,74 @@
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { SpecFile, StoreId } from "./schema.js";
+/**
+ * Competitors in the repo: their listing, the searches they rank for, and what
+ * their users say, one file per competitor in appeeky/competitors/. Pull again
+ * and the git diff shows what they changed.
+ */
+export type Competitor = SpecFile["competitors"][number];
+export declare const competitorsDir: (root: string) => string;
+export declare function competitorSlug(c: Competitor): string;
+export interface CompetitorStore {
+    id: string;
+    title?: string;
+    developer?: string;
+    rating?: number;
+    ratings?: number;
+    version?: string;
+    updated?: string;
+    releaseNotes?: string;
+    description?: string;
+    /** The searches it ranks for in `country`, best first. */
+    ranks: Array<{
+        keyword: string;
+        rank: number;
+        popularity?: number;
+        trend?: string;
+    }>;
+    /** Where it ranks for your own targets. */
+    yourTargets: Array<{
+        keyword: string;
+        rank: number;
+    }>;
+    recentReviews?: {
+        count: number;
+        average: number;
+        low: Array<{
+            rating: number;
+            text: string;
+        }>;
+    };
+}
+export interface CompetitorFile {
+    name: string;
+    pulledAt: string;
+    country: string;
+    stores: Partial<Record<StoreId, CompetitorStore>>;
+}
+export declare function fetchCompetitorStore(api: AppeekyApi, store: StoreId, id: string, country: string, targets: string[]): Promise<CompetitorStore>;
+/**
+ * What a competitor changed since the last pull: its title, a new version, a rewritten
+ * description, or a climb into the top 10 for one of your targets.
+ */
+export declare function competitorChanges(prev: CompetitorFile, next: CompetitorFile): string[];
+export declare const changesFile: (root: string) => string;
+/** Competitor changes recorded on or after a date, from changes.md. */
+export declare function readChanges(root: string): Promise<Array<{
+    date: string;
+    name: string;
+    change: string;
+}>>;
+/** Pull every competitor listed in the spec and write its file. */
+export declare function pullCompetitors(api: AppeekyApi, root: string, spec: SpecFile, now?: Date): Promise<Array<{
+    file: string;
+    errors: string[];
+    changes: string[];
+}>>;
+/** Apps like yours, to pick competitors from. */
+export declare function similarApps(api: AppeekyApi, store: StoreId, id: string, country: string): Promise<Array<{
+    id: string;
+    title: string;
+    rating?: number;
+    ratings?: number;
+}>>;
+export declare function readCompetitor(file: string): Promise<CompetitorFile | null>;

package/dist/competitors.js

@@ -0,0 +1,143 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import YAML from "yaml";
+import { SPEC_DIR } from "./files.js";
+import { normalize } from "./text.js";
+export const competitorsDir = (root) => join(root, SPEC_DIR, "competitors");
+export function competitorSlug(c) {
+    const base = c.name ?? c.appStore ?? c.googlePlay ?? "competitor";
+    return normalize(base).replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "competitor";
+}
+const platform = (store) => (store === "app-store" ? "apple" : "google");
+const trim = (s, n) => (s ? (s.length > n ? `${s.slice(0, n).trimEnd()}…` : s) : undefined);
+const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== ""));
+export async function fetchCompetitorStore(api, store, id, country, targets) {
+    const q = { country, platform: platform(store) };
+    const app = (await api.get(`/apps/${encodeURIComponent(id)}`, q)) ?? {};
+    const kw = await api.get(`/apps/${encodeURIComponent(id)}/keywords`, q).catch(() => null);
+    const rv = await api.get(`/apps/${encodeURIComponent(id)}/reviews`, { ...q, sortBy: "mostRecent", page: "1" }).catch(() => null);
+    const ranked = (kw?.keywords ?? []).filter((k) => typeof k.rank === "number").sort((a, b) => a.rank - b.rank);
+    const wanted = new Set(targets.map((t) => normalize(t).trim()));
+    const reviews = rv?.reviews ?? [];
+    const m = app.metadata ?? {};
+    return clean({
+        id,
+        title: app.title ?? m.trackName,
+        developer: app.developer,
+        rating: round(app.averageUserRating ?? m.averageUserRating),
+        ratings: app.userRatingCount ?? m.userRatingCount,
+        version: m.version,
+        updated: m.currentVersionReleaseDate?.slice(0, 10),
+        releaseNotes: trim(m.releaseNotes, 300),
+        description: trim(m.description, 600),
+        ranks: ranked.slice(0, 25).map((k) => clean({ keyword: k.keyword, rank: k.rank, popularity: k.popularity ?? k.volumeScore, trend: k.trend })),
+        yourTargets: ranked.filter((k) => wanted.has(normalize(k.keyword).trim())).map((k) => ({ keyword: k.keyword, rank: k.rank })),
+        recentReviews: reviews.length
+            ? {
+                count: reviews.length,
+                average: round(reviews.reduce((n, r) => n + r.rating, 0) / reviews.length),
+                low: reviews
+                    .filter((r) => r.rating <= 2)
+                    .slice(0, 5)
+                    .map((r) => ({ rating: r.rating, text: trim([r.title, r.content].filter(Boolean).join(". ").replace(/\s+/g, " "), 160) })),
+            }
+            : undefined,
+    });
+}
+function round(n) {
+    return n === undefined ? undefined : Math.round(n * 100) / 100;
+}
+/**
+ * What a competitor changed since the last pull: its title, a new version, a rewritten
+ * description, or a climb into the top 10 for one of your targets.
+ */
+export function competitorChanges(prev, next) {
+    const out = [];
+    for (const store of ["app-store", "google-play"]) {
+        const a = prev.stores[store];
+        const b = next.stores[store];
+        if (!a || !b)
+            continue;
+        const where = store === "app-store" ? "App Store" : "Google Play";
+        if (a.title && b.title && a.title !== b.title)
+            out.push(`${where}: title "${a.title}" → "${b.title}"`);
+        if (a.version && b.version && a.version !== b.version)
+            out.push(`${where}: version ${b.version}${b.releaseNotes ? `: ${trim(b.releaseNotes.replace(/\s+/g, " "), 90)}` : ""}`);
+        if (a.description && b.description && a.description !== b.description)
+            out.push(`${where}: rewrote the description`);
+        const before = new Map(a.yourTargets.map((t) => [t.keyword, t.rank]));
+        for (const t of b.yourTargets) {
+            const was = before.get(t.keyword);
+            if (t.rank <= 10 && (was === undefined || was > 10))
+                out.push(`${where}: now #${t.rank} for "${t.keyword}" (was ${was === undefined ? "not ranked" : `#${was}`})`);
+        }
+    }
+    return out;
+}
+export const changesFile = (root) => join(competitorsDir(root), "changes.md");
+/** Add the day's changes to appeeky/competitors/changes.md, newest first. */
+async function recordChanges(root, date, name, changes) {
+    if (changes.length === 0)
+        return;
+    const file = changesFile(root);
+    const old = existsSync(file) ? await readFile(file, "utf8") : "# Competitor changes\n\nWritten by `competitors pull`: what each competitor changed since the pull before.\n";
+    const [head, ...rest] = old.split(/\n(?=- )/);
+    const lines = changes.map((c) => `- ${date} · ${name} · ${c}`);
+    await writeFile(file, [head.trimEnd(), "", ...lines, ...rest.map((r) => r.trimEnd())].join("\n") + "\n");
+}
+/** Competitor changes recorded on or after a date, from changes.md. */
+export async function readChanges(root) {
+    const file = changesFile(root);
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    for (const line of (await readFile(file, "utf8")).split("\n")) {
+        const m = line.match(/^- (\d{4}-\d{2}-\d{2}) · (.+?) · (.+)$/);
+        if (m)
+            out.push({ date: m[1], name: m[2], change: m[3] });
+    }
+    return out;
+}
+/** Pull every competitor listed in the spec and write its file. */
+export async function pullCompetitors(api, root, spec, now = new Date()) {
+    const country = Object.keys(spec.targets)[0] ?? "us";
+    const targets = spec.targets[country] ?? [];
+    const out = [];
+    await mkdir(competitorsDir(root), { recursive: true });
+    for (const c of spec.competitors) {
+        const data = { name: c.name ?? c.appStore ?? c.googlePlay ?? "competitor", pulledAt: now.toISOString().slice(0, 10), country, stores: {} };
+        const errors = [];
+        for (const [store, id] of [["app-store", c.appStore], ["google-play", c.googlePlay]]) {
+            if (!id)
+                continue;
+            try {
+                data.stores[store] = await fetchCompetitorStore(api, store, id, country, targets);
+                if (!c.name && data.stores[store]?.title)
+                    data.name = data.stores[store].title;
+            }
+            catch (e) {
+                errors.push(`${store}: ${e.message}`);
+            }
+        }
+        const file = join(competitorsDir(root), `${competitorSlug({ ...c, name: data.name })}.yaml`);
+        let changes = [];
+        if (Object.keys(data.stores).length) {
+            const prev = await readCompetitor(file);
+            changes = prev ? competitorChanges(prev, data) : [];
+            await recordChanges(root, data.pulledAt, data.name, changes);
+            await writeFile(file, YAML.stringify(data, { lineWidth: 0 }));
+        }
+        out.push({ file, errors, changes });
+    }
+    return out;
+}
+/** Apps like yours, to pick competitors from. */
+export async function similarApps(api, store, id, country) {
+    const data = await api.get(`/apps/${encodeURIComponent(id)}/similar`, { country, platform: platform(store) });
+    return (data ?? []).map((a) => clean({ id: String(a.appId), title: a.title, rating: a.rating, ratings: a.reviewsCount }));
+}
+export async function readCompetitor(file) {
+    return existsSync(file) ? YAML.parse(await readFile(file, "utf8")) : null;
+}
+//# sourceMappingURL=competitors.js.map

package/dist/control.d.ts

@@ -0,0 +1,21 @@
+import type { ReleaseRecord } from "./history.js";
+import type { Project } from "./schema.js";
+import type { RankSnapshot } from "./verify.js";
+export interface ControlComparison {
+    /** Storefronts whose indexed listing changed in this release. */
+    changed: string[];
+    /** Storefronts with targets whose listing did not change. */
+    control: string[];
+    /** Average places gained per target (positive is better), in each group. */
+    changedMove: number;
+    controlMove: number;
+    /** changedMove − controlMove: what the release did beyond the store-wide move. */
+    net: number;
+}
+/** Storefronts in the baseline whose listing this release changed. */
+export declare function changedStorefronts(project: Project, release: ReleaseRecord, storefronts: string[]): string[];
+/** The fewest targets on each side for the comparison to mean anything. */
+export declare const MIN_CONTROL_TARGETS = 3;
+export declare function compareWithControl(project: Project, release: ReleaseRecord, before: RankSnapshot, after: RankSnapshot): ControlComparison | null;
+/** A gain smaller than this, beyond the control group's, is the store moving, not the release. */
+export declare const MIN_NET_PLACES = 2;

package/dist/control.js

@@ -0,0 +1,53 @@
+import { indexedLocales, playLanguageFor } from "./storefronts.js";
+/**
+ * A control group for a release: the storefronts whose listing did not change.
+ *
+ * A push to en-US changes what the US store reads; the German store reads de-DE and did not
+ * change. Ranks there still move with everything else: the store's algorithm, the season,
+ * competitors. Comparing the changed storefronts with the unchanged ones over the same days
+ * takes that common move out, so a store-wide lift does not count as the release's win.
+ */
+/** Not ranked counts as just past the 200 results the stores return. */
+const UNRANKED = 201;
+const asRank = (r) => (r === null || r === undefined ? UNRANKED : r);
+/** Storefronts in the baseline whose listing this release changed. */
+export function changedStorefronts(project, release, storefronts) {
+    const locales = new Set(release.changes.map((c) => c.locale));
+    return storefronts.filter((cc) => {
+        if (release.store === "app-store")
+            return indexedLocales(project, cc).some((l) => locales.has(l));
+        const lang = playLanguageFor(project, cc);
+        return lang !== undefined && locales.has(lang);
+    });
+}
+function averageMove(before, after, storefronts) {
+    let sum = 0;
+    let n = 0;
+    for (const cc of storefronts)
+        for (const [keyword, b] of Object.entries(before[cc] ?? {})) {
+            if (!(keyword in (after[cc] ?? {})))
+                continue;
+            // Cap each move so one keyword going from unranked to #5 does not drown the rest.
+            sum += Math.max(-50, Math.min(50, asRank(b) - asRank(after[cc][keyword])));
+            n++;
+        }
+    return { move: n ? sum / n : 0, targets: n };
+}
+/** The fewest targets on each side for the comparison to mean anything. */
+export const MIN_CONTROL_TARGETS = 3;
+export function compareWithControl(project, release, before, after) {
+    const storefronts = Object.keys(before);
+    const changed = changedStorefronts(project, release, storefronts);
+    const control = storefronts.filter((cc) => !changed.includes(cc));
+    if (changed.length === 0 || control.length === 0)
+        return null;
+    const a = averageMove(before, after, changed);
+    const b = averageMove(before, after, control);
+    if (a.targets < MIN_CONTROL_TARGETS || b.targets < MIN_CONTROL_TARGETS)
+        return null;
+    const round = (x) => Math.round(x * 10) / 10;
+    return { changed, control, changedMove: round(a.move), controlMove: round(b.move), net: round(a.move - b.move) };
+}
+/** A gain smaller than this, beyond the control group's, is the store moving, not the release. */
+export const MIN_NET_PLACES = 2;
+//# sourceMappingURL=control.js.map

package/dist/core.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser-safe part of Appeeky Spec: schema, limits, lint rules, keyword
+ * coverage and diffing. No Node built-ins, so editors can run it in the UI.
+ */
+export * from "./schema.js";
+export * from "./limits.js";
+export * from "./text.js";
+export * from "./lint.js";
+export * from "./coverage.js";
+export * from "./storefronts.js";
+export * from "./diff.js";
+export * from "./suggest.js";
+export * from "./verify.js";
+export * from "./metrics.js";
+export type { FieldChange, PushResult, RemoteState, StoreAdapter } from "./stores/types.js";

package/dist/core.js

@@ -0,0 +1,15 @@
+/**
+ * Browser-safe part of Appeeky Spec: schema, limits, lint rules, keyword
+ * coverage and diffing. No Node built-ins, so editors can run it in the UI.
+ */
+export * from "./schema.js";
+export * from "./limits.js";
+export * from "./text.js";
+export * from "./lint.js";
+export * from "./coverage.js";
+export * from "./storefronts.js";
+export * from "./diff.js";
+export * from "./suggest.js";
+export * from "./verify.js";
+export * from "./metrics.js";
+//# sourceMappingURL=core.js.map

package/dist/coverage.d.ts

@@ -0,0 +1,46 @@
+import type { Project, StoreId } from "./schema.js";
+/**
+ * How well the listing covers a target search, strongest first.
+ * - `title`: the exact phrase is in the name (App Store) or title (Google Play)
+ * - `subtitle`: every word is in the name or subtitle (App Store)
+ * - `short`: every word is in the short description (Google Play)
+ * - `full`: every word is indexed somewhere in one locale
+ * - `split`: every word is indexed, but across different locales (App Store; may not combine)
+ * - `partial`: some words are indexed
+ * - `none`: no word is indexed
+ */
+export type CoverageLevel = "title" | "subtitle" | "short" | "full" | "split" | "partial" | "none";
+export interface KeywordCoverage {
+    keyword: string;
+    level: CoverageLevel;
+    /** Locale that gives the best level. */
+    locale?: string;
+    /** Words of the keyword the listing does not index. */
+    missing: string[];
+    /** 0–100 search popularity from the Appeeky API, when fetched. */
+    popularity?: number;
+    difficulty?: number;
+}
+export interface StorefrontCoverage {
+    store: StoreId;
+    country: string;
+    locales: string[];
+    keywords: KeywordCoverage[];
+    covered: number;
+    total: number;
+    /** Share of targets fully indexed (title, subtitle, short or full), 0–100. */
+    percent: number;
+    /** Same share weighted by popularity, when popularity is known for every target. */
+    weightedPercent?: number;
+}
+export declare function isCovered(level: CoverageLevel): boolean;
+export type PopularityLookup = (keyword: string, country: string, store: StoreId) => {
+    popularity?: number;
+    difficulty?: number;
+} | undefined;
+/** App Store coverage of one storefront's targets across the locales that storefront indexes. */
+export declare function appStoreCoverage(project: Project, country: string, lookup?: PopularityLookup): StorefrontCoverage;
+/** Google Play coverage of one storefront's targets in the language that storefront most likely shows. */
+export declare function googlePlayCoverage(project: Project, country: string, lookup?: PopularityLookup): StorefrontCoverage;
+/** Coverage for every storefront with targets, for each store the spec ships to. */
+export declare function projectCoverage(project: Project, lookup?: PopularityLookup): StorefrontCoverage[];

package/dist/coverage.js

@@ -0,0 +1,115 @@
+import { indexedLocales, playLanguageFor } from "./storefronts.js";
+import { keyWords, keywordEntries, normalize, words } from "./text.js";
+const RANK = { title: 6, subtitle: 5, short: 5, full: 4, split: 2, partial: 1, none: 0 };
+const COVERED = new Set(["title", "subtitle", "short", "full"]);
+export function isCovered(level) {
+    return COVERED.has(level);
+}
+function containsPhrase(haystack, phrase) {
+    if (phrase.length === 0)
+        return false;
+    outer: for (let i = 0; i + phrase.length <= haystack.length; i++) {
+        for (let j = 0; j < phrase.length; j++)
+            if (haystack[i + j] !== phrase[j])
+                continue outer;
+        return true;
+    }
+    return false;
+}
+function scoreAppStoreLocale(keyword, listing) {
+    const name = words(listing.name);
+    const titled = new Set([...name, ...words(listing.subtitle)]);
+    const all = new Set([...titled, ...keywordEntries(listing.keywords).flatMap((e) => words(e))]);
+    const missing = keyword.filter((w) => !all.has(w));
+    if (containsPhrase(name, keyword))
+        return { level: "title", missing: [] };
+    if (keyword.every((w) => titled.has(w)))
+        return { level: "subtitle", missing: [] };
+    if (missing.length === 0)
+        return { level: "full", missing };
+    if (missing.length < keyword.length)
+        return { level: "partial", missing };
+    return { level: "none", missing };
+}
+function scoreGooglePlay(keyword, listing) {
+    const title = words(listing.title);
+    const short = new Set(words(listing.shortDescription));
+    const all = new Set([...title, ...short, ...words(listing.fullDescription)]);
+    const missing = keyword.filter((w) => !all.has(w));
+    if (containsPhrase(title, keyword))
+        return { level: "title", missing: [] };
+    if (keyword.every((w) => short.has(w) || title.includes(w)))
+        return { level: "short", missing: [] };
+    if (missing.length === 0)
+        return { level: "full", missing };
+    if (missing.length < keyword.length)
+        return { level: "partial", missing };
+    return { level: "none", missing };
+}
+function summarize(store, country, locales, keywords) {
+    const covered = keywords.filter((k) => isCovered(k.level)).length;
+    const total = keywords.length;
+    const result = {
+        store,
+        country,
+        locales,
+        keywords,
+        covered,
+        total,
+        percent: total === 0 ? 0 : Math.round((covered / total) * 100),
+    };
+    if (total > 0 && keywords.every((k) => typeof k.popularity === "number")) {
+        const weight = keywords.reduce((s, k) => s + Math.max(k.popularity, 1), 0);
+        const hit = keywords.filter((k) => isCovered(k.level)).reduce((s, k) => s + Math.max(k.popularity, 1), 0);
+        result.weightedPercent = Math.round((hit / weight) * 100);
+    }
+    return result;
+}
+/** App Store coverage of one storefront's targets across the locales that storefront indexes. */
+export function appStoreCoverage(project, country, lookup) {
+    const locales = indexedLocales(project, country);
+    const targets = project.spec.targets[country] ?? [];
+    const keywords = targets.map((raw) => {
+        const kw = keyWords(raw);
+        let best = { level: "none", missing: kw };
+        const union = new Set();
+        for (const locale of locales) {
+            const listing = project.listings["app-store"][locale] ?? {};
+            const scored = scoreAppStoreLocale(kw, listing);
+            kw.filter((w) => !scored.missing.includes(w)).forEach((w) => union.add(w));
+            if (RANK[scored.level] > RANK[best.level] || (RANK[scored.level] === RANK[best.level] && scored.missing.length < best.missing.length)) {
+                best = { ...scored, locale };
+            }
+        }
+        if (!isCovered(best.level) && kw.length > 0 && kw.every((w) => union.has(w))) {
+            best = { level: "split", missing: [], locale: undefined };
+        }
+        return { keyword: normalize(raw).trim(), level: best.level, locale: best.locale, missing: best.missing, ...lookup?.(raw, country, "app-store") };
+    });
+    return summarize("app-store", country, locales, keywords);
+}
+/** Google Play coverage of one storefront's targets in the language that storefront most likely shows. */
+export function googlePlayCoverage(project, country, lookup) {
+    const language = playLanguageFor(project, country);
+    const listing = language ? (project.listings["google-play"][language] ?? {}) : {};
+    const targets = project.spec.targets[country] ?? [];
+    const keywords = targets.map((raw) => {
+        const scored = scoreGooglePlay(keyWords(raw), listing);
+        return { keyword: normalize(raw).trim(), level: scored.level, locale: language, missing: scored.missing, ...lookup?.(raw, country, "google-play") };
+    });
+    return summarize("google-play", country, language ? [language] : [], keywords);
+}
+/** Coverage for every storefront with targets, for each store the spec ships to. */
+export function projectCoverage(project, lookup) {
+    const out = [];
+    for (const country of Object.keys(project.spec.targets)) {
+        if (project.spec.stores.appStore && Object.keys(project.listings["app-store"]).length > 0) {
+            out.push(appStoreCoverage(project, country, lookup));
+        }
+        if (project.spec.stores.googlePlay && Object.keys(project.listings["google-play"]).length > 0) {
+            out.push(googlePlayCoverage(project, country, lookup));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=coverage.js.map

package/dist/data.d.ts

@@ -0,0 +1,48 @@
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { AttributionClient, AttributionClients } from "./attribution.js";
+import type { Project } from "./schema.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 declare function dataDir(project: Project): string;
+type Row = Record<string, string | number | null | undefined>;
+export interface DataFile {
+    name: string;
+    /** What it holds, for the index. */
+    about: string;
+    key: string[];
+    columns: string[];
+    rows: Row[];
+}
+/** Merge rows into a CSV file by key: new rows replace old ones with the same key. */
+export declare function mergeCsv(dir: string, file: DataFile): Promise<{
+    path: string;
+    rows: number;
+    from?: string;
+    to?: string;
+}>;
+/** [from, to] inclusive, split into chunks the API accepts. */
+export declare function dateChunks(from: string, to: string, maxDays?: number): Array<[string, string]>;
+export interface PullResult {
+    files: Array<{
+        name: string;
+        path: string;
+        rows: number;
+        from?: string;
+        to?: string;
+        about: string;
+    }>;
+    errors: Array<{
+        source: string;
+        message: string;
+    }>;
+}
+/** Every source this spec can read, over the `days` up to yesterday. */
+export declare function pullData(api: AppeekyApi | undefined, project: Project, days: number, now?: Date, attributionIn?: AttributionClient | AttributionClients): Promise<PullResult>;
+export {};