@shware/analytics 11.7.0 → 11.8.0

package/README.md

@@ -341,6 +341,46 @@ 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.
+
 ## UTM params
 
 Typed as `UTMParams` (exported from `@shware/analytics`). Value unions follow the

package/dist/ads/index.cjs

@@ -0,0 +1,9 @@
+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.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 } from "./meta.cjs";
+import { addDays, addMonths, todayIn, zonedHourToUtc } from "./time.cjs";
+export { type AdPerformanceRow, type AdPlatform, MetaAdPerformanceOptions, MetaAdsApiError, type ReportDate, addDays, addMonths, fetchMetaAdPerformance, todayIn, zonedHourToUtc };

package/dist/ads/index.d.mts

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

package/dist/ads/index.mjs

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

package/dist/ads/meta.cjs

@@ -0,0 +1,234 @@
+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;
+/**
+* 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;
+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;
+}
+function toRow(insight, accountId, currency, timeZone, actionType) {
+	const start = require_ads_time.zonedHourToUtc(insight.date_start, hourOf(insight[HOURLY]), timeZone);
+	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: start.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
+	};
+}
+/**
+* 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 accountId = options.accountId.replace(/^act_/, "");
+	const actionType = options.conversionActionType ?? "purchase";
+	const account = await graphGet(`act_${accountId}`, { fields: "currency,timezone_name" }, options, parseWith(accountSchema, "ad account"));
+	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}`);
+	const rows = [];
+	for (let from = since; from <= until; from = require_ads_time.addDays(from, CHUNK_DAYS)) {
+		const last = require_ads_time.addDays(from, 6);
+		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",
+				breakdowns: HOURLY,
+				action_attribution_windows: JSON.stringify([CLICK_WINDOW, VIEW_WINDOW]),
+				use_unified_attribution_setting: "true",
+				limit: "500"
+			};
+			if (after) params.after = after;
+			const page = await graphGet(`act_${accountId}/insights`, params, options, parseWith(pageSchema, "insights"));
+			for (const insight of page.data) rows.push(toRow(insight, accountId, account.currency, account.timezone_name, actionType));
+			after = page.paging?.next ? page.paging.cursors?.after : void 0;
+		} while (after);
+	}
+	return rows;
+}
+//#endregion
+exports.MetaAdsApiError = MetaAdsApiError;
+exports.fetchMetaAdPerformance = fetchMetaAdPerformance;
+
+//# 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","zonedHourToUtc","channelGroupOf","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/**\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\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\nfunction toRow(\n  insight: Insight,\n  accountId: string,\n  currency: string,\n  timeZone: string,\n  actionType: string\n): AdPerformanceRow {\n  const start = zonedHourToUtc(insight.date_start, hourOf(insight[HOURLY]), timeZone);\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: start.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 * 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 accountId = options.accountId.replace(/^act_/, '');\n  const actionType = options.conversionActionType ?? 'purchase';\n\n  const account = await graphGet(\n    `act_${accountId}`,\n    { fields: 'currency,timezone_name' },\n    options,\n    parseWith(accountSchema, 'ad account')\n  );\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: AdPerformanceRow[] = [];\n  for (let from = since; from <= until; from = addDays(from, CHUNK_DAYS)) {\n    const last = addDays(from, CHUNK_DAYS - 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`.\n        time_increment: '1',\n        breakdowns: HOURLY,\n        action_attribution_windows: JSON.stringify([CLICK_WINDOW, VIEW_WINDOW]),\n        use_unified_attribution_setting: 'true',\n        limit: '500',\n      };\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      for (const insight of page.data) {\n        rows.push(toRow(insight, accountId, account.currency, account.timezone_name, actionType));\n      }\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\n  return rows;\n}\n"],"mappings":"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"}

package/dist/ads/meta.d.cts

@@ -0,0 +1,48 @@
+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);
+}
+/**
+ * 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[]>;
+//#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":";;iBAwEiB;;EAEf;;EAEA;;EAEA,OAAO;;EAEP,OAAO;;;;;EAKP;;;;;EAKA;;;qBAIW,wBAAwB;WAGxB;WACA;WACA;WACA;EALX,YACE,iBACS,gBACA,0BACA,6BACA;;;;;;;;;;;;;;;;;wBA4KS,uBACpB,SAAS,2BACR,QAAQ"}

package/dist/ads/meta.d.mts

@@ -0,0 +1,48 @@
+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);
+}
+/**
+ * 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[]>;
+//#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":";;iBAwEiB;;EAEf;;EAEA;;EAEA,OAAO;;EAEP,OAAO;;;;;EAKP;;;;;EAKA;;;qBAIW,wBAAwB;WAGxB;WACA;WACA;WACA;EALX,YACE,iBACS,gBACA,0BACA,6BACA;;;;;;;;;;;;;;;;;wBA4KS,uBACpB,SAAS,2BACR,QAAQ"}

package/dist/ads/meta.mjs

@@ -0,0 +1,232 @@
+import { channelGroupOf } from "../attribution/classify.mjs";
+import "../attribution/index.mjs";
+import { addDays, addMonths, todayIn, zonedHourToUtc } from "./time.mjs";
+import { fetch } from "@shware/utils";
+import { array, number, object, optional, safeParse, string } from "zod/mini";
+import { createHmac } from "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;
+/**
+* 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;
+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 = object({
+	action_type: 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: optional(string()),
+	[CLICK_WINDOW]: optional(string()),
+	[VIEW_WINDOW]: optional(string())
+});
+const insightSchema = object({
+	ad_id: string(),
+	ad_name: optional(string()),
+	adset_id: optional(string()),
+	adset_name: optional(string()),
+	campaign_id: string(),
+	campaign_name: optional(string()),
+	spend: optional(string()),
+	impressions: optional(string()),
+	inline_link_clicks: optional(string()),
+	actions: optional(array(actionSchema)),
+	action_values: optional(array(actionSchema)),
+	date_start: string(),
+	[HOURLY]: optional(string())
+});
+const pageSchema = object({
+	data: array(insightSchema),
+	paging: optional(object({
+		cursors: optional(object({ after: optional(string()) })),
+		next: optional(string())
+	}))
+});
+const accountSchema = object({
+	currency: string(),
+	timezone_name: string()
+});
+const errorSchema = object({ error: object({
+	message: string(),
+	code: optional(number()),
+	error_subcode: optional(number()),
+	fbtrace_id: optional(string())
+}) });
+async function graphGet(path, params, options, parse) {
+	const query = new URLSearchParams(params);
+	if (options.appSecret) query.set("appsecret_proof", createHmac("sha256", options.appSecret).update(options.accessToken).digest("hex"));
+	const response = await fetch(`${GRAPH}/${path}?${query}`, { headers: { authorization: `Bearer ${options.accessToken}` } });
+	const body = await response.json().catch(() => null);
+	if (!response.ok) {
+		const parsed = 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 = 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;
+}
+function toRow(insight, accountId, currency, timeZone, actionType) {
+	const start = zonedHourToUtc(insight.date_start, hourOf(insight[HOURLY]), timeZone);
+	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: channelGroupOf(CHANNEL, MEDIUM),
+		hour_start: start.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
+	};
+}
+/**
+* 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 accountId = options.accountId.replace(/^act_/, "");
+	const actionType = options.conversionActionType ?? "purchase";
+	const account = await graphGet(`act_${accountId}`, { fields: "currency,timezone_name" }, options, parseWith(accountSchema, "ad account"));
+	const since = addDays(options.since, 0);
+	const until = addDays(options.until, 0);
+	const earliest = addMonths(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}`);
+	const rows = [];
+	for (let from = since; from <= until; from = addDays(from, CHUNK_DAYS)) {
+		const last = addDays(from, 6);
+		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",
+				breakdowns: HOURLY,
+				action_attribution_windows: JSON.stringify([CLICK_WINDOW, VIEW_WINDOW]),
+				use_unified_attribution_setting: "true",
+				limit: "500"
+			};
+			if (after) params.after = after;
+			const page = await graphGet(`act_${accountId}/insights`, params, options, parseWith(pageSchema, "insights"));
+			for (const insight of page.data) rows.push(toRow(insight, accountId, account.currency, account.timezone_name, actionType));
+			after = page.paging?.next ? page.paging.cursors?.after : void 0;
+		} while (after);
+	}
+	return rows;
+}
+//#endregion
+export { MetaAdsApiError, fetchMetaAdPerformance };
+
+//# sourceMappingURL=meta.mjs.map

package/dist/ads/meta.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.mjs","names":[],"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/**\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\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\nfunction toRow(\n  insight: Insight,\n  accountId: string,\n  currency: string,\n  timeZone: string,\n  actionType: string\n): AdPerformanceRow {\n  const start = zonedHourToUtc(insight.date_start, hourOf(insight[HOURLY]), timeZone);\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: start.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 * 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 accountId = options.accountId.replace(/^act_/, '');\n  const actionType = options.conversionActionType ?? 'purchase';\n\n  const account = await graphGet(\n    `act_${accountId}`,\n    { fields: 'currency,timezone_name' },\n    options,\n    parseWith(accountSchema, 'ad account')\n  );\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: AdPerformanceRow[] = [];\n  for (let from = since; from <= until; from = addDays(from, CHUNK_DAYS)) {\n    const last = addDays(from, CHUNK_DAYS - 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`.\n        time_increment: '1',\n        breakdowns: HOURLY,\n        action_attribution_windows: JSON.stringify([CLICK_WINDOW, VIEW_WINDOW]),\n        use_unified_attribution_setting: 'true',\n        limit: '500',\n      };\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      for (const insight of page.data) {\n        rows.push(toRow(insight, accountId, account.currency, account.timezone_name, actionType));\n      }\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\n  return rows;\n}\n"],"mappings":"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"}

package/dist/ads/time.cjs

@@ -0,0 +1,59 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/ads/time.ts
+/** The zone's offset from UTC at an instant, in milliseconds (local minus UTC). */
+function offsetAt(instant, timeZone) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		hourCycle: "h23",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit"
+	}).formatToParts(new Date(instant));
+	const get = (type) => Number(parts.find((part) => part.type === type)?.value);
+	return Date.UTC(get("year"), get("month") - 1, get("day"), get("hour"), get("minute"), get("second")) - Math.floor(instant / 1e3) * 1e3;
+}
+/**
+* The UTC instant of `hour:00` on `date` (`YYYY-MM-DD`) in an IANA time zone. An hour skipped by
+* a daylight-saving jump resolves to the instant after the jump; a repeated hour to its first
+* occurrence — no platform reports delivery in a skipped hour, and a repeated one comes as a
+* single bucket.
+*/
+function zonedHourToUtc(date, hour, timeZone) {
+	const [year, month, day] = date.split("-").map(Number);
+	const wall = Date.UTC(year, month - 1, day, hour);
+	const first = wall - offsetAt(wall, timeZone);
+	const second = wall - offsetAt(first, timeZone);
+	const valid = [first, second].filter((c) => c + offsetAt(c, timeZone) === wall);
+	return new Date(valid.length > 0 ? Math.min(...valid) : Math.max(first, second));
+}
+const pad = (n) => String(n).padStart(2, "0");
+function format(year, month, day) {
+	return `${year}-${pad(month)}-${pad(day)}`;
+}
+/** Today's date in an IANA time zone. */
+function todayIn(timeZone, now = /* @__PURE__ */ new Date()) {
+	return new Intl.DateTimeFormat("en-CA", { timeZone }).format(now);
+}
+/** `date` moved by whole days. */
+function addDays(date, days) {
+	const [year, month, day] = date.split("-").map(Number);
+	const moved = new Date(Date.UTC(year, month - 1, day + days));
+	return format(moved.getUTCFullYear(), moved.getUTCMonth() + 1, moved.getUTCDate());
+}
+/** `date` moved by whole months, the day clamped to the target month's last (03-31 − 1 → 02-28). */
+function addMonths(date, months) {
+	const [year, month, day] = date.split("-").map(Number);
+	const target = new Date(Date.UTC(year, month - 1 + months, 1));
+	const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+	return format(target.getUTCFullYear(), target.getUTCMonth() + 1, Math.min(day, last));
+}
+//#endregion
+exports.addDays = addDays;
+exports.addMonths = addMonths;
+exports.todayIn = todayIn;
+exports.zonedHourToUtc = zonedHourToUtc;
+
+//# sourceMappingURL=time.cjs.map

