@appeeky/spec 0.0.0-stage → 0.1.0

package/dist/text.js

@@ -0,0 +1,55 @@
+/** Text helpers shared by the lint rules and the coverage report. */
+const encoder = new TextEncoder();
+/** UTF-8 byte length: the unit Apple uses for the 100-byte keyword field. */
+export function byteLength(value) {
+    return encoder.encode(value).length;
+}
+/** Character count as the stores count it (user-perceived characters, not UTF-16 units). */
+export function charLength(value) {
+    return [...value].length;
+}
+export function normalize(value) {
+    return value.normalize("NFKC").toLocaleLowerCase();
+}
+/** Lowercased words; punctuation and symbols split words, apostrophes inside a word are kept. */
+export function words(value) {
+    if (!value)
+        return [];
+    return (normalize(value)
+        .replace(/[’']/g, "'")
+        .match(/[\p{L}\p{N}]+(?:'[\p{L}\p{N}]+)*/gu) ?? []);
+}
+/** Entries of an App Store keyword field, as written (trimmed, empty ones dropped). */
+export function keywordEntries(field) {
+    if (!field)
+        return [];
+    return field
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** Naive English singular form, only used to flag likely plural pairs. */
+export function singular(word) {
+    if (word.length > 4 && word.endsWith("ies"))
+        return `${word.slice(0, -3)}y`;
+    if (word.length > 3 && word.endsWith("es") && /(s|x|z|ch|sh)es$/.test(word))
+        return word.slice(0, -2);
+    if (word.length > 3 && word.endsWith("s") && !word.endsWith("ss"))
+        return word.slice(0, -1);
+    return word;
+}
+export function isEnglish(locale) {
+    return locale.toLowerCase().startsWith("en");
+}
+export function unique(items) {
+    return [...new Set(items)];
+}
+/** Short English words that do not decide a search; ignored when a phrase has other words. */
+export const STOPWORDS = new Set(["a", "an", "the", "and", "or", "for", "to", "of", "in", "on", "with", "my", "your", "by", "at", "app", "apps"]);
+/** Words of a target that matter for coverage: stopwords drop out unless they are all there is. */
+export function keyWords(value) {
+    const all = words(value);
+    const kept = all.filter((w) => !STOPWORDS.has(w));
+    return kept.length > 0 ? kept : all;
+}
+//# sourceMappingURL=text.js.map

package/dist/transport.d.ts

@@ -0,0 +1,98 @@
+import type { StoreId, TransportMode } from "./schema.js";
+/**
+ * Both store CLIs expose the same named operations locally (`appstore ops call`,
+ * `gps call`) and on Appeeky's hosted gateways (`POST /v1/ops/<name>`), so a
+ * store adapter only needs `call(op, args)`.
+ */
+export interface OpsTransport {
+    readonly kind: "local" | "hosted";
+    readonly label: string;
+    call<T = unknown>(op: string, args: Record<string, unknown>, options?: {
+        write?: boolean;
+    }): Promise<T>;
+}
+export declare class TransportError extends Error {
+    readonly op?: string | undefined;
+    constructor(message: string, op?: string | undefined);
+}
+interface StoreCli {
+    bin: string;
+    npmPackage: string;
+    /** argv before the op name, e.g. `ops call` vs `call`. */
+    callArgs: string[];
+    /** Flag that picks a named account or profile. */
+    accountFlag: string;
+    hostedUrl: string;
+    writeHeader: string;
+    setupHint: string;
+}
+export declare const STORE_CLIS: Record<StoreId, StoreCli>;
+export declare function onPath(bin: string, env?: NodeJS.ProcessEnv): boolean;
+export type Runner = (command: string, args: string[], env?: Record<string, string>) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export interface LocalCliOptions {
+    /** Named account (`appstore --account`) or profile (`gps --profile`). */
+    account?: string;
+    /** Run the CLI through `npx` when it is not installed. */
+    useNpx?: boolean;
+    /**
+     * Run a specific executable instead of the CLI on PATH, e.g. an app that
+     * bundles the store CLI: `{ file: process.execPath, args: ["/path/to/bin.js"] }`.
+     */
+    command?: {
+        file: string;
+        args: string[];
+    };
+    /**
+     * Extra environment for the CLI, e.g. credentials:
+     * `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY` or `GPS_CREDENTIALS` (inline JSON).
+     */
+    env?: Record<string, string>;
+    label?: string;
+    runner?: Runner;
+}
+/** Runs operations through the store CLI on this machine, with the user's own key. */
+export declare class LocalCliTransport implements OpsTransport {
+    private readonly store;
+    private readonly options;
+    readonly kind: "local";
+    readonly label: string;
+    constructor(store: StoreId, options?: LocalCliOptions);
+    call<T>(op: string, args: Record<string, unknown>, options?: {
+        write?: boolean;
+    }): Promise<T>;
+}
+export type Fetcher = typeof fetch;
+/** Runs operations on Appeeky's hosted gateway with an Appeeky API key; the store key never leaves Appeeky. */
+export declare class HostedTransport implements OpsTransport {
+    private readonly store;
+    private readonly apiKey;
+    private readonly options;
+    readonly kind: "hosted";
+    readonly label: string;
+    constructor(store: StoreId, apiKey: string, options?: {
+        baseUrl?: string;
+        fetcher?: Fetcher;
+    });
+    call<T>(op: string, args: Record<string, unknown>, options?: {
+        write?: boolean;
+    }): Promise<T>;
+}
+export interface TransportOptions {
+    via: TransportMode;
+    account?: string;
+    apiKey?: string;
+    env?: NodeJS.ProcessEnv;
+    runner?: Runner;
+    fetcher?: Fetcher;
+}
+/**
+ * `auto` prefers the local CLI when it is installed (your key, nothing leaves
+ * your machine), then the hosted gateway when an Appeeky API key is set, and
+ * finally the CLI through npx.
+ */
+export declare function createTransport(store: StoreId, options: TransportOptions): OpsTransport;
+export {};

package/dist/transport.js

@@ -0,0 +1,170 @@
+import { spawn } from "node:child_process";
+import { delimiter, join } from "node:path";
+import { existsSync } from "node:fs";
+export class TransportError extends Error {
+    op;
+    constructor(message, op) {
+        super(message);
+        this.op = op;
+        this.name = "TransportError";
+    }
+}
+export const STORE_CLIS = {
+    "app-store": {
+        bin: "appstore",
+        npmPackage: "@appeeky/app-store-connect-cli",
+        callArgs: ["ops", "call"],
+        accountFlag: "--account",
+        hostedUrl: "https://asc-api.appeeky.com",
+        writeHeader: "X-ASC-Allow-Writes",
+        setupHint: "Save your App Store Connect API key once with the App Store Connect CLI: `npx -p @appeeky/app-store-connect-cli appstore accounts add my-team --key-id … --issuer-id … --private-key-path AuthKey.p8 --default` (github.com/appeeky/app-store-connect-cli). Or set APPEEKY_API_KEY to use your connection in Appeeky.",
+    },
+    "google-play": {
+        bin: "gps",
+        npmPackage: "@appeeky/google-play-store-cli",
+        callArgs: ["call"],
+        accountFlag: "--account",
+        hostedUrl: "https://gps-api.appeeky.com",
+        writeHeader: "X-GPS-Allow-Writes",
+        setupHint: "Save your Google Play service account once with the Google Play CLI: `npx -p @appeeky/google-play-store-cli gps accounts add my-co --credentials service-account.json --default` (github.com/appeeky/google-play-console-cli). Or set APPEEKY_API_KEY to use your connection in Appeeky.",
+    },
+};
+export function onPath(bin, env = process.env) {
+    const exts = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD").split(";") : [""];
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts)
+            if (existsSync(join(dir, bin + ext)))
+                return true;
+    }
+    return false;
+}
+const defaultRunner = (command, args, env) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: process.platform === "win32",
+        env: env ? { ...process.env, ...env } : process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+});
+/** Runs operations through the store CLI on this machine, with the user's own key. */
+export class LocalCliTransport {
+    store;
+    options;
+    kind = "local";
+    label;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.options = options;
+        const cli = STORE_CLIS[store];
+        this.label = options.label ?? (options.useNpx ? `npx ${cli.npmPackage}` : `local ${cli.bin} CLI`);
+    }
+    async call(op, args, options = {}) {
+        const cli = STORE_CLIS[this.store];
+        const argv = ["--json"];
+        if (this.options.account)
+            argv.push(cli.accountFlag, this.options.account);
+        if (options.write)
+            argv.push("--confirm");
+        argv.push(...cli.callArgs, op, JSON.stringify(args));
+        const [command, full] = this.options.command
+            ? [this.options.command.file, [...this.options.command.args, ...argv]]
+            : this.options.useNpx
+                ? ["npx", ["-y", "-p", cli.npmPackage, cli.bin, ...argv]]
+                : [cli.bin, argv];
+        const run = this.options.runner ?? defaultRunner;
+        let result;
+        try {
+            result = await run(command, full, this.options.env);
+        }
+        catch (err) {
+            throw new TransportError(`Could not start ${command}: ${err.message}. ${cli.setupHint}`, op);
+        }
+        if (result.code !== 0) {
+            const detail = (result.stderr || result.stdout).trim().split("\n").slice(-3).join(" ");
+            throw new TransportError(`${cli.bin} ${op} failed: ${detail || `exit ${result.code}`}`, op);
+        }
+        const text = result.stdout.trim();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new TransportError(`${cli.bin} ${op} returned output that is not JSON: ${text.slice(0, 200)}`, op);
+        }
+    }
+}
+/** Runs operations on Appeeky's hosted gateway with an Appeeky API key; the store key never leaves Appeeky. */
+export class HostedTransport {
+    store;
+    apiKey;
+    options;
+    kind = "hosted";
+    label;
+    constructor(store, apiKey, options = {}) {
+        this.store = store;
+        this.apiKey = apiKey;
+        this.options = options;
+        this.label = `hosted ${new URL(options.baseUrl ?? STORE_CLIS[store].hostedUrl).host}`;
+    }
+    async call(op, args, options = {}) {
+        const cli = STORE_CLIS[this.store];
+        const base = (this.options.baseUrl ?? cli.hostedUrl).replace(/\/$/, "");
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": "appeeky-spec",
+        };
+        if (options.write)
+            headers[cli.writeHeader] = "true";
+        const doFetch = this.options.fetcher ?? fetch;
+        let res;
+        try {
+            res = await doFetch(`${base}/v1/ops/${op}`, { method: "POST", headers, body: JSON.stringify(args) });
+        }
+        catch (err) {
+            throw new TransportError(`Could not reach ${base}: ${err.message}`, op);
+        }
+        const body = (await res.json().catch(() => null));
+        if (!res.ok) {
+            const message = body?.error?.message ?? `HTTP ${res.status}`;
+            throw new TransportError(`${op} failed on ${new URL(base).host}: ${message}`, op);
+        }
+        return body?.data;
+    }
+}
+/**
+ * `auto` prefers the local CLI when it is installed (your key, nothing leaves
+ * your machine), then the hosted gateway when an Appeeky API key is set, and
+ * finally the CLI through npx.
+ */
+export function createTransport(store, options) {
+    const env = options.env ?? process.env;
+    const apiKey = options.apiKey ?? env.APPEEKY_API_KEY;
+    const cli = STORE_CLIS[store];
+    const local = (useNpx) => new LocalCliTransport(store, { account: options.account, useNpx, runner: options.runner });
+    const hostedBase = store === "app-store" ? env.APPEEKY_ASC_URL : env.APPEEKY_GPS_URL;
+    const hosted = (key) => new HostedTransport(store, key, { baseUrl: hostedBase, fetcher: options.fetcher });
+    switch (options.via) {
+        case "local":
+            return local(!onPath(cli.bin, env));
+        case "hosted":
+            if (!apiKey)
+                throw new TransportError(`Set APPEEKY_API_KEY to use the hosted ${store} gateway.`);
+            return hosted(apiKey);
+        case "auto":
+            if (onPath(cli.bin, env))
+                return local(false);
+            if (apiKey)
+                return hosted(apiKey);
+            return local(true);
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/verify.d.ts

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

package/dist/verify.js

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

package/dist/visibility.d.ts

@@ -0,0 +1,149 @@
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { MetricSource } from "./metrics.js";
+import type { Project, SpecFile, StoreId } from "./schema.js";
+/**
+ * AI visibility in the repo: whether ChatGPT, Claude, Gemini and Perplexity name
+ * the app when people ask for an app like it, who they name instead, and which
+ * pages they cite. The intents and prompts live in appeeky.spec.yaml; Appeeky AI
+ * Visibility asks the assistants on a schedule, and `visibility pull` writes what
+ * they answered to appeeky/visibility/<country>.yaml.
+ */
+export declare const MODELS: readonly ["chatgpt", "claude", "gemini", "perplexity"];
+export type Model = (typeof MODELS)[number];
+export type AiIntent = NonNullable<SpecFile["aiVisibility"]>["intents"][string][number];
+export declare const visibilityDir: (root: string) => string;
+export declare const visibilityChangesFile: (root: string) => string;
+export interface VisibilityTarget {
+    store: StoreId;
+    /** The store id: numeric App Store id or Google Play package name. */
+    appId: string;
+    countries: string[];
+}
+/** Which app and storefronts to watch. */
+export declare function visibilityTarget(project: Project): VisibilityTarget | null;
+/** ISO 639-1 language for a storefront's prompts, from the listing locale it indexes first. */
+export declare function languageFor(project: Project, country: string): string;
+export interface RemoteIntentRow {
+    intentId: string;
+    label: string;
+    description: string | null;
+    status: "active" | "paused" | "archived";
+    visibilityPct: number;
+    promptsTotal: number;
+}
+export interface RemotePrompt {
+    promptId: string;
+    text: string;
+    status: "active" | "paused" | "archived";
+}
+interface Opportunity {
+    intentId: string;
+    label: string;
+    status: "missing" | "weak" | "winning" | "no_data";
+    ownerVisibilityPct: number | null;
+    byModel: Partial<Record<Model, {
+        visibilityPct: number;
+        positionAvg: number | null;
+        promptsTotal: number;
+        date: string;
+    }>>;
+    winners: Array<{
+        name: string;
+        sharePct: number;
+        models: Model[];
+    }>;
+}
+export declare function remoteIntents(api: AppeekyApi, appId: string, country: string): Promise<RemoteIntentRow[]>;
+export declare function remotePrompts(api: AppeekyApi, appId: string, country: string, intentId: string): Promise<RemotePrompt[]>;
+export interface VisibilityFile {
+    pulledAt: string;
+    country: string;
+    store: StoreId;
+    appId: string;
+    /** Intents by status: missing = no assistant names the app, weak = some do, rarely. */
+    summary: {
+        winning: number;
+        weak: number;
+        missing: number;
+        noData: number;
+    };
+    intents: Array<{
+        label: string;
+        status: Opportunity["status"];
+        /** Share of prompts whose answer names the app, averaged over the assistants (0–100). */
+        you?: number;
+        byModel?: Partial<Record<Model, number>>;
+        /** Who the assistants name instead. */
+        namedInstead?: string[];
+    }>;
+    /** Pages the assistants cite, most cited first. */
+    sources: Array<{
+        domain: string;
+        count: number;
+        yours?: true;
+        url: string;
+    }>;
+    /** What Appeeky suggests changing, still open. */
+    fixes: Array<{
+        intent: string;
+        title: string;
+        why: string;
+        page?: string;
+    }>;
+}
+export declare function fetchVisibility(api: AppeekyApi, target: VisibilityTarget, country: string, now?: Date): Promise<VisibilityFile>;
+export declare const visibilityPath: (root: string, country: string) => string;
+export declare function readVisibility(root: string, country: string): Promise<VisibilityFile | null>;
+/** What moved since the last pull: an intent the assistants started or stopped naming the app for. */
+export declare function visibilityChanges(prev: VisibilityFile, next: VisibilityFile): string[];
+/** Pull every watched storefront and write its file. */
+export declare function pullVisibility(api: AppeekyApi, project: Project, countries?: string[], now?: Date): Promise<Array<{
+    country: string;
+    file?: string;
+    data?: VisibilityFile;
+    changes: string[];
+    error?: string;
+}>>;
+/** The intents and prompts Appeeky tracks for a storefront, in the spec's shape. */
+export declare function readRemoteIntents(api: AppeekyApi, appId: string, country: string): Promise<AiIntent[]>;
+/** Ask Appeeky to write intents and prompts from the store listing (runs in the background). */
+export declare function bootstrapIntents(api: AppeekyApi, appId: string, country: string, language: string): Promise<{
+    queued: boolean;
+    already: boolean;
+}>;
+export interface SyncPlan {
+    country: string;
+    addIntents: AiIntent[];
+    addPrompts: Array<{
+        intentId: string;
+        label: string;
+        text: string;
+    }>;
+    /** Tracked in Appeeky but not in the spec: archived only with --prune. */
+    extraIntents: Array<{
+        intentId: string;
+        label: string;
+    }>;
+    extraPrompts: Array<{
+        promptId: string;
+        label: string;
+        text: string;
+    }>;
+}
+/** Compare the spec's intents for a storefront with what Appeeky tracks. */
+export declare function planSync(api: AppeekyApi, appId: string, country: string, wanted: AiIntent[]): Promise<SyncPlan>;
+/** Apply a plan: add what the spec has; archive what it does not only when `prune` is set. */
+export declare function applySync(api: AppeekyApi, appId: string, plan: SyncPlan, language: string, prune: boolean): Promise<{
+    intents: number;
+    prompts: number;
+    archived: number;
+}>;
+/** Ask the assistants now instead of waiting for the schedule. Charged in AI Visibility credits. */
+export declare function scanVisibility(api: AppeekyApi, appId: string, country: string): Promise<unknown>;
+/**
+ * `ai_visibility` around a push: the share of prompts whose answer names the
+ * app, averaged over the scanned days in the window and the assistants (0–1).
+ * Reads Appeeky's daily series once per assistant per run.
+ */
+export declare function visibilityMetricSource(api: AppeekyApi, project: Project): MetricSource | null;
+export {};