@appeeky/spec 0.0.0-stage → 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,519 @@
+import { z } from "zod";
+/** Stores a spec can describe. The ids double as folder names under `appeeky/store/`. */
+export declare const STORES: readonly ["app-store", "google-play"];
+export type StoreId = (typeof STORES)[number];
+/** How a store is reached: the local store CLI with your own key, or Appeeky's hosted gateway. */
+export declare const transportMode: z.ZodEnum<["auto", "local", "hosted"]>;
+export type TransportMode = z.infer<typeof transportMode>;
+/** Store charts a category rank is read from. */
+export declare const CHARTS: readonly ["top-free", "top-paid", "top-grossing"];
+export type Chart = (typeof CHARTS)[number];
+/** `appeeky.spec.yaml`: who the app is, where it ships, and what it should be found for. */
+export declare const specFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    app: z.ZodObject<{
+        name: z.ZodString;
+        /** Locale the store falls back to when a storefront has no localization of its own. */
+        primaryLocale: z.ZodDefault<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        primaryLocale: string;
+    }, {
+        name: string;
+        primaryLocale?: string | undefined;
+    }>;
+    stores: z.ZodDefault<z.ZodObject<{
+        appStore: z.ZodOptional<z.ZodObject<{
+            /** Numeric App Store id (or a bundle id; the local CLI resolves it). */
+            appId: z.ZodString;
+            platform: z.ZodDefault<z.ZodEnum<["IOS", "MAC_OS", "TV_OS", "VISION_OS"]>>;
+            via: z.ZodDefault<z.ZodEnum<["auto", "local", "hosted"]>>;
+            /** Named account of the local `appstore` CLI. */
+            account: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            appId: string;
+            platform: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS";
+            via: "auto" | "local" | "hosted";
+            account?: string | undefined;
+        }, {
+            appId: string;
+            platform?: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS" | undefined;
+            via?: "auto" | "local" | "hosted" | undefined;
+            account?: string | undefined;
+        }>>;
+        googlePlay: z.ZodOptional<z.ZodObject<{
+            packageName: z.ZodString;
+            via: z.ZodDefault<z.ZodEnum<["auto", "local", "hosted"]>>;
+            /** Named account of the local `gps` CLI (`gps accounts add`). */
+            account: z.ZodOptional<z.ZodString>;
+            /** Old name for `account`. */
+            profile: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            via: "auto" | "local" | "hosted";
+            packageName: string;
+            account?: string | undefined;
+            profile?: string | undefined;
+        }, {
+            packageName: string;
+            via?: "auto" | "local" | "hosted" | undefined;
+            account?: string | undefined;
+            profile?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        appStore?: {
+            appId: string;
+            platform: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS";
+            via: "auto" | "local" | "hosted";
+            account?: string | undefined;
+        } | undefined;
+        googlePlay?: {
+            via: "auto" | "local" | "hosted";
+            packageName: string;
+            account?: string | undefined;
+            profile?: string | undefined;
+        } | undefined;
+    }, {
+        appStore?: {
+            appId: string;
+            platform?: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS" | undefined;
+            via?: "auto" | "local" | "hosted" | undefined;
+            account?: string | undefined;
+        } | undefined;
+        googlePlay?: {
+            packageName: string;
+            via?: "auto" | "local" | "hosted" | undefined;
+            account?: string | undefined;
+            profile?: string | undefined;
+        } | undefined;
+    }>>;
+    /** Target keywords per storefront: the searches this app should be found for. */
+    targets: z.ZodDefault<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodDefault<z.ZodArray<z.ZodString, "many">>>>;
+    /** Override which listing locales a storefront indexes (App Store). */
+    storefronts: z.ZodDefault<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodArray<z.ZodString, "many">>>;
+    /**
+     * Paid channels outside the store. Apple Search Ads needs nothing here: it is
+     * matched to the app in Appeeky. Meta and TikTok campaigns are listed by id.
+     */
+    ads: z.ZodDefault<z.ZodObject<{
+        meta: z.ZodOptional<z.ZodObject<{
+            /** Ad account (act_…); defaults to the one picked in Appeeky. */
+            adAccount: z.ZodOptional<z.ZodString>;
+            campaigns: z.ZodArray<z.ZodString, "many">;
+        }, "strict", z.ZodTypeAny, {
+            campaigns: string[];
+            adAccount?: string | undefined;
+        }, {
+            campaigns: string[];
+            adAccount?: string | undefined;
+        }>>;
+        tiktok: z.ZodOptional<z.ZodObject<{
+            /** Advertiser id; defaults to the one picked in Appeeky. */
+            advertiser: z.ZodOptional<z.ZodString>;
+            campaigns: z.ZodArray<z.ZodString, "many">;
+        }, "strict", z.ZodTypeAny, {
+            campaigns: string[];
+            advertiser?: string | undefined;
+        }, {
+            campaigns: string[];
+            advertiser?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        meta?: {
+            campaigns: string[];
+            adAccount?: string | undefined;
+        } | undefined;
+        tiktok?: {
+            campaigns: string[];
+            advertiser?: string | undefined;
+        } | undefined;
+    }, {
+        meta?: {
+            campaigns: string[];
+            adAccount?: string | undefined;
+        } | undefined;
+        tiktok?: {
+            campaigns: string[];
+            advertiser?: string | undefined;
+        } | undefined;
+    }>>;
+    /** Apps you compete with. `competitors pull` writes each one to appeeky/competitors/. */
+    competitors: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        appStore: z.ZodOptional<z.ZodString>;
+        googlePlay: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        name?: string | undefined;
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+    }, {
+        name?: string | undefined;
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+    }>, {
+        name?: string | undefined;
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+    }, {
+        name?: string | undefined;
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+    }>, "many">>;
+    /**
+     * Install attribution from Appeeky Analytics: organic search, Search Ads keywords,
+     * smart links, with the revenue each led to. `via: self` reads your own server on
+     * Cloudflare (`url`, ATTRIBUTION_TOKEN); `via: hosted` reads Appeeky's (APPEEKY_API_KEY).
+     */
+    attribution: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        via: z.ZodDefault<z.ZodEnum<["self", "hosted"]>>;
+        url: z.ZodOptional<z.ZodString>;
+        /**
+         * The app's id in Appeeky Analytics. An app there is one platform, so an app on both
+         * stores gives one per store: `{ app-store: …, google-play: … }`.
+         */
+        app: z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodObject<{
+            "app-store": z.ZodOptional<z.ZodString>;
+            "google-play": z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        }, {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        }>, {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        }, {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        }>]>;
+    }, "strict", z.ZodTypeAny, {
+        via: "hosted" | "self";
+        app: string | {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        };
+        url?: string | undefined;
+    }, {
+        app: string | {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        };
+        via?: "hosted" | "self" | undefined;
+        url?: string | undefined;
+    }>, {
+        via: "hosted" | "self";
+        app: string | {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        };
+        url?: string | undefined;
+    }, {
+        app: string | {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        };
+        via?: "hosted" | "self" | undefined;
+        url?: string | undefined;
+    }>>;
+    /**
+     * Where `data pull` writes store analytics, ads and revenue. They are your private
+     * business numbers, so by default they stay in .appeeky/data/ (gitignored).
+     * `commit: true` writes them to appeeky/data/ so they are versioned with the spec.
+     */
+    data: z.ZodDefault<z.ZodObject<{
+        commit: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        commit: boolean;
+    }, {
+        commit?: boolean | undefined;
+    }>>;
+    /**
+     * Whether ChatGPT, Claude, Gemini and Perplexity name the app when people ask
+     * for one like it. Intents are what people want ("fall asleep to rain sounds"),
+     * prompts are how they ask; both are tracked per storefront in Appeeky AI Visibility.
+     */
+    aiVisibility: z.ZodOptional<z.ZodObject<{
+        /** Which app to watch when it is on both stores; defaults to the App Store app. */
+        store: z.ZodOptional<z.ZodEnum<["app-store", "google-play"]>>;
+        /** Storefronts to watch; defaults to the first storefront under targets. */
+        countries: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        /** What people ask AI assistants, per storefront. `visibility sync` sends them to Appeeky. */
+        intents: z.ZodDefault<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            prompts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            label: string;
+            prompts: string[];
+            description?: string | undefined;
+        }, {
+            label: string;
+            description?: string | undefined;
+            prompts?: string[] | undefined;
+        }>, "many">>>;
+    }, "strict", z.ZodTypeAny, {
+        intents: Record<string, {
+            label: string;
+            prompts: string[];
+            description?: string | undefined;
+        }[]>;
+        store?: "app-store" | "google-play" | undefined;
+        countries?: string[] | undefined;
+    }, {
+        store?: "app-store" | "google-play" | undefined;
+        countries?: string[] | undefined;
+        intents?: Record<string, {
+            label: string;
+            description?: string | undefined;
+            prompts?: string[] | undefined;
+        }[]> | undefined;
+    }>>;
+    /** Rank in the app's category chart (top 100), recorded daily by `category pull`. */
+    category: z.ZodOptional<z.ZodObject<{
+        /** App Store genre id, e.g. "6013" for Health & Fitness; read from the app when left out. */
+        appStore: z.ZodOptional<z.ZodString>;
+        /** Google Play category, e.g. HEALTH_AND_FITNESS. */
+        googlePlay: z.ZodOptional<z.ZodString>;
+        /** Defaults to top-paid for a paid App Store app, top-free otherwise. */
+        chart: z.ZodOptional<z.ZodEnum<["top-free", "top-paid", "top-grossing"]>>;
+        /** Storefronts to record; defaults to the storefronts under targets. */
+        countries: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+        countries?: string[] | undefined;
+        chart?: "top-free" | "top-paid" | "top-grossing" | undefined;
+    }, {
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+        countries?: string[] | undefined;
+        chart?: "top-free" | "top-paid" | "top-grossing" | undefined;
+    }>>;
+    /** Who the app is for. Experiments, screenshots and UGC refer to these by id. */
+    personas: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        /** How this persona searches: seeds for targets and keyword ideas. */
+        searches: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        searches: string[];
+        description?: string | undefined;
+    }, {
+        name: string;
+        id: string;
+        description?: string | undefined;
+        searches?: string[] | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    version: 1;
+    app: {
+        name: string;
+        primaryLocale: string;
+    };
+    stores: {
+        appStore?: {
+            appId: string;
+            platform: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS";
+            via: "auto" | "local" | "hosted";
+            account?: string | undefined;
+        } | undefined;
+        googlePlay?: {
+            via: "auto" | "local" | "hosted";
+            packageName: string;
+            account?: string | undefined;
+            profile?: string | undefined;
+        } | undefined;
+    };
+    targets: Record<string, string[]>;
+    storefronts: Record<string, string[]>;
+    ads: {
+        meta?: {
+            campaigns: string[];
+            adAccount?: string | undefined;
+        } | undefined;
+        tiktok?: {
+            campaigns: string[];
+            advertiser?: string | undefined;
+        } | undefined;
+    };
+    competitors: {
+        name?: string | undefined;
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+    }[];
+    data: {
+        commit: boolean;
+    };
+    personas: {
+        name: string;
+        id: string;
+        searches: string[];
+        description?: string | undefined;
+    }[];
+    attribution?: {
+        via: "hosted" | "self";
+        app: string | {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        };
+        url?: string | undefined;
+    } | undefined;
+    aiVisibility?: {
+        intents: Record<string, {
+            label: string;
+            prompts: string[];
+            description?: string | undefined;
+        }[]>;
+        store?: "app-store" | "google-play" | undefined;
+        countries?: string[] | undefined;
+    } | undefined;
+    category?: {
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+        countries?: string[] | undefined;
+        chart?: "top-free" | "top-paid" | "top-grossing" | undefined;
+    } | undefined;
+}, {
+    version: 1;
+    app: {
+        name: string;
+        primaryLocale?: string | undefined;
+    };
+    stores?: {
+        appStore?: {
+            appId: string;
+            platform?: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS" | undefined;
+            via?: "auto" | "local" | "hosted" | undefined;
+            account?: string | undefined;
+        } | undefined;
+        googlePlay?: {
+            packageName: string;
+            via?: "auto" | "local" | "hosted" | undefined;
+            account?: string | undefined;
+            profile?: string | undefined;
+        } | undefined;
+    } | undefined;
+    targets?: Record<string, string[] | undefined> | undefined;
+    storefronts?: Record<string, string[]> | undefined;
+    ads?: {
+        meta?: {
+            campaigns: string[];
+            adAccount?: string | undefined;
+        } | undefined;
+        tiktok?: {
+            campaigns: string[];
+            advertiser?: string | undefined;
+        } | undefined;
+    } | undefined;
+    competitors?: {
+        name?: string | undefined;
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+    }[] | undefined;
+    attribution?: {
+        app: string | {
+            "app-store"?: string | undefined;
+            "google-play"?: string | undefined;
+        };
+        via?: "hosted" | "self" | undefined;
+        url?: string | undefined;
+    } | undefined;
+    data?: {
+        commit?: boolean | undefined;
+    } | undefined;
+    aiVisibility?: {
+        store?: "app-store" | "google-play" | undefined;
+        countries?: string[] | undefined;
+        intents?: Record<string, {
+            label: string;
+            description?: string | undefined;
+            prompts?: string[] | undefined;
+        }[]> | undefined;
+    } | undefined;
+    category?: {
+        appStore?: string | undefined;
+        googlePlay?: string | undefined;
+        countries?: string[] | undefined;
+        chart?: "top-free" | "top-paid" | "top-grossing" | undefined;
+    } | undefined;
+    personas?: {
+        name: string;
+        id: string;
+        description?: string | undefined;
+        searches?: string[] | undefined;
+    }[] | undefined;
+}>;
+export type SpecFile = z.infer<typeof specFileSchema>;
+export type SpecFileInput = z.input<typeof specFileSchema>;
+/**
+ * One App Store locale: `appeeky/store/app-store/<locale>.yaml`.
+ * A field left out is not managed by the spec: it is never diffed or pushed.
+ */
+export declare const appStoreListingSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodString>;
+    promotionalText: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    whatsNew: z.ZodOptional<z.ZodString>;
+    marketingUrl: z.ZodOptional<z.ZodString>;
+    supportUrl: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    description?: string | undefined;
+    name?: string | undefined;
+    subtitle?: string | undefined;
+    keywords?: string | undefined;
+    promotionalText?: string | undefined;
+    whatsNew?: string | undefined;
+    marketingUrl?: string | undefined;
+    supportUrl?: string | undefined;
+}, {
+    description?: string | undefined;
+    name?: string | undefined;
+    subtitle?: string | undefined;
+    keywords?: string | undefined;
+    promotionalText?: string | undefined;
+    whatsNew?: string | undefined;
+    marketingUrl?: string | undefined;
+    supportUrl?: string | undefined;
+}>;
+export type AppStoreListing = z.infer<typeof appStoreListingSchema>;
+/** One Google Play language: `appeeky/store/google-play/<language>.yaml`. */
+export declare const googlePlayListingSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    shortDescription: z.ZodOptional<z.ZodString>;
+    fullDescription: z.ZodOptional<z.ZodString>;
+    video: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    title?: string | undefined;
+    shortDescription?: string | undefined;
+    fullDescription?: string | undefined;
+    video?: string | undefined;
+}, {
+    title?: string | undefined;
+    shortDescription?: string | undefined;
+    fullDescription?: string | undefined;
+    video?: string | undefined;
+}>;
+export type GooglePlayListing = z.infer<typeof googlePlayListingSchema>;
+export type Listing = AppStoreListing | GooglePlayListing;
+export declare const APP_STORE_FIELDS: readonly ["name", "subtitle", "keywords", "promotionalText", "description", "whatsNew", "marketingUrl", "supportUrl"];
+export declare const GOOGLE_PLAY_FIELDS: readonly ["title", "shortDescription", "fullDescription", "video"];
+export type AppStoreField = (typeof APP_STORE_FIELDS)[number];
+export type GooglePlayField = (typeof GOOGLE_PLAY_FIELDS)[number];
+export declare function fieldsFor(store: StoreId): readonly string[];
+/** Listings of one store, keyed by locale. */
+export type StoreListings<T extends Listing = Listing> = Record<string, T>;
+/** A whole spec as loaded from disk. */
+export interface Project {
+    /** Folder that holds `appeeky.spec.yaml`. */
+    root: string;
+    spec: SpecFile;
+    listings: {
+        "app-store": StoreListings<AppStoreListing>;
+        "google-play": StoreListings<GooglePlayListing>;
+    };
+}