package/dist/ads/time.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.cjs","names":[],"sources":["../../src/ads/time.ts"],"sourcesContent":["import type { ReportDate } from './types';\n\n/** The zone's offset from UTC at an instant, in milliseconds (local minus UTC). */\nfunction offsetAt(instant: number, timeZone: string): number {\n  const parts = new Intl.DateTimeFormat('en-US', {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n    hour: '2-digit',\n    minute: '2-digit',\n    second: '2-digit',\n  }).formatToParts(new Date(instant));\n  const get = (type: Intl.DateTimeFormatPartTypes) =>\n    Number(parts.find((part) => part.type === type)?.value);\n  const local = Date.UTC(\n    get('year'),\n    get('month') - 1,\n    get('day'),\n    get('hour'),\n    get('minute'),\n    get('second')\n  );\n  return local - Math.floor(instant / 1000) * 1000;\n}\n\n/**\n * The UTC instant of `hour:00` on `date` (`YYYY-MM-DD`) in an IANA time zone. An hour skipped by\n * a daylight-saving jump resolves to the instant after the jump; a repeated hour to its first\n * occurrence — no platform reports delivery in a skipped hour, and a repeated one comes as a\n * single bucket.\n */\nexport function zonedHourToUtc(date: string, hour: number, timeZone: string): Date {\n  const [year, month, day] = date.split('-').map(Number) as [number, number, number];\n  const wall = Date.UTC(year, month - 1, day, hour);\n  // The offset at the wall time read as UTC is a guess that is off by the jump near a transition;\n  // the offset at that first candidate gives the other. A candidate is right when it reads back\n  // as the wall time in the zone.\n  const first = wall - offsetAt(wall, timeZone);\n  const second = wall - offsetAt(first, timeZone);\n  const valid = [first, second].filter((c) => c + offsetAt(c, timeZone) === wall);\n  return new Date(valid.length > 0 ? Math.min(...valid) : Math.max(first, second));\n}\n\nconst pad = (n: number) => String(n).padStart(2, '0');\n\nfunction format(year: number, month: number, day: number): ReportDate {\n  return `${year}-${pad(month)}-${pad(day)}` as ReportDate;\n}\n\n/** Today's date in an IANA time zone. */\nexport function todayIn(timeZone: string, now = new Date()): ReportDate {\n  // en-CA formats as YYYY-MM-DD.\n  return new Intl.DateTimeFormat('en-CA', { timeZone }).format(now) as ReportDate;\n}\n\n/** `date` moved by whole days. */\nexport function addDays(date: string, days: number): ReportDate {\n  const [year, month, day] = date.split('-').map(Number) as [number, number, number];\n  const moved = new Date(Date.UTC(year, month - 1, day + days));\n  return format(moved.getUTCFullYear(), moved.getUTCMonth() + 1, moved.getUTCDate());\n}\n\n/** `date` moved by whole months, the day clamped to the target month's last (03-31 − 1 → 02-28). */\nexport function addMonths(date: string, months: number): ReportDate {\n  const [year, month, day] = date.split('-').map(Number) as [number, number, number];\n  const target = new Date(Date.UTC(year, month - 1 + months, 1));\n  const last = new Date(\n    Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)\n  ).getUTCDate();\n  return format(target.getUTCFullYear(), target.getUTCMonth() + 1, Math.min(day, last));\n}\n"],"mappings":";;;AAGA,SAAS,SAAS,SAAiB,UAA0B;CAC3D,MAAM,QAAQ,IAAI,KAAK,eAAe,SAAS;EAC7C;EACA,WAAW;EACX,MAAM;EACN,OAAO;EACP,KAAK;EACL,MAAM;EACN,QAAQ;EACR,QAAQ;CACV,CAAC,CAAC,CAAC,cAAc,IAAI,KAAK,OAAO,CAAC;CAClC,MAAM,OAAO,SACX,OAAO,MAAM,MAAM,SAAS,KAAK,SAAS,IAAI,CAAC,EAAE,KAAK;CASxD,OARc,KAAK,IACjB,IAAI,MAAM,GACV,IAAI,OAAO,IAAI,GACf,IAAI,KAAK,GACT,IAAI,MAAM,GACV,IAAI,QAAQ,GACZ,IAAI,QAAQ,CAEH,IAAI,KAAK,MAAM,UAAU,GAAI,IAAI;AAC9C;;;;;;;AAQA,SAAgB,eAAe,MAAc,MAAc,UAAwB;CACjF,MAAM,CAAC,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;CACrD,MAAM,OAAO,KAAK,IAAI,MAAM,QAAQ,GAAG,KAAK,IAAI;CAIhD,MAAM,QAAQ,OAAO,SAAS,MAAM,QAAQ;CAC5C,MAAM,SAAS,OAAO,SAAS,OAAO,QAAQ;CAC9C,MAAM,QAAQ,CAAC,OAAO,MAAM,CAAC,CAAC,QAAQ,MAAM,IAAI,SAAS,GAAG,QAAQ,MAAM,IAAI;CAC9E,OAAO,IAAI,KAAK,MAAM,SAAS,IAAI,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,IAAI,OAAO,MAAM,CAAC;AACjF;AAEA,MAAM,OAAO,MAAc,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,GAAG;AAEpD,SAAS,OAAO,MAAc,OAAe,KAAyB;CACpE,OAAO,GAAG,KAAK,GAAG,IAAI,KAAK,EAAE,GAAG,IAAI,GAAG;AACzC;;AAGA,SAAgB,QAAQ,UAAkB,sBAAM,IAAI,KAAK,GAAe;CAEtE,OAAO,IAAI,KAAK,eAAe,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,GAAG;AAClE;;AAGA,SAAgB,QAAQ,MAAc,MAA0B;CAC9D,MAAM,CAAC,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;CACrD,MAAM,QAAQ,IAAI,KAAK,KAAK,IAAI,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC;CAC5D,OAAO,OAAO,MAAM,eAAe,GAAG,MAAM,YAAY,IAAI,GAAG,MAAM,WAAW,CAAC;AACnF;;AAGA,SAAgB,UAAU,MAAc,QAA4B;CAClE,MAAM,CAAC,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;CACrD,MAAM,SAAS,IAAI,KAAK,KAAK,IAAI,MAAM,QAAQ,IAAI,QAAQ,CAAC,CAAC;CAC7D,MAAM,OAAO,IAAI,KACf,KAAK,IAAI,OAAO,eAAe,GAAG,OAAO,YAAY,IAAI,GAAG,CAAC,CAC/D,CAAC,CAAC,WAAW;CACb,OAAO,OAAO,OAAO,eAAe,GAAG,OAAO,YAAY,IAAI,GAAG,KAAK,IAAI,KAAK,IAAI,CAAC;AACtF"}

package/dist/ads/time.d.cts

@@ -0,0 +1,17 @@
+import { ReportDate } from "./types.cjs";
+//#region src/ads/time.d.ts
+/**
+ * The UTC instant of `hour:00` on `date` (`YYYY-MM-DD`) in an IANA time zone. An hour skipped by
+ * a daylight-saving jump resolves to the instant after the jump; a repeated hour to its first
+ * occurrence — no platform reports delivery in a skipped hour, and a repeated one comes as a
+ * single bucket.
+ */
+export declare function zonedHourToUtc(date: string, hour: number, timeZone: string): Date;
+/** Today's date in an IANA time zone. */
+export declare function todayIn(timeZone: string, now?: Date): ReportDate;
+/** `date` moved by whole days. */
+export declare function addDays(date: string, days: number): ReportDate;
+/** `date` moved by whole months, the day clamped to the target month's last (03-31 − 1 → 02-28). */
+export declare function addMonths(date: string, months: number): ReportDate;
+//#endregion
+//# sourceMappingURL=time.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.cts","names":[],"sources":["../../src/ads/time.ts"],"mappings":";;;;;;;;wBAiCgB,eAAe,cAAc,cAAc,mBAAmB;;wBAmB9D,QAAQ,kBAAkB,MAAG,OAAgB;;wBAM7C,QAAQ,cAAc,eAAe;;wBAOrC,UAAU,cAAc,iBAAiB"}

package/dist/ads/time.d.mts

@@ -0,0 +1,17 @@
+import { ReportDate } from "./types.mjs";
+//#region src/ads/time.d.ts
+/**
+ * The UTC instant of `hour:00` on `date` (`YYYY-MM-DD`) in an IANA time zone. An hour skipped by
+ * a daylight-saving jump resolves to the instant after the jump; a repeated hour to its first
+ * occurrence — no platform reports delivery in a skipped hour, and a repeated one comes as a
+ * single bucket.
+ */
+export declare function zonedHourToUtc(date: string, hour: number, timeZone: string): Date;
+/** Today's date in an IANA time zone. */
+export declare function todayIn(timeZone: string, now?: Date): ReportDate;
+/** `date` moved by whole days. */
+export declare function addDays(date: string, days: number): ReportDate;
+/** `date` moved by whole months, the day clamped to the target month's last (03-31 − 1 → 02-28). */
+export declare function addMonths(date: string, months: number): ReportDate;
+//#endregion
+//# sourceMappingURL=time.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.mts","names":[],"sources":["../../src/ads/time.ts"],"mappings":";;;;;;;;wBAiCgB,eAAe,cAAc,cAAc,mBAAmB;;wBAmB9D,QAAQ,kBAAkB,MAAG,OAAgB;;wBAM7C,QAAQ,cAAc,eAAe;;wBAOrC,UAAU,cAAc,iBAAiB"}

package/dist/ads/time.mjs

@@ -0,0 +1,55 @@
+//#region src/ads/time.ts
+/** The zone's offset from UTC at an instant, in milliseconds (local minus UTC). */
+function offsetAt(instant, timeZone) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		hourCycle: "h23",
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit"
+	}).formatToParts(new Date(instant));
+	const get = (type) => Number(parts.find((part) => part.type === type)?.value);
+	return Date.UTC(get("year"), get("month") - 1, get("day"), get("hour"), get("minute"), get("second")) - Math.floor(instant / 1e3) * 1e3;
+}
+/**
+* The UTC instant of `hour:00` on `date` (`YYYY-MM-DD`) in an IANA time zone. An hour skipped by
+* a daylight-saving jump resolves to the instant after the jump; a repeated hour to its first
+* occurrence — no platform reports delivery in a skipped hour, and a repeated one comes as a
+* single bucket.
+*/
+function zonedHourToUtc(date, hour, timeZone) {
+	const [year, month, day] = date.split("-").map(Number);
+	const wall = Date.UTC(year, month - 1, day, hour);
+	const first = wall - offsetAt(wall, timeZone);
+	const second = wall - offsetAt(first, timeZone);
+	const valid = [first, second].filter((c) => c + offsetAt(c, timeZone) === wall);
+	return new Date(valid.length > 0 ? Math.min(...valid) : Math.max(first, second));
+}
+const pad = (n) => String(n).padStart(2, "0");
+function format(year, month, day) {
+	return `${year}-${pad(month)}-${pad(day)}`;
+}
+/** Today's date in an IANA time zone. */
+function todayIn(timeZone, now = /* @__PURE__ */ new Date()) {
+	return new Intl.DateTimeFormat("en-CA", { timeZone }).format(now);
+}
+/** `date` moved by whole days. */
+function addDays(date, days) {
+	const [year, month, day] = date.split("-").map(Number);
+	const moved = new Date(Date.UTC(year, month - 1, day + days));
+	return format(moved.getUTCFullYear(), moved.getUTCMonth() + 1, moved.getUTCDate());
+}
+/** `date` moved by whole months, the day clamped to the target month's last (03-31 − 1 → 02-28). */
+function addMonths(date, months) {
+	const [year, month, day] = date.split("-").map(Number);
+	const target = new Date(Date.UTC(year, month - 1 + months, 1));
+	const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+	return format(target.getUTCFullYear(), target.getUTCMonth() + 1, Math.min(day, last));
+}
+//#endregion
+export { addDays, addMonths, todayIn, zonedHourToUtc };
+
+//# sourceMappingURL=time.mjs.map

package/dist/ads/time.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.mjs","names":[],"sources":["../../src/ads/time.ts"],"sourcesContent":["import type { ReportDate } from './types';\n\n/** The zone's offset from UTC at an instant, in milliseconds (local minus UTC). */\nfunction offsetAt(instant: number, timeZone: string): number {\n  const parts = new Intl.DateTimeFormat('en-US', {\n    timeZone,\n    hourCycle: 'h23',\n    year: 'numeric',\n    month: '2-digit',\n    day: '2-digit',\n    hour: '2-digit',\n    minute: '2-digit',\n    second: '2-digit',\n  }).formatToParts(new Date(instant));\n  const get = (type: Intl.DateTimeFormatPartTypes) =>\n    Number(parts.find((part) => part.type === type)?.value);\n  const local = Date.UTC(\n    get('year'),\n    get('month') - 1,\n    get('day'),\n    get('hour'),\n    get('minute'),\n    get('second')\n  );\n  return local - Math.floor(instant / 1000) * 1000;\n}\n\n/**\n * The UTC instant of `hour:00` on `date` (`YYYY-MM-DD`) in an IANA time zone. An hour skipped by\n * a daylight-saving jump resolves to the instant after the jump; a repeated hour to its first\n * occurrence — no platform reports delivery in a skipped hour, and a repeated one comes as a\n * single bucket.\n */\nexport function zonedHourToUtc(date: string, hour: number, timeZone: string): Date {\n  const [year, month, day] = date.split('-').map(Number) as [number, number, number];\n  const wall = Date.UTC(year, month - 1, day, hour);\n  // The offset at the wall time read as UTC is a guess that is off by the jump near a transition;\n  // the offset at that first candidate gives the other. A candidate is right when it reads back\n  // as the wall time in the zone.\n  const first = wall - offsetAt(wall, timeZone);\n  const second = wall - offsetAt(first, timeZone);\n  const valid = [first, second].filter((c) => c + offsetAt(c, timeZone) === wall);\n  return new Date(valid.length > 0 ? Math.min(...valid) : Math.max(first, second));\n}\n\nconst pad = (n: number) => String(n).padStart(2, '0');\n\nfunction format(year: number, month: number, day: number): ReportDate {\n  return `${year}-${pad(month)}-${pad(day)}` as ReportDate;\n}\n\n/** Today's date in an IANA time zone. */\nexport function todayIn(timeZone: string, now = new Date()): ReportDate {\n  // en-CA formats as YYYY-MM-DD.\n  return new Intl.DateTimeFormat('en-CA', { timeZone }).format(now) as ReportDate;\n}\n\n/** `date` moved by whole days. */\nexport function addDays(date: string, days: number): ReportDate {\n  const [year, month, day] = date.split('-').map(Number) as [number, number, number];\n  const moved = new Date(Date.UTC(year, month - 1, day + days));\n  return format(moved.getUTCFullYear(), moved.getUTCMonth() + 1, moved.getUTCDate());\n}\n\n/** `date` moved by whole months, the day clamped to the target month's last (03-31 − 1 → 02-28). */\nexport function addMonths(date: string, months: number): ReportDate {\n  const [year, month, day] = date.split('-').map(Number) as [number, number, number];\n  const target = new Date(Date.UTC(year, month - 1 + months, 1));\n  const last = new Date(\n    Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)\n  ).getUTCDate();\n  return format(target.getUTCFullYear(), target.getUTCMonth() + 1, Math.min(day, last));\n}\n"],"mappings":";;AAGA,SAAS,SAAS,SAAiB,UAA0B;CAC3D,MAAM,QAAQ,IAAI,KAAK,eAAe,SAAS;EAC7C;EACA,WAAW;EACX,MAAM;EACN,OAAO;EACP,KAAK;EACL,MAAM;EACN,QAAQ;EACR,QAAQ;CACV,CAAC,CAAC,CAAC,cAAc,IAAI,KAAK,OAAO,CAAC;CAClC,MAAM,OAAO,SACX,OAAO,MAAM,MAAM,SAAS,KAAK,SAAS,IAAI,CAAC,EAAE,KAAK;CASxD,OARc,KAAK,IACjB,IAAI,MAAM,GACV,IAAI,OAAO,IAAI,GACf,IAAI,KAAK,GACT,IAAI,MAAM,GACV,IAAI,QAAQ,GACZ,IAAI,QAAQ,CAEH,IAAI,KAAK,MAAM,UAAU,GAAI,IAAI;AAC9C;;;;;;;AAQA,SAAgB,eAAe,MAAc,MAAc,UAAwB;CACjF,MAAM,CAAC,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;CACrD,MAAM,OAAO,KAAK,IAAI,MAAM,QAAQ,GAAG,KAAK,IAAI;CAIhD,MAAM,QAAQ,OAAO,SAAS,MAAM,QAAQ;CAC5C,MAAM,SAAS,OAAO,SAAS,OAAO,QAAQ;CAC9C,MAAM,QAAQ,CAAC,OAAO,MAAM,CAAC,CAAC,QAAQ,MAAM,IAAI,SAAS,GAAG,QAAQ,MAAM,IAAI;CAC9E,OAAO,IAAI,KAAK,MAAM,SAAS,IAAI,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,IAAI,OAAO,MAAM,CAAC;AACjF;AAEA,MAAM,OAAO,MAAc,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,GAAG;AAEpD,SAAS,OAAO,MAAc,OAAe,KAAyB;CACpE,OAAO,GAAG,KAAK,GAAG,IAAI,KAAK,EAAE,GAAG,IAAI,GAAG;AACzC;;AAGA,SAAgB,QAAQ,UAAkB,sBAAM,IAAI,KAAK,GAAe;CAEtE,OAAO,IAAI,KAAK,eAAe,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,GAAG;AAClE;;AAGA,SAAgB,QAAQ,MAAc,MAA0B;CAC9D,MAAM,CAAC,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;CACrD,MAAM,QAAQ,IAAI,KAAK,KAAK,IAAI,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC;CAC5D,OAAO,OAAO,MAAM,eAAe,GAAG,MAAM,YAAY,IAAI,GAAG,MAAM,WAAW,CAAC;AACnF;;AAGA,SAAgB,UAAU,MAAc,QAA4B;CAClE,MAAM,CAAC,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM;CACrD,MAAM,SAAS,IAAI,KAAK,KAAK,IAAI,MAAM,QAAQ,IAAI,QAAQ,CAAC,CAAC;CAC7D,MAAM,OAAO,IAAI,KACf,KAAK,IAAI,OAAO,eAAe,GAAG,OAAO,YAAY,IAAI,GAAG,CAAC,CAC/D,CAAC,CAAC,WAAW;CACb,OAAO,OAAO,OAAO,eAAe,GAAG,OAAO,YAAY,IAAI,GAAG,KAAK,IAAI,KAAK,IAAI,CAAC;AACtF"}

package/dist/ads/types.d.cts

@@ -0,0 +1,57 @@
+import { ChannelGroup } from "../attribution/vocabulary.cjs";
+//#region src/ads/types.d.ts
+/** The ad platforms whose reporting APIs this module reads. */
+export type AdPlatform = 'meta';
+/**
+ * One row of ad delivery: one ad over one hour. The row a host stores in its `ad_performance`
+ * table, unique on (`platform`, `account_id`, `ad_id`, `hour_start`).
+ *
+ * Every platform yields hourly rows, so that a sum over any span in any time zone — the way the
+ * host's attribution is grouped — is a sum of whole rows, and a table never mixes a day row with
+ * the hour rows inside it (an upsert would overwrite one with the other on the shared start, and
+ * the rest would count twice). A platform that reports only days spreads each day evenly over its
+ * hours, the counts then fractional.
+ *
+ * `channel`, `medium` and `channel_group` use the attribution vocabulary (`classifyTouch`), so a
+ * row joins the host's sessions and attribution on the same values with no mapping in SQL.
+ */
+export interface AdPerformanceRow {
+  /** The reporting API the row came from; `channel` is what it joins attribution on. */
+  platform: AdPlatform;
+  /** The platform's account id, without a prefix (Meta's `act_` is stripped). */
+  account_id: string;
+  campaign_id: string;
+  campaign_name: string | null;
+  /** The level between campaign and ad: Meta's ad set. */
+  ad_group_id: string | null;
+  ad_group_name: string | null;
+  ad_id: string;
+  ad_name: string | null;
+  channel: string;
+  medium: string;
+  channel_group: ChannelGroup;
+  /** The start of the hour, an ISO 8601 UTC instant; the row covers the hour that follows. */
+  hour_start: string;
+  /** The account's currency, ISO 4217; every amount of the row is in it. */
+  currency: string;
+  spend: number;
+  impressions: number;
+  /**
+   * Clicks to the advertiser's site — Meta's `inline_link_clicks`, not `clicks`, which also counts
+   * likes, expands and profile taps. The number to compare with the sessions an ad brought.
+   */
+  clicks: number;
+  /**
+   * The platform's own count of the conversion event (and its value) under the attribution
+   * setting of the ad — view-through included. Null when the platform reported none.
+   */
+  conversions: number | null;
+  conversion_value: number | null;
+  /** The click-through part only: the platform's number to set against a click-based attribution. */
+  click_conversions: number | null;
+  click_conversion_value: number | null;
+}
+/** A calendar date, `YYYY-MM-DD`, in the ad account's own time zone. */
+export type ReportDate = `${number}-${number}-${number}`;
+//#endregion
+//# sourceMappingURL=types.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/ads/types.ts"],"mappings":";;;YAGY;;;;;;;;;;;;;;iBAeK;;EAEf,UAAU;;EAEV;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;EACA;EACA,eAAe;;EAEf;;EAEA;EACA;EACA;;;;;EAKA;;;;;EAKA;EACA;;EAEA;EACA;;;YAIU"}

package/dist/ads/types.d.mts

@@ -0,0 +1,57 @@
+import { ChannelGroup } from "../attribution/vocabulary.mjs";
+//#region src/ads/types.d.ts
+/** The ad platforms whose reporting APIs this module reads. */
+export type AdPlatform = 'meta';
+/**
+ * One row of ad delivery: one ad over one hour. The row a host stores in its `ad_performance`
+ * table, unique on (`platform`, `account_id`, `ad_id`, `hour_start`).
+ *
+ * Every platform yields hourly rows, so that a sum over any span in any time zone — the way the
+ * host's attribution is grouped — is a sum of whole rows, and a table never mixes a day row with
+ * the hour rows inside it (an upsert would overwrite one with the other on the shared start, and
+ * the rest would count twice). A platform that reports only days spreads each day evenly over its
+ * hours, the counts then fractional.
+ *
+ * `channel`, `medium` and `channel_group` use the attribution vocabulary (`classifyTouch`), so a
+ * row joins the host's sessions and attribution on the same values with no mapping in SQL.
+ */
+export interface AdPerformanceRow {
+  /** The reporting API the row came from; `channel` is what it joins attribution on. */
+  platform: AdPlatform;
+  /** The platform's account id, without a prefix (Meta's `act_` is stripped). */
+  account_id: string;
+  campaign_id: string;
+  campaign_name: string | null;
+  /** The level between campaign and ad: Meta's ad set. */
+  ad_group_id: string | null;
+  ad_group_name: string | null;
+  ad_id: string;
+  ad_name: string | null;
+  channel: string;
+  medium: string;
+  channel_group: ChannelGroup;
+  /** The start of the hour, an ISO 8601 UTC instant; the row covers the hour that follows. */
+  hour_start: string;
+  /** The account's currency, ISO 4217; every amount of the row is in it. */
+  currency: string;
+  spend: number;
+  impressions: number;
+  /**
+   * Clicks to the advertiser's site — Meta's `inline_link_clicks`, not `clicks`, which also counts
+   * likes, expands and profile taps. The number to compare with the sessions an ad brought.
+   */
+  clicks: number;
+  /**
+   * The platform's own count of the conversion event (and its value) under the attribution
+   * setting of the ad — view-through included. Null when the platform reported none.
+   */
+  conversions: number | null;
+  conversion_value: number | null;
+  /** The click-through part only: the platform's number to set against a click-based attribution. */
+  click_conversions: number | null;
+  click_conversion_value: number | null;
+}
+/** A calendar date, `YYYY-MM-DD`, in the ad account's own time zone. */
+export type ReportDate = `${number}-${number}-${number}`;
+//#endregion
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/ads/types.ts"],"mappings":";;;YAGY;;;;;;;;;;;;;;iBAeK;;EAEf,UAAU;;EAEV;EACA;EACA;;EAEA;EACA;EACA;EACA;EACA;EACA;EACA,eAAe;;EAEf;;EAEA;EACA;EACA;;;;;EAKA;;;;;EAKA;EACA;;EAEA;EACA;;;YAIU"}

package/dist/ads/types.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shware/analytics",
-  "version": "11.7.0",
+  "version": "11.8.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -21,6 +21,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./ads": {
+      "import": {
+        "types": "./dist/ads/index.d.mts",
+        "default": "./dist/ads/index.mjs"
+      },
+      "require": {
+        "types": "./dist/ads/index.d.cts",
+        "default": "./dist/ads/index.cjs"
+      }
+    },
     "./attribution": {
       "import": {
         "types": "./dist/attribution/index.d.mts",