@shware/analytics 11.7.0 → 11.9.0

package/README.md

@@ -341,6 +341,51 @@ What the SDK guarantees for this to hold:
   `setVisitor` hands the server's value to the third-party user setters, and PostHog is identified
   by it once a user is known.
 
+## Ad performance (`@shware/analytics/ads`)
+
+Spend, impressions, clicks and the platforms' own conversions, read from the ad platforms'
+reporting APIs as typed `AdPerformanceRow`s — one per ad and hour — for a host to store next to its
+sessions and compute ROAS, cost per session and the click → session landing rate.
+
+```ts
+import { fetchMetaAdPerformance } from '@shware/analytics/ads';
+
+const rows = await fetchMetaAdPerformance({
+  accessToken: env.META_ADS_ACCESS_TOKEN, // a system user token with ads_read
+  accountId: '1234567890', // with or without act_
+  since: '2026-10-01', // days in the ad account's time zone
+  until: '2026-10-07',
+});
+```
+
+- **Hourly rows only.** `hour_start` is a UTC instant, so a sum over any span in any time zone is
+  a sum of whole rows and lines up with the sessions grouped the same way, whatever time zone each
+  ad account reports in. A table never mixes a day row with the hours inside it: an upsert would
+  overwrite one with the other on their shared start, and the rest would count twice. A platform
+  that reports only days spreads each day evenly over its hours.
+- **The attribution vocabulary.** `channel`, `medium` and `channel_group` are the values
+  `classifyTouch` gives the platform's ad clicks (`meta / cpc / paid_social`), so rows join
+  sessions and attribution with no mapping. Join on `channel` and `channel_group` together: the
+  same channel also brings organic traffic (Google search, ChatGPT answers).
+- **Clicks are link clicks** to the site (Meta's `inline_link_clicks`), the number to compare
+  with sessions; Meta's `clicks` also counts likes and expands.
+- **Two conversion counts.** `conversions` / `conversion_value` are the platform's under each ad's
+  attribution setting, view-through included — what its own dashboard shows.
+  `click_conversions` / `click_conversion_value` are the click-through part (Meta's 7-day click),
+  the one to set against a click-based attribution.
+- **Re-fetch and upsert.** Platforms restate the past: a purchase is credited to the hour of the
+  click up to 7 days later, and spend is corrected for invalid traffic. Re-fetch today and
+  yesterday hourly, the last 8 days daily (the 7-day window plus a day of time zone slack) and the
+  last 30 weekly, upserting on (`platform`, `account_id`, `ad_id`, `hour_start`).
+- **Retention.** Meta keeps the hourly breakdown for 13 months; `since` earlier than that throws
+  rather than returning the empty answer Meta gives. Long ranges are fetched in 7-day windows, as a
+  single request over months times out on Meta's side.
+- **Older history.** `fetchMetaAdPerformanceHistory` reads the days before the hourly 13 months
+  (Meta keeps 37) and spreads each day evenly over its hours, so the table stays hourly: whole-day
+  sums are Meta's exactly, the hours inside such a day are an even split. Run it once, up to the
+  day before the first hourly day stored — a day must never hold both spread and real hourly rows,
+  as an hour without delivery is absent from the hourly data and its spread share would remain.
+
 ## UTM params
 
 Typed as `UTMParams` (exported from `@shware/analytics`). Value unions follow the

package/dist/ads/index.cjs

@@ -0,0 +1,11 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_ads_time = require("./time.cjs");
+const require_ads_meta = require("./meta.cjs");
+exports.MetaAdsApiError = require_ads_meta.MetaAdsApiError;
+exports.addDays = require_ads_time.addDays;
+exports.addMonths = require_ads_time.addMonths;
+exports.fetchMetaAdPerformance = require_ads_meta.fetchMetaAdPerformance;
+exports.fetchMetaAdPerformanceHistory = require_ads_meta.fetchMetaAdPerformanceHistory;
+exports.spread = require_ads_meta.spread;
+exports.todayIn = require_ads_time.todayIn;
+exports.zonedHourToUtc = require_ads_time.zonedHourToUtc;

package/dist/ads/index.d.cts

@@ -0,0 +1,4 @@
+import { AdPerformanceRow, AdPlatform, ReportDate } from "./types.cjs";
+import { MetaAdPerformanceOptions, MetaAdsApiError, fetchMetaAdPerformance, fetchMetaAdPerformanceHistory, spread } from "./meta.cjs";
+import { addDays, addMonths, todayIn, zonedHourToUtc } from "./time.cjs";
+export { type AdPerformanceRow, type AdPlatform, MetaAdPerformanceOptions, MetaAdsApiError, type ReportDate, addDays, addMonths, fetchMetaAdPerformance, fetchMetaAdPerformanceHistory, spread, todayIn, zonedHourToUtc };

package/dist/ads/index.d.mts

@@ -0,0 +1,4 @@
+import { AdPerformanceRow, AdPlatform, ReportDate } from "./types.mjs";
+import { MetaAdPerformanceOptions, MetaAdsApiError, fetchMetaAdPerformance, fetchMetaAdPerformanceHistory, spread } from "./meta.mjs";
+import { addDays, addMonths, todayIn, zonedHourToUtc } from "./time.mjs";
+export { type AdPerformanceRow, type AdPlatform, MetaAdPerformanceOptions, MetaAdsApiError, type ReportDate, addDays, addMonths, fetchMetaAdPerformance, fetchMetaAdPerformanceHistory, spread, todayIn, zonedHourToUtc };

package/dist/ads/index.mjs

@@ -0,0 +1,3 @@
+import { addDays, addMonths, todayIn, zonedHourToUtc } from "./time.mjs";
+import { MetaAdsApiError, fetchMetaAdPerformance, fetchMetaAdPerformanceHistory, spread } from "./meta.mjs";
+export { MetaAdsApiError, addDays, addMonths, fetchMetaAdPerformance, fetchMetaAdPerformanceHistory, spread, todayIn, zonedHourToUtc };

package/dist/ads/meta.cjs

@@ -0,0 +1,323 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_attribution_classify = require("../attribution/classify.cjs");
+require("../attribution/index.cjs");
+const require_ads_time = require("./time.cjs");
+let _shware_utils = require("@shware/utils");
+let zod_mini = require("zod/mini");
+let node_crypto = require("node:crypto");
+//#region src/ads/meta.ts
+/**
+* Meta ad delivery through the Marketing API's Insights endpoint, over plain `fetch`: one row per
+* ad and hour, in the attribution vocabulary (see `AdPerformanceRow`).
+*
+* The token needs `ads_read` on the ad account — a system user token with the account assigned
+* at "View performance". It is sent in the `Authorization` header and never put in a URL: paging
+* follows the `after` cursor rather than Meta's `paging.next`, which embeds the token.
+*
+* https://developers.facebook.com/docs/marketing-api/insights
+* https://developers.facebook.com/docs/marketing-api/insights/breakdowns
+*/
+const GRAPH = `https://graph.facebook.com/v24.0`;
+/** What an ad click is in the attribution vocabulary: `meta / cpc`, a paid social touch. */
+const CHANNEL = "meta";
+const MEDIUM = "cpc";
+/**
+* The click window of the click-through columns. Meta's longest since 2021, and the click part of
+* its default setting (7-day click, 1-day view).
+*/
+const CLICK_WINDOW = "7d_click";
+const VIEW_WINDOW = "1d_view";
+const HOURLY = "hourly_stats_aggregated_by_advertiser_time_zone";
+/**
+* How far back Meta answers the hourly breakdown, in months. Past it Meta does not fail — it
+* returns no rows — so a backfill would silently store a gap.
+* https://developers.facebook.com/docs/marketing-api/insights/best-practices
+*/
+const HOURLY_RETENTION_MONTHS = 13;
+/** How far back Meta answers Insights without the hourly breakdown, in months. */
+const DAILY_RETENTION_MONTHS = 37;
+/**
+* Days per Insights request. A synchronous request over a long range of ad rows times out on
+* Meta's side (`code 1, subcode 99`, "An unknown error occurred", as a 500): 17 months of daily
+* ad rows did. A range is split into windows this long, each paged on its own.
+*/
+const CHUNK_DAYS = 7;
+/** Days per request for daily rows: 24 times fewer rows than hourly ones per day. */
+const DAILY_CHUNK_DAYS = 30;
+/** Decimal places of a day's numbers spread over its hours. */
+const SPREAD_SCALE = 1e6;
+const FIELDS = [
+	"ad_id",
+	"ad_name",
+	"adset_id",
+	"adset_name",
+	"campaign_id",
+	"campaign_name",
+	"spend",
+	"impressions",
+	"inline_link_clicks",
+	"actions",
+	"action_values"
+];
+/** A Graph API error, with Meta's code, for a caller deciding whether to retry. */
+var MetaAdsApiError = class extends Error {
+	constructor(message, status, code, subcode, fbtraceId) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.subcode = subcode;
+		this.fbtraceId = fbtraceId;
+		this.name = "MetaAdsApiError";
+	}
+};
+const actionSchema = (0, zod_mini.object)({
+	action_type: (0, zod_mini.string)(),
+	/**
+	* The count under the ad's own attribution setting. Absent when the setting does not count any
+	* of it — a view-only conversion of an ad set to 1-day click — which only shows in the windows.
+	*/
+	value: (0, zod_mini.optional)((0, zod_mini.string)()),
+	[CLICK_WINDOW]: (0, zod_mini.optional)((0, zod_mini.string)()),
+	[VIEW_WINDOW]: (0, zod_mini.optional)((0, zod_mini.string)())
+});
+const insightSchema = (0, zod_mini.object)({
+	ad_id: (0, zod_mini.string)(),
+	ad_name: (0, zod_mini.optional)((0, zod_mini.string)()),
+	adset_id: (0, zod_mini.optional)((0, zod_mini.string)()),
+	adset_name: (0, zod_mini.optional)((0, zod_mini.string)()),
+	campaign_id: (0, zod_mini.string)(),
+	campaign_name: (0, zod_mini.optional)((0, zod_mini.string)()),
+	spend: (0, zod_mini.optional)((0, zod_mini.string)()),
+	impressions: (0, zod_mini.optional)((0, zod_mini.string)()),
+	inline_link_clicks: (0, zod_mini.optional)((0, zod_mini.string)()),
+	actions: (0, zod_mini.optional)((0, zod_mini.array)(actionSchema)),
+	action_values: (0, zod_mini.optional)((0, zod_mini.array)(actionSchema)),
+	date_start: (0, zod_mini.string)(),
+	[HOURLY]: (0, zod_mini.optional)((0, zod_mini.string)())
+});
+const pageSchema = (0, zod_mini.object)({
+	data: (0, zod_mini.array)(insightSchema),
+	paging: (0, zod_mini.optional)((0, zod_mini.object)({
+		cursors: (0, zod_mini.optional)((0, zod_mini.object)({ after: (0, zod_mini.optional)((0, zod_mini.string)()) })),
+		next: (0, zod_mini.optional)((0, zod_mini.string)())
+	}))
+});
+const accountSchema = (0, zod_mini.object)({
+	currency: (0, zod_mini.string)(),
+	timezone_name: (0, zod_mini.string)()
+});
+const errorSchema = (0, zod_mini.object)({ error: (0, zod_mini.object)({
+	message: (0, zod_mini.string)(),
+	code: (0, zod_mini.optional)((0, zod_mini.number)()),
+	error_subcode: (0, zod_mini.optional)((0, zod_mini.number)()),
+	fbtrace_id: (0, zod_mini.optional)((0, zod_mini.string)())
+}) });
+async function graphGet(path, params, options, parse) {
+	const query = new URLSearchParams(params);
+	if (options.appSecret) query.set("appsecret_proof", (0, node_crypto.createHmac)("sha256", options.appSecret).update(options.accessToken).digest("hex"));
+	const response = await (0, _shware_utils.fetch)(`${GRAPH}/${path}?${query}`, { headers: { authorization: `Bearer ${options.accessToken}` } });
+	const body = await response.json().catch(() => null);
+	if (!response.ok) {
+		const parsed = (0, zod_mini.safeParse)(errorSchema, body);
+		const error = parsed.success ? parsed.data.error : void 0;
+		throw new MetaAdsApiError(error?.message ?? `Meta Graph API responded ${response.status}`, response.status, error?.code, error?.error_subcode, error?.fbtrace_id);
+	}
+	return parse(body);
+}
+function parseWith(schema, what) {
+	return (body) => {
+		const parsed = (0, zod_mini.safeParse)(schema, body);
+		if (!parsed.success) {
+			const issues = parsed.error.issues;
+			const first = issues.slice(0, 3).map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+			throw new Error(`Unexpected Meta ${what} response (${issues.length} issues): ${first}${issues.length > 3 ? "; …" : ""}`);
+		}
+		return parsed.data;
+	};
+}
+function count(value) {
+	return value === void 0 ? 0 : Number(value);
+}
+/** The action's total and its click-through part; nulls when Meta reported no such action. */
+function conversion(actions, actionType) {
+	const action = actions?.find((a) => a.action_type === actionType);
+	if (!action) return {
+		total: null,
+		click: null
+	};
+	return {
+		total: Number(action.value ?? 0),
+		click: Number(action[CLICK_WINDOW] ?? 0)
+	};
+}
+/** `"13:00:00 - 13:59:59"` → 13. */
+function hourOf(bucket) {
+	const hour = Number(bucket?.slice(0, 2));
+	if (!Number.isInteger(hour) || hour < 0 || hour > 23) throw new Error(`Unexpected Meta hourly bucket: ${bucket}`);
+	return hour;
+}
+/** A row for one hour: what Meta reports of an ad, its numbers as given. */
+function toRow(insight, hourStart, accountId, currency, actionType) {
+	const conversions = conversion(insight.actions, actionType);
+	const values = conversion(insight.action_values, actionType);
+	return {
+		platform: "meta",
+		account_id: accountId,
+		campaign_id: insight.campaign_id,
+		campaign_name: insight.campaign_name ?? null,
+		ad_group_id: insight.adset_id ?? null,
+		ad_group_name: insight.adset_name ?? null,
+		ad_id: insight.ad_id,
+		ad_name: insight.ad_name ?? null,
+		channel: CHANNEL,
+		medium: MEDIUM,
+		channel_group: require_attribution_classify.channelGroupOf(CHANNEL, MEDIUM),
+		hour_start: hourStart.toISOString(),
+		currency,
+		spend: Number(insight.spend ?? 0),
+		impressions: count(insight.impressions),
+		clicks: count(insight.inline_link_clicks),
+		conversions: conversions.total,
+		conversion_value: values.total,
+		click_conversions: conversions.click,
+		click_conversion_value: values.click
+	};
+}
+/**
+* `value` in `parts` equal shares rounded to `SPREAD_SCALE`, the rounding left in the last share
+* so that the shares add back to `value` exactly as Meta reported it.
+*/
+function spread(value, parts) {
+	const share = Math.round(value / parts * SPREAD_SCALE) / SPREAD_SCALE;
+	const last = Math.round((value - share * (parts - 1)) * SPREAD_SCALE) / SPREAD_SCALE;
+	return [...Array.from({ length: parts - 1 }, () => share), last];
+}
+/**
+* A day row as one row per hour of the account's calendar day — 24, or 23 / 25 across a
+* daylight-saving change — each number spread evenly (nulls stay null).
+*/
+function spreadDay(day, date, timeZone) {
+	const start = require_ads_time.zonedHourToUtc(date, 0, timeZone).getTime();
+	const end = require_ads_time.zonedHourToUtc(require_ads_time.addDays(date, 1), 0, timeZone).getTime();
+	const hours = Math.round((end - start) / 36e5);
+	const shares = (value) => value === null ? null : spread(value, hours);
+	const spend = spread(day.spend, hours);
+	const impressions = spread(day.impressions, hours);
+	const clicks = spread(day.clicks, hours);
+	const conversions = shares(day.conversions);
+	const conversionValue = shares(day.conversion_value);
+	const clickConversions = shares(day.click_conversions);
+	const clickConversionValue = shares(day.click_conversion_value);
+	return Array.from({ length: hours }, (_, hour) => ({
+		...day,
+		hour_start: new Date(start + hour * 36e5).toISOString(),
+		spend: spend[hour],
+		impressions: impressions[hour],
+		clicks: clicks[hour],
+		conversions: conversions?.[hour] ?? null,
+		conversion_value: conversionValue?.[hour] ?? null,
+		click_conversions: clickConversions?.[hour] ?? null,
+		click_conversion_value: clickConversionValue?.[hour] ?? null
+	}));
+}
+async function accountOf(options) {
+	const id = options.accountId.replace(/^act_/, "");
+	return {
+		id,
+		...await graphGet(`act_${id}`, { fields: "currency,timezone_name" }, options, parseWith(accountSchema, "ad account"))
+	};
+}
+/** Every ad row of the account between `since` and `until`, one request per window of `chunkDays`. */
+async function insights(options, accountId, since, until, { chunkDays, hourly }) {
+	const rows = [];
+	for (let from = since; from <= until; from = require_ads_time.addDays(from, chunkDays)) {
+		const last = require_ads_time.addDays(from, chunkDays - 1);
+		const to = last < until ? last : until;
+		let after;
+		do {
+			const params = {
+				level: "ad",
+				fields: FIELDS.join(","),
+				time_range: JSON.stringify({
+					since: from,
+					until: to
+				}),
+				time_increment: "1",
+				action_attribution_windows: JSON.stringify([CLICK_WINDOW, VIEW_WINDOW]),
+				use_unified_attribution_setting: "true",
+				limit: "500"
+			};
+			if (hourly) params.breakdowns = HOURLY;
+			if (after) params.after = after;
+			const page = await graphGet(`act_${accountId}/insights`, params, options, parseWith(pageSchema, "insights"));
+			rows.push(...page.data);
+			after = page.paging?.next ? page.paging.cursors?.after : void 0;
+		} while (after);
+	}
+	return rows;
+}
+/**
+* Hourly delivery of every ad of the account that ran between `since` and `until` — deleted and
+* archived ads included — one row per ad and hour (hours without delivery are absent). The hours
+* are Meta's, in the account's time zone, turned into UTC instants. Conversions are those of each
+* ad's attribution setting (`use_unified_attribution_setting`), their click-through part from the
+* 7-day click window.
+*
+* Meta restates past hours as late conversions arrive — a purchase is credited to the hour of the
+* click, up to 7 days after it — and corrects spend for invalid traffic: re-fetch the last 8 days
+* daily (the 7-day window plus a day of time zone slack) and upsert on (`platform`, `account_id`,
+* `ad_id`, `hour_start`).
+*
+* @throws RangeError when `since` is more than 13 months back, where Meta keeps no hourly
+* breakdown and would answer with no rows rather than an error.
+*/
+async function fetchMetaAdPerformance(options) {
+	const actionType = options.conversionActionType ?? "purchase";
+	const account = await accountOf(options);
+	const since = require_ads_time.addDays(options.since, 0);
+	const until = require_ads_time.addDays(options.until, 0);
+	const earliest = require_ads_time.addMonths(require_ads_time.todayIn(account.timezone_name), -13);
+	if (since < earliest) throw new RangeError(`Meta keeps hourly insights for ${HOURLY_RETENTION_MONTHS} months: since ${since} is before ${earliest}`);
+	return (await insights(options, account.id, since, until, {
+		chunkDays: CHUNK_DAYS,
+		hourly: true
+	})).map((insight) => toRow(insight, require_ads_time.zonedHourToUtc(insight.date_start, hourOf(insight[HOURLY]), account.timezone_name), account.id, account.currency, actionType));
+}
+/**
+* The delivery older than Meta's 13 months of hourly data, as hourly rows: Meta's daily ad rows,
+* each spread evenly over the hours of the account's day (`spread`), so that one table stays
+* hourly from end to end. Sums over whole days are Meta's exactly; the hours within a day are an
+* even split, not when the ads actually ran.
+*
+* Only for days the hourly data no longer covers, and only once: a day stored this way must
+* never also get hourly rows (an hour without delivery is not reported hourly, so its spread
+* share would stay and count twice). Fetch up to the day before the first hourly day stored.
+* These days are final; they need no re-fetch.
+*
+* @throws RangeError when `until` is within the 13 months of hourly data (use
+* `fetchMetaAdPerformance`), or `since` is past the 37 months Meta keeps at all.
+*/
+async function fetchMetaAdPerformanceHistory(options) {
+	const actionType = options.conversionActionType ?? "purchase";
+	const account = await accountOf(options);
+	const since = require_ads_time.addDays(options.since, 0);
+	const until = require_ads_time.addDays(options.until, 0);
+	const today = require_ads_time.todayIn(account.timezone_name);
+	const hourlyFrom = require_ads_time.addMonths(today, -13);
+	const earliest = require_ads_time.addMonths(today, -37);
+	if (until >= hourlyFrom) throw new RangeError(`Meta has hourly insights from ${hourlyFrom}: until ${until} must be before it, fetch those days with fetchMetaAdPerformance`);
+	if (since < earliest) throw new RangeError(`Meta keeps insights for ${DAILY_RETENTION_MONTHS} months: since ${since} is before ${earliest}`);
+	return (await insights(options, account.id, since, until, {
+		chunkDays: DAILY_CHUNK_DAYS,
+		hourly: false
+	})).flatMap((insight) => {
+		return spreadDay(toRow(insight, require_ads_time.zonedHourToUtc(insight.date_start, 0, account.timezone_name), account.id, account.currency, actionType), insight.date_start, account.timezone_name);
+	});
+}
+//#endregion
+exports.MetaAdsApiError = MetaAdsApiError;
+exports.fetchMetaAdPerformance = fetchMetaAdPerformance;
+exports.fetchMetaAdPerformanceHistory = fetchMetaAdPerformanceHistory;
+exports.spread = spread;
+
+//# sourceMappingURL=meta.cjs.map

package/dist/ads/meta.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.cjs","names":["object","string","optional","array","number","createHmac","fetch","safeParse","channelGroupOf","zonedHourToUtc","addDays","addMonths","todayIn"],"sources":["../../src/ads/meta.ts"],"sourcesContent":["/**\n * Meta ad delivery through the Marketing API's Insights endpoint, over plain `fetch`: one row per\n * ad and hour, in the attribution vocabulary (see `AdPerformanceRow`).\n *\n * The token needs `ads_read` on the ad account — a system user token with the account assigned\n * at \"View performance\". It is sent in the `Authorization` header and never put in a URL: paging\n * follows the `after` cursor rather than Meta's `paging.next`, which embeds the token.\n *\n * https://developers.facebook.com/docs/marketing-api/insights\n * https://developers.facebook.com/docs/marketing-api/insights/breakdowns\n */\nimport { createHmac } from 'node:crypto';\nimport { fetch } from '@shware/utils';\nimport {\n  type infer as Infer,\n  type ZodMiniType,\n  array,\n  number,\n  object,\n  optional,\n  safeParse,\n  string,\n} from 'zod/mini';\nimport { channelGroupOf } from '../attribution';\nimport { addDays, addMonths, todayIn, zonedHourToUtc } from './time';\nimport type { AdPerformanceRow, ReportDate } from './types';\n\n/** Same Graph API version as the Conversions API sender. */\nconst API_VERSION = 'v24.0';\nconst GRAPH = `https://graph.facebook.com/${API_VERSION}`;\n\n/** What an ad click is in the attribution vocabulary: `meta / cpc`, a paid social touch. */\nconst CHANNEL = 'meta';\nconst MEDIUM = 'cpc';\n\n/**\n * The click window of the click-through columns. Meta's longest since 2021, and the click part of\n * its default setting (7-day click, 1-day view).\n */\nconst CLICK_WINDOW = '7d_click';\nconst VIEW_WINDOW = '1d_view';\n\nconst HOURLY = 'hourly_stats_aggregated_by_advertiser_time_zone';\n\n/**\n * How far back Meta answers the hourly breakdown, in months. Past it Meta does not fail — it\n * returns no rows — so a backfill would silently store a gap.\n * https://developers.facebook.com/docs/marketing-api/insights/best-practices\n */\nconst HOURLY_RETENTION_MONTHS = 13;\n\n/** How far back Meta answers Insights without the hourly breakdown, in months. */\nconst DAILY_RETENTION_MONTHS = 37;\n\n/**\n * Days per Insights request. A synchronous request over a long range of ad rows times out on\n * Meta's side (`code 1, subcode 99`, \"An unknown error occurred\", as a 500): 17 months of daily\n * ad rows did. A range is split into windows this long, each paged on its own.\n */\nconst CHUNK_DAYS = 7;\n\n/** Days per request for daily rows: 24 times fewer rows than hourly ones per day. */\nconst DAILY_CHUNK_DAYS = 30;\n\n/** Decimal places of a day's numbers spread over its hours. */\nconst SPREAD_SCALE = 1e6;\n\nconst FIELDS = [\n  'ad_id',\n  'ad_name',\n  'adset_id',\n  'adset_name',\n  'campaign_id',\n  'campaign_name',\n  'spend',\n  'impressions',\n  'inline_link_clicks',\n  'actions',\n  'action_values',\n];\n\nexport interface MetaAdPerformanceOptions {\n  /** A token with `ads_read` on the account. */\n  accessToken: string;\n  /** The ad account id, with or without its `act_` prefix. */\n  accountId: string;\n  /** First day, in the ad account's time zone. */\n  since: ReportDate;\n  /** Last day, inclusive, in the ad account's time zone. */\n  until: ReportDate;\n  /**\n   * The `action_type` counted as the conversion, default `purchase` (Meta's total of the pixel,\n   * Conversions API and in-app purchases of an event, deduplicated).\n   */\n  conversionActionType?: string;\n  /**\n   * The app secret, when the app requires `appsecret_proof` (App settings → Advanced → \"Require\n   * app secret\"). The proof is computed here; the secret itself is never sent.\n   */\n  appSecret?: string;\n}\n\n/** A Graph API error, with Meta's code, for a caller deciding whether to retry. */\nexport class MetaAdsApiError extends Error {\n  constructor(\n    message: string,\n    readonly status: number,\n    readonly code: number | undefined,\n    readonly subcode: number | undefined,\n    readonly fbtraceId: string | undefined\n  ) {\n    super(message);\n    this.name = 'MetaAdsApiError';\n  }\n}\n\nconst actionSchema = object({\n  action_type: string(),\n  /**\n   * The count under the ad's own attribution setting. Absent when the setting does not count any\n   * of it — a view-only conversion of an ad set to 1-day click — which only shows in the windows.\n   */\n  value: optional(string()),\n  [CLICK_WINDOW]: optional(string()),\n  [VIEW_WINDOW]: optional(string()),\n});\n\nconst insightSchema = object({\n  ad_id: string(),\n  ad_name: optional(string()),\n  adset_id: optional(string()),\n  adset_name: optional(string()),\n  campaign_id: string(),\n  campaign_name: optional(string()),\n  spend: optional(string()),\n  impressions: optional(string()),\n  inline_link_clicks: optional(string()),\n  actions: optional(array(actionSchema)),\n  action_values: optional(array(actionSchema)),\n  date_start: string(),\n  [HOURLY]: optional(string()),\n});\n\nconst pageSchema = object({\n  data: array(insightSchema),\n  paging: optional(\n    object({ cursors: optional(object({ after: optional(string()) })), next: optional(string()) })\n  ),\n});\n\nconst accountSchema = object({ currency: string(), timezone_name: string() });\n\nconst errorSchema = object({\n  error: object({\n    message: string(),\n    code: optional(number()),\n    error_subcode: optional(number()),\n    fbtrace_id: optional(string()),\n  }),\n});\n\ntype Insight = Infer<typeof insightSchema>;\ntype Action = Infer<typeof actionSchema>;\n\nasync function graphGet<T>(\n  path: string,\n  params: Record<string, string>,\n  options: MetaAdPerformanceOptions,\n  parse: (body: unknown) => T\n): Promise<T> {\n  const query = new URLSearchParams(params);\n  if (options.appSecret) {\n    query.set(\n      'appsecret_proof',\n      createHmac('sha256', options.appSecret).update(options.accessToken).digest('hex')\n    );\n  }\n  const response = await fetch(`${GRAPH}/${path}?${query}`, {\n    headers: { authorization: `Bearer ${options.accessToken}` },\n  });\n  const body: unknown = await response.json().catch(() => null);\n  if (!response.ok) {\n    const parsed = safeParse(errorSchema, body);\n    const error = parsed.success ? parsed.data.error : undefined;\n    throw new MetaAdsApiError(\n      error?.message ?? `Meta Graph API responded ${response.status}`,\n      response.status,\n      error?.code,\n      error?.error_subcode,\n      error?.fbtrace_id\n    );\n  }\n  return parse(body);\n}\n\nfunction parseWith<T>(schema: ZodMiniType<T>, what: string) {\n  return (body: unknown): T => {\n    const parsed = safeParse(schema, body);\n    if (!parsed.success) {\n      const issues = parsed.error.issues;\n      const first = issues\n        .slice(0, 3)\n        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)\n        .join('; ');\n      throw new Error(\n        `Unexpected Meta ${what} response (${issues.length} issues): ${first}${issues.length > 3 ? '; …' : ''}`\n      );\n    }\n    return parsed.data;\n  };\n}\n\nfunction count(value: string | undefined): number {\n  return value === undefined ? 0 : Number(value);\n}\n\n/** The action's total and its click-through part; nulls when Meta reported no such action. */\nfunction conversion(actions: Action[] | undefined, actionType: string) {\n  const action = actions?.find((a) => a.action_type === actionType);\n  if (!action) return { total: null, click: null };\n  return { total: Number(action.value ?? 0), click: Number(action[CLICK_WINDOW] ?? 0) };\n}\n\n/** `\"13:00:00 - 13:59:59\"` → 13. */\nfunction hourOf(bucket: string | undefined): number {\n  const hour = Number(bucket?.slice(0, 2));\n  if (!Number.isInteger(hour) || hour < 0 || hour > 23) {\n    throw new Error(`Unexpected Meta hourly bucket: ${bucket}`);\n  }\n  return hour;\n}\n\n/** A row for one hour: what Meta reports of an ad, its numbers as given. */\nfunction toRow(\n  insight: Insight,\n  hourStart: Date,\n  accountId: string,\n  currency: string,\n  actionType: string\n): AdPerformanceRow {\n  const conversions = conversion(insight.actions, actionType);\n  const values = conversion(insight.action_values, actionType);\n  return {\n    platform: 'meta',\n    account_id: accountId,\n    campaign_id: insight.campaign_id,\n    campaign_name: insight.campaign_name ?? null,\n    ad_group_id: insight.adset_id ?? null,\n    ad_group_name: insight.adset_name ?? null,\n    ad_id: insight.ad_id,\n    ad_name: insight.ad_name ?? null,\n    channel: CHANNEL,\n    medium: MEDIUM,\n    channel_group: channelGroupOf(CHANNEL, MEDIUM),\n    hour_start: hourStart.toISOString(),\n    currency,\n    spend: Number(insight.spend ?? 0),\n    impressions: count(insight.impressions),\n    clicks: count(insight.inline_link_clicks),\n    conversions: conversions.total,\n    conversion_value: values.total,\n    click_conversions: conversions.click,\n    click_conversion_value: values.click,\n  };\n}\n\n/**\n * `value` in `parts` equal shares rounded to `SPREAD_SCALE`, the rounding left in the last share\n * so that the shares add back to `value` exactly as Meta reported it.\n */\nexport function spread(value: number, parts: number): number[] {\n  const share = Math.round((value / parts) * SPREAD_SCALE) / SPREAD_SCALE;\n  const last = Math.round((value - share * (parts - 1)) * SPREAD_SCALE) / SPREAD_SCALE;\n  return [...Array.from({ length: parts - 1 }, () => share), last];\n}\n\n/**\n * A day row as one row per hour of the account's calendar day — 24, or 23 / 25 across a\n * daylight-saving change — each number spread evenly (nulls stay null).\n */\nfunction spreadDay(day: AdPerformanceRow, date: string, timeZone: string): AdPerformanceRow[] {\n  const start = zonedHourToUtc(date, 0, timeZone).getTime();\n  const end = zonedHourToUtc(addDays(date, 1), 0, timeZone).getTime();\n  const hours = Math.round((end - start) / 3_600_000);\n  const shares = (value: number | null) => (value === null ? null : spread(value, hours));\n  const spend = spread(day.spend, hours);\n  const impressions = spread(day.impressions, hours);\n  const clicks = spread(day.clicks, hours);\n  const conversions = shares(day.conversions);\n  const conversionValue = shares(day.conversion_value);\n  const clickConversions = shares(day.click_conversions);\n  const clickConversionValue = shares(day.click_conversion_value);\n  return Array.from({ length: hours }, (_, hour) => ({\n    ...day,\n    hour_start: new Date(start + hour * 3_600_000).toISOString(),\n    spend: spend[hour],\n    impressions: impressions[hour],\n    clicks: clicks[hour],\n    conversions: conversions?.[hour] ?? null,\n    conversion_value: conversionValue?.[hour] ?? null,\n    click_conversions: clickConversions?.[hour] ?? null,\n    click_conversion_value: clickConversionValue?.[hour] ?? null,\n  }));\n}\n\ninterface Account {\n  id: string;\n  currency: string;\n  timezone_name: string;\n}\n\nasync function accountOf(options: MetaAdPerformanceOptions): Promise<Account> {\n  const id = options.accountId.replace(/^act_/, '');\n  const account = await graphGet(\n    `act_${id}`,\n    { fields: 'currency,timezone_name' },\n    options,\n    parseWith(accountSchema, 'ad account')\n  );\n  return { id, ...account };\n}\n\n/** Every ad row of the account between `since` and `until`, one request per window of `chunkDays`. */\nasync function insights(\n  options: MetaAdPerformanceOptions,\n  accountId: string,\n  since: string,\n  until: string,\n  { chunkDays, hourly }: { chunkDays: number; hourly: boolean }\n): Promise<Insight[]> {\n  const rows: Insight[] = [];\n  for (let from = since; from <= until; from = addDays(from, chunkDays)) {\n    const last = addDays(from, chunkDays - 1);\n    const to = last < until ? last : until;\n    let after: string | undefined;\n    do {\n      const params: Record<string, string> = {\n        level: 'ad',\n        fields: FIELDS.join(','),\n        time_range: JSON.stringify({ since: from, until: to }),\n        // One row per day. Without it the hourly breakdown folds the whole range into 24\n        // hour-of-day buckets, all dated `since`, and a daily request returns the range's total.\n        time_increment: '1',\n        action_attribution_windows: JSON.stringify([CLICK_WINDOW, VIEW_WINDOW]),\n        use_unified_attribution_setting: 'true',\n        limit: '500',\n      };\n      if (hourly) params.breakdowns = HOURLY;\n      if (after) params.after = after;\n      const page = await graphGet(\n        `act_${accountId}/insights`,\n        params,\n        options,\n        parseWith(pageSchema, 'insights')\n      );\n      rows.push(...page.data);\n      // `next` is absent on the last page; the cursor alone is not a signal, Meta returns it there too.\n      after = page.paging?.next ? page.paging.cursors?.after : undefined;\n    } while (after);\n  }\n  return rows;\n}\n\n/**\n * Hourly delivery of every ad of the account that ran between `since` and `until` — deleted and\n * archived ads included — one row per ad and hour (hours without delivery are absent). The hours\n * are Meta's, in the account's time zone, turned into UTC instants. Conversions are those of each\n * ad's attribution setting (`use_unified_attribution_setting`), their click-through part from the\n * 7-day click window.\n *\n * Meta restates past hours as late conversions arrive — a purchase is credited to the hour of the\n * click, up to 7 days after it — and corrects spend for invalid traffic: re-fetch the last 8 days\n * daily (the 7-day window plus a day of time zone slack) and upsert on (`platform`, `account_id`,\n * `ad_id`, `hour_start`).\n *\n * @throws RangeError when `since` is more than 13 months back, where Meta keeps no hourly\n * breakdown and would answer with no rows rather than an error.\n */\nexport async function fetchMetaAdPerformance(\n  options: MetaAdPerformanceOptions\n): Promise<AdPerformanceRow[]> {\n  const actionType = options.conversionActionType ?? 'purchase';\n  const account = await accountOf(options);\n\n  // Normalized, so `2025-9-8` compares as `2025-09-08`.\n  const since = addDays(options.since, 0);\n  const until = addDays(options.until, 0);\n  const earliest = addMonths(todayIn(account.timezone_name), -HOURLY_RETENTION_MONTHS);\n  if (since < earliest) {\n    throw new RangeError(\n      `Meta keeps hourly insights for ${HOURLY_RETENTION_MONTHS} months: since ${since} is before ${earliest}`\n    );\n  }\n\n  const rows = await insights(options, account.id, since, until, {\n    chunkDays: CHUNK_DAYS,\n    hourly: true,\n  });\n  return rows.map((insight) =>\n    toRow(\n      insight,\n      zonedHourToUtc(insight.date_start, hourOf(insight[HOURLY]), account.timezone_name),\n      account.id,\n      account.currency,\n      actionType\n    )\n  );\n}\n\n/**\n * The delivery older than Meta's 13 months of hourly data, as hourly rows: Meta's daily ad rows,\n * each spread evenly over the hours of the account's day (`spread`), so that one table stays\n * hourly from end to end. Sums over whole days are Meta's exactly; the hours within a day are an\n * even split, not when the ads actually ran.\n *\n * Only for days the hourly data no longer covers, and only once: a day stored this way must\n * never also get hourly rows (an hour without delivery is not reported hourly, so its spread\n * share would stay and count twice). Fetch up to the day before the first hourly day stored.\n * These days are final; they need no re-fetch.\n *\n * @throws RangeError when `until` is within the 13 months of hourly data (use\n * `fetchMetaAdPerformance`), or `since` is past the 37 months Meta keeps at all.\n */\nexport async function fetchMetaAdPerformanceHistory(\n  options: MetaAdPerformanceOptions\n): Promise<AdPerformanceRow[]> {\n  const actionType = options.conversionActionType ?? 'purchase';\n  const account = await accountOf(options);\n\n  const since = addDays(options.since, 0);\n  const until = addDays(options.until, 0);\n  const today = todayIn(account.timezone_name);\n  const hourlyFrom = addMonths(today, -HOURLY_RETENTION_MONTHS);\n  const earliest = addMonths(today, -DAILY_RETENTION_MONTHS);\n  if (until >= hourlyFrom) {\n    throw new RangeError(\n      `Meta has hourly insights from ${hourlyFrom}: until ${until} must be before it, fetch those days with fetchMetaAdPerformance`\n    );\n  }\n  if (since < earliest) {\n    throw new RangeError(\n      `Meta keeps insights for ${DAILY_RETENTION_MONTHS} months: since ${since} is before ${earliest}`\n    );\n  }\n\n  const days = await insights(options, account.id, since, until, {\n    chunkDays: DAILY_CHUNK_DAYS,\n    hourly: false,\n  });\n  return days.flatMap((insight) => {\n    const day = toRow(\n      insight,\n      zonedHourToUtc(insight.date_start, 0, account.timezone_name),\n      account.id,\n      account.currency,\n      actionType\n    );\n    return spreadDay(day, insight.date_start, account.timezone_name);\n  });\n}\n"],"mappings":"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"}

package/dist/ads/meta.d.cts

@@ -0,0 +1,68 @@
+import { AdPerformanceRow, ReportDate } from "./types.cjs";
+//#region src/ads/meta.d.ts
+export interface MetaAdPerformanceOptions {
+  /** A token with `ads_read` on the account. */
+  accessToken: string;
+  /** The ad account id, with or without its `act_` prefix. */
+  accountId: string;
+  /** First day, in the ad account's time zone. */
+  since: ReportDate;
+  /** Last day, inclusive, in the ad account's time zone. */
+  until: ReportDate;
+  /**
+   * The `action_type` counted as the conversion, default `purchase` (Meta's total of the pixel,
+   * Conversions API and in-app purchases of an event, deduplicated).
+   */
+  conversionActionType?: string;
+  /**
+   * The app secret, when the app requires `appsecret_proof` (App settings → Advanced → "Require
+   * app secret"). The proof is computed here; the secret itself is never sent.
+   */
+  appSecret?: string;
+}
+/** A Graph API error, with Meta's code, for a caller deciding whether to retry. */
+export declare class MetaAdsApiError extends Error {
+  readonly status: number;
+  readonly code: number | undefined;
+  readonly subcode: number | undefined;
+  readonly fbtraceId: string | undefined;
+  constructor(message: string, status: number, code: number | undefined, subcode: number | undefined, fbtraceId: string | undefined);
+}
+/**
+ * `value` in `parts` equal shares rounded to `SPREAD_SCALE`, the rounding left in the last share
+ * so that the shares add back to `value` exactly as Meta reported it.
+ */
+export declare function spread(value: number, parts: number): number[];
+/**
+ * Hourly delivery of every ad of the account that ran between `since` and `until` — deleted and
+ * archived ads included — one row per ad and hour (hours without delivery are absent). The hours
+ * are Meta's, in the account's time zone, turned into UTC instants. Conversions are those of each
+ * ad's attribution setting (`use_unified_attribution_setting`), their click-through part from the
+ * 7-day click window.
+ *
+ * Meta restates past hours as late conversions arrive — a purchase is credited to the hour of the
+ * click, up to 7 days after it — and corrects spend for invalid traffic: re-fetch the last 8 days
+ * daily (the 7-day window plus a day of time zone slack) and upsert on (`platform`, `account_id`,
+ * `ad_id`, `hour_start`).
+ *
+ * @throws RangeError when `since` is more than 13 months back, where Meta keeps no hourly
+ * breakdown and would answer with no rows rather than an error.
+ */
+export declare function fetchMetaAdPerformance(options: MetaAdPerformanceOptions): Promise<AdPerformanceRow[]>;
+/**
+ * The delivery older than Meta's 13 months of hourly data, as hourly rows: Meta's daily ad rows,
+ * each spread evenly over the hours of the account's day (`spread`), so that one table stays
+ * hourly from end to end. Sums over whole days are Meta's exactly; the hours within a day are an
+ * even split, not when the ads actually ran.
+ *
+ * Only for days the hourly data no longer covers, and only once: a day stored this way must
+ * never also get hourly rows (an hour without delivery is not reported hourly, so its spread
+ * share would stay and count twice). Fetch up to the day before the first hourly day stored.
+ * These days are final; they need no re-fetch.
+ *
+ * @throws RangeError when `until` is within the 13 months of hourly data (use
+ * `fetchMetaAdPerformance`), or `since` is past the 37 months Meta keeps at all.
+ */
+export declare function fetchMetaAdPerformanceHistory(options: MetaAdPerformanceOptions): Promise<AdPerformanceRow[]>;
+//#endregion
+//# sourceMappingURL=meta.d.cts.map

package/dist/ads/meta.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.cts","names":[],"sources":["../../src/ads/meta.ts"],"mappings":";;iBAiFiB;;EAEf;;EAEA;;EAEA,OAAO;;EAEP,OAAO;;;;;EAKP;;;;;EAKA;;;qBAIW,wBAAwB;WAGxB;WACA;WACA;WACA;EALX,YACE,iBACS,gBACA,0BACA,6BACA;;;;;;wBAiKG,OAAO,eAAe;;;;;;;;;;;;;;;;wBA4GhB,uBACpB,SAAS,2BACR,QAAQ;;;;;;;;;;;;;;;wBA2CW,8BACpB,SAAS,2BACR,QAAQ"}

package/dist/ads/meta.d.mts

@@ -0,0 +1,68 @@
+import { AdPerformanceRow, ReportDate } from "./types.mjs";
+//#region src/ads/meta.d.ts
+export interface MetaAdPerformanceOptions {
+  /** A token with `ads_read` on the account. */
+  accessToken: string;
+  /** The ad account id, with or without its `act_` prefix. */
+  accountId: string;
+  /** First day, in the ad account's time zone. */
+  since: ReportDate;
+  /** Last day, inclusive, in the ad account's time zone. */
+  until: ReportDate;
+  /**
+   * The `action_type` counted as the conversion, default `purchase` (Meta's total of the pixel,
+   * Conversions API and in-app purchases of an event, deduplicated).
+   */
+  conversionActionType?: string;
+  /**
+   * The app secret, when the app requires `appsecret_proof` (App settings → Advanced → "Require
+   * app secret"). The proof is computed here; the secret itself is never sent.
+   */
+  appSecret?: string;
+}
+/** A Graph API error, with Meta's code, for a caller deciding whether to retry. */
+export declare class MetaAdsApiError extends Error {
+  readonly status: number;
+  readonly code: number | undefined;
+  readonly subcode: number | undefined;
+  readonly fbtraceId: string | undefined;
+  constructor(message: string, status: number, code: number | undefined, subcode: number | undefined, fbtraceId: string | undefined);
+}
+/**
+ * `value` in `parts` equal shares rounded to `SPREAD_SCALE`, the rounding left in the last share
+ * so that the shares add back to `value` exactly as Meta reported it.
+ */
+export declare function spread(value: number, parts: number): number[];
+/**
+ * Hourly delivery of every ad of the account that ran between `since` and `until` — deleted and
+ * archived ads included — one row per ad and hour (hours without delivery are absent). The hours
+ * are Meta's, in the account's time zone, turned into UTC instants. Conversions are those of each
+ * ad's attribution setting (`use_unified_attribution_setting`), their click-through part from the
+ * 7-day click window.
+ *
+ * Meta restates past hours as late conversions arrive — a purchase is credited to the hour of the
+ * click, up to 7 days after it — and corrects spend for invalid traffic: re-fetch the last 8 days
+ * daily (the 7-day window plus a day of time zone slack) and upsert on (`platform`, `account_id`,
+ * `ad_id`, `hour_start`).
+ *
+ * @throws RangeError when `since` is more than 13 months back, where Meta keeps no hourly
+ * breakdown and would answer with no rows rather than an error.
+ */
+export declare function fetchMetaAdPerformance(options: MetaAdPerformanceOptions): Promise<AdPerformanceRow[]>;
+/**
+ * The delivery older than Meta's 13 months of hourly data, as hourly rows: Meta's daily ad rows,
+ * each spread evenly over the hours of the account's day (`spread`), so that one table stays
+ * hourly from end to end. Sums over whole days are Meta's exactly; the hours within a day are an
+ * even split, not when the ads actually ran.
+ *
+ * Only for days the hourly data no longer covers, and only once: a day stored this way must
+ * never also get hourly rows (an hour without delivery is not reported hourly, so its spread
+ * share would stay and count twice). Fetch up to the day before the first hourly day stored.
+ * These days are final; they need no re-fetch.
+ *
+ * @throws RangeError when `until` is within the 13 months of hourly data (use
+ * `fetchMetaAdPerformance`), or `since` is past the 37 months Meta keeps at all.
+ */
+export declare function fetchMetaAdPerformanceHistory(options: MetaAdPerformanceOptions): Promise<AdPerformanceRow[]>;
+//#endregion
+//# sourceMappingURL=meta.d.mts.map

package/dist/ads/meta.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.mts","names":[],"sources":["../../src/ads/meta.ts"],"mappings":";;iBAiFiB;;EAEf;;EAEA;;EAEA,OAAO;;EAEP,OAAO;;;;;EAKP;;;;;EAKA;;;qBAIW,wBAAwB;WAGxB;WACA;WACA;WACA;EALX,YACE,iBACS,gBACA,0BACA,6BACA;;;;;;wBAiKG,OAAO,eAAe;;;;;;;;;;;;;;;;wBA4GhB,uBACpB,SAAS,2BACR,QAAQ;;;;;;;;;;;;;;;wBA2CW,8BACpB,SAAS,2BACR,QAAQ"}