@viccydev/pi-fpa 0.2.0

package/extensions/fpa-data/registry.ts

@@ -0,0 +1,303 @@
+/**
+ * Metric and dataset registry for the FP&A Supabase mart.
+ *
+ * Every queryable dataset, dimension, and measure is declared here so the SQL
+ * builder can only ever reference vetted expressions. The LLM never supplies
+ * SQL or arithmetic — it picks names from this registry.
+ */
+
+export type MeasureUnit = "usd" | "count" | "users" | "ratio";
+
+export interface DimensionDef {
+	name: string;
+	sql: string;
+	description: string;
+}
+
+export interface MeasureDef {
+	name: string;
+	sql: string;
+	description: string;
+	unit: MeasureUnit;
+}
+
+export interface DerivedDef {
+	name: string;
+	description: string;
+	numerator: string;
+	denominator: string;
+	/** Multiplier applied to numerator/denominator, e.g. 1000 for CPM. */
+	scale?: number;
+	unit: MeasureUnit;
+}
+
+export interface EventNameExpansion {
+	/** JSONB column expanded with jsonb_each when the event_name dimension is used. */
+	jsonbColumn: string;
+	/** Measure name -> aggregate SQL over the expanded pair e(k, v). */
+	measures: Record<string, string>;
+}
+
+export interface BreakdownRule {
+	column: string;
+	/** Value used when none of the dimension-specific variants apply. */
+	base: string;
+	/** Dimension name -> required breakdown value. */
+	byDimension: Record<string, string>;
+}
+
+export interface DatasetDef {
+	id: string;
+	table: string;
+	dateColumn: string;
+	description: string;
+	dimensions: DimensionDef[];
+	measures: MeasureDef[];
+	derived: DerivedDef[];
+	notes: string[];
+	breakdown?: BreakdownRule;
+	eventName?: EventNameExpansion;
+	/** Extra FROM clause fragments (lateral joins) required by the measures. */
+	lateral?: string;
+}
+
+const AF_METRIC_FIELDS: Record<string, string> = {
+	event_count: "event_count",
+	unique_users: "unique_appsflyer_user_count",
+	gross_sales: "gross_sales_usd",
+	gross_refunds: "gross_refund_usd",
+	net_proceeds: "net_proceeds_usd",
+	net_refund_proceeds: "net_refund_proceeds_usd",
+};
+
+function afEventMeasures(): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const [name, field] of Object.entries(AF_METRIC_FIELDS)) {
+		out[name] = `sum((e.v->>'${field}')::numeric)`;
+	}
+	return out;
+}
+
+function appleSum(key: string): string {
+	return `sum((m.elem->>'value')::numeric) filter (where m.elem->>'metric_key' = '${key}')`;
+}
+
+function appleAvg(key: string): string {
+	return `avg((m.elem->>'value')::numeric) filter (where m.elem->>'metric_key' = '${key}')`;
+}
+
+function appleLatest(key: string): string {
+	return `(array_agg((m.elem->>'value')::numeric order by metric_date desc) filter (where m.elem->>'metric_key' = '${key}'))[1]`;
+}
+
+export const DATASETS: DatasetDef[] = [
+	{
+		id: "ua_spend",
+		table: "appsflyer_ua_campaign_daily",
+		dateColumn: "install_date",
+		description:
+			"AppsFlyer UA spend and acquisition funnel per campaign per install day (impressions, clicks, installs, cost).",
+		dimensions: [
+			{ name: "app_code", sql: "app_code", description: "Internal app code" },
+			{ name: "platform", sql: "platform", description: "ios or android" },
+			{ name: "media_source", sql: "media_source", description: "Ad network / media source" },
+			{ name: "campaign_name", sql: "campaign_name", description: "Campaign name" },
+			{ name: "campaign_id", sql: "campaign_id", description: "Campaign id" },
+			{
+				name: "country_code",
+				sql: "country_code",
+				description: "Geo (forces breakdown_type=CAMPAIGN_GEO)",
+			},
+			{
+				name: "channel",
+				sql: "channel",
+				description: "Channel within a media source (forces breakdown_type=CAMPAIGN_CHANNEL)",
+			},
+		],
+		measures: [
+			{ name: "spend", sql: "sum(cost_usd)", description: "UA cost in USD", unit: "usd" },
+			{ name: "impressions", sql: "sum(impressions)", description: "Ad impressions", unit: "count" },
+			{ name: "clicks", sql: "sum(clicks)", description: "Ad clicks", unit: "count" },
+			{ name: "installs", sql: "sum(installs)", description: "Attributed installs", unit: "count" },
+		],
+		derived: [
+			{ name: "cpi", description: "Cost per install = spend / installs", numerator: "spend", denominator: "installs", unit: "usd" },
+			{ name: "ctr", description: "Click-through rate = clicks / impressions", numerator: "clicks", denominator: "impressions", unit: "ratio" },
+			{ name: "cvr", description: "Click-to-install rate = installs / clicks", numerator: "installs", denominator: "clicks", unit: "ratio" },
+			{ name: "cpm", description: "Cost per mille = spend * 1000 / impressions", numerator: "spend", denominator: "impressions", scale: 1000, unit: "usd" },
+		],
+		notes: [
+			"The table stores three overlapping breakdowns of the SAME spend (CAMPAIGN, CAMPAIGN_GEO, CAMPAIGN_CHANNEL). The builder pins exactly one breakdown_type per query, so totals are never double-counted.",
+			"country_code and channel cannot be combined in one query: no breakdown carries both.",
+		],
+		breakdown: {
+			column: "breakdown_type",
+			base: "CAMPAIGN",
+			byDimension: { country_code: "CAMPAIGN_GEO", channel: "CAMPAIGN_CHANNEL" },
+		},
+	},
+	{
+		id: "revenue_activity",
+		table: "appsflyer_install_cohort_daily",
+		dateColumn: "event_date",
+		description:
+			"AppsFlyer revenue and activity booked per calendar day (event_date axis, all install cohorts combined). Use fpa_cohort for install-cohort LTV/ROAS/retention.",
+		dimensions: [
+			{ name: "app_code", sql: "app_code", description: "Internal app code" },
+			{ name: "platform", sql: "platform", description: "ios or android" },
+		],
+		measures: [
+			{ name: "gross_sales", sql: "sum(gross_sales_usd)", description: "Gross sales USD", unit: "usd" },
+			{ name: "gross_refunds", sql: "sum(gross_refund_usd)", description: "Gross refunds USD", unit: "usd" },
+			{ name: "net_proceeds", sql: "sum(net_proceeds_usd)", description: "Net proceeds USD", unit: "usd" },
+			{ name: "net_refund_proceeds", sql: "sum(net_refund_proceeds_usd)", description: "Net refund proceeds USD", unit: "usd" },
+			{ name: "active_user_days", sql: "sum(active_user_count)", description: "Sum of daily active users (user-days when aggregated over multiple days)", unit: "users" },
+			{ name: "event_count", sql: "sum(event_count)", description: "Tracked event count", unit: "count" },
+		],
+		derived: [
+			{ name: "refund_rate", description: "gross_refunds / gross_sales", numerator: "gross_refunds", denominator: "gross_sales", unit: "ratio" },
+		],
+		notes: [
+			"This is the activity view of the install-cohort table: a day's revenue includes payments from all historical cohorts.",
+		],
+	},
+	{
+		id: "apple_store",
+		table: "apple_app_daily",
+		dateColumn: "metric_date",
+		description:
+			"App Store Connect daily analytics per app (proceeds, units, conversion rate, paying users, subscription states).",
+		dimensions: [
+			{ name: "studio_code", sql: "studio_code", description: "Studio code" },
+			{ name: "adam_id", sql: "adam_id", description: "App Store Adam ID" },
+			{ name: "platform", sql: "platform", description: "Store platform" },
+		],
+		measures: [
+			{ name: "proceeds", sql: appleSum("proceeds"), description: "Apple proceeds (developer share)", unit: "usd" },
+			{ name: "units", sql: appleSum("units"), description: "First-time downloads", unit: "count" },
+			{ name: "iap_count", sql: appleSum("iap"), description: "In-app purchase count", unit: "count" },
+			{ name: "redownloads", sql: appleSum("redownloads"), description: "Redownloads", unit: "count" },
+			{ name: "updates", sql: appleSum("updates"), description: "App updates", unit: "count" },
+			{ name: "page_views", sql: appleSum("pageViewCount"), description: "Product page views", unit: "count" },
+			{ name: "store_impressions", sql: appleSum("impressionsTotal"), description: "Store impressions", unit: "count" },
+			{ name: "conversion_rate_avg", sql: appleAvg("conversionRate"), description: "Unweighted average of DAILY store conversion rate (source metric_type=AVERAGE; do not sum)", unit: "ratio" },
+			{ name: "paying_users_avg", sql: appleAvg("payingUsers"), description: "Unweighted average of DAILY paying users (source metric_type=AVERAGE; do not sum)", unit: "users" },
+			{ name: "subs_paid_latest", sql: appleLatest("subscription-state-paid"), description: "Paid subscriptions state on the LAST day of the range (source metric_type=LATEST)", unit: "count" },
+			{ name: "subs_plans_active_latest", sql: appleLatest("subscription-state-plans-active"), description: "Active subscription plans on the LAST day of the range (source metric_type=LATEST)", unit: "count" },
+		],
+		derived: [
+			{ name: "proceeds_per_unit", description: "proceeds / units", numerator: "proceeds", denominator: "units", unit: "usd" },
+		],
+		notes: [
+			"Metrics live in a JSONB array with per-metric aggregation semantics: COUNT metrics are summed, AVERAGE metrics are daily averages, LATEST metrics take the last day's value.",
+			"Keyed by adam_id, not app_code; join to other datasets via mixpanel_app_daily.adam_id when needed.",
+		],
+		lateral:
+			"left join lateral jsonb_array_elements(coalesce(metrics->'metric', '[]'::jsonb)) as m(elem) on true",
+	},
+	{
+		id: "product_events",
+		table: "appsflyer_event_daily",
+		dateColumn: "event_date",
+		description:
+			"AppsFlyer daily event aggregates per app, with optional per-event-name breakdown (funnel events, paywall events, purchases).",
+		dimensions: [
+			{ name: "app_code", sql: "app_code", description: "Internal app code" },
+			{ name: "platform", sql: "platform", description: "ios or android" },
+			{ name: "event_name", sql: "e.k", description: "Tracked event name (expands the event_metrics JSONB)" },
+		],
+		measures: [
+			{ name: "event_count", sql: "sum(event_count)", description: "Event count", unit: "count" },
+			{ name: "unique_users", sql: "sum(unique_appsflyer_user_count)", description: "Unique AppsFlyer users", unit: "users" },
+			{ name: "gross_sales", sql: "sum(gross_sales_usd)", description: "Gross sales USD", unit: "usd" },
+			{ name: "gross_refunds", sql: "sum(gross_refund_usd)", description: "Gross refunds USD", unit: "usd" },
+			{ name: "net_proceeds", sql: "sum(net_proceeds_usd)", description: "Net proceeds USD", unit: "usd" },
+			{ name: "net_refund_proceeds", sql: "sum(net_refund_proceeds_usd)", description: "Net refund proceeds USD", unit: "usd" },
+		],
+		derived: [
+			{ name: "refund_rate", description: "gross_refunds / gross_sales", numerator: "gross_refunds", denominator: "gross_sales", unit: "ratio" },
+			{ name: "events_per_user", description: "event_count / unique_users", numerator: "event_count", denominator: "unique_users", unit: "ratio" },
+		],
+		notes: [],
+		eventName: {
+			jsonbColumn: "event_metrics",
+			measures: afEventMeasures(),
+		},
+	},
+	{
+		id: "mixpanel_product",
+		table: "mixpanel_app_daily",
+		dateColumn: "business_date",
+		description:
+			"Mixpanel product analytics per app per day (first opens, actives, sessions), with optional per-event-name counts.",
+		dimensions: [
+			{ name: "app_code", sql: "app_code", description: "Internal app code" },
+			{ name: "platform", sql: "platform", description: "ios or android" },
+			{ name: "adam_id", sql: "adam_id", description: "App Store Adam ID (joins to apple_store)" },
+			{ name: "event_name", sql: "e.k", description: "Mixpanel event name (expands the mp_event_counts JSONB)" },
+		],
+		measures: [
+			{ name: "first_open_users", sql: "sum(mp_first_open_users)", description: "First-open users", unit: "users" },
+			{ name: "active_users", sql: "sum(mp_active_users)", description: "Daily active users (user-days when aggregated over multiple days)", unit: "users" },
+			{ name: "event_users", sql: "sum(mp_event_users)", description: "Users with any event", unit: "users" },
+			{ name: "session_count", sql: "sum(mp_session_count)", description: "Session count", unit: "count" },
+			{ name: "session_users", sql: "sum(mp_session_users)", description: "Users with a session", unit: "users" },
+			{ name: "updated_users", sql: "sum(mp_updated_users)", description: "Users who updated the app", unit: "users" },
+		],
+		derived: [
+			{ name: "sessions_per_session_user", description: "session_count / session_users", numerator: "session_count", denominator: "session_users", unit: "ratio" },
+		],
+		notes: ["Only a subset of apps is instrumented in Mixpanel."],
+		eventName: {
+			jsonbColumn: "mp_event_counts",
+			measures: { event_count: "sum((e.v)::numeric)" },
+		},
+	},
+];
+
+export const DATASET_IDS = DATASETS.map((d) => d.id);
+
+export function getDataset(id: string): DatasetDef {
+	const dataset = DATASETS.find((d) => d.id === id);
+	if (!dataset) {
+		throw new Error(`Unknown dataset "${id}". Available datasets: ${DATASET_IDS.join(", ")}.`);
+	}
+	return dataset;
+}
+
+export interface CatalogCaveat {
+	scope: string;
+	caveat: string;
+}
+
+export const CATALOG_CAVEATS: CatalogCaveat[] = [
+	{
+		scope: "ua_spend",
+		caveat:
+			"breakdown_type variants (CAMPAIGN / CAMPAIGN_GEO / CAMPAIGN_CHANNEL) each contain the full spend. The builder pins one variant per query; never aggregate this table without that pin.",
+	},
+	{
+		scope: "cohort",
+		caveat:
+			"installed_user_count (cohort size) is NULL for install dates before 2026-08-01. LTV/retention per install return NULL for those cohorts instead of a fabricated denominator.",
+	},
+	{
+		scope: "cohort",
+		caveat:
+			"appsflyer_install_cohort_daily is a rolling activity window: event_date only covers recent days. Cohorts installed before the window's start have incomplete horizon revenue, so fpa_cohort returns NULL horizon metrics for them.",
+	},
+	{
+		scope: "coverage",
+		caveat:
+			"Date coverage differs per dataset. Always read the coverage block returned by fpa_data_catalog and the date_min/date_max columns in query results before comparing datasets.",
+	},
+	{
+		scope: "currency",
+		caveat: "All monetary values are USD.",
+	},
+	{
+		scope: "computation",
+		caveat:
+			"All arithmetic (aggregation, ratios, deltas) happens in SQL or in extension code. Never compute metrics manually from partial rows; re-query with the right grouping or use fpa_calc.",
+	},
+];