@shware/analytics 7.5.0 → 7.6.0

package/dist/server/meta-capi.cjs

@@ -0,0 +1,258 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_third_parties_ignored_events = require("../third-parties/ignored-events.cjs");
+const require_click_id_index = require("../click-id/index.cjs");
+const require_server_action_source = require("./action-source.cjs");
+const require_track_fbq = require("../track/fbq.cjs");
+const require_server_page_location = require("./page-location.cjs");
+let _shware_utils = require("@shware/utils");
+let node_crypto = require("node:crypto");
+let capi_param_builder_nodejs = require("capi-param-builder-nodejs");
+//#region src/server/meta-capi.ts
+/**
+* Meta Conversions API sender built on `capi-param-builder-nodejs` and plain `fetch`, replacing
+* the 31MB `facebook-nodejs-business-sdk` with ~0.5MB of parameter building. `sendMetaEvents`
+* stays exported and untouched; this module is the drop-in successor hosts opt into.
+*
+* The wire payload is byte-identical to what the business SDK's `ServerEvent.normalize()`
+* produces — enforced by a differential test that runs both builders over the same events.
+* Where the two libraries normalize differently (the business SDK keeps punctuation in names,
+* spaces in multi-word last names, accents in cities; the param builder strips them per the
+* current documented rules), this module follows the business SDK so that switching senders
+* cannot change a single hash Meta receives. The param builder is used where the two provably
+* agree — email, phone, gender, country — and its adoption-tracking appendix (`<hash>.<token>`)
+* is stripped for the same reason.
+*
+* Two deliberate behavior differences from the business SDK, both on invalid input only:
+* an invalid field (malformed email, non-ISO country, letters in a phone) is dropped from
+* user_data instead of throwing inside `execute()` and costing the whole batch; an invalid
+* currency is uppercased and forwarded instead of rejected. Valid input is unaffected.
+*
+* https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api
+* https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+*/
+/** Matches the Graph API version the pinned business SDK speaks (`FacebookAdsApi.VERSION`). */
+const API_VERSION = "v24.0";
+const USER_ASSIGNED_COUNTRIES = ["xk"];
+function normalizeCountry(input) {
+	const country = input?.split(/[-_]/).at(0)?.toLowerCase();
+	if (!country) return void 0;
+	return USER_ASSIGNED_COUNTRIES.includes(country) ? void 0 : country;
+}
+/**
+* Lazy for the same reason as the session and the token bucket (see setup/session.ts):
+* Cloudflare Workers refuse some work in module scope, and nothing here is per-request state.
+*/
+let paramBuilder;
+/**
+* Normalize and hash one PII value through the param builder, stripped to the bare SHA-256 the
+* business SDK sends: the builder appends a `.<language-token>` adoption marker that Meta's
+* endpoint tolerates but the business SDK never produced. Pre-hashed input passes through, as
+* it does in the business SDK.
+*/
+function pii(value, dataType) {
+	if (!value) return void 0;
+	return (paramBuilder ??= new capi_param_builder_nodejs.ParamBuilder()).getNormalizedAndHashedPII(value, dataType)?.split(".").at(0) ?? void 0;
+}
+const SHA256_OR_MD5 = /^[a-f0-9]{64}$|^[a-f0-9]{32}$/;
+/**
+* The business SDK's `normalizeAndHash` for the fields where the param builder normalizes
+* differently (names, city, state, zip): trim + lowercase, pass a pre-hashed value through,
+* apply the field rule, SHA-256. Field rules are copied from `ServerSideUtils` verbatim so the
+* differential test can hold the outputs equal.
+*/
+function hashed(input, rule) {
+	if (!input) return void 0;
+	const lowered = input.trim().toLowerCase();
+	if (!lowered) return void 0;
+	if (SHA256_OR_MD5.test(lowered)) return lowered;
+	const normalized = rule(lowered);
+	if (normalized === void 0) return void 0;
+	return (0, node_crypto.createHash)("sha256").update(normalized).digest("hex");
+}
+const nameRule = (v) => v;
+const f5Rule = (v) => v.length <= 5 ? v : v.slice(0, 5);
+const cityStateRule = (v) => v.replace(/[0-9\s().-]/g, "");
+const zipRule = (v) => {
+	const zip = v.replace(/\s/g, "").split("-", 1)[0];
+	return zip.length < 2 ? void 0 : zip;
+};
+/**
+* Every multi-value field is deduplicated after hashing, order preserved — the SDK runs each
+* through `dedupArray` (a Set), `external_id` included.
+*/
+const dedupe = (hashes) => Array.from(new Set(hashes.filter((hash) => hash !== void 0)));
+const list = (hashes) => {
+	const deduped = dedupe(hashes);
+	return deduped.length > 0 ? deduped : void 0;
+};
+function getUserData(tags, data, eventTimeMs) {
+	const userData = {};
+	if (data.email) {
+		const emails = Array.isArray(data.email) ? data.email : [data.email];
+		userData.em = list(emails.map((email) => pii(email, capi_param_builder_nodejs.PII_DATA_TYPE.EMAIL)));
+	}
+	if (data.phone_number) {
+		const phones = Array.isArray(data.phone_number) ? data.phone_number : [data.phone_number];
+		userData.ph = list(phones.map((phone) => pii(phone, capi_param_builder_nodejs.PII_DATA_TYPE.PHONE)));
+	}
+	if (data.gender === "female" || data.gender === "male") userData.ge = list([pii(data.gender === "female" ? "f" : "m", capi_param_builder_nodejs.PII_DATA_TYPE.GENDER)]);
+	if (data.address) if (Array.isArray(data.address)) {
+		userData.fn = dedupe(data.address.map((a) => hashed(a.first_name, nameRule)));
+		userData.ln = dedupe(data.address.map((a) => hashed(a.last_name, nameRule)));
+		userData.ct = dedupe(data.address.map((a) => hashed(a.city, cityStateRule)));
+		userData.st = dedupe(data.address.map((a) => hashed(a.region, cityStateRule)));
+		userData.zp = dedupe(data.address.map((a) => hashed(a.postal_code, zipRule)));
+		userData.country = dedupe(data.address.map((a) => pii(normalizeCountry(a.country), capi_param_builder_nodejs.PII_DATA_TYPE.COUNTRY)));
+	} else {
+		userData.fn = list([hashed(data.address.first_name, nameRule)]);
+		userData.ln = list([hashed(data.address.last_name, nameRule)]);
+		userData.ct = list([hashed(data.address.city, cityStateRule)]);
+		userData.st = list([hashed(data.address.region, cityStateRule)]);
+		userData.zp = list([hashed(data.address.postal_code, zipRule)]);
+		userData.country = list([pii(normalizeCountry(data.address.country), capi_param_builder_nodejs.PII_DATA_TYPE.COUNTRY)]);
+		userData.f5first = hashed(data.address.first_name?.slice(0, 5), f5Rule);
+		userData.f5last = hashed(data.address.last_name?.slice(0, 5), f5Rule);
+	}
+	if (data.birthday) {
+		const { year, month, day } = data.birthday;
+		if (/^\d{4}$/.test(year.toString())) userData.doby = (0, node_crypto.createHash)("sha256").update(year.toString()).digest("hex");
+		if (month >= 1 && month <= 12) userData.dobm = (0, node_crypto.createHash)("sha256").update(month.toString().padStart(2, "0")).digest("hex");
+		if (day >= 1 && day <= 31) userData.dobd = (0, node_crypto.createHash)("sha256").update(day.toString().padStart(2, "0")).digest("hex");
+	}
+	if (data.user_id && data.user_id.length !== 0) userData.external_id = [data.user_id];
+	if (data.ip_address) userData.client_ip_address = data.ip_address;
+	if (data.user_agent) userData.client_user_agent = data.user_agent;
+	if (data.fb_login_id) userData.fb_login_id = data.fb_login_id;
+	if (data.fb_page_id) userData.page_id = data.fb_page_id;
+	if (tags.fbc) userData.fbc = tags.fbc;
+	else if (tags.fbclid) userData.fbc = require_click_id_index.formatFbc(tags.fbclid, eventTimeMs);
+	if (tags.fbp) userData.fbp = tags.fbp;
+	if (tags.advertising_id) userData.madid = tags.advertising_id;
+	if (tags.ip_address && typeof tags.ip_address === "string") userData.client_ip_address = tags.ip_address;
+	return userData;
+}
+const DELIVERY_CATEGORIES = [
+	"in_store",
+	"curbside",
+	"home_delivery"
+];
+function getCustomData({ name, properties }) {
+	const [_, _name, fbEventProperties] = require_track_fbq.mapFBEvent(name, properties);
+	const { value, currency, content_name, content_category, content_ids, contents, content_type, predicted_ltv, num_items, search_string, status, delivery_category, ...custom_properties } = fbEventProperties;
+	const customData = {};
+	if (value !== void 0 && value !== null && Number.isFinite(Number.parseFloat(String(value)))) customData.value = Number.parseFloat(String(value));
+	if (currency) customData.currency = currency.trim().toUpperCase().replace(/[^A-Z]/g, "");
+	if (content_name) customData.content_name = content_name;
+	if (content_category) customData.content_category = content_category;
+	if (content_ids) customData.content_ids = content_ids;
+	if (contents) customData.contents = contents.map((c) => {
+		const content = {};
+		if (c.id) content.id = c.id;
+		if (c.quantity) content.quantity = c.quantity;
+		if (c.item_price) content.item_price = c.item_price;
+		if (c.title) content.title = c.title;
+		if (c.description) content.description = c.description;
+		if (c.brand) content.brand = c.brand;
+		if (c.category) content.category = c.category;
+		const delivery = c.delivery_category?.trim().toLowerCase();
+		if (delivery && DELIVERY_CATEGORIES.includes(delivery)) content.delivery_category = delivery;
+		return content;
+	});
+	if (content_type) customData.content_type = content_type;
+	if (predicted_ltv) customData.predicted_ltv = predicted_ltv;
+	if (num_items) customData.num_items = num_items;
+	if (search_string) customData.search_string = search_string;
+	if (status) customData.status = status.toString();
+	const delivery = delivery_category?.trim().toLowerCase();
+	if (delivery && DELIVERY_CATEGORIES.includes(delivery)) customData.delivery_category = delivery;
+	return {
+		...customData,
+		...custom_properties
+	};
+}
+/**
+* `extinfo` is keyed by field index. The business SDK builds the same object and leaves unset
+* indexes out when it serializes; the documented 16-element array is what the Graph endpoint
+* decodes this into. Indexes: 0 version, 1 package, 2 short version, 3 long version, 4 OS
+* version, 5 device model, 6 locale, 9 screen width, 10 height, 11 density.
+*/
+function getAppData(tags, appPackageName) {
+	const extinfo = {};
+	if (tags.os_name === "iOS" || tags.os_name === "iPadOS") extinfo[0] = "i2";
+	else if (tags.os_name === "Android") extinfo[0] = "a2";
+	extinfo[1] = appPackageName;
+	const shortVersion = tags.release?.split(".").at(0);
+	if (shortVersion) extinfo[2] = shortVersion;
+	if (tags.release) extinfo[3] = tags.release;
+	if (tags.os_version) extinfo[4] = tags.os_version;
+	if (tags.device_model_id) extinfo[5] = tags.device_model_id;
+	if (tags.language) extinfo[6] = tags.language;
+	if (tags.screen_width) extinfo[9] = tags.screen_width;
+	if (tags.screen_height) extinfo[10] = tags.screen_height;
+	if (tags.device_pixel_ratio) extinfo[11] = tags.device_pixel_ratio.toString();
+	const appData = { extinfo };
+	if (tags.advertising_id) appData.advertiser_tracking_enabled = true;
+	if (tags.install_referrer) appData.install_referrer = tags.install_referrer;
+	return appData;
+}
+/**
+* `action_source` is derived from `event.platform` alone: an OS platform is an app, `web` is a
+* website, and everything else — including a backend-built offline conversion, which should
+* declare `platform: 'unknown'` — lands in Meta's `other`, exactly where the business-SDK
+* sender put an explicit `'offline'` too.
+*/
+function getCapiEvent(event, data, appPackageName) {
+	const eventTimeMs = new Date(event.created_at).getTime();
+	const [_, eventName] = require_track_fbq.mapFBEvent(event.name, event.properties);
+	const source = require_server_action_source.resolveActionSource(event.platform);
+	const capiEvent = {
+		event_name: eventName,
+		event_time: Math.round(eventTimeMs / 1e3),
+		event_id: event.tags.idempotency_key ?? event.id,
+		action_source: source === "app" ? "app" : source === "web" ? "website" : "other",
+		user_data: getUserData(event.tags, data, eventTimeMs),
+		custom_data: getCustomData(event)
+	};
+	if (source === "app" && appPackageName) capiEvent.app_data = getAppData(event.tags, appPackageName);
+	const eventSourceUrl = require_server_page_location.pageLocation(event.tags);
+	if (eventSourceUrl) capiEvent.event_source_url = eventSourceUrl;
+	return capiEvent;
+}
+/**
+* The lightweight counterpart to `sendMetaEvents`: same filtering, same payload, same
+* never-throws contract, minus the 31MB SDK. The token travels in the JSON body, never in the
+* URL, and is never logged.
+*/
+async function sendMetaConversions(accessToken, pixelId, events, data = {}, options = {}) {
+	const capiEvents = events.filter((event) => !require_third_parties_ignored_events.IGNORED_EVENTS.includes(event.name)).map((event) => getCapiEvent(event, data, options.appPackageName));
+	if (capiEvents.length === 0) return void 0;
+	const version = options.apiVersion ?? API_VERSION;
+	try {
+		const response = await (0, _shware_utils.fetch)(`https://graph.facebook.com/${version}/${pixelId}/events`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			},
+			body: JSON.stringify({
+				data: capiEvents,
+				test_event_code: options.testEventCode,
+				access_token: accessToken
+			})
+		});
+		if (response.ok) return await response.json();
+		const { status } = response;
+		const message = await response.text();
+		console.error(`Failed to send Meta conversion, status: ${status}, body: ${message}`);
+		return;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`Failed to send Meta conversion, network error: ${message}`);
+		return;
+	}
+}
+//#endregion
+exports.getCapiEvent = getCapiEvent;
+exports.sendMetaConversions = sendMetaConversions;
+
+//# sourceMappingURL=meta-capi.cjs.map

package/dist/server/meta-capi.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-capi.cjs","names":["ParamBuilder","PII_DATA_TYPE","formatFbc","mapFBEvent","resolveActionSource","pageLocation","IGNORED_EVENTS"],"sources":["../../src/server/meta-capi.ts"],"sourcesContent":["/**\n * Meta Conversions API sender built on `capi-param-builder-nodejs` and plain `fetch`, replacing\n * the 31MB `facebook-nodejs-business-sdk` with ~0.5MB of parameter building. `sendMetaEvents`\n * stays exported and untouched; this module is the drop-in successor hosts opt into.\n *\n * The wire payload is byte-identical to what the business SDK's `ServerEvent.normalize()`\n * produces — enforced by a differential test that runs both builders over the same events.\n * Where the two libraries normalize differently (the business SDK keeps punctuation in names,\n * spaces in multi-word last names, accents in cities; the param builder strips them per the\n * current documented rules), this module follows the business SDK so that switching senders\n * cannot change a single hash Meta receives. The param builder is used where the two provably\n * agree — email, phone, gender, country — and its adoption-tracking appendix (`<hash>.<token>`)\n * is stripped for the same reason.\n *\n * Two deliberate behavior differences from the business SDK, both on invalid input only:\n * an invalid field (malformed email, non-ISO country, letters in a phone) is dropped from\n * user_data instead of throwing inside `execute()` and costing the whole batch; an invalid\n * currency is uppercased and forwarded instead of rejected. Valid input is unaffected.\n *\n * https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api\n * https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters\n */\nimport { createHash } from 'node:crypto';\nimport { fetch } from '@shware/utils';\nimport { PII_DATA_TYPE, ParamBuilder } from 'capi-param-builder-nodejs';\nimport { formatFbc } from '../click-id/index';\nimport { IGNORED_EVENTS } from '../third-parties/ignored-events';\nimport { mapFBEvent } from '../track/fbq';\nimport type { TrackEvent, TrackTags, UserProvidedData } from '../track/types';\nimport { resolveActionSource } from './action-source';\nimport { pageLocation } from './page-location';\n\n/** Matches the Graph API version the pinned business SDK speaks (`FacebookAdsApi.VERSION`). */\nconst API_VERSION = 'v24.0';\n\nconst USER_ASSIGNED_COUNTRIES: string[] = ['xk'];\nfunction normalizeCountry(input: string | undefined): string | undefined {\n  const country = input?.split(/[-_]/).at(0)?.toLowerCase();\n  if (!country) return undefined;\n  return USER_ASSIGNED_COUNTRIES.includes(country) ? undefined : country;\n}\n\n/**\n * Lazy for the same reason as the session and the token bucket (see setup/session.ts):\n * Cloudflare Workers refuse some work in module scope, and nothing here is per-request state.\n */\nlet paramBuilder: ParamBuilder | undefined;\n\n/**\n * Normalize and hash one PII value through the param builder, stripped to the bare SHA-256 the\n * business SDK sends: the builder appends a `.<language-token>` adoption marker that Meta's\n * endpoint tolerates but the business SDK never produced. Pre-hashed input passes through, as\n * it does in the business SDK.\n */\nfunction pii(value: string | undefined, dataType: string): string | undefined {\n  if (!value) return undefined;\n  const built = (paramBuilder ??= new ParamBuilder()).getNormalizedAndHashedPII(value, dataType);\n  return built?.split('.').at(0) ?? undefined;\n}\n\nconst SHA256_OR_MD5 = /^[a-f0-9]{64}$|^[a-f0-9]{32}$/;\n\n/**\n * The business SDK's `normalizeAndHash` for the fields where the param builder normalizes\n * differently (names, city, state, zip): trim + lowercase, pass a pre-hashed value through,\n * apply the field rule, SHA-256. Field rules are copied from `ServerSideUtils` verbatim so the\n * differential test can hold the outputs equal.\n */\nfunction hashed(\n  input: string | undefined,\n  rule: (lowered: string) => string | undefined\n): string | undefined {\n  if (!input) return undefined;\n  const lowered = input.trim().toLowerCase();\n  if (!lowered) return undefined;\n  if (SHA256_OR_MD5.test(lowered)) return lowered;\n  const normalized = rule(lowered);\n  if (normalized === undefined) return undefined;\n  return createHash('sha256').update(normalized).digest('hex');\n}\n\nconst nameRule = (v: string) => v;\nconst f5Rule = (v: string) => (v.length <= 5 ? v : v.slice(0, 5));\nconst cityStateRule = (v: string) => v.replace(/[0-9\\s().-]/g, '');\nconst zipRule = (v: string) => {\n  const zip = v.replace(/\\s/g, '').split('-', 1)[0];\n  return zip.length < 2 ? undefined : zip;\n};\n\n/**\n * Every multi-value field is deduplicated after hashing, order preserved — the SDK runs each\n * through `dedupArray` (a Set), `external_id` included.\n */\nconst dedupe = (hashes: (string | undefined)[]) =>\n  Array.from(new Set(hashes.filter((hash): hash is string => hash !== undefined)));\n\nconst list = (hashes: (string | undefined)[]) => {\n  const deduped = dedupe(hashes);\n  return deduped.length > 0 ? deduped : undefined;\n};\n\ninterface CapiUserData {\n  em?: string[];\n  ph?: string[];\n  ge?: string[];\n  fn?: string[];\n  ln?: string[];\n  ct?: string[];\n  st?: string[];\n  zp?: string[];\n  country?: string[];\n  external_id?: string[];\n  client_ip_address?: string;\n  client_user_agent?: string;\n  fbc?: string;\n  fbp?: string;\n  fb_login_id?: string;\n  page_id?: string;\n  f5first?: string;\n  f5last?: string;\n  dobd?: string;\n  dobm?: string;\n  doby?: string;\n  madid?: string;\n}\n\nfunction getUserData(tags: TrackTags, data: UserProvidedData, eventTimeMs: number): CapiUserData {\n  const userData: CapiUserData = {};\n\n  if (data.email) {\n    const emails = Array.isArray(data.email) ? data.email : [data.email];\n    userData.em = list(emails.map((email) => pii(email, PII_DATA_TYPE.EMAIL)));\n  }\n  if (data.phone_number) {\n    const phones = Array.isArray(data.phone_number) ? data.phone_number : [data.phone_number];\n    userData.ph = list(phones.map((phone) => pii(phone, PII_DATA_TYPE.PHONE)));\n  }\n  if (data.gender === 'female' || data.gender === 'male') {\n    userData.ge = list([pii(data.gender === 'female' ? 'f' : 'm', PII_DATA_TYPE.GENDER)]);\n  }\n  if (data.address) {\n    if (Array.isArray(data.address)) {\n      // The SDK sets these lists unconditionally in the multi-address branch, so an all-empty\n      // column still goes out as `[]` — kept for byte-equality with the current sender.\n      userData.fn = dedupe(data.address.map((a) => hashed(a.first_name, nameRule)));\n      userData.ln = dedupe(data.address.map((a) => hashed(a.last_name, nameRule)));\n      userData.ct = dedupe(data.address.map((a) => hashed(a.city, cityStateRule)));\n      userData.st = dedupe(data.address.map((a) => hashed(a.region, cityStateRule)));\n      userData.zp = dedupe(data.address.map((a) => hashed(a.postal_code, zipRule)));\n      userData.country = dedupe(\n        data.address.map((a) => pii(normalizeCountry(a.country), PII_DATA_TYPE.COUNTRY))\n      );\n    } else {\n      userData.fn = list([hashed(data.address.first_name, nameRule)]);\n      userData.ln = list([hashed(data.address.last_name, nameRule)]);\n      userData.ct = list([hashed(data.address.city, cityStateRule)]);\n      userData.st = list([hashed(data.address.region, cityStateRule)]);\n      userData.zp = list([hashed(data.address.postal_code, zipRule)]);\n      userData.country = list([pii(normalizeCountry(data.address.country), PII_DATA_TYPE.COUNTRY)]);\n      // The 5-character prefixes, exactly as the current sender builds them: sliced first, then\n      // normalized. Only the single-address branch sets them, as before.\n      userData.f5first = hashed(data.address.first_name?.slice(0, 5), f5Rule);\n      userData.f5last = hashed(data.address.last_name?.slice(0, 5), f5Rule);\n    }\n  }\n  if (data.birthday) {\n    const { year, month, day } = data.birthday;\n    if (/^\\d{4}$/.test(year.toString())) {\n      userData.doby = createHash('sha256').update(year.toString()).digest('hex');\n    }\n    if (month >= 1 && month <= 12) {\n      userData.dobm = createHash('sha256').update(month.toString().padStart(2, '0')).digest('hex');\n    }\n    if (day >= 1 && day <= 31) {\n      userData.dobd = createHash('sha256').update(day.toString().padStart(2, '0')).digest('hex');\n    }\n  }\n  if (data.user_id && data.user_id.length !== 0) {\n    // Unhashed, as the business SDK sends it. Meta documents hashing as recommended, not\n    // required; changing it here would break continuity with every event sent so far.\n    userData.external_id = [data.user_id];\n  }\n  if (data.ip_address) {\n    userData.client_ip_address = data.ip_address;\n  }\n  if (data.user_agent) {\n    userData.client_user_agent = data.user_agent;\n  }\n  if (data.fb_login_id) {\n    userData.fb_login_id = data.fb_login_id;\n  }\n  if (data.fb_page_id) {\n    userData.page_id = data.fb_page_id;\n  }\n\n  if (tags.fbc) {\n    userData.fbc = tags.fbc;\n  } else if (tags.fbclid) {\n    userData.fbc = formatFbc(tags.fbclid, eventTimeMs);\n  }\n  if (tags.fbp) {\n    userData.fbp = tags.fbp;\n  }\n  if (tags.advertising_id) {\n    userData.madid = tags.advertising_id;\n  }\n  if (tags.ip_address && typeof tags.ip_address === 'string') {\n    userData.client_ip_address = tags.ip_address;\n  }\n\n  return userData;\n}\n\nconst DELIVERY_CATEGORIES = ['in_store', 'curbside', 'home_delivery'];\n\n// oxlint-disable-next-line @typescript-eslint/no-explicit-any\nfunction getCustomData({ name, properties }: TrackEvent<any>): Record<string, unknown> {\n  const [_, _name, fbEventProperties] = mapFBEvent(name, properties);\n  const {\n    value,\n    currency,\n    content_name,\n    content_category,\n    content_ids,\n    contents,\n    content_type,\n    predicted_ltv,\n    num_items,\n    search_string,\n    status,\n    delivery_category,\n    ...custom_properties\n  } = fbEventProperties;\n\n  const customData: Record<string, unknown> = {};\n  // oxlint-disable-next-line typescript/no-unnecessary-condition -- custom event properties may carry `value: null` at runtime despite the declared type\n  if (value !== undefined && value !== null && Number.isFinite(Number.parseFloat(String(value)))) {\n    customData.value = Number.parseFloat(String(value));\n  }\n  if (currency) {\n    // The business SDK also validates against the ISO 4217 list and throws; here an unknown\n    // code is forwarded uppercased rather than costing the batch.\n    customData.currency = currency.trim().toUpperCase().replace(/[^A-Z]/g, '');\n  }\n  if (content_name) customData.content_name = content_name;\n  if (content_category) customData.content_category = content_category;\n  if (content_ids) customData.content_ids = content_ids;\n  if (contents) {\n    customData.contents = contents.map((c) => {\n      const content: Record<string, unknown> = {};\n      if (c.id) content.id = c.id;\n      if (c.quantity) content.quantity = c.quantity;\n      if (c.item_price) content.item_price = c.item_price;\n      if (c.title) content.title = c.title;\n      if (c.description) content.description = c.description;\n      if (c.brand) content.brand = c.brand;\n      if (c.category) content.category = c.category;\n      const delivery = c.delivery_category?.trim().toLowerCase();\n      if (delivery && DELIVERY_CATEGORIES.includes(delivery)) content.delivery_category = delivery;\n      return content;\n    });\n  }\n  if (content_type) customData.content_type = content_type;\n  if (predicted_ltv) customData.predicted_ltv = predicted_ltv;\n  if (num_items) customData.num_items = num_items;\n  if (search_string) customData.search_string = search_string;\n  if (status) customData.status = status.toString();\n  const delivery = delivery_category?.trim().toLowerCase();\n  if (delivery && DELIVERY_CATEGORIES.includes(delivery)) customData.delivery_category = delivery;\n\n  return { ...customData, ...custom_properties };\n}\n\n/**\n * `extinfo` is keyed by field index. The business SDK builds the same object and leaves unset\n * indexes out when it serializes; the documented 16-element array is what the Graph endpoint\n * decodes this into. Indexes: 0 version, 1 package, 2 short version, 3 long version, 4 OS\n * version, 5 device model, 6 locale, 9 screen width, 10 height, 11 density.\n */\nfunction getAppData(tags: TrackTags, appPackageName: string): Record<string, unknown> {\n  const extinfo: Record<number, string | number> = {};\n  if (tags.os_name === 'iOS' || tags.os_name === 'iPadOS') {\n    extinfo[0] = 'i2';\n  } else if (tags.os_name === 'Android') {\n    extinfo[0] = 'a2';\n  }\n  extinfo[1] = appPackageName;\n  const shortVersion = tags.release?.split('.').at(0);\n  if (shortVersion) extinfo[2] = shortVersion;\n  if (tags.release) extinfo[3] = tags.release;\n  if (tags.os_version) extinfo[4] = tags.os_version;\n  if (tags.device_model_id) extinfo[5] = tags.device_model_id;\n  if (tags.language) extinfo[6] = tags.language;\n  if (tags.screen_width) extinfo[9] = tags.screen_width;\n  if (tags.screen_height) extinfo[10] = tags.screen_height;\n  if (tags.device_pixel_ratio) extinfo[11] = tags.device_pixel_ratio.toString();\n\n  const appData: Record<string, unknown> = { extinfo };\n  if (tags.advertising_id) appData.advertiser_tracking_enabled = true;\n  if (tags.install_referrer) appData.install_referrer = tags.install_referrer;\n  return appData;\n}\n\n/** One entry of the `data` array POSTed to `/{pixel_id}/events`. */\nexport interface CapiEvent {\n  event_name: string;\n  event_time: number;\n  event_id: string;\n  event_source_url?: string;\n  action_source: 'app' | 'website' | 'other';\n  user_data: CapiUserData;\n  custom_data: Record<string, unknown>;\n  app_data?: Record<string, unknown>;\n}\n\n/**\n * `action_source` is derived from `event.platform` alone: an OS platform is an app, `web` is a\n * website, and everything else — including a backend-built offline conversion, which should\n * declare `platform: 'unknown'` — lands in Meta's `other`, exactly where the business-SDK\n * sender put an explicit `'offline'` too.\n */\nexport function getCapiEvent(\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  event: TrackEvent<any>,\n  data: UserProvidedData,\n  appPackageName?: string\n): CapiEvent {\n  const eventTimeMs = new Date(event.created_at).getTime();\n  const [_, eventName] = mapFBEvent(event.name, event.properties);\n  const source = resolveActionSource(event.platform);\n\n  const capiEvent: CapiEvent = {\n    event_name: eventName,\n    event_time: Math.round(eventTimeMs / 1000),\n    event_id: event.tags.idempotency_key ?? event.id,\n    // `action_source` is required; an offline conversion and an undeterminable platform both\n    // land in Meta's catch-all, exactly as in the business-SDK sender.\n    action_source: source === 'app' ? 'app' : source === 'web' ? 'website' : 'other',\n    user_data: getUserData(event.tags, data, eventTimeMs),\n    custom_data: getCustomData(event),\n  };\n  if (source === 'app' && appPackageName) {\n    capiEvent.app_data = getAppData(event.tags, appPackageName);\n  }\n  const eventSourceUrl = pageLocation(event.tags);\n  if (eventSourceUrl) {\n    capiEvent.event_source_url = eventSourceUrl;\n  }\n  return capiEvent;\n}\n\nexport interface MetaConversionsOptions {\n  /** Attaches `app_data`/extinfo to events whose platform resolves to an app. */\n  appPackageName?: string;\n  /** Routes the batch to Events Manager's Test Events tab instead of production. */\n  testEventCode?: string;\n  /** Graph API version, e.g. 'v24.0'. */\n  apiVersion?: string;\n}\n\nexport interface MetaConversionsResponse {\n  events_received?: number;\n  messages?: string[];\n  fbtrace_id?: string;\n}\n\n/**\n * The lightweight counterpart to `sendMetaEvents`: same filtering, same payload, same\n * never-throws contract, minus the 31MB SDK. The token travels in the JSON body, never in the\n * URL, and is never logged.\n */\nexport async function sendMetaConversions(\n  accessToken: string,\n  pixelId: string,\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  events: TrackEvent<any>[],\n  data: UserProvidedData = {},\n  options: MetaConversionsOptions = {}\n): Promise<MetaConversionsResponse | undefined> {\n  const capiEvents = events\n    .filter((event) => !IGNORED_EVENTS.includes(event.name))\n    .map((event) => getCapiEvent(event, data, options.appPackageName));\n  if (capiEvents.length === 0) return undefined;\n\n  const version = options.apiVersion ?? API_VERSION;\n  try {\n    const response = await fetch(`https://graph.facebook.com/${version}/${pixelId}/events`, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },\n      body: JSON.stringify({\n        data: capiEvents,\n        test_event_code: options.testEventCode,\n        access_token: accessToken,\n      }),\n    });\n    if (response.ok) return (await response.json()) as MetaConversionsResponse;\n    const { status } = response;\n    const message = await response.text();\n    console.error(`Failed to send Meta conversion, status: ${status}, body: ${message}`);\n    return undefined;\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    console.error(`Failed to send Meta conversion, network error: ${message}`);\n    return undefined;\n  }\n}\n"],"mappings":"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"}

package/dist/server/meta-capi.d.cts

@@ -0,0 +1,66 @@
+import { TrackEvent, UserProvidedData } from "../track/types.cjs";
+//#region src/server/meta-capi.d.ts
+interface CapiUserData {
+  em?: string[];
+  ph?: string[];
+  ge?: string[];
+  fn?: string[];
+  ln?: string[];
+  ct?: string[];
+  st?: string[];
+  zp?: string[];
+  country?: string[];
+  external_id?: string[];
+  client_ip_address?: string;
+  client_user_agent?: string;
+  fbc?: string;
+  fbp?: string;
+  fb_login_id?: string;
+  page_id?: string;
+  f5first?: string;
+  f5last?: string;
+  dobd?: string;
+  dobm?: string;
+  doby?: string;
+  madid?: string;
+}
+/** One entry of the `data` array POSTed to `/{pixel_id}/events`. */
+interface CapiEvent {
+  event_name: string;
+  event_time: number;
+  event_id: string;
+  event_source_url?: string;
+  action_source: 'app' | 'website' | 'other';
+  user_data: CapiUserData;
+  custom_data: Record<string, unknown>;
+  app_data?: Record<string, unknown>;
+}
+/**
+ * `action_source` is derived from `event.platform` alone: an OS platform is an app, `web` is a
+ * website, and everything else — including a backend-built offline conversion, which should
+ * declare `platform: 'unknown'` — lands in Meta's `other`, exactly where the business-SDK
+ * sender put an explicit `'offline'` too.
+ */
+declare function getCapiEvent(event: TrackEvent<any>, data: UserProvidedData, appPackageName?: string): CapiEvent;
+interface MetaConversionsOptions {
+  /** Attaches `app_data`/extinfo to events whose platform resolves to an app. */
+  appPackageName?: string;
+  /** Routes the batch to Events Manager's Test Events tab instead of production. */
+  testEventCode?: string;
+  /** Graph API version, e.g. 'v24.0'. */
+  apiVersion?: string;
+}
+interface MetaConversionsResponse {
+  events_received?: number;
+  messages?: string[];
+  fbtrace_id?: string;
+}
+/**
+ * The lightweight counterpart to `sendMetaEvents`: same filtering, same payload, same
+ * never-throws contract, minus the 31MB SDK. The token travels in the JSON body, never in the
+ * URL, and is never logged.
+ */
+declare function sendMetaConversions(accessToken: string, pixelId: string, events: TrackEvent<any>[], data?: UserProvidedData, options?: MetaConversionsOptions): Promise<MetaConversionsResponse | undefined>;
+//#endregion
+export { CapiEvent, MetaConversionsOptions, MetaConversionsResponse, getCapiEvent, sendMetaConversions };
+//# sourceMappingURL=meta-capi.d.cts.map

package/dist/server/meta-capi.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-capi.d.cts","names":[],"sources":["../../src/server/meta-capi.ts"],"mappings":";;UAqGU;EACR;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;UAqLe;EACf;EACA;EACA;EACA;EACA;EACA,WAAW;EACX,aAAa;EACb,WAAW;;;;;;;;iBASG,aAEd,OAAO,iBACP,MAAM,kBACN,0BACC;UAyBc;;EAEf;;EAEA;;EAEA;;UAGe;EACf;EACA;EACA;;;;;;;iBAQoB,oBACpB,qBACA,iBAEA,QAAQ,mBACR,OAAM,kBACN,UAAS,yBACR,QAAQ"}

package/dist/server/meta-capi.d.mts

@@ -0,0 +1,66 @@
+import { TrackEvent, UserProvidedData } from "../track/types.mjs";
+//#region src/server/meta-capi.d.ts
+interface CapiUserData {
+  em?: string[];
+  ph?: string[];
+  ge?: string[];
+  fn?: string[];
+  ln?: string[];
+  ct?: string[];
+  st?: string[];
+  zp?: string[];
+  country?: string[];
+  external_id?: string[];
+  client_ip_address?: string;
+  client_user_agent?: string;
+  fbc?: string;
+  fbp?: string;
+  fb_login_id?: string;
+  page_id?: string;
+  f5first?: string;
+  f5last?: string;
+  dobd?: string;
+  dobm?: string;
+  doby?: string;
+  madid?: string;
+}
+/** One entry of the `data` array POSTed to `/{pixel_id}/events`. */
+interface CapiEvent {
+  event_name: string;
+  event_time: number;
+  event_id: string;
+  event_source_url?: string;
+  action_source: 'app' | 'website' | 'other';
+  user_data: CapiUserData;
+  custom_data: Record<string, unknown>;
+  app_data?: Record<string, unknown>;
+}
+/**
+ * `action_source` is derived from `event.platform` alone: an OS platform is an app, `web` is a
+ * website, and everything else — including a backend-built offline conversion, which should
+ * declare `platform: 'unknown'` — lands in Meta's `other`, exactly where the business-SDK
+ * sender put an explicit `'offline'` too.
+ */
+declare function getCapiEvent(event: TrackEvent<any>, data: UserProvidedData, appPackageName?: string): CapiEvent;
+interface MetaConversionsOptions {
+  /** Attaches `app_data`/extinfo to events whose platform resolves to an app. */
+  appPackageName?: string;
+  /** Routes the batch to Events Manager's Test Events tab instead of production. */
+  testEventCode?: string;
+  /** Graph API version, e.g. 'v24.0'. */
+  apiVersion?: string;
+}
+interface MetaConversionsResponse {
+  events_received?: number;
+  messages?: string[];
+  fbtrace_id?: string;
+}
+/**
+ * The lightweight counterpart to `sendMetaEvents`: same filtering, same payload, same
+ * never-throws contract, minus the 31MB SDK. The token travels in the JSON body, never in the
+ * URL, and is never logged.
+ */
+declare function sendMetaConversions(accessToken: string, pixelId: string, events: TrackEvent<any>[], data?: UserProvidedData, options?: MetaConversionsOptions): Promise<MetaConversionsResponse | undefined>;
+//#endregion
+export { CapiEvent, MetaConversionsOptions, MetaConversionsResponse, getCapiEvent, sendMetaConversions };
+//# sourceMappingURL=meta-capi.d.mts.map

package/dist/server/meta-capi.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-capi.d.mts","names":[],"sources":["../../src/server/meta-capi.ts"],"mappings":";;UAqGU;EACR;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;UAqLe;EACf;EACA;EACA;EACA;EACA;EACA,WAAW;EACX,aAAa;EACb,WAAW;;;;;;;;iBASG,aAEd,OAAO,iBACP,MAAM,kBACN,0BACC;UAyBc;;EAEf;;EAEA;;EAEA;;UAGe;EACf;EACA;EACA;;;;;;;iBAQoB,oBACpB,qBACA,iBAEA,QAAQ,mBACR,OAAM,kBACN,UAAS,yBACR,QAAQ"}