@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/appeeky-api.d.ts

@@ -0,0 +1,62 @@
+import type { PopularityLookup } from "./coverage.js";
+import type { RankSource } from "./verify.js";
+import { type MetricSource } from "./metrics.js";
+import type { SpecFile, StoreId } from "./schema.js";
+export declare const APPEEKY_API_URL = "https://api.appeeky.com/v1";
+export interface KeywordMetric {
+    popularity: number;
+    difficulty: number;
+    fetchedAt: string;
+}
+type Fetcher = typeof fetch;
+/**
+ * Small client for the Appeeky API (market data for ASO). Needs an API key
+ * from appeeky.com; every command that uses it also works without it.
+ */
+export declare class AppeekyApi {
+    private readonly apiKey;
+    private readonly base;
+    constructor(apiKey: string, options?: {
+        baseUrl?: string;
+        fetcher?: Fetcher;
+    });
+    private readonly fetcher;
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    /** Any other method, e.g. DELETE. */
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** Keyword opportunities for an app: popular searches it does not rank for yet. */
+    opportunities(appId: string, country: string, store: StoreId): Promise<Array<{
+        keyword: string;
+        popularity: number;
+        difficulty: number | null;
+        source?: string;
+    }>>;
+    /** Popularity (0–100) and difficulty for one keyword in several storefronts. */
+    keywordMetrics(keyword: string, countries: string[], store: StoreId): Promise<Record<string, KeywordMetric>>;
+}
+/**
+ * Fetch popularity for every target keyword, reusing a 7-day cache in
+ * `.appeeky/cache/metrics.json` so repeated runs stay inside the API's
+ * per-minute limit. Returns a lookup for the coverage report.
+ */
+export declare function loadPopularity(root: string, api: AppeekyApi | undefined, targets: Record<string, string[]>, stores: StoreId[], onProgress?: (done: number, total: number) => void): Promise<{
+    lookup: PopularityLookup;
+    fetched: number;
+    failed: string[];
+}>;
+/** Live ranks from the Appeeky API (App Store and Google Play), 10 keywords per request. */
+export declare function appeekyRankSource(api: AppeekyApi): RankSource;
+/**
+ * Outcome metrics (store analytics, Search Ads, RevenueCat) for an app in the
+ * user's Appeeky list. Apps that are not in the list, or have nothing
+ * connected, give null.
+ */
+export declare function appeekyMetricSource(api: AppeekyApi): MetricSource;
+/** Spend and installs of the Meta campaigns listed under `ads.meta`, through the Meta connection in Appeeky. */
+export declare function metaMetricSource(api: AppeekyApi, config: NonNullable<SpecFile["ads"]["meta"]>): MetricSource;
+/** Spend and conversions of the TikTok campaigns listed under `ads.tiktok`, through the TikTok connection in Appeeky. */
+export declare function tiktokMetricSource(api: AppeekyApi, config: NonNullable<SpecFile["ads"]["tiktok"]>): MetricSource;
+/** Every outcome source a spec can use: the app's connected data, plus the Meta and TikTok campaigns it lists. */
+export declare function metricSourceFor(api: AppeekyApi, spec: SpecFile): MetricSource;
+export {};

package/dist/appeeky-api.js

@@ -0,0 +1,240 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { combineSources, summarizeMeta, summarizeMetrics, summarizeTikTok, } from "./metrics.js";
+import { normalize } from "./text.js";
+export const APPEEKY_API_URL = "https://api.appeeky.com/v1";
+/**
+ * Small client for the Appeeky API (market data for ASO). Needs an API key
+ * from appeeky.com; every command that uses it also works without it.
+ */
+export class AppeekyApi {
+    apiKey;
+    base;
+    constructor(apiKey, options = {}) {
+        this.apiKey = apiKey;
+        this.base = (options.baseUrl ?? APPEEKY_API_URL).replace(/\/$/, "");
+        this.fetcher = options.fetcher ?? fetch;
+    }
+    fetcher;
+    async get(path, query = {}) {
+        const url = new URL(this.base + path);
+        for (const [k, v] of Object.entries(query))
+            url.searchParams.set(k, v);
+        const res = await this.fetcher(url, { headers: { "X-API-Key": this.apiKey, "User-Agent": "appeeky-spec" } });
+        const body = (await res.json().catch(() => null));
+        if (!res.ok) {
+            const retry = res.headers.get("retry-after");
+            throw new Error(`Appeeky API ${path}: ${body?.error?.message ?? `HTTP ${res.status}`}${retry ? ` (retry after ${retry}s)` : ""}`);
+        }
+        return body?.data;
+    }
+    async post(path, body) {
+        const res = await this.fetcher(this.base + path, {
+            method: "POST",
+            headers: { "X-API-Key": this.apiKey, "Content-Type": "application/json", "User-Agent": "appeeky-spec" },
+            body: JSON.stringify(body),
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok)
+            throw new Error(`Appeeky API ${path}: ${json?.error?.message ?? `HTTP ${res.status}`}`);
+        return json?.data;
+    }
+    /** Any other method, e.g. DELETE. */
+    async request(method, path, body) {
+        const res = await this.fetcher(this.base + path, {
+            method,
+            headers: { "X-API-Key": this.apiKey, "User-Agent": "appeeky-spec", ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok)
+            throw new Error(`Appeeky API ${path}: ${json?.error?.message ?? `HTTP ${res.status}`}`);
+        return json?.data;
+    }
+    /** Keyword opportunities for an app: popular searches it does not rank for yet. */
+    async opportunities(appId, country, store) {
+        const data = await this.get(`/aso/opportunities/${encodeURIComponent(appId)}`, { country, platform: store === "app-store" ? "apple" : "google" });
+        return (data?.opportunities ?? [])
+            .filter((o) => !o.isBrandTerm)
+            .map((o) => ({ keyword: o.keyword, popularity: o.volumeScore, difficulty: o.difficulty, source: o.source }));
+    }
+    /** Popularity (0–100) and difficulty for one keyword in several storefronts. */
+    async keywordMetrics(keyword, countries, store) {
+        const data = await this.get("/keywords/metrics", {
+            keyword,
+            countries: countries.join(","),
+            platform: store === "app-store" ? "apple" : "google",
+        });
+        const now = new Date().toISOString();
+        const out = {};
+        for (const [cc, m] of Object.entries(data?.results ?? {})) {
+            out[cc] = { popularity: m.volumeScore ?? 0, difficulty: m.difficulty ?? 0, fetchedAt: now };
+        }
+        return out;
+    }
+}
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+function cacheKey(store, country, keyword) {
+    return `${store}:${country}:${normalize(keyword).trim()}`;
+}
+/**
+ * Fetch popularity for every target keyword, reusing a 7-day cache in
+ * `.appeeky/cache/metrics.json` so repeated runs stay inside the API's
+ * per-minute limit. Returns a lookup for the coverage report.
+ */
+export async function loadPopularity(root, api, targets, stores, onProgress) {
+    const file = join(root, ".appeeky", "cache", "metrics.json");
+    let cache = {};
+    if (existsSync(file)) {
+        try {
+            cache = JSON.parse(await readFile(file, "utf8"));
+        }
+        catch {
+            cache = {};
+        }
+    }
+    const fresh = (m) => m && Date.now() - Date.parse(m.fetchedAt) < CACHE_TTL_MS;
+    // One request per keyword covers every storefront that targets it.
+    const byKeyword = new Map();
+    for (const [country, keywords] of Object.entries(targets)) {
+        for (const k of keywords) {
+            const key = normalize(k).trim();
+            if (!byKeyword.has(key))
+                byKeyword.set(key, new Set());
+            byKeyword.get(key).add(country);
+        }
+    }
+    let fetched = 0;
+    const failed = [];
+    if (api) {
+        const jobs = [];
+        for (const store of stores) {
+            for (const [keyword, countries] of byKeyword) {
+                const stale = [...countries].filter((cc) => !fresh(cache[cacheKey(store, cc, keyword)]));
+                if (stale.length > 0)
+                    jobs.push({ store, keyword, countries: stale });
+            }
+        }
+        for (const [i, job] of jobs.entries()) {
+            // The API allows 10 metrics requests a minute per key; pace after the first burst.
+            if (i >= 10)
+                await new Promise((r) => setTimeout(r, 6_100));
+            try {
+                const metrics = await api.keywordMetrics(job.keyword, job.countries, job.store);
+                for (const [cc, m] of Object.entries(metrics))
+                    cache[cacheKey(job.store, cc, job.keyword)] = m;
+                fetched++;
+            }
+            catch (err) {
+                failed.push(`${job.keyword}: ${err.message}`);
+                if (/retry after|burst|429/i.test(err.message))
+                    break;
+            }
+            onProgress?.(i + 1, jobs.length);
+        }
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, JSON.stringify(cache, null, 2));
+    }
+    const lookup = (keyword, country, store) => {
+        const m = cache[cacheKey(store, country, keyword)];
+        return m ? { popularity: m.popularity, difficulty: m.difficulty } : undefined;
+    };
+    return { lookup, fetched, failed };
+}
+/** Live ranks from the Appeeky API (App Store and Google Play), 10 keywords per request. */
+export function appeekyRankSource(api) {
+    return {
+        label: "Appeeky API",
+        async ranks(store, appId, country, keywords) {
+            const out = {};
+            for (let i = 0; i < keywords.length; i += 10) {
+                const batch = keywords.slice(i, i + 10);
+                const data = await api.post(`/apps/${encodeURIComponent(appId)}/keywords/verify`, { keywords: batch, country, platform: store === "app-store" ? "apple" : "google" });
+                for (const r of data?.results ?? [])
+                    out[normalize(r.keyword).trim()] = r.rank ?? null;
+            }
+            return out;
+        },
+    };
+}
+/**
+ * Outcome metrics (store analytics, Search Ads, RevenueCat) for an app in the
+ * user's Appeeky list. Apps that are not in the list, or have nothing
+ * connected, give null.
+ */
+export function appeekyMetricSource(api) {
+    return {
+        label: "Appeeky (store analytics, Search Ads, RevenueCat)",
+        async window(_store, appId, from, to) {
+            // The API takes an inclusive last day; windows here end exclusively.
+            const last = new Date(Date.parse(to) - 86_400_000).toISOString().slice(0, 10);
+            try {
+                const data = await api.get(`/user/apps/${encodeURIComponent(appId)}/metrics`, { from, to: last });
+                if (!data)
+                    return null;
+                const window = summarizeMetrics(data, from, to);
+                return Object.keys(window.values).length > 0 ? window : null;
+            }
+            catch (e) {
+                if (/not found/i.test(e.message))
+                    return null;
+                throw e;
+            }
+        },
+    };
+}
+/** The window's inclusive last day; windows here end exclusively. */
+const lastDay = (to) => new Date(Date.parse(to) - 86_400_000).toISOString().slice(0, 10);
+const daysIn = (from, to) => Math.max(1, Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000));
+/** Spend and installs of the Meta campaigns listed under `ads.meta`, through the Meta connection in Appeeky. */
+export function metaMetricSource(api, config) {
+    return {
+        label: "Meta Ads",
+        async window(_store, _appId, from, to) {
+            const rows = [];
+            for (const campaign of config.campaigns) {
+                const data = await api.get("/connect/meta-ads/insights", {
+                    targetType: "campaign",
+                    targetId: campaign,
+                    since: from,
+                    until: lastDay(to),
+                    fields: "spend,actions",
+                    ...(config.adAccount ? { adAccountId: config.adAccount } : {}),
+                });
+                rows.push(...(data?.data ?? []));
+            }
+            const values = summarizeMeta(rows, daysIn(from, to));
+            return Object.keys(values).length > 0 ? { from, to, days: daysIn(from, to), values } : null;
+        },
+    };
+}
+/** Spend and conversions of the TikTok campaigns listed under `ads.tiktok`, through the TikTok connection in Appeeky. */
+export function tiktokMetricSource(api, config) {
+    return {
+        label: "TikTok Ads",
+        async window(_store, _appId, from, to) {
+            const data = await api.get("/connect/tiktok-ads/report", {
+                dataLevel: "AUCTION_CAMPAIGN",
+                dimensions: "campaign_id",
+                metrics: "spend,conversion",
+                startDate: from,
+                endDate: lastDay(to),
+                pageSize: "1000",
+                ...(config.advertiser ? { advertiserId: config.advertiser } : {}),
+            });
+            const values = summarizeTikTok(data?.list ?? [], config.campaigns, daysIn(from, to));
+            return Object.keys(values).length > 0 ? { from, to, days: daysIn(from, to), values } : null;
+        },
+    };
+}
+/** Every outcome source a spec can use: the app's connected data, plus the Meta and TikTok campaigns it lists. */
+export function metricSourceFor(api, spec) {
+    const sources = [appeekyMetricSource(api)];
+    if (spec.ads.meta)
+        sources.push(metaMetricSource(api, spec.ads.meta));
+    if (spec.ads.tiktok)
+        sources.push(tiktokMetricSource(api, spec.ads.tiktok));
+    return sources.length === 1 ? sources[0] : combineSources(sources);
+}
+//# sourceMappingURL=appeeky-api.js.map

package/dist/attribution-setup.d.ts

@@ -0,0 +1,28 @@
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { SpecFile, StoreId } from "./schema.js";
+/**
+ * `attribution init`: create (or find) the app in Appeeky Analytics for each store in the
+ * spec, and say what to put in the app and in RevenueCat. Self-hosted, it talks to your
+ * server with its admin token; hosted, it turns attribution on for the app in Appeeky.
+ */
+export interface AttributionApp {
+    store: StoreId;
+    /** The id the spec reads: the server's app id, or the store id when hosted. */
+    id: string;
+    publishableKey: string;
+    /** The SDK's ingest URL. */
+    endpoint: string;
+    created: boolean;
+}
+export declare function specStores(spec: SpecFile): Array<{
+    store: StoreId;
+    storeId: string;
+}>;
+/** Self-hosted: find each store's app on the server by its store id, or create it. */
+export declare function initSelfHosted(spec: SpecFile, url: string, token: string, fetcher?: typeof fetch): Promise<AttributionApp[]>;
+/** Hosted: turn attribution on for each store's app in Appeeky (already on is fine). */
+export declare function initHosted(spec: SpecFile, api: AppeekyApi): Promise<AttributionApp[]>;
+/** The `attribution:` block for these apps: one id, or one per store when they differ. */
+export declare function attributionBlock(via: "self" | "hosted", apps: AttributionApp[], url?: string): NonNullable<SpecFile["attribution"]>;
+/** What to do next, in the app and in RevenueCat. */
+export declare function nextSteps(via: "self" | "hosted", apps: AttributionApp[], url?: string): string[];

package/dist/attribution-setup.js

@@ -0,0 +1,65 @@
+const PLATFORM = { "app-store": "apple", "google-play": "google" };
+export function specStores(spec) {
+    return [
+        ...(spec.stores.appStore?.appId ? [{ store: "app-store", storeId: spec.stores.appStore.appId }] : []),
+        ...(spec.stores.googlePlay?.packageName ? [{ store: "google-play", storeId: spec.stores.googlePlay.packageName }] : []),
+    ];
+}
+/** Self-hosted: find each store's app on the server by its store id, or create it. */
+export async function initSelfHosted(spec, url, token, fetcher = fetch) {
+    const base = url.replace(/\/$/, "");
+    const call = async (path, init = {}) => {
+        const res = await fetcher(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+        const body = (await res.json().catch(() => null));
+        if (!res.ok)
+            throw new Error(`${path}: ${body?.error?.message ?? `HTTP ${res.status}`}`);
+        return body;
+    };
+    const { apps } = await call("/v1/apps");
+    const out = [];
+    for (const { store, storeId } of specStores(spec)) {
+        const found = apps.find((a) => a.platform === PLATFORM[store] && a.storeAppId === storeId);
+        const app = found ??
+            (await call("/v1/apps", {
+                method: "POST",
+                body: JSON.stringify({ name: spec.app.name, platform: PLATFORM[store], storeAppId: storeId }),
+            }));
+        out.push({ store, id: app.id, publishableKey: app.publishableKey, endpoint: `${base}/v1/ingest`, created: !found });
+    }
+    return out;
+}
+/** Hosted: turn attribution on for each store's app in Appeeky (already on is fine). */
+export async function initHosted(spec, api) {
+    const out = [];
+    for (const { store, storeId } of specStores(spec)) {
+        const res = await api.post(`/analytics/apps/${encodeURIComponent(storeId)}/enable`, {});
+        const body = res && "data" in res ? res.data : res;
+        out.push({ store, id: storeId, publishableKey: body.publishableKey, endpoint: body.endpoint, created: true });
+    }
+    return out;
+}
+/** The `attribution:` block for these apps: one id, or one per store when they differ. */
+export function attributionBlock(via, apps, url) {
+    const ids = [...new Set(apps.map((a) => a.id))];
+    const app = ids.length === 1 ? ids[0] : Object.fromEntries(apps.map((a) => [a.store, a.id]));
+    return { via, ...(via === "self" && url ? { url: url.replace(/\/$/, "") } : {}), app };
+}
+/** What to do next, in the app and in RevenueCat. */
+export function nextSteps(via, apps, url) {
+    const lines = ["In the app (React Native and Expo; Swift, Kotlin and Flutter work the same way):", ""];
+    const endpoint = via === "self" && apps[0] ? `, endpoint: "${apps[0].endpoint}"` : "";
+    const ios = apps.find((a) => a.store === "app-store");
+    const android = apps.find((a) => a.store === "google-play");
+    // One codebase, a key per platform.
+    const key = ios && android ? `Platform.OS === "ios" ? "${ios.publishableKey}" : "${android.publishableKey}"` : `"${(ios ?? android).publishableKey}"`;
+    lines.push(`  Appeeky.init({ key: ${key}${endpoint} });`);
+    lines.push("  Appeeky.identify(await Purchases.getAppUserID());", "");
+    if (via === "self") {
+        lines.push("In RevenueCat, Integrations → Webhooks:", `  URL: ${url.replace(/\/$/, "")}/v1/webhooks/revenuecat`, "  Authorization header: your REVENUECAT_WEBHOOK_SECRET", "  Environment: production");
+    }
+    else {
+        lines.push("Connect RevenueCat in Appeeky if it is not connected: purchases reach attribution from there.");
+    }
+    return lines;
+}
+//# sourceMappingURL=attribution-setup.js.map

package/dist/attribution.d.ts

@@ -0,0 +1,121 @@
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { MetricSource } from "./metrics.js";
+import type { SpecFile, StoreId } from "./schema.js";
+/**
+ * Install attribution from Appeeky Analytics: which source each install came from
+ * (organic store search, Apple Search Ads down to the keyword, a smart link, the
+ * Google Play referrer) and the trials and revenue it led to.
+ *
+ * Two ways to reach it, like the stores:
+ *   via: self    your own server on Cloudflare (apps/worker), with ATTRIBUTION_TOKEN (its ADMIN_TOKEN)
+ *   via: hosted  Appeeky's hosted service, through the Appeeky API with APPEEKY_API_KEY
+ */
+export type AttributionConfig = NonNullable<SpecFile["attribution"]>;
+type Fetcher = typeof fetch;
+export interface AttributionClient {
+    readonly label: string;
+    get<T>(view: string, query?: Record<string, string>): Promise<T>;
+    post<T>(view: string, body: unknown): Promise<T>;
+}
+export interface SourceRow {
+    source: string;
+    campaign: string | null;
+    installs: number;
+    trials: number;
+    payers: number;
+    revenueUsd: number;
+}
+export interface Summary {
+    days: number;
+    since: string;
+    installs: number;
+    revenueUsd: number;
+    bySource: SourceRow[];
+    unattributedRevenueUsd: number;
+}
+export interface BreakdownRow {
+    key: string | null;
+    count: number;
+    revenueUsd: number | null;
+    payers: number;
+    campaign?: string | null;
+    country?: string | null;
+}
+export interface LinkStats {
+    link: {
+        id: string;
+        slug: string;
+        name: string;
+        campaign: string;
+        channel: string | null;
+    };
+    clicks: {
+        total: number;
+        ios: number;
+        android: number;
+        other: number;
+    };
+    installs: number;
+    revenueUsd: number;
+}
+export declare function selfHostedClient(config: AttributionConfig, token: string, fetcher?: Fetcher, app?: string): AttributionClient;
+export declare function hostedClient(config: AttributionConfig, api: AppeekyApi, app?: string): AttributionClient;
+/** The Appeeky Analytics app for each store: one id for every store in the spec, or one per store. */
+export declare function attributionApps(spec: SpecFile): Partial<Record<StoreId, string>>;
+export type AttributionClients = Partial<Record<StoreId, AttributionClient>>;
+/** A client per store the spec's `attribution:` covers, or why there are none. */
+export declare function attributionClients(spec: SpecFile, api: AppeekyApi | undefined, env?: NodeJS.ProcessEnv): AttributionClients | {
+    missing: string;
+};
+/**
+ * The client for one store, or the first one. Without a store, Google Play comes first:
+ * its install referrer is what lets a smart link count installs.
+ */
+export declare function attributionClient(spec: SpecFile, api: AppeekyApi | undefined, env?: NodeJS.ProcessEnv, store?: StoreId): AttributionClient | {
+    missing: string;
+};
+/** Which store the client `attributionClient` picks without one belongs to. */
+export declare function linkStore(spec: SpecFile): StoreId | undefined;
+export declare const isClient: (c: AttributionClient | {
+    missing: string;
+}) => c is AttributionClient;
+export declare const hasClients: (c: AttributionClients | {
+    missing: string;
+}) => c is AttributionClients;
+/** Installs from organic store search (App Store or Google Play), the ones a listing change moves. */
+export declare function organicRow(summary: Summary): {
+    installs: number;
+    payers: number;
+    revenueUsd: number;
+};
+/**
+ * Organic installs and what they paid, around a push. The server answers for the
+ * installs first seen in the last N days, so a window that ends before today is the
+ * difference of two answers. Revenue counts what those installs paid up to now, so
+ * an older window has had longer to pay: a rise in organic revenue after a push is
+ * a conservative reading.
+ */
+export declare function attributionMetricSource(clients: AttributionClient | AttributionClients, now?: Date): MetricSource;
+/** A smart link for an experiment: one URL that sends each visitor to the right store, counted to the install. */
+export declare function createExperimentLink(client: AttributionClient, experimentId: string, stores: {
+    appStoreId?: string;
+    packageName?: string;
+}, channel?: string): Promise<{
+    slug: string;
+    id: string;
+}>;
+/** Clicks, installs and revenue of one smart link over the last 30 days. */
+export declare function linkResult(client: AttributionClient, slug: string): Promise<LinkStats | null>;
+/**
+ * On iOS the App Store passes nothing from a link click to the installed app, and the
+ * service does not fingerprint devices, so a new iOS install is never tied to a click.
+ * The SDK reads the link only on the app's first launch, so on iOS a link install is
+ * counted only when that first launch comes through the link (a deep link opening an
+ * app that was installed but never opened). Link installs are, in practice, Google
+ * Play installs (the install referrer). For an App Store only app, measure clicks, or
+ * organic installs around the post.
+ */
+export declare const IOS_LINK_NOTE: string;
+/** An installs or revenue metric on a link that can only send people to the App Store. */
+export declare function iosOnlyLink(spec: SpecFile, metric: string): boolean;
+export {};