@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/schema.js

@@ -0,0 +1,253 @@
+import { z } from "zod";
+/** Stores a spec can describe. The ids double as folder names under `appeeky/store/`. */
+export const STORES = ["app-store", "google-play"];
+/** How a store is reached: the local store CLI with your own key, or Appeeky's hosted gateway. */
+export const transportMode = z.enum(["auto", "local", "hosted"]);
+const countryCode = z
+    .string()
+    .regex(/^[a-z]{2}$/i, "Use a two-letter storefront code such as us, gb or tr")
+    .transform((s) => s.toLowerCase());
+const appStoreConfig = z
+    .object({
+    /** Numeric App Store id (or a bundle id; the local CLI resolves it). */
+    appId: z.string().min(1),
+    platform: z.enum(["IOS", "MAC_OS", "TV_OS", "VISION_OS"]).default("IOS"),
+    via: transportMode.default("auto"),
+    /** Named account of the local `appstore` CLI. */
+    account: z.string().optional(),
+    /**
+     * Apple Search Ads on your own API key (ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID, ASA_PRIVATE_KEY):
+     * `search-ads pull` reads this app's campaigns. Without it, Search Ads comes from Appeeky.
+     */
+    searchAds: z
+        .object({
+        /** The organization, when the key reaches more than one. */
+        orgId: z.string().regex(/^\d+$/, "Use the numeric org id from Apple Search Ads → Account Settings").optional(),
+        /** Only these campaign ids; default: every campaign for this app. */
+        campaigns: z.array(z.string().regex(/^\d+$/)).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+const googlePlayConfig = z
+    .object({
+    packageName: z.string().regex(/^[A-Za-z][\w]*(\.[A-Za-z_][\w]*)+$/, "Use the package name, e.g. com.example.app"),
+    via: transportMode.default("auto"),
+    /** Named account of the local `gps` CLI (`gps accounts add`). */
+    account: z.string().optional(),
+    /** Old name for `account`. */
+    profile: z.string().optional(),
+})
+    .strict();
+/** Meta ad campaigns that promote this app. Insights come through the Meta connection in Appeeky. */
+const metaAdsConfig = z
+    .object({
+    /** Ad account (act_…); defaults to the one picked in Appeeky. */
+    adAccount: z.string().optional(),
+    campaigns: z.array(z.string().min(1)).min(1),
+})
+    .strict();
+/** TikTok ad campaigns that promote this app. Reports come through the TikTok connection in Appeeky. */
+const tiktokAdsConfig = z
+    .object({
+    /** Advertiser id; defaults to the one picked in Appeeky. */
+    advertiser: z.string().optional(),
+    campaigns: z.array(z.string().min(1)).min(1),
+})
+    .strict();
+/** One thing people ask AI assistants for, and the prompts that ask it. */
+const aiIntent = z
+    .object({
+    label: z.string().min(8, "An intent label needs at least 8 characters"),
+    description: z.string().optional(),
+    prompts: z.array(z.string().min(15, "A prompt needs at least 15 characters")).default([]),
+})
+    .strict();
+/** Store charts a category rank is read from. */
+export const CHARTS = ["top-free", "top-paid", "top-grossing"];
+/** `appeeky.spec.yaml`: who the app is, where it ships, and what it should be found for. */
+export const specFileSchema = z
+    .object({
+    version: z.literal(1),
+    app: z
+        .object({
+        name: z.string().min(1),
+        /** Locale the store falls back to when a storefront has no localization of its own. */
+        primaryLocale: z.string().default("en-US"),
+    })
+        .strict(),
+    stores: z
+        .object({
+        appStore: appStoreConfig.optional(),
+        googlePlay: googlePlayConfig.optional(),
+    })
+        .strict()
+        .default({}),
+    /** Target keywords per storefront: the searches this app should be found for. */
+    targets: z.record(countryCode, z.array(z.string().min(1)).default([])).default({}),
+    /** Override which listing locales a storefront indexes (App Store). */
+    storefronts: z.record(countryCode, z.array(z.string().min(2)).min(1)).default({}),
+    /**
+     * 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
+        .object({
+        meta: metaAdsConfig.optional(),
+        tiktok: tiktokAdsConfig.optional(),
+    })
+        .strict()
+        .default({}),
+    /** Apps you compete with. `competitors pull` writes each one to appeeky/competitors/. */
+    competitors: z
+        .array(z
+        .object({
+        name: z.string().optional(),
+        appStore: z.string().regex(/^\d+$/, "Use the numeric App Store id").optional(),
+        googlePlay: z.string().optional(),
+    })
+        .strict()
+        .refine((c) => c.appStore || c.googlePlay, "Give an appStore id or a googlePlay package name"))
+        .default([]),
+    /**
+     * 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
+        .object({
+        via: z.enum(["self", "hosted"]).default("hosted"),
+        url: z.string().url().optional(),
+        /**
+         * 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.union([
+            z.string().min(1),
+            z
+                .object({ "app-store": z.string().min(1).optional(), "google-play": z.string().min(1).optional() })
+                .strict()
+                .refine((m) => m["app-store"] || m["google-play"], "give the app id for app-store, google-play or both"),
+        ]),
+    })
+        .strict()
+        .refine((a) => a.via !== "self" || a.url, "via: self needs the url of your Appeeky Analytics server")
+        .optional(),
+    /**
+     * 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.object({ commit: z.boolean().default(false) }).strict().default({}),
+    /**
+     * 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
+        .object({
+        /** Which app to watch when it is on both stores; defaults to the App Store app. */
+        store: z.enum(STORES).optional(),
+        /** Storefronts to watch; defaults to the first storefront under targets. */
+        countries: z.array(countryCode).min(1).optional(),
+        /** What people ask AI assistants, per storefront. `visibility sync` sends them to Appeeky. */
+        intents: z.record(countryCode, z.array(aiIntent)).default({}),
+        /** Assistants `visibility scan --local` asks, among those with a key set; defaults to all of them. */
+        models: z.array(z.enum(["chatgpt", "claude", "gemini", "perplexity"])).min(1).optional(),
+        /** Other names the assistants may use for the app, e.g. the brand without the subtitle. */
+        aliases: z.array(z.string().min(2)).optional(),
+    })
+        .strict()
+        .optional(),
+    /**
+     * The app's website. `seo check` reads it for search and AI readiness; `seo pull` records
+     * its Google Search Console clicks with your own service account.
+     */
+    web: z
+        .object({
+        url: z.string().url(),
+        /** Search Console property: "sc-domain:example.com" or "https://example.com/"; defaults to the url's domain. */
+        searchConsole: z.string().min(3).optional(),
+        /** Google searches to watch with `seo ranks` and `seo keywords`, per storefront; default: the store targets. */
+        keywords: z.record(countryCode, z.array(z.string().min(1))).optional(),
+        /** Storefronts to watch; default: the first one under keywords or targets. */
+        countries: z.array(countryCode).min(1).optional(),
+        /** The results page to read; default mobile, where people look for apps. */
+        device: z.enum(["mobile", "desktop"]).optional(),
+    })
+        .strict()
+        .optional(),
+    /** Rank in the app's category chart (top 100), recorded daily by `category pull`. */
+    category: z
+        .object({
+        /** App Store genre id, e.g. "6013" for Health & Fitness; read from the app when left out. */
+        appStore: z.string().regex(/^\d+$/, "Use the numeric App Store genre id, e.g. 6013").optional(),
+        /** Google Play category, e.g. HEALTH_AND_FITNESS. */
+        googlePlay: z.string().regex(/^[A-Z_]+$/, "Use the Google Play category id, e.g. HEALTH_AND_FITNESS").optional(),
+        /** Defaults to top-paid for a paid App Store app, top-free otherwise. */
+        chart: z.enum(CHARTS).optional(),
+        /** Storefronts to record; defaults to the storefronts under targets. */
+        countries: z.array(countryCode).min(1).optional(),
+    })
+        .strict()
+        .optional(),
+    /** Who the app is for. Experiments, screenshots and UGC refer to these by id. */
+    personas: z
+        .array(z
+        .object({
+        id: z.string().regex(/^[a-z0-9-]+$/),
+        name: z.string().min(1),
+        description: z.string().optional(),
+        /** How this persona searches: seeds for targets and keyword ideas. */
+        searches: z.array(z.string()).default([]),
+    })
+        .strict())
+        .default([]),
+})
+    .strict();
+/**
+ * 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 const appStoreListingSchema = z
+    .object({
+    name: z.string().optional(),
+    subtitle: z.string().optional(),
+    keywords: z.string().optional(),
+    promotionalText: z.string().optional(),
+    description: z.string().optional(),
+    whatsNew: z.string().optional(),
+    marketingUrl: z.string().url().optional(),
+    supportUrl: z.string().url().optional(),
+})
+    .strict();
+/** One Google Play language: `appeeky/store/google-play/<language>.yaml`. */
+export const googlePlayListingSchema = z
+    .object({
+    title: z.string().optional(),
+    shortDescription: z.string().optional(),
+    fullDescription: z.string().optional(),
+    video: z.string().url().optional(),
+})
+    .strict();
+export const APP_STORE_FIELDS = [
+    "name",
+    "subtitle",
+    "keywords",
+    "promotionalText",
+    "description",
+    "whatsNew",
+    "marketingUrl",
+    "supportUrl",
+];
+export const GOOGLE_PLAY_FIELDS = [
+    "title",
+    "shortDescription",
+    "fullDescription",
+    "video",
+];
+export function fieldsFor(store) {
+    return store === "app-store" ? APP_STORE_FIELDS : GOOGLE_PLAY_FIELDS;
+}
+//# sourceMappingURL=schema.js.map

package/dist/screenshots.d.ts

@@ -0,0 +1,23 @@
+import type { Issue } from "./lint.js";
+import type { RemoteState } from "./stores/types.js";
+import type { OpsTransport } from "./transport.js";
+/**
+ * Screenshots live next to the listings:
+ * `appeeky/screenshots/app-store/<locale>/<DISPLAY_TYPE>/01.png`.
+ * `screenshots pull` downloads the live set; `check` validates sizes and counts.
+ */
+export declare function screenshotsDir(root: string): string;
+/** Portrait sizes App Store Connect accepts per display type (landscape is the same, swapped). */
+export declare const SCREENSHOT_SIZES: Record<string, Array<[number, number]>>;
+/** Width and height from a PNG or JPEG header, without decoding the image. */
+export declare function imageSize(file: string): Promise<{
+    width: number;
+    height: number;
+} | null>;
+/** Sizes and counts of every screenshot set in the spec. */
+export declare function checkScreenshots(root: string): Promise<Issue[]>;
+/** Download the live App Store screenshots of every locale into the spec. */
+export declare function pullScreenshots(root: string, transport: OpsTransport, state: RemoteState, options?: {
+    locales?: string[];
+    fetcher?: typeof fetch;
+}): Promise<number>;

package/dist/screenshots.js

@@ -0,0 +1,116 @@
+import { existsSync } from "node:fs";
+import { mkdir, open, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { SPEC_DIR } from "./files.js";
+/**
+ * Screenshots live next to the listings:
+ * `appeeky/screenshots/app-store/<locale>/<DISPLAY_TYPE>/01.png`.
+ * `screenshots pull` downloads the live set; `check` validates sizes and counts.
+ */
+export function screenshotsDir(root) {
+    return join(root, SPEC_DIR, "screenshots", "app-store");
+}
+/** Portrait sizes App Store Connect accepts per display type (landscape is the same, swapped). */
+export const SCREENSHOT_SIZES = {
+    APP_IPHONE_67: [[1290, 2796], [1320, 2868], [1260, 2736]],
+    APP_IPHONE_65: [[1242, 2688], [1284, 2778]],
+    APP_IPHONE_61: [[1179, 2556], [1206, 2622], [1170, 2532]],
+    APP_IPHONE_58: [[1125, 2436], [1080, 2340]],
+    APP_IPHONE_55: [[1242, 2208]],
+    APP_IPAD_PRO_3GEN_129: [[2048, 2732], [2064, 2752]],
+    APP_IPAD_PRO_129: [[2048, 2732]],
+    APP_IPAD_PRO_3GEN_11: [[1668, 2388], [1640, 2360]],
+};
+const MAX_PER_SET = 10;
+/** Width and height from a PNG or JPEG header, without decoding the image. */
+export async function imageSize(file) {
+    const fh = await open(file, "r");
+    try {
+        const head = Buffer.alloc(64 * 1024);
+        const { bytesRead } = await fh.read(head, 0, head.length, 0);
+        const b = head.subarray(0, bytesRead);
+        if (b.length >= 24 && b.readUInt32BE(0) === 0x89504e47)
+            return { width: b.readUInt32BE(16), height: b.readUInt32BE(20) };
+        if (b[0] === 0xff && b[1] === 0xd8) {
+            let i = 2;
+            while (i + 9 < b.length) {
+                if (b[i] !== 0xff)
+                    return null;
+                const marker = b[i + 1];
+                const len = b.readUInt16BE(i + 2);
+                if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+                    return { height: b.readUInt16BE(i + 5), width: b.readUInt16BE(i + 7) };
+                }
+                i += 2 + len;
+            }
+        }
+        return null;
+    }
+    finally {
+        await fh.close();
+    }
+}
+/** Sizes and counts of every screenshot set in the spec. */
+export async function checkScreenshots(root) {
+    const base = screenshotsDir(root);
+    if (!existsSync(base))
+        return [];
+    const issues = [];
+    for (const locale of await readdir(base)) {
+        const localeDir = join(base, locale);
+        if (!(await readdir(localeDir).catch(() => null)))
+            continue;
+        for (const type of await readdir(localeDir)) {
+            const files = (await readdir(join(localeDir, type)).catch(() => [])).filter((f) => /\.(png|jpe?g)$/i.test(f)).sort();
+            const at = (severity, message) => issues.push({ severity, rule: "screenshots", store: "app-store", locale, field: type, message });
+            if (files.length > MAX_PER_SET)
+                at("error", `${type} has ${files.length} screenshots; the limit is ${MAX_PER_SET}.`);
+            const sizes = SCREENSHOT_SIZES[type];
+            if (!sizes)
+                continue;
+            for (const f of files) {
+                const size = await imageSize(join(localeDir, type, f));
+                if (!size)
+                    continue;
+                const ok = sizes.some(([w, h]) => (size.width === w && size.height === h) || (size.width === h && size.height === w));
+                if (!ok)
+                    at("error", `${f} is ${size.width}×${size.height}; ${type} takes ${sizes.map(([w, h]) => `${w}×${h}`).join(", ")}.`);
+            }
+        }
+    }
+    return issues;
+}
+const list = (doc) => {
+    const d = doc?.data;
+    return Array.isArray(d) ? d : [];
+};
+/** Download the live App Store screenshots of every locale into the spec. */
+export async function pullScreenshots(root, transport, state, options = {}) {
+    const ctx = state.context;
+    const doFetch = options.fetcher ?? fetch;
+    let count = 0;
+    for (const [locale, localizationId] of Object.entries(ctx.versionLocIds)) {
+        if (options.locales && !options.locales.includes(locale))
+            continue;
+        const sets = list(await transport.call("appstore_list_screenshot_sets", { localizationId, limit: 50 }));
+        for (const set of sets) {
+            const type = set.attributes?.screenshotDisplayType ?? "UNKNOWN";
+            const shots = list(await transport.call("appstore_list_screenshots", { setId: set.id, limit: 50 }));
+            const dir = join(screenshotsDir(root), locale, type);
+            await mkdir(dir, { recursive: true });
+            for (const [i, shot] of shots.entries()) {
+                const asset = shot.attributes?.imageAsset;
+                if (!asset?.templateUrl || !asset.width || !asset.height)
+                    continue;
+                const url = asset.templateUrl.replace("{w}", String(asset.width)).replace("{h}", String(asset.height)).replace("{f}", "png");
+                const res = await doFetch(url);
+                if (!res.ok)
+                    continue;
+                await writeFile(join(dir, `${String(i + 1).padStart(2, "0")}.png`), Buffer.from(await res.arrayBuffer()));
+                count++;
+            }
+        }
+    }
+    return count;
+}
+//# sourceMappingURL=screenshots.js.map

package/dist/search-ads.d.ts

@@ -0,0 +1,137 @@
+import { type Runner } from "./transport.js";
+import type { MetricSource } from "./metrics.js";
+import type { Project } from "./schema.js";
+export declare const searchAdsDir: (root: string) => string;
+export interface SearchAdsCredentials {
+    clientId: string;
+    teamId: string;
+    keyId: string;
+    privateKey: string;
+    orgId?: string;
+}
+/** ASA_* (or the APPLE_SEARCH_ADS_* spelling); null when no key is set. */
+export declare function readSearchAdsCredentials(env: Record<string, string | undefined>, orgId?: string): Promise<SearchAdsCredentials | null>;
+/** The client secret Apple wants: a JWT signed with the API key (ES256). */
+export declare function clientSecret(creds: SearchAdsCredentials, now?: Date): string;
+/** One Search Ads API call: returns Apple's JSON body, or throws with Apple's message. */
+export type SearchAdsRequest = (method: string, path: string, body?: unknown) => Promise<{
+    data?: unknown;
+}>;
+/** Calls Apple directly with a key from the environment (ASA_*). */
+export declare function directRequest(creds: SearchAdsCredentials, fetcher?: typeof fetch): {
+    request: SearchAdsRequest;
+    org: () => Promise<string>;
+};
+/**
+ * Calls Apple through the App Store Connect CLI (`appstore search-ads call`), with the Search Ads key
+ * saved on an account next to its App Store Connect key, so the private key never leaves the CLI:
+ *   appstore accounts search-ads <account> --client-id … --team-id … --key-id … --private-key-path …
+ */
+export declare function cliRequest(options?: {
+    account?: string;
+    orgId?: string;
+    runner?: Runner;
+    useNpx?: boolean;
+}): {
+    request: SearchAdsRequest;
+    org: () => Promise<string>;
+};
+/**
+ * Where the Search Ads key comes from: ASA_* in the environment (called directly), else the
+ * App Store Connect CLI account in stores.appStore.account (or its default account).
+ */
+export declare function searchAdsSource(project: Project, env?: Record<string, string | undefined>, runner?: Runner): Promise<{
+    label: string;
+    source: SearchAdsCredentials;
+} | {
+    label: string;
+    source: {
+        request: SearchAdsRequest;
+        org: () => Promise<string>;
+    };
+}>;
+export declare class SearchAdsClient {
+    private readonly request;
+    private readonly resolveOrg;
+    /** A key from the environment (calls Apple directly), or another way to call it, such as the appstore CLI. */
+    constructor(source: SearchAdsCredentials | {
+        request: SearchAdsRequest;
+        org: () => Promise<string>;
+    }, fetcher?: typeof fetch);
+    private call;
+    /** The organization the calls go to. */
+    org(): Promise<string>;
+    campaigns(): Promise<Campaign[]>;
+    /** Per campaign and day. */
+    daily(from: string, to: string): Promise<CampaignReportRow[]>;
+    /** Totals per keyword (or per search term) for one campaign. */
+    totals(campaignId: number | string, kind: "keywords" | "searchterms", from: string, to: string): Promise<TotalsRow[]>;
+}
+export interface Campaign {
+    id: number;
+    name: string;
+    adamId: number;
+    status?: string;
+    displayStatus?: string;
+    countriesOrRegions?: string[];
+    /** Where the ads show: only APPSTORE_SEARCH_RESULTS campaigns have keywords and search terms. */
+    supplySources?: string[];
+    adChannelType?: string;
+}
+interface Metrics {
+    impressions?: number;
+    taps?: number;
+    totalInstalls?: number;
+    installs?: number;
+    tapInstalls?: number;
+    localSpend?: {
+        amount: string;
+        currency: string;
+    };
+}
+export interface CampaignReportRow {
+    metadata: {
+        campaignId: number;
+        campaignName?: string;
+        adamId?: number;
+    };
+    granularity?: Array<Metrics & {
+        date: string;
+    }>;
+}
+export interface TotalsRow {
+    metadata: {
+        keyword?: string;
+        searchTermText?: string | null;
+        matchType?: string;
+        countryOrRegion?: string;
+        countriesOrRegions?: string[];
+        keywordStatus?: string;
+    };
+    total?: Metrics;
+}
+export interface SearchAdsPullResult {
+    orgId: string;
+    campaigns: Array<{
+        id: number;
+        name: string;
+        status?: string;
+    }>;
+    currency?: string;
+    last30: {
+        spend: number;
+        installs: number;
+        taps: number;
+        impressions: number;
+    };
+    keywords: number;
+    searchTerms: number;
+    /** Reports that could not be read; the rest were written. */
+    errors: string[];
+    files: string[];
+}
+/** The App Store app's campaigns only: ads for other apps in the same organization stay out. */
+export declare function pullSearchAds(project: Project, client: SearchAdsClient, now?: Date, days?: number): Promise<SearchAdsPullResult>;
+/** `ad_installs` and `cpa` per day from appeeky/search-ads/daily.csv, for the App Store app. */
+export declare function searchAdsMetricSource(root: string): MetricSource | null;
+export {};