@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/attribution.js

@@ -0,0 +1,170 @@
+/** Both the self-hosted server (plain JSON) and the Appeeky API (`{ data }`) answer here. */
+const unwrap = (body) => (body && typeof body === "object" && "data" in body ? body.data : body);
+export function selfHostedClient(config, token, fetcher = fetch, app = appIdsOf(config)[0]) {
+    if (!config.url)
+        throw new Error("attribution.url is needed with via: self (your Appeeky Analytics server).");
+    const base = `${config.url.replace(/\/$/, "")}/v1/apps/${encodeURIComponent(app)}`;
+    const call = async (view, init, query = {}) => {
+        const url = new URL(`${base}/${view}`);
+        for (const [k, v] of Object.entries(query))
+            url.searchParams.set(k, v);
+        const res = await fetcher(url, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...(init.headers ?? {}) } });
+        const body = (await res.json().catch(() => null));
+        if (!res.ok)
+            throw new Error(`Attribution ${view}: ${body?.error?.message ?? `HTTP ${res.status}`}`);
+        return unwrap(body);
+    };
+    return {
+        label: "Appeeky Analytics (self-hosted)",
+        get: (view, query) => call(view, { method: "GET" }, query),
+        post: (view, body) => call(view, { method: "POST", body: JSON.stringify(body) }),
+    };
+}
+export function hostedClient(config, api, app = appIdsOf(config)[0]) {
+    const base = `/analytics/apps/${encodeURIComponent(app)}`;
+    return {
+        label: "Appeeky Analytics",
+        get: async (view, query) => unwrap(await api.get(`${base}/${view}`, query)),
+        post: async (view, body) => unwrap(await api.post(`${base}/${view}`, body)),
+    };
+}
+function appIdsOf(config) {
+    return typeof config.app === "string" ? [config.app] : [config.app["app-store"], config.app["google-play"]].filter((x) => Boolean(x));
+}
+/** The Appeeky Analytics app for each store: one id for every store in the spec, or one per store. */
+export function attributionApps(spec) {
+    const config = spec.attribution;
+    if (!config)
+        return {};
+    if (typeof config.app !== "string")
+        return { ...config.app };
+    const out = {};
+    if (spec.stores.appStore)
+        out["app-store"] = config.app;
+    if (spec.stores.googlePlay)
+        out["google-play"] = config.app;
+    if (!out["app-store"] && !out["google-play"])
+        out["app-store"] = config.app;
+    return out;
+}
+/** A client per store the spec's `attribution:` covers, or why there are none. */
+export function attributionClients(spec, api, env = process.env) {
+    const config = spec.attribution;
+    if (!config)
+        return { missing: "No attribution: in appeeky.spec.yaml." };
+    if (config.via === "self" && !env.ATTRIBUTION_TOKEN)
+        return { missing: "Set ATTRIBUTION_TOKEN to your Appeeky Analytics server's ADMIN_TOKEN." };
+    if (config.via !== "self" && !api)
+        return { missing: "Set APPEEKY_API_KEY to read attribution from Appeeky." };
+    const made = new Map();
+    const out = {};
+    for (const [store, app] of Object.entries(attributionApps(spec))) {
+        // One app id shared by both stores is one client.
+        if (!made.has(app))
+            made.set(app, config.via === "self" ? selfHostedClient(config, env.ATTRIBUTION_TOKEN, fetch, app) : hostedClient(config, api, app));
+        out[store] = made.get(app);
+    }
+    return out;
+}
+/**
+ * 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 function attributionClient(spec, api, env = process.env, store) {
+    const clients = attributionClients(spec, api, env);
+    if ("missing" in clients)
+        return clients;
+    const client = store ? clients[store] : (clients["google-play"] ?? clients["app-store"]);
+    return client ?? { missing: `No attribution app for ${store} in appeeky.spec.yaml.` };
+}
+/** Which store the client `attributionClient` picks without one belongs to. */
+export function linkStore(spec) {
+    const apps = attributionApps(spec);
+    return apps["google-play"] ? "google-play" : apps["app-store"] ? "app-store" : undefined;
+}
+export const isClient = (c) => !("missing" in c);
+export const hasClients = (c) => !("missing" in c);
+/** Installs from organic store search (App Store or Google Play), the ones a listing change moves. */
+export function organicRow(summary) {
+    const rows = summary.bySource.filter((r) => r.source === "organic");
+    return {
+        installs: rows.reduce((n, r) => n + r.installs, 0),
+        payers: rows.reduce((n, r) => n + r.payers, 0),
+        revenueUsd: rows.reduce((n, r) => n + r.revenueUsd, 0),
+    };
+}
+const DAY = 86_400_000;
+/**
+ * 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 function attributionMetricSource(clients, now = new Date()) {
+    const daysBack = (iso) => Math.max(0, Math.round((now.getTime() - Date.parse(iso)) / DAY));
+    const forStore = (store) => ("get" in clients ? clients : clients[store]);
+    const any = "get" in clients ? clients : Object.values(clients)[0];
+    return {
+        label: any?.label ?? "Appeeky Analytics",
+        async window(store, _appId, from, to) {
+            const client = forStore(store);
+            if (!client)
+                return null;
+            const summary = (days) => client.get("summary", { days: String(days) });
+            const fromBack = daysBack(from);
+            const toBack = daysBack(to);
+            if (fromBack <= toBack || fromBack > 180)
+                return null;
+            const all = organicRow(await summary(fromBack));
+            const later = toBack > 0 ? organicRow(await summary(toBack)) : { installs: 0, payers: 0, revenueUsd: 0 };
+            const days = fromBack - toBack;
+            const installs = all.installs - later.installs;
+            if (installs <= 0)
+                return null;
+            return {
+                from,
+                to,
+                days,
+                values: {
+                    organic_installs: installs / days,
+                    organic_revenue: (all.revenueUsd - later.revenueUsd) / days,
+                    organic_paid: (all.payers - later.payers) / installs,
+                },
+                currency: "USD",
+            };
+        },
+    };
+}
+/** A smart link for an experiment: one URL that sends each visitor to the right store, counted to the install. */
+export async function createExperimentLink(client, experimentId, stores, channel) {
+    return client.post("links", {
+        name: experimentId,
+        campaign: experimentId,
+        ...(stores.appStoreId ? { iosUrl: `https://apps.apple.com/app/id${stores.appStoreId}` } : {}),
+        ...(stores.packageName ? { androidUrl: `https://play.google.com/store/apps/details?id=${stores.packageName}` } : {}),
+        ...(channel ? { channel } : {}),
+    });
+}
+/** Clicks, installs and revenue of one smart link over the last 30 days. */
+export async function linkResult(client, slug) {
+    const data = await client.get("links", { range: "30d" });
+    return data?.links?.find((l) => l.link.slug === slug) ?? 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 const IOS_LINK_NOTE = "  iOS: the App Store does not pass a link to a new install, so link installs and revenue are, in practice, Google Play\n" +
+    "  installs. For this App Store only app use --metric link_clicks (or organic_installs).";
+/** An installs or revenue metric on a link that can only send people to the App Store. */
+export function iosOnlyLink(spec, metric) {
+    const ios = spec.attribution ? linkStore(spec) === "app-store" : Boolean(spec.stores.appStore && !spec.stores.googlePlay);
+    return ios && (metric === "link_installs" || metric === "link_revenue");
+}
+//# sourceMappingURL=attribution.js.map

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+await run();
+//# sourceMappingURL=bin.js.map

package/dist/category.d.ts

@@ -0,0 +1,71 @@
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { MetricSource } from "./metrics.js";
+import type { Chart, Project, StoreId } from "./schema.js";
+/**
+ * The app's rank in its category chart, one row per day, store and storefront in
+ * appeeky/category.csv. Ranks are public, so the file is committed with the spec
+ * and `verify` reads it as the `category_rank` metric.
+ *
+ * App Store charts come from Apple's public RSS (no key). Google Play charts come
+ * through the Appeeky API (APPEEKY_API_KEY).
+ */
+/** Charts list the top 100 apps; an app below that is "not in the chart". */
+export declare const CHART_SIZE = 100;
+export declare const categoryFile: (root: string) => string;
+export interface CategoryRank {
+    date: string;
+    /** Category name for people; not written to the file. */
+    name?: string;
+    store: StoreId;
+    country: string;
+    chart: Chart;
+    category: string;
+    /** null = not in the top 100. */
+    rank: number | null;
+}
+export interface ChartSource {
+    readonly label: string;
+    /** App ids in chart order, best first, or null when the chart could not be read. */
+    chart(store: StoreId, category: string, country: string, chart: Chart): Promise<string[] | null>;
+}
+/** Apple's public category charts: the real per-genre chart, not the overall one filtered. */
+export declare function appleChartSource(fetcher?: typeof fetch): ChartSource;
+/** Google Play category charts through the Appeeky API. */
+export declare function playChartSource(api: AppeekyApi): ChartSource;
+/** Both stores: Apple's RSS for the App Store, the Appeeky API for Google Play when there is a key. */
+export declare function chartSources(api: AppeekyApi | undefined, fetcher?: typeof fetch): ChartSource;
+/** The App Store app's genre and whether it is paid, from Apple's public lookup. */
+export declare function appleAppInfo(appId: string, country: string, fetcher?: typeof fetch): Promise<{
+    genreId: string;
+    genre: string;
+    paid: boolean;
+} | null>;
+export interface CategoryPlan {
+    store: StoreId;
+    appId: string;
+    category: string;
+    chart: Chart;
+    countries: string[];
+    /** Category name for people, e.g. "Health & Fitness". */
+    name?: string;
+}
+/** Which charts to read: the configured category, or the App Store app's own genre. */
+export declare function categoryPlans(project: Project, fetcher?: typeof fetch): Promise<{
+    plans: CategoryPlan[];
+    notes: string[];
+}>;
+/** Read every planned chart once and find the app in it. Charts that cannot be read are left out. */
+export declare function readCategoryRanks(plans: CategoryPlan[], source: ChartSource, now?: Date): Promise<{
+    ranks: CategoryRank[];
+    failed: string[];
+}>;
+export declare function readCategoryHistory(root: string): Promise<CategoryRank[]>;
+/** Add today's ranks to appeeky/category.csv (one row per day, store, storefront and chart). */
+export declare function saveCategoryRanks(root: string, ranks: CategoryRank[]): Promise<string>;
+/** The latest row before `date` for the same store, storefront and chart. */
+export declare function previousRank(history: CategoryRank[], r: CategoryRank): CategoryRank | undefined;
+/**
+ * `category_rank` from the recorded history: the average rank over the days in
+ * the window, across the recorded storefronts. Needs two recorded days.
+ */
+export declare function categoryMetricSource(root: string): MetricSource;

package/dist/category.js

@@ -0,0 +1,198 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { mergeCsv } from "./data.js";
+import { SPEC_DIR } from "./files.js";
+import { rankAppIds } from "./verify.js";
+/**
+ * The app's rank in its category chart, one row per day, store and storefront in
+ * appeeky/category.csv. Ranks are public, so the file is committed with the spec
+ * and `verify` reads it as the `category_rank` metric.
+ *
+ * App Store charts come from Apple's public RSS (no key). Google Play charts come
+ * through the Appeeky API (APPEEKY_API_KEY).
+ */
+/** Charts list the top 100 apps; an app below that is "not in the chart". */
+export const CHART_SIZE = 100;
+export const categoryFile = (root) => join(root, SPEC_DIR, "category.csv");
+const RSS_FEED = {
+    "top-free": "topfreeapplications",
+    "top-paid": "toppaidapplications",
+    "top-grossing": "topgrossingapplications",
+};
+/** Apple's public category charts: the real per-genre chart, not the overall one filtered. */
+export function appleChartSource(fetcher = fetch) {
+    return {
+        label: "App Store charts",
+        async chart(store, category, country, chart) {
+            if (store !== "app-store")
+                return null;
+            const url = `https://itunes.apple.com/${encodeURIComponent(country)}/rss/${RSS_FEED[chart]}/limit=${CHART_SIZE}/genre=${encodeURIComponent(category)}/json`;
+            const res = await fetcher(url, { headers: { "User-Agent": "appeeky-spec" } });
+            if (!res.ok)
+                return null;
+            const json = (await res.json().catch(() => null));
+            if (!json?.feed)
+                return null;
+            const entries = json.feed.entry === undefined ? [] : Array.isArray(json.feed.entry) ? json.feed.entry : [json.feed.entry];
+            return entries.map((e) => e.id?.attributes?.["im:id"]).filter((id) => Boolean(id));
+        },
+    };
+}
+/** Google Play category charts through the Appeeky API. */
+export function playChartSource(api) {
+    return {
+        label: "Google Play charts (Appeeky API)",
+        async chart(store, category, country, chart) {
+            if (store !== "google-play")
+                return null;
+            const data = await api.get(`/categories/${encodeURIComponent(category)}/top`, {
+                platform: "google",
+                country,
+                chart,
+                limit: String(CHART_SIZE),
+            });
+            const apps = data?.apps ?? [];
+            // The API answers an empty list when it could not read the chart: unknown, not "unranked".
+            if (apps.length === 0)
+                return null;
+            return [...apps].sort((a, b) => a.rank - b.rank).map((a) => a.appId);
+        },
+    };
+}
+/** Both stores: Apple's RSS for the App Store, the Appeeky API for Google Play when there is a key. */
+export function chartSources(api, fetcher = fetch) {
+    const apple = appleChartSource(fetcher);
+    const play = api ? playChartSource(api) : undefined;
+    return {
+        label: [apple.label, play?.label].filter(Boolean).join(" + "),
+        chart: (store, category, country, chart) => (store === "app-store" ? apple.chart(store, category, country, chart) : play ? play.chart(store, category, country, chart) : Promise.resolve(null)),
+    };
+}
+/** The App Store app's genre and whether it is paid, from Apple's public lookup. */
+export async function appleAppInfo(appId, country, fetcher = fetch) {
+    const res = await fetcher(`https://itunes.apple.com/lookup?id=${encodeURIComponent(appId)}&country=${encodeURIComponent(country)}`, { headers: { "User-Agent": "appeeky-spec" } });
+    if (!res.ok)
+        return null;
+    const json = (await res.json().catch(() => null));
+    const app = json?.results?.[0];
+    if (!app?.primaryGenreId)
+        return null;
+    return { genreId: String(app.primaryGenreId), genre: app.primaryGenreName ?? String(app.primaryGenreId), paid: (app.price ?? 0) > 0 };
+}
+/** Which charts to read: the configured category, or the App Store app's own genre. */
+export async function categoryPlans(project, fetcher = fetch) {
+    const cfg = project.spec.category ?? {};
+    const ids = rankAppIds(project);
+    const countries = cfg.countries ?? (Object.keys(project.spec.targets).length ? Object.keys(project.spec.targets) : ["us"]);
+    const plans = [];
+    const notes = [];
+    if (ids["app-store"]) {
+        let category = cfg.appStore;
+        let chart = cfg.chart;
+        const info = await appleAppInfo(ids["app-store"], countries[0], fetcher).catch(() => null);
+        category ??= info?.genreId;
+        chart ??= info?.paid ? "top-paid" : "top-free";
+        const name = info && info.genreId === category ? info.genre : undefined;
+        if (category)
+            plans.push({ store: "app-store", appId: ids["app-store"], category, chart, countries, ...(name ? { name } : {}) });
+        else
+            notes.push("App Store: could not read the app's genre. Set category.appStore in appeeky.spec.yaml (e.g. 6013).");
+    }
+    else if (project.spec.stores.appStore) {
+        notes.push("App Store: category charts need the numeric appId in stores.appStore.");
+    }
+    if (ids["google-play"]) {
+        if (cfg.googlePlay)
+            plans.push({ store: "google-play", appId: ids["google-play"], category: cfg.googlePlay, chart: cfg.chart ?? "top-free", countries, name: cfg.googlePlay.toLowerCase().replace(/_/g, " ") });
+        else
+            notes.push("Google Play: set category.googlePlay in appeeky.spec.yaml (e.g. HEALTH_AND_FITNESS) to record its chart.");
+    }
+    return { plans, notes };
+}
+/** Read every planned chart once and find the app in it. Charts that cannot be read are left out. */
+export async function readCategoryRanks(plans, source, now = new Date()) {
+    const date = now.toISOString().slice(0, 10);
+    const ranks = [];
+    const failed = [];
+    for (const p of plans) {
+        for (const country of p.countries) {
+            try {
+                const ids = await source.chart(p.store, p.category, country, p.chart);
+                if (!ids) {
+                    failed.push(`${p.store} ${country.toUpperCase()}: chart not available`);
+                    continue;
+                }
+                const index = ids.indexOf(p.appId);
+                ranks.push({ date, store: p.store, country, chart: p.chart, category: p.category, rank: index >= 0 ? index + 1 : null, ...(p.name ? { name: p.name } : {}) });
+            }
+            catch (e) {
+                failed.push(`${p.store} ${country.toUpperCase()}: ${e.message}`);
+            }
+        }
+    }
+    return { ranks, failed };
+}
+const COLUMNS = ["date", "store", "country", "chart", "category", "rank"];
+export async function readCategoryHistory(root) {
+    const file = categoryFile(root);
+    if (!existsSync(file))
+        return [];
+    const [head, ...lines] = (await readFile(file, "utf8")).trim().split("\n");
+    if (!head)
+        return [];
+    const cols = head.split(",");
+    return lines.map((line) => {
+        const v = Object.fromEntries(line.split(",").map((x, i) => [cols[i], x]));
+        return {
+            date: v.date ?? "",
+            store: v.store,
+            country: v.country ?? "",
+            chart: v.chart,
+            category: v.category ?? "",
+            rank: v.rank ? Number(v.rank) : null,
+        };
+    });
+}
+/** Add today's ranks to appeeky/category.csv (one row per day, store, storefront and chart). */
+export async function saveCategoryRanks(root, ranks) {
+    const { path } = await mergeCsv(join(root, SPEC_DIR), {
+        name: "category",
+        about: "Rank in the category chart",
+        key: ["date", "store", "country", "chart"],
+        columns: COLUMNS,
+        rows: ranks.map((r) => ({ ...r, rank: r.rank ?? "" })),
+    });
+    return path;
+}
+/** The latest row before `date` for the same store, storefront and chart. */
+export function previousRank(history, r) {
+    return history
+        .filter((h) => h.store === r.store && h.country === r.country && h.chart === r.chart && h.date < r.date)
+        .sort((a, b) => b.date.localeCompare(a.date))[0];
+}
+/** Not in the chart counts as just past its end, so "out → out" is no move. */
+const asRank = (r) => r ?? CHART_SIZE + 1;
+/**
+ * `category_rank` from the recorded history: the average rank over the days in
+ * the window, across the recorded storefronts. Needs two recorded days.
+ */
+export function categoryMetricSource(root) {
+    let history;
+    return {
+        label: "Category charts in the repo",
+        async window(store, _appId, from, to) {
+            history ??= readCategoryHistory(root);
+            const rows = (await history).filter((h) => h.store === store && h.date >= from && h.date < to);
+            if (new Set(rows.map((r) => r.date)).size < 2)
+                return null;
+            // Every storefront out of the chart the whole time says nothing.
+            if (rows.every((r) => r.rank === null))
+                return null;
+            const days = Math.max(1, Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000));
+            const values = { category_rank: rows.reduce((n, r) => n + asRank(r.rank), 0) / rows.length };
+            return { from, to, days, values };
+        },
+    };
+}
+//# sourceMappingURL=category.js.map

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function buildProgram(): Command;
+export declare function run(argv?: string[]): Promise<void>;