@appeeky/spec 0.1.0 → 0.2.0

package/dist/schema.d.ts

@@ -30,16 +30,40 @@ export declare const specFileSchema: z.ZodObject<{
             via: z.ZodDefault<z.ZodEnum<["auto", "local", "hosted"]>>;
             /** Named account of the local `appstore` CLI. */
             account: z.ZodOptional<z.ZodString>;
+            /**
+             * 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.ZodOptional<z.ZodObject<{
+                /** The organization, when the key reaches more than one. */
+                orgId: z.ZodOptional<z.ZodString>;
+                /** Only these campaign ids; default: every campaign for this app. */
+                campaigns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            }, "strict", z.ZodTypeAny, {
+                orgId?: string | undefined;
+                campaigns?: string[] | undefined;
+            }, {
+                orgId?: string | undefined;
+                campaigns?: string[] | undefined;
+            }>>;
         }, "strict", z.ZodTypeAny, {
             appId: string;
             platform: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS";
             via: "auto" | "local" | "hosted";
             account?: string | undefined;
+            searchAds?: {
+                orgId?: string | undefined;
+                campaigns?: string[] | undefined;
+            } | undefined;
         }, {
             appId: string;
             platform?: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS" | undefined;
             via?: "auto" | "local" | "hosted" | undefined;
             account?: string | undefined;
+            searchAds?: {
+                orgId?: string | undefined;
+                campaigns?: string[] | undefined;
+            } | undefined;
         }>>;
         googlePlay: z.ZodOptional<z.ZodObject<{
             packageName: z.ZodString;
@@ -65,6 +89,10 @@ export declare const specFileSchema: z.ZodObject<{
             platform: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS";
             via: "auto" | "local" | "hosted";
             account?: string | undefined;
+            searchAds?: {
+                orgId?: string | undefined;
+                campaigns?: string[] | undefined;
+            } | undefined;
         } | undefined;
         googlePlay?: {
             via: "auto" | "local" | "hosted";
@@ -78,6 +106,10 @@ export declare const specFileSchema: z.ZodObject<{
             platform?: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS" | undefined;
             via?: "auto" | "local" | "hosted" | undefined;
             account?: string | undefined;
+            searchAds?: {
+                orgId?: string | undefined;
+                campaigns?: string[] | undefined;
+            } | undefined;
         } | undefined;
         googlePlay?: {
             packageName: string;
@@ -251,6 +283,10 @@ export declare const specFileSchema: z.ZodObject<{
             description?: string | undefined;
             prompts?: string[] | undefined;
         }>, "many">>>;
+        /** Assistants `visibility scan --local` asks, among those with a key set; defaults to all of them. */
+        models: z.ZodOptional<z.ZodArray<z.ZodEnum<["chatgpt", "claude", "gemini", "perplexity"]>, "many">>;
+        /** Other names the assistants may use for the app, e.g. the brand without the subtitle. */
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         intents: Record<string, {
             label: string;
@@ -259,6 +295,8 @@ export declare const specFileSchema: z.ZodObject<{
         }[]>;
         store?: "app-store" | "google-play" | undefined;
         countries?: string[] | undefined;
+        models?: ("chatgpt" | "claude" | "gemini" | "perplexity")[] | undefined;
+        aliases?: string[] | undefined;
     }, {
         store?: "app-store" | "google-play" | undefined;
         countries?: string[] | undefined;
@@ -267,6 +305,35 @@ export declare const specFileSchema: z.ZodObject<{
             description?: string | undefined;
             prompts?: string[] | undefined;
         }[]> | undefined;
+        models?: ("chatgpt" | "claude" | "gemini" | "perplexity")[] | undefined;
+        aliases?: string[] | undefined;
+    }>>;
+    /**
+     * 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.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        /** Search Console property: "sc-domain:example.com" or "https://example.com/"; defaults to the url's domain. */
+        searchConsole: z.ZodOptional<z.ZodString>;
+        /** Google searches to watch with `seo ranks` and `seo keywords`, per storefront; default: the store targets. */
+        keywords: z.ZodOptional<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodArray<z.ZodString, "many">>>;
+        /** Storefronts to watch; default: the first one under keywords or targets. */
+        countries: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        /** The results page to read; default mobile, where people look for apps. */
+        device: z.ZodOptional<z.ZodEnum<["mobile", "desktop"]>>;
+    }, "strict", z.ZodTypeAny, {
+        url: string;
+        countries?: string[] | undefined;
+        searchConsole?: string | undefined;
+        keywords?: Record<string, string[]> | undefined;
+        device?: "mobile" | "desktop" | undefined;
+    }, {
+        url: string;
+        countries?: string[] | undefined;
+        searchConsole?: string | undefined;
+        keywords?: Record<string, string[]> | undefined;
+        device?: "mobile" | "desktop" | undefined;
     }>>;
     /** Rank in the app's category chart (top 100), recorded daily by `category pull`. */
     category: z.ZodOptional<z.ZodObject<{
@@ -319,6 +386,10 @@ export declare const specFileSchema: z.ZodObject<{
             platform: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS";
             via: "auto" | "local" | "hosted";
             account?: string | undefined;
+            searchAds?: {
+                orgId?: string | undefined;
+                campaigns?: string[] | undefined;
+            } | undefined;
         } | undefined;
         googlePlay?: {
             via: "auto" | "local" | "hosted";
@@ -369,6 +440,15 @@ export declare const specFileSchema: z.ZodObject<{
         }[]>;
         store?: "app-store" | "google-play" | undefined;
         countries?: string[] | undefined;
+        models?: ("chatgpt" | "claude" | "gemini" | "perplexity")[] | undefined;
+        aliases?: string[] | undefined;
+    } | undefined;
+    web?: {
+        url: string;
+        countries?: string[] | undefined;
+        searchConsole?: string | undefined;
+        keywords?: Record<string, string[]> | undefined;
+        device?: "mobile" | "desktop" | undefined;
     } | undefined;
     category?: {
         appStore?: string | undefined;
@@ -388,6 +468,10 @@ export declare const specFileSchema: z.ZodObject<{
             platform?: "IOS" | "MAC_OS" | "TV_OS" | "VISION_OS" | undefined;
             via?: "auto" | "local" | "hosted" | undefined;
             account?: string | undefined;
+            searchAds?: {
+                orgId?: string | undefined;
+                campaigns?: string[] | undefined;
+            } | undefined;
         } | undefined;
         googlePlay?: {
             packageName: string;
@@ -432,6 +516,15 @@ export declare const specFileSchema: z.ZodObject<{
             description?: string | undefined;
             prompts?: string[] | undefined;
         }[]> | undefined;
+        models?: ("chatgpt" | "claude" | "gemini" | "perplexity")[] | undefined;
+        aliases?: string[] | undefined;
+    } | undefined;
+    web?: {
+        url: string;
+        countries?: string[] | undefined;
+        searchConsole?: string | undefined;
+        keywords?: Record<string, string[]> | undefined;
+        device?: "mobile" | "desktop" | undefined;
     } | undefined;
     category?: {
         appStore?: string | undefined;
@@ -464,8 +557,8 @@ export declare const appStoreListingSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     description?: string | undefined;
     name?: string | undefined;
-    subtitle?: string | undefined;
     keywords?: string | undefined;
+    subtitle?: string | undefined;
     promotionalText?: string | undefined;
     whatsNew?: string | undefined;
     marketingUrl?: string | undefined;
@@ -473,8 +566,8 @@ export declare const appStoreListingSchema: z.ZodObject<{
 }, {
     description?: string | undefined;
     name?: string | undefined;
-    subtitle?: string | undefined;
     keywords?: string | undefined;
+    subtitle?: string | undefined;
     promotionalText?: string | undefined;
     whatsNew?: string | undefined;
     marketingUrl?: string | undefined;

package/dist/schema.js

@@ -15,6 +15,19 @@ const appStoreConfig = z
     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
@@ -140,6 +153,28 @@ export const specFileSchema = z
         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(),

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 {};