@shware/analytics 9.0.0 → 9.1.0

package/dist/track/index.mjs

@@ -38,145 +38,211 @@ async function captureTags() {
 	}
 }
 /**
-* The `session_start` a failed batch took down with it, kept for the next batch of the same
-* session. `fetch` has already retried the transient failures by the time a batch fails here;
-* what remains is a batch the server rejected outright — one invalid event fails the whole batch,
-* and `session_start` with it — or a network that stayed down past the retries. Neither is a
-* reason to lose the session's one attribution record, so it goes out again, with the tags and
-* timestamp of the moment the session actually began, under the same session id. Held in memory
-* only: a reload loses it, and with it the session_start — the same as before this existed.
+* The events not yet sent, and the only place they are: a batch leaves it at the moment it is
+* handed to `fetch` or to a beacon, never earlier. So when the page is hidden or left,
+* everything still unsent is right here for `sendPendingEvents`.
 */
-let pendingStart;
-async function sendEvents(events) {
-	/** The announcement this batch carries, if any, so the catch below can hold it back. */
-	let announcement;
+const list = [];
+const batchSize = 10;
+const delay = 2e3;
+let timer = null;
+/**
+* Queues an event, preceded by a `session_start` when it is the one that opens a session.
+*
+* The session is decided here, when the event happens, as GA4 and PostHog decide it: the
+* `session_start` then sits in the queue right before the event that opened the session, so
+* wherever that event goes — a batch, a beacon, a retry — its announcement has gone ahead of it.
+* It carries that event's tags and time, as GA4 derives it from the hit that started the
+* session: the landing page is where the session began, whatever the page has navigated to by
+* the time the batch goes out.
+*/
+function enqueue(name, properties, options) {
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	const tags = captureTags();
+	const { id: session_id, started } = getSession().touch(Date.parse(timestamp));
+	const item = (fields) => {
+		const result = {
+			...fields,
+			tags,
+			timestamp,
+			session_id
+		};
+		tags.then((settled) => result.settled = settled);
+		return result;
+	};
+	if (started) list.push(item({
+		name: "session_start",
+		properties: {},
+		options: { enableThirdPartyTracking: false }
+	}));
+	const event = item({
+		name,
+		properties,
+		options
+	});
+	list.push(event);
+	return event;
+}
+/**
+* Sends the queue. Everything that has to be awaited is awaited first, and only then are the
+* events taken off the queue and handed to `fetch` in the same synchronous step — so there is
+* no moment at which an event is neither queued nor sent.
+*/
+async function flush() {
+	if (timer) {
+		clearTimeout(timer);
+		timer = null;
+	}
+	if (list.length === 0) return;
+	let events = [];
 	try {
-		if (events.length === 0) return;
-		const opening = events[0];
-		const { id: session_id, started } = getSession().touch(Date.parse(opening.timestamp), Date.parse(events[events.length - 1].timestamp));
-		if (started || pendingStart?.session_id === session_id) {
-			const start = pendingStart?.session_id === session_id ? pendingStart.item : {
-				name: "session_start",
-				properties: {},
-				options: { enableThirdPartyTracking: false },
-				tags: opening.tags,
-				timestamp: opening.timestamp
-			};
-			pendingStart = void 0;
-			announcement = {
-				session_id,
-				item: start
-			};
-			events.unshift(start);
-		}
 		await getTokenBucket().removeTokens();
 		const visitor_id = (await getVisitor()).id;
+		const headers = await config.getHeaders();
+		await Promise.all(list.map((event) => event.tags));
+		events = list.splice(0);
+		if (events.length === 0) return;
 		const dto = await Promise.all(events.map(async (event) => ({
 			name: event.name,
 			properties: event.properties,
 			tags: await event.tags,
 			visitor_id,
-			session_id,
+			session_id: event.session_id,
 			platform: config.platform,
 			environment: config.environment,
 			timestamp: event.timestamp
 		})));
+		const body = JSON.stringify(dto);
 		const response = await fetch(`${config.endpoint}/events`, {
 			method: "POST",
 			credentials: "include",
-			keepalive: true,
-			headers: await config.getHeaders(),
-			body: JSON.stringify(dto)
+			keepalive: body.length < 6e4,
+			headers,
+			body
 		});
 		if (!response.ok) throw new Error(`Failed to send track event: ${response.status} ${await response.text()}`);
 		const data = await response.json();
-		let index = 0;
-		while (events.length > 0) {
-			const event = events.shift();
-			if (!event) {
-				index++;
-				continue;
-			}
-			const { options, name, properties } = event;
+		events.forEach((event, index) => {
 			const eventId = data.at(index)?.id;
-			options.onSucceed?.(eventId ? { id: eventId } : void 0);
-			index++;
-			if (options.enableThirdPartyTracking === false || IGNORED_EVENTS.includes(name)) continue;
+			event.options.onSucceed?.(eventId ? { id: eventId } : void 0);
+			if (event.options.enableThirdPartyTracking === false || IGNORED_EVENTS.includes(event.name)) return;
 			config.thirdPartyTrackers.forEach((tracker) => {
 				try {
-					tracker(name, properties, eventId);
+					tracker(event.name, event.properties, eventId);
 				} catch (e) {
 					if (e instanceof Error) console.log(e.message);
 				}
 			});
-		}
+		});
 	} catch (e) {
 		if (e instanceof Error) console.log(e.message);
-		if (announcement) pendingStart = announcement;
-		events.forEach((event) => event.options.onError?.(e));
-	}
-}
-const batch = 10;
-const delay = 2e3;
-const list = [];
-let timer = null;
-/**
-* Both paths into a send go through here, so a batch that fills up cancels the timer the
-* previous push armed rather than leaving it to wake up on its own with nothing to send.
-*/
-function flush() {
-	if (timer) {
-		clearTimeout(timer);
-		timer = null;
+		const starts = events.filter((event) => event.name === "session_start");
+		list.unshift(...starts);
+		events.filter((event) => event.name !== "session_start").forEach((event) => event.options.onError?.(e));
 	}
-	if (list.length === 0) return;
-	const copy = [...list];
-	list.length = 0;
-	sendEvents(copy);
 }
 function track(name, properties, options = defaultOptions) {
-	list.push({
-		name,
-		properties,
-		options,
-		tags: captureTags(),
-		timestamp: (/* @__PURE__ */ new Date()).toISOString()
-	});
-	if (list.length >= batch) {
+	enqueue(name, properties, options);
+	if (list.length >= batchSize) {
 		flush();
 		return;
 	}
 	if (timer) clearTimeout(timer);
-	timer = setTimeout(flush, delay);
+	timer = setTimeout(() => void flush(), delay);
 }
+/**
+* Sends the event now, with whatever is queued, and resolves once it has been sent or lost — or,
+* when no visitor could be created to send it with, at once, the event left queued for the next
+* send. It never rejects: tracking must not fail the step that awaits it.
+*/
 async function trackAsync(name, properties, options = defaultOptions) {
-	await sendEvents([{
-		name,
-		properties,
-		options,
-		tags: captureTags(),
-		timestamp: (/* @__PURE__ */ new Date()).toISOString()
-	}]);
+	let settle;
+	const settled = new Promise((resolve) => {
+		settle = resolve;
+	});
+	const event = enqueue(name, properties, {
+		...options,
+		onSucceed: (response) => {
+			options.onSucceed?.(response);
+			settle();
+		},
+		onError: (error) => {
+			options.onError?.(error);
+			settle();
+		}
+	});
+	await flush();
+	if (list.includes(event)) return;
+	await settled;
 }
-function sendBeacon(name, properties) {
+/**
+* The visitor id a beacon can carry. It is persisted, so a returning visitor already has one
+* before `getVisitor` has finished its round trip for this page. Requiring the in-memory copy
+* threw away exactly the events a beacon exists for: everything a visit accrues before its first
+* batch comes back, which for a short visit is the whole of it. A visitor the server has never
+* seen has none: the server would reject its events.
+*/
+function beaconVisitorId() {
 	const stored = config.storage.getItem(keys.visitor_id);
-	const visitor_id = cache.visitor?.id ?? (stored && stored !== "undefined" ? stored : void 0);
+	return cache.visitor?.id ?? (stored && stored !== "undefined" ? stored : void 0);
+}
+function beacon(dto) {
+	if (typeof navigator === "undefined" || !("sendBeacon" in navigator)) return false;
+	const blob = new Blob([JSON.stringify(dto)], { type: "text/plain;charset=UTF-8" });
+	return navigator.sendBeacon(`${config.endpoint}/events`, blob);
+}
+/**
+* Sends the queue by beacon, now: for when the page is hidden or left, the last moment its
+* script is sure to run — what PostHog's `requestQueue.unload()` and GA4 do on the same events.
+* Call it before the engagement beacon: a new session's `session_start` is in this queue.
+*
+* Nothing can be awaited here, so the events go with the tags they have settled on (the last
+* built ones otherwise), and without the server's ids: their third-party trackers are not fired,
+* as an id-less browser event could not be deduplicated against the server's. When no beacon can
+* take them — a visitor the server does not know yet, no `sendBeacon`, a refused body — they stay
+* queued for the usual send, which also creates the visitor.
+*/
+function sendPendingEvents() {
+	if (list.length === 0) return;
+	const visitor_id = beaconVisitorId();
+	const dto = list.map((event) => ({
+		name: event.name,
+		properties: event.properties,
+		tags: event.settled ?? cache.tags ?? {},
+		visitor_id: visitor_id ?? "",
+		session_id: event.session_id,
+		platform: config.platform,
+		environment: config.environment,
+		timestamp: event.timestamp
+	}));
+	if (!visitor_id || !beacon(dto)) {
+		flush();
+		return;
+	}
+	if (timer) {
+		clearTimeout(timer);
+		timer = null;
+	}
+	list.splice(0).forEach((event) => event.options.onSucceed?.(void 0));
+}
+function sendBeacon(name, properties) {
+	const visitor_id = beaconVisitorId();
 	if (!visitor_id) return;
-	const dto = [{
+	const session_id = getSession().extend();
+	if (!session_id) return;
+	if (beacon([{
 		name,
 		properties,
 		tags: cache.tags ?? {},
 		visitor_id,
-		session_id: getSession().extend(),
+		session_id,
 		platform: config.platform,
 		environment: config.environment,
 		timestamp: (/* @__PURE__ */ new Date()).toISOString()
-	}];
-	const blob = new Blob([JSON.stringify(dto)], { type: "application/json" });
-	if (navigator.sendBeacon(`${config.endpoint}/events`, blob)) return;
+	}])) return;
 	console.warn("Failed to send beacon", name, properties);
 }
 //#endregion
-export { sendBeacon, track, trackAsync };
+export { sendBeacon, sendPendingEvents, track, trackAsync };
 
 //# sourceMappingURL=index.mjs.map

package/dist/track/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/track/index.ts"],"sourcesContent":["import { TokenBucket, fetch } from '@shware/utils';\nimport { keys } from '../constants/storage';\nimport type { CreateTrackEventDTO } from '../schema/index';\nimport { cache, config } from '../setup/index';\nimport { getSession } from '../setup/session';\nimport { IGNORED_EVENTS } from '../third-parties/ignored-events';\nimport { getVisitor } from '../visitor/index';\nimport type { EventName, TrackEventResponse, TrackName, TrackProperties, TrackTags } from './types';\n\nexport interface TrackOptions {\n  enableThirdPartyTracking?: boolean;\n  onSucceed?: (response?: TrackEventResponse[number]) => void;\n  onError?: (error: unknown) => void;\n}\n\nconst defaultOptions: TrackOptions = {};\n\nlet tokenBucket: TokenBucket | undefined;\n\n/**\n * The rate limiter, built on the first send rather than at module scope: its\n * constructor starts a refill `setInterval`, and Cloudflare Workers refuse to\n * set a timer outside a request handler for the same reason they refuse to\n * generate random values there — see `setup/session.ts`.\n */\nfunction getTokenBucket() {\n  return (tokenBucket ??= new TokenBucket({ rate: 1, capacity: 20, requested: 2 }));\n}\n\ntype Item = {\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  name: TrackName<any>;\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  properties: TrackProperties<any>;\n  tags: Promise<TrackTags>;\n  timestamp: string;\n  options: TrackOptions;\n};\n\n/**\n * Tags belong to the moment the event happened, not to the moment its batch goes out: a queued\n * event waits up to `delay` ms, and a single page app can navigate in that window, which would\n * stamp every pending event with the URL of the page the user has already left.\n *\n * The promise then sits in the queue with nothing awaiting it, so a failure has to be absorbed\n * here — an unhandled rejection would surface as a global error long before `sendEvents` could\n * catch it. Falling back to the last built tags keeps the event, minus whatever changed since.\n */\nasync function captureTags(): Promise<TrackTags> {\n  try {\n    return await config.getTags();\n  } catch (e: unknown) {\n    if (e instanceof Error) console.log(e.message);\n    return cache.tags ?? {};\n  }\n}\n\n/**\n * The `session_start` a failed batch took down with it, kept for the next batch of the same\n * session. `fetch` has already retried the transient failures by the time a batch fails here;\n * what remains is a batch the server rejected outright — one invalid event fails the whole batch,\n * and `session_start` with it — or a network that stayed down past the retries. Neither is a\n * reason to lose the session's one attribution record, so it goes out again, with the tags and\n * timestamp of the moment the session actually began, under the same session id. Held in memory\n * only: a reload loses it, and with it the session_start — the same as before this existed.\n */\nlet pendingStart: { session_id: string; item: Item } | undefined;\n\nasync function sendEvents(events: Item[]) {\n  /** The announcement this batch carries, if any, so the catch below can hold it back. */\n  let announcement: { session_id: string; item: Item } | undefined;\n  try {\n    if (events.length === 0) return;\n\n    // One read-modify-write of the stored session for the whole batch: it answers which session\n    // these events belong to and whether this batch is the one that started it. Timed by the\n    // events themselves rather than by this moment — a tab frozen in the background can hold a\n    // batch for far longer than `delay`, and those events belong to the session they happened in.\n    const opening = events[0];\n    const { id: session_id, started } = getSession().touch(\n      Date.parse(opening.timestamp),\n      Date.parse(events[events.length - 1].timestamp)\n    );\n    if (started || pendingStart?.session_id === session_id) {\n      // `session_start` is derived from the event that opened the session, as GA4 derives it\n      // from the hit that did: when that event happened is when the session began, and the page\n      // it was captured on is where. Neither is read now — this batch goes out up to `delay` ms\n      // later, a batch held in a frozen tab far later still, and a landing page that redirects\n      // inside that window would stamp the session's one attribution record with the URL the utm\n      // parameters were already stripped from.\n      const start: Item =\n        pendingStart?.session_id === session_id\n          ? pendingStart.item\n          : {\n              name: 'session_start',\n              properties: {},\n              options: { enableThirdPartyTracking: false },\n              tags: opening.tags,\n              timestamp: opening.timestamp,\n            };\n      pendingStart = undefined;\n      announcement = { session_id, item: start };\n      events.unshift(start);\n    }\n\n    await getTokenBucket().removeTokens();\n\n    const visitor_id = (await getVisitor()).id;\n\n    const dto: CreateTrackEventDTO = await Promise.all(\n      events.map(async (event) => ({\n        name: event.name,\n        properties: event.properties,\n        tags: await event.tags,\n        visitor_id,\n        session_id,\n        platform: config.platform,\n        environment: config.environment,\n        timestamp: event.timestamp,\n      }))\n    );\n\n    const response = await fetch(`${config.endpoint}/events`, {\n      method: 'POST',\n      credentials: 'include',\n      // Survive the page being unloaded mid-flight: a batch waits up to `delay` ms, so closing\n      // the tab inside that window would otherwise abort the request and lose every event in it.\n      // The body stays far under keepalive's 64KB in-flight budget at 100 events per batch.\n      keepalive: true,\n      headers: await config.getHeaders(),\n      body: JSON.stringify(dto),\n    });\n\n    if (!response.ok) {\n      throw new Error(`Failed to send track event: ${response.status} ${await response.text()}`);\n    }\n\n    const data = (await response.json()) as TrackEventResponse;\n\n    let index = 0;\n    while (events.length > 0) {\n      const event = events.shift();\n      if (!event) {\n        index++;\n        continue;\n      }\n      const { options, name, properties } = event;\n      const eventId = data.at(index)?.id;\n      options.onSucceed?.(eventId ? { id: eventId } : undefined);\n      index++;\n      // An explicit false, not falsiness: a caller passing `{ onSucceed }` replaces the options\n      // object wholesale, and leaving the flag out must not silently switch forwarding off.\n      if (options.enableThirdPartyTracking === false || IGNORED_EVENTS.includes(name)) {\n        continue;\n      }\n      config.thirdPartyTrackers.forEach((tracker) => {\n        try {\n          tracker(name, properties, eventId);\n        } catch (e: unknown) {\n          // A third-party script does not get to take the rest of the batch with it. This loop is\n          // still draining `events` with `shift`, so a throw would escape to the catch below and\n          // report failure to whatever is left in the queue — for events the server has already\n          // accepted, and after the ones ahead of them were told they succeeded.\n          if (e instanceof Error) console.log(e.message);\n        }\n      });\n    }\n  } catch (e: unknown) {\n    if (e instanceof Error) console.log(e.message);\n    // The other events are reported lost and stay lost; `session_start` alone is worth carrying\n    // over, because it is the session's only attribution record — a session without one has no\n    // channel, and its every later event drops out of an attribution join.\n    if (announcement) pendingStart = announcement;\n    events.forEach((event) => event.options.onError?.(e));\n  }\n}\n\nconst batch = 10;\nconst delay = 2000;\nconst list: Item[] = [];\nlet timer: ReturnType<typeof setTimeout> | null = null;\n\n/**\n * Both paths into a send go through here, so a batch that fills up cancels the timer the\n * previous push armed rather than leaving it to wake up on its own with nothing to send.\n */\nfunction flush() {\n  if (timer) {\n    clearTimeout(timer);\n    timer = null;\n  }\n  if (list.length === 0) return;\n  const copy = [...list];\n  list.length = 0;\n  void sendEvents(copy);\n}\n\nexport function track<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>,\n  options: TrackOptions = defaultOptions\n) {\n  list.push({\n    name,\n    properties,\n    options,\n    tags: captureTags(),\n    timestamp: new Date().toISOString(),\n  });\n  if (list.length >= batch) {\n    flush();\n    return;\n  }\n  if (timer) clearTimeout(timer);\n  timer = setTimeout(flush, delay);\n}\n\nexport async function trackAsync<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>,\n  options: TrackOptions = defaultOptions\n) {\n  await sendEvents([\n    { name, properties, options, tags: captureTags(), timestamp: new Date().toISOString() },\n  ]);\n}\n\nexport function sendBeacon<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>\n) {\n  // The visitor id is persisted, so a returning visitor already has one before `getVisitor` has\n  // finished its round trip for this page. Requiring the in-memory copy threw away exactly the\n  // events this function exists for: everything a visit accrues before its first batch comes\n  // back, which for a short visit is the whole of it.\n  const stored = config.storage.getItem(keys.visitor_id);\n  const visitor_id = cache.visitor?.id ?? (stored && stored !== 'undefined' ? stored : undefined);\n  if (!visitor_id) return;\n\n  const dto: CreateTrackEventDTO = [\n    {\n      name,\n      properties,\n      // Tags are worth less than the event carrying them: an empty set still reports the\n      // engagement, and every field in `tagsSchema` is optional.\n      tags: cache.tags ?? {},\n      visitor_id,\n      session_id: getSession().extend(),\n      platform: config.platform,\n      environment: config.environment,\n      timestamp: new Date().toISOString(),\n    },\n  ];\n  const blob = new Blob([JSON.stringify(dto)], { type: 'application/json' });\n  const success = navigator.sendBeacon(`${config.endpoint}/events`, blob);\n  if (success) return;\n  console.warn('Failed to send beacon', name, properties);\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/track/index.ts"],"sourcesContent":["import { TokenBucket, fetch } from '@shware/utils';\nimport { keys } from '../constants/storage';\nimport type { CreateTrackEventDTO } from '../schema/index';\nimport { cache, config } from '../setup/index';\nimport { getSession } from '../setup/session';\nimport { IGNORED_EVENTS } from '../third-parties/ignored-events';\nimport { getVisitor } from '../visitor/index';\nimport type { EventName, TrackEventResponse, TrackName, TrackProperties, TrackTags } from './types';\n\nexport interface TrackOptions {\n  enableThirdPartyTracking?: boolean;\n  onSucceed?: (response?: TrackEventResponse[number]) => void;\n  onError?: (error: unknown) => void;\n}\n\nconst defaultOptions: TrackOptions = {};\n\nlet tokenBucket: TokenBucket | undefined;\n\n/**\n * The rate limiter, built on the first send rather than at module scope: its\n * constructor starts a refill `setInterval`, and Cloudflare Workers refuse to\n * set a timer outside a request handler for the same reason they refuse to\n * generate random values there — see `setup/session.ts`.\n */\nfunction getTokenBucket() {\n  return (tokenBucket ??= new TokenBucket({ rate: 1, capacity: 20, requested: 2 }));\n}\n\ntype Item = {\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  name: TrackName<any>;\n  // oxlint-disable-next-line @typescript-eslint/no-explicit-any\n  properties: TrackProperties<any>;\n  tags: Promise<TrackTags>;\n  /** `tags` once settled: a page being hidden can await nothing, and sends what it has. */\n  settled?: TrackTags;\n  /** Decided when the event happens, as GA4 and PostHog decide it, never when it is sent. */\n  session_id: string;\n  timestamp: string;\n  options: TrackOptions;\n};\n\n/**\n * Tags belong to the moment the event happened, not to the moment its batch goes out: a queued\n * event waits up to `delay` ms, and a single page app can navigate in that window, which would\n * stamp every pending event with the URL of the page the user has already left.\n *\n * The promise then sits in the queue with nothing awaiting it, so a failure has to be absorbed\n * here — an unhandled rejection would surface as a global error long before `sendEvents` could\n * catch it. Falling back to the last built tags keeps the event, minus whatever changed since.\n */\nasync function captureTags(): Promise<TrackTags> {\n  try {\n    return await config.getTags();\n  } catch (e: unknown) {\n    if (e instanceof Error) console.log(e.message);\n    return cache.tags ?? {};\n  }\n}\n\n/**\n * The events not yet sent, and the only place they are: a batch leaves it at the moment it is\n * handed to `fetch` or to a beacon, never earlier. So when the page is hidden or left,\n * everything still unsent is right here for `sendPendingEvents`.\n */\nconst list: Item[] = [];\nconst batchSize = 10;\nconst delay = 2000;\nlet timer: ReturnType<typeof setTimeout> | null = null;\n\n/**\n * Queues an event, preceded by a `session_start` when it is the one that opens a session.\n *\n * The session is decided here, when the event happens, as GA4 and PostHog decide it: the\n * `session_start` then sits in the queue right before the event that opened the session, so\n * wherever that event goes — a batch, a beacon, a retry — its announcement has gone ahead of it.\n * It carries that event's tags and time, as GA4 derives it from the hit that started the\n * session: the landing page is where the session began, whatever the page has navigated to by\n * the time the batch goes out.\n */\nfunction enqueue(name: Item['name'], properties: Item['properties'], options: TrackOptions): Item {\n  const timestamp = new Date().toISOString();\n  const tags = captureTags();\n  const { id: session_id, started } = getSession().touch(Date.parse(timestamp));\n  const item = (fields: Pick<Item, 'name' | 'properties' | 'options'>): Item => {\n    const result: Item = { ...fields, tags, timestamp, session_id };\n    void tags.then((settled) => (result.settled = settled));\n    return result;\n  };\n  if (started) {\n    const options = { enableThirdPartyTracking: false };\n    list.push(item({ name: 'session_start', properties: {}, options }));\n  }\n  const event = item({ name, properties, options });\n  list.push(event);\n  return event;\n}\n\n/**\n * Sends the queue. Everything that has to be awaited is awaited first, and only then are the\n * events taken off the queue and handed to `fetch` in the same synchronous step — so there is\n * no moment at which an event is neither queued nor sent.\n */\nasync function flush() {\n  if (timer) {\n    clearTimeout(timer);\n    timer = null;\n  }\n  if (list.length === 0) return;\n\n  let events: Item[] = [];\n  try {\n    await getTokenBucket().removeTokens();\n    const visitor_id = (await getVisitor()).id;\n    const headers = await config.getHeaders();\n    // Settled before the events leave the queue; those queued meanwhile are a microtask away.\n    await Promise.all(list.map((event) => event.tags));\n\n    events = list.splice(0);\n    if (events.length === 0) return;\n    const dto: CreateTrackEventDTO = await Promise.all(\n      events.map(async (event) => ({\n        name: event.name,\n        properties: event.properties,\n        tags: await event.tags,\n        visitor_id,\n        session_id: event.session_id,\n        platform: config.platform,\n        environment: config.environment,\n        timestamp: event.timestamp,\n      }))\n    );\n\n    const body = JSON.stringify(dto);\n    const response = await fetch(`${config.endpoint}/events`, {\n      method: 'POST',\n      credentials: 'include',\n      // keepalive lets the request survive the page being unloaded mid-flight, within a 64KB\n      // budget shared by every such request of the page; a body that could not fit goes as a\n      // plain POST rather than failing outright.\n      keepalive: body.length < 60_000,\n      headers,\n      body,\n    });\n\n    if (!response.ok) {\n      throw new Error(`Failed to send track event: ${response.status} ${await response.text()}`);\n    }\n\n    const data = (await response.json()) as TrackEventResponse;\n\n    events.forEach((event, index) => {\n      const eventId = data.at(index)?.id;\n      event.options.onSucceed?.(eventId ? { id: eventId } : undefined);\n      // An explicit false, not falsiness: a caller passing `{ onSucceed }` replaces the options\n      // object wholesale, and leaving the flag out must not silently switch forwarding off.\n      if (event.options.enableThirdPartyTracking === false || IGNORED_EVENTS.includes(event.name)) {\n        return;\n      }\n      config.thirdPartyTrackers.forEach((tracker) => {\n        try {\n          tracker(event.name, event.properties, eventId);\n        } catch (e: unknown) {\n          // A third-party script does not get to take the rest of the batch with it.\n          if (e instanceof Error) console.log(e.message);\n        }\n      });\n    });\n  } catch (e: unknown) {\n    if (e instanceof Error) console.log(e.message);\n    // `fetch` has already retried the transient failures by the time a batch fails here; what\n    // remains is a batch the server rejected outright — one invalid event fails the whole batch\n    // — or a network that stayed down past the retries. The other events are reported lost;\n    // `session_start` alone goes back on the queue for the next send, because it is the\n    // session's only attribution record: a session without one has no channel, and its every\n    // later event drops out of an attribution join.\n    const starts = events.filter((event) => event.name === 'session_start');\n    list.unshift(...starts);\n    events\n      .filter((event) => event.name !== 'session_start')\n      .forEach((event) => event.options.onError?.(e));\n  }\n}\n\nexport function track<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>,\n  options: TrackOptions = defaultOptions\n) {\n  enqueue(name, properties, options);\n  if (list.length >= batchSize) {\n    void flush();\n    return;\n  }\n  if (timer) clearTimeout(timer);\n  timer = setTimeout(() => void flush(), delay);\n}\n\n/**\n * Sends the event now, with whatever is queued, and resolves once it has been sent or lost — or,\n * when no visitor could be created to send it with, at once, the event left queued for the next\n * send. It never rejects: tracking must not fail the step that awaits it.\n */\nexport async function trackAsync<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>,\n  options: TrackOptions = defaultOptions\n) {\n  let settle!: () => void;\n  const settled = new Promise<void>((resolve) => {\n    settle = resolve;\n  });\n  const event = enqueue(name, properties, {\n    ...options,\n    onSucceed: (response) => {\n      options.onSucceed?.(response);\n      settle();\n    },\n    onError: (error) => {\n      options.onError?.(error);\n      settle();\n    },\n  });\n  await flush();\n  // Still queued: this send could not take it — no visitor id to send it with yet. It waits for\n  // the next send, but the caller, who may be holding a navigation on this, does not.\n  if (list.includes(event)) return;\n  await settled;\n}\n\n/**\n * The visitor id a beacon can carry. It is persisted, so a returning visitor already has one\n * before `getVisitor` has finished its round trip for this page. Requiring the in-memory copy\n * threw away exactly the events a beacon exists for: everything a visit accrues before its first\n * batch comes back, which for a short visit is the whole of it. A visitor the server has never\n * seen has none: the server would reject its events.\n */\nfunction beaconVisitorId(): string | undefined {\n  const stored = config.storage.getItem(keys.visitor_id);\n  return cache.visitor?.id ?? (stored && stored !== 'undefined' ? stored : undefined);\n}\n\nfunction beacon(dto: CreateTrackEventDTO): boolean {\n  // Not every runtime with a `navigator` has it: React Native has neither beacons nor pages.\n  if (typeof navigator === 'undefined' || !('sendBeacon' in navigator)) return false;\n  // text/plain keeps a cross-origin beacon a CORS simple request: as application/json it needs a\n  // preflight, which a page being closed often cannot complete, and the beacon is then dropped.\n  // The server reads it as JSON (`zBeaconJson` in @shware/http).\n  const blob = new Blob([JSON.stringify(dto)], { type: 'text/plain;charset=UTF-8' });\n  return navigator.sendBeacon(`${config.endpoint}/events`, blob);\n}\n\n/**\n * Sends the queue by beacon, now: for when the page is hidden or left, the last moment its\n * script is sure to run — what PostHog's `requestQueue.unload()` and GA4 do on the same events.\n * Call it before the engagement beacon: a new session's `session_start` is in this queue.\n *\n * Nothing can be awaited here, so the events go with the tags they have settled on (the last\n * built ones otherwise), and without the server's ids: their third-party trackers are not fired,\n * as an id-less browser event could not be deduplicated against the server's. When no beacon can\n * take them — a visitor the server does not know yet, no `sendBeacon`, a refused body — they stay\n * queued for the usual send, which also creates the visitor.\n */\nexport function sendPendingEvents() {\n  if (list.length === 0) return;\n  const visitor_id = beaconVisitorId();\n  const dto: CreateTrackEventDTO = list.map((event) => ({\n    name: event.name,\n    properties: event.properties,\n    tags: event.settled ?? cache.tags ?? {},\n    visitor_id: visitor_id ?? '',\n    session_id: event.session_id,\n    platform: config.platform,\n    environment: config.environment,\n    timestamp: event.timestamp,\n  }));\n  if (!visitor_id || !beacon(dto)) {\n    void flush();\n    return;\n  }\n  if (timer) {\n    clearTimeout(timer);\n    timer = null;\n  }\n  list.splice(0).forEach((event) => event.options.onSucceed?.(undefined));\n}\n\nexport function sendBeacon<T extends EventName = EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>\n) {\n  const visitor_id = beaconVisitorId();\n  if (!visitor_id) return;\n  // No stored session means no event was ever queued from this storage, so there is no session\n  // to report for — and one started here could never be announced. See `Session.extend`.\n  const session_id = getSession().extend();\n  if (!session_id) return;\n\n  const dto: CreateTrackEventDTO = [\n    {\n      name,\n      properties,\n      // Tags are worth less than the event carrying them: an empty set still reports the\n      // engagement, and every field in `tagsSchema` is optional.\n      tags: cache.tags ?? {},\n      visitor_id,\n      session_id,\n      platform: config.platform,\n      environment: config.environment,\n      timestamp: new Date().toISOString(),\n    },\n  ];\n  if (beacon(dto)) return;\n  console.warn('Failed to send beacon', name, properties);\n}\n"],"mappings":"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"}

package/dist/track/oaiq.cjs

@@ -10,6 +10,43 @@ const NON_AD_EVENTS = [
 	"view_promotion",
 	"select_promotion"
 ];
+const STANDARD_EVENTS = [
+	"appointment_scheduled",
+	"checkout_started",
+	"contents_viewed",
+	"items_added",
+	"lead_created",
+	"order_created",
+	"page_viewed",
+	"registration_completed",
+	"subscription_created",
+	"trial_started"
+];
+/**
+* A track name as an OpenAI `custom_event_name`: 1–64 letters, digits, underscores or hyphens,
+* starting and ending with a letter or digit, not a standard event name; the API lowercases it.
+* Anything else becomes an underscore, so `Sign Up.Clicked` is `sign_up_clicked`. Undefined when
+* nothing usable is left — the event is then not sent at all. The pixel and the server both name
+* a custom event through this, so the two still deduplicate.
+* https://developers.openai.com/ads/supported-events
+*/
+function oaiCustomEventName(name) {
+	const sanitized = name.toLowerCase().replace(/[^a-z0-9_-]+/g, "_").slice(0, 64).replace(/^[_-]+|[_-]+$/g, "");
+	if (!sanitized || STANDARD_EVENTS.includes(sanitized)) return void 0;
+	return sanitized;
+}
+/**
+* A phone number as OpenAI hashes it: whitespace, parentheses, periods and hyphens removed, then
+* the leading `+` and zeroes; 8–15 digits with the country code, else not a usable number.
+*/
+function normalizeOAIPhone(phone) {
+	const digits = phone.replace(/[\s().-]/g, "").replace(/^\+/, "").replace(/^0+/, "");
+	return /^\d{8,15}$/.test(digits) ? digits : void 0;
+}
+/** A name as OpenAI hashes it: lowercase, no whitespace or ASCII punctuation, accents kept. */
+function normalizeOAIName(name) {
+	return name?.toLowerCase().replace(/[\s!-/:-@[-`{-~]/g, "") || void 0;
+}
 /**
 * Currencies whose minor unit has 0 or 3 decimal places; everything else uses 2.
 * Follows Stripe's zero-decimal convention (e.g., MGA is treated as 0, ISK is included),
@@ -44,24 +81,32 @@ const THREE_DECIMAL_CURRENCIES = /* @__PURE__ */ new Set([
 	"OMR",
 	"TND"
 ]);
-/** Convert a major-unit amount (e.g., 129.99) into ISO 4217 minor units (e.g., 12,999). */
+/**
+* Convert a major-unit amount (e.g., 129.99) into ISO 4217 minor units (e.g., 12,999). None
+* without a currency: the minor unit depends on it, and OpenAI requires a `currency` with every
+* `amount` — an amount alone would be invalid, not just imprecise.
+*/
 function toMinorUnits(value, currency) {
 	if (value === void 0 || value === null || Number.isNaN(value)) return void 0;
 	const code = currency?.toUpperCase();
+	if (!code) return void 0;
 	const exponent = code && ZERO_DECIMAL_CURRENCIES.has(code) ? 0 : code && THREE_DECIMAL_CURRENCIES.has(code) ? 3 : 2;
 	return Math.round(value * 10 ** exponent);
 }
 function mapContents(items, currency) {
 	if (!items || items.length === 0) return void 0;
 	const code = currency?.toUpperCase();
-	return items.map((item) => ({
-		id: item.item_id,
-		name: item.item_name,
-		content_type: item.item_category,
-		quantity: item.quantity,
-		amount: toMinorUnits(item.price, currency),
-		currency: item.price !== void 0 ? code : void 0
-	}));
+	return items.map((item) => {
+		const amount = toMinorUnits(item.price, currency);
+		return {
+			id: item.item_id,
+			name: item.item_name,
+			content_type: item.item_category,
+			quantity: item.quantity,
+			amount,
+			currency: amount !== void 0 ? code : void 0
+		};
+	});
 }
 /** Safely read a property off loosely typed track properties without widening to `any`. */
 function prop(properties, key) {
@@ -171,6 +216,9 @@ function mapOAIEvent(name, properties) {
 exports.NON_AD_EVENTS = NON_AD_EVENTS;
 exports.mapContents = mapContents;
 exports.mapOAIEvent = mapOAIEvent;
+exports.normalizeOAIName = normalizeOAIName;
+exports.normalizeOAIPhone = normalizeOAIPhone;
+exports.oaiCustomEventName = oaiCustomEventName;
 exports.toMinorUnits = toMinorUnits;
 
 //# sourceMappingURL=oaiq.cjs.map

package/dist/track/oaiq.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"oaiq.cjs","names":[],"sources":["../../src/track/oaiq.ts"],"sourcesContent":["import type { Item } from './gtag';\nimport type { EventName, TrackName, TrackProperties } from './types';\n\nexport const NON_AD_EVENTS = [\n  // metrics\n  'CLS',\n  'FCP',\n  'FID',\n  'INP',\n  'LCP',\n  'TTFB',\n  // promotions\n  'view_promotion',\n  'select_promotion',\n];\n\n/**\n * Content item shared by `contents` and `plan_enrollment` events.\n * https://developers.openai.com/ads/supported-events\n */\nexport type ContentItem = {\n  id?: string;\n  name?: string;\n  content_type?: string;\n  quantity?: number;\n  /** Per-item monetary value in ISO 4217 minor units (e.g., 12,999 = $129.99 USD). */\n  amount?: number;\n  currency?: string;\n};\n\nexport type ContentsData = {\n  type: 'contents';\n  /** Monetary value in ISO 4217 minor units (e.g., 12,999 = $129.99 USD). */\n  amount?: number;\n  currency?: string;\n  contents?: ContentItem[];\n};\n\nexport type CustomerActionData = {\n  type: 'customer_action';\n  amount?: number;\n  currency?: string;\n};\n\nexport type PlanEnrollmentData = {\n  type: 'plan_enrollment';\n  plan_id?: string;\n  amount?: number;\n  currency?: string;\n  contents?: ContentItem[];\n};\n\nexport type CustomEventData = {\n  type: 'custom';\n  amount?: number;\n  currency?: string;\n  contents?: ContentItem[];\n};\n\nexport type EventData = ContentsData | CustomerActionData | PlanEnrollmentData | CustomEventData;\n\n/**\n * Standard event names and the `data` shape each one expects.\n * https://developers.openai.com/ads/supported-events\n */\nexport type StandardEvents = {\n  appointment_scheduled: CustomerActionData;\n  checkout_started: ContentsData;\n  contents_viewed: ContentsData;\n  items_added: ContentsData;\n  lead_created: CustomerActionData;\n  order_created: ContentsData;\n  page_viewed: ContentsData;\n  registration_completed: CustomerActionData;\n  subscription_created: PlanEnrollmentData;\n  trial_started: PlanEnrollmentData;\n};\n\nexport type StandardEvent = keyof StandardEvents;\n\n/**\n * Identity fields passed to `oaiq(\"init\", ...)` for conversion matching. Email and external id\n * must be pre-hashed as lowercase 64-char SHA-256 hex strings; the rest are sent as raw values.\n * https://developers.openai.com/ads/measurement-pixel\n */\nexport type OAIQUser = {\n  email_sha256?: string;\n  external_id_sha256?: string;\n  /** Two-letter ISO 3166-1 country code (e.g. \"US\"). */\n  country?: string;\n  /** Lowercased, max 128 characters. */\n  city?: string;\n  /** Max 32 characters. */\n  zip_code?: string;\n};\n\nexport type InitConfig = {\n  pixelId: string;\n  /** Log SDK activity to the browser console. */\n  debug?: boolean;\n  user?: OAIQUser;\n};\n\n/**\n * Fourth argument of `oaiq(\"measure\", ...)`. Required for custom events (carries\n * `custom_event_name`); optional for standard events.\n */\nexport type MeasureOptions = {\n  /** Shared with the Conversions API to deduplicate the same conversion across browser and server. */\n  event_id?: string;\n  /** Required for custom events; 1-64 chars of letters, numbers, underscores, or dashes. */\n  custom_event_name?: string;\n  /** When true, opts the event out of user-level personalization. */\n  opt_out?: boolean;\n};\n\nexport interface OAIQ {\n  oaiq(command: 'init', config: InitConfig): void;\n  oaiq<T extends StandardEvent>(\n    command: 'measure',\n    event: T,\n    data: StandardEvents[T],\n    options?: MeasureOptions\n  ): void;\n  oaiq(\n    command: 'measure',\n    event: 'custom',\n    data: CustomEventData,\n    options: MeasureOptions & { custom_event_name: string }\n  ): void;\n}\n\n/**\n * Currencies whose minor unit has 0 or 3 decimal places; everything else uses 2.\n * Follows Stripe's zero-decimal convention (e.g., MGA is treated as 0, ISK is included),\n * which can differ from strict ISO 4217 exponents.\n * https://docs.stripe.com/currencies#zero-decimal\n */\nconst ZERO_DECIMAL_CURRENCIES = new Set([\n  'BIF',\n  'CLP',\n  'DJF',\n  'GNF',\n  'ISK',\n  'JPY',\n  'KMF',\n  'KRW',\n  'MGA',\n  'PYG',\n  'RWF',\n  'UGX',\n  'VND',\n  'VUV',\n  'XAF',\n  'XOF',\n  'XPF',\n]);\nconst THREE_DECIMAL_CURRENCIES = new Set(['BHD', 'IQD', 'JOD', 'KWD', 'LYD', 'OMR', 'TND']);\n\n/** Convert a major-unit amount (e.g., 129.99) into ISO 4217 minor units (e.g., 12,999). */\nexport function toMinorUnits(value?: number | null, currency?: string): number | undefined {\n  if (value === undefined || value === null || Number.isNaN(value)) return undefined;\n  const code = currency?.toUpperCase();\n  const exponent =\n    code && ZERO_DECIMAL_CURRENCIES.has(code)\n      ? 0\n      : code && THREE_DECIMAL_CURRENCIES.has(code)\n        ? 3\n        : 2;\n  return Math.round(value * 10 ** exponent);\n}\n\nexport function mapContents(items?: Item[], currency?: string): ContentItem[] | undefined {\n  if (!items || items.length === 0) return undefined;\n  const code = currency?.toUpperCase();\n  return items.map((item) => ({\n    id: item.item_id,\n    name: item.item_name,\n    content_type: item.item_category,\n    quantity: item.quantity,\n    amount: toMinorUnits(item.price, currency),\n    currency: item.price !== undefined ? code : undefined,\n  }));\n}\n\n/** Safely read a property off loosely typed track properties without widening to `any`. */\nfunction prop(properties: unknown, key: string): unknown {\n  return typeof properties === 'object' && properties !== null\n    ? (properties as Record<string, unknown>)[key]\n    : undefined;\n}\n\nfunction readValue(properties: unknown): number | undefined {\n  const value = prop(properties, 'value');\n  return typeof value === 'number' ? value : undefined;\n}\n\nfunction readCurrency(properties: unknown): string | undefined {\n  const currency = prop(properties, 'currency');\n  return typeof currency === 'string' ? currency : undefined;\n}\n\nfunction readItems(properties: unknown): Item[] | undefined {\n  const items = prop(properties, 'items');\n  return Array.isArray(items) ? (items as Item[]) : undefined;\n}\n\nfunction contentsData(properties: unknown): ContentsData {\n  const currency = readCurrency(properties);\n  return {\n    type: 'contents',\n    amount: toMinorUnits(readValue(properties), currency),\n    currency: currency?.toUpperCase(),\n    contents: mapContents(readItems(properties), currency),\n  };\n}\n\nfunction customerActionData(properties: unknown): CustomerActionData {\n  const currency = readCurrency(properties);\n  return {\n    type: 'customer_action',\n    amount: toMinorUnits(readValue(properties), currency),\n    currency: currency?.toUpperCase(),\n  };\n}\n\nfunction planEnrollmentData(properties: unknown): PlanEnrollmentData {\n  const currency = readCurrency(properties);\n  const items = readItems(properties);\n  return {\n    type: 'plan_enrollment',\n    plan_id: items?.[0]?.item_id,\n    amount: toMinorUnits(readValue(properties), currency),\n    currency: currency?.toUpperCase(),\n    contents: mapContents(items, currency),\n  };\n}\n\nexport type MappedOAIEvent = {\n  type: StandardEvent | 'custom';\n  data: EventData;\n};\n\n/** Map an internal track event onto an OpenAI standard (or custom) conversion event. */\nexport function mapOAIEvent<T extends EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>\n): MappedOAIEvent {\n  switch (name) {\n    case 'page_view':\n      return { type: 'page_viewed', data: contentsData(properties) };\n    case 'view_item':\n    case 'view_item_list':\n      return { type: 'contents_viewed', data: contentsData(properties) };\n    case 'begin_checkout':\n      return { type: 'checkout_started', data: contentsData(properties) };\n    case 'add_to_cart':\n      return { type: 'items_added', data: contentsData(properties) };\n    case 'purchase':\n      return { type: 'order_created', data: contentsData(properties) };\n    case 'generate_lead':\n    case 'qualify_lead':\n      return { type: 'lead_created', data: customerActionData(properties) };\n    case 'sign_up':\n    case 'login':\n      return { type: 'registration_completed', data: customerActionData(properties) };\n    case 'schedule':\n      return { type: 'appointment_scheduled', data: customerActionData(properties) };\n    case 'subscribe':\n      return { type: 'subscription_created', data: planEnrollmentData(properties) };\n    case 'trial_begin':\n      return { type: 'trial_started', data: planEnrollmentData(properties) };\n    default: {\n      const currency = readCurrency(properties);\n      return {\n        type: 'custom',\n        data: {\n          type: 'custom',\n          amount: toMinorUnits(readValue(properties), currency),\n          currency: currency?.toUpperCase(),\n          contents: mapContents(readItems(properties), currency),\n        },\n      };\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"oaiq.cjs","names":[],"sources":["../../src/track/oaiq.ts"],"sourcesContent":["import type { Item } from './gtag';\nimport type { EventName, TrackName, TrackProperties } from './types';\n\nexport const NON_AD_EVENTS = [\n  // metrics\n  'CLS',\n  'FCP',\n  'FID',\n  'INP',\n  'LCP',\n  'TTFB',\n  // promotions\n  'view_promotion',\n  'select_promotion',\n];\n\n/**\n * Content item shared by `contents` and `plan_enrollment` events.\n * https://developers.openai.com/ads/supported-events\n */\nexport type ContentItem = {\n  id?: string;\n  name?: string;\n  content_type?: string;\n  quantity?: number;\n  /** Per-item monetary value in ISO 4217 minor units (e.g., 12,999 = $129.99 USD). */\n  amount?: number;\n  currency?: string;\n};\n\nexport type ContentsData = {\n  type: 'contents';\n  /** Monetary value in ISO 4217 minor units (e.g., 12,999 = $129.99 USD). */\n  amount?: number;\n  currency?: string;\n  contents?: ContentItem[];\n};\n\nexport type CustomerActionData = {\n  type: 'customer_action';\n  amount?: number;\n  currency?: string;\n};\n\nexport type PlanEnrollmentData = {\n  type: 'plan_enrollment';\n  plan_id?: string;\n  amount?: number;\n  currency?: string;\n  contents?: ContentItem[];\n};\n\nexport type CustomEventData = {\n  type: 'custom';\n  amount?: number;\n  currency?: string;\n  contents?: ContentItem[];\n};\n\nexport type EventData = ContentsData | CustomerActionData | PlanEnrollmentData | CustomEventData;\n\n/**\n * Standard event names and the `data` shape each one expects.\n * https://developers.openai.com/ads/supported-events\n */\nexport type StandardEvents = {\n  appointment_scheduled: CustomerActionData;\n  checkout_started: ContentsData;\n  contents_viewed: ContentsData;\n  items_added: ContentsData;\n  lead_created: CustomerActionData;\n  order_created: ContentsData;\n  page_viewed: ContentsData;\n  registration_completed: CustomerActionData;\n  subscription_created: PlanEnrollmentData;\n  trial_started: PlanEnrollmentData;\n};\n\nexport type StandardEvent = keyof StandardEvents;\n\nconst STANDARD_EVENTS: readonly string[] = [\n  'appointment_scheduled',\n  'checkout_started',\n  'contents_viewed',\n  'items_added',\n  'lead_created',\n  'order_created',\n  'page_viewed',\n  'registration_completed',\n  'subscription_created',\n  'trial_started',\n] satisfies StandardEvent[];\n\n/**\n * A track name as an OpenAI `custom_event_name`: 1–64 letters, digits, underscores or hyphens,\n * starting and ending with a letter or digit, not a standard event name; the API lowercases it.\n * Anything else becomes an underscore, so `Sign Up.Clicked` is `sign_up_clicked`. Undefined when\n * nothing usable is left — the event is then not sent at all. The pixel and the server both name\n * a custom event through this, so the two still deduplicate.\n * https://developers.openai.com/ads/supported-events\n */\nexport function oaiCustomEventName(name: string): string | undefined {\n  const sanitized = name\n    .toLowerCase()\n    .replace(/[^a-z0-9_-]+/g, '_')\n    .slice(0, 64)\n    .replace(/^[_-]+|[_-]+$/g, '');\n  if (!sanitized || STANDARD_EVENTS.includes(sanitized)) return undefined;\n  return sanitized;\n}\n\n/**\n * Identity fields passed to `oaiq(\"init\", ...)` for conversion matching. Identifiers are\n * normalized, then sent as lowercase 64-char SHA-256 hex strings; geographic values are raw.\n * https://developers.openai.com/ads/measurement-pixel#send-user-data\n */\nexport type OAIQUser = {\n  email_sha256?: string;\n  /** 8–15 digits with the country code, no leading `+` or zeroes (`normalizeOAIPhone`). */\n  phone_number_sha256?: string;\n  external_id_sha256?: string;\n  /** Lowercase, without whitespace or ASCII punctuation (`normalizeOAIName`). */\n  first_name_sha256?: string;\n  last_name_sha256?: string;\n  /** Two-letter ISO 3166-1 country code (e.g. \"US\"). */\n  country?: string;\n  /** Max 128 characters; OpenAI trims and lowercases it. */\n  city?: string;\n  /** State, province or region, max 128 characters. */\n  region?: string;\n  postal_code?: string;\n};\n\n/**\n * A phone number as OpenAI hashes it: whitespace, parentheses, periods and hyphens removed, then\n * the leading `+` and zeroes; 8–15 digits with the country code, else not a usable number.\n */\nexport function normalizeOAIPhone(phone: string): string | undefined {\n  const digits = phone\n    .replace(/[\\s().-]/g, '')\n    .replace(/^\\+/, '')\n    .replace(/^0+/, '');\n  return /^\\d{8,15}$/.test(digits) ? digits : undefined;\n}\n\n/** A name as OpenAI hashes it: lowercase, no whitespace or ASCII punctuation, accents kept. */\nexport function normalizeOAIName(name: string | undefined): string | undefined {\n  return name?.toLowerCase().replace(/[\\s!-/:-@[-`{-~]/g, '') || undefined;\n}\n\nexport type InitConfig = {\n  pixelId: string;\n  /** Log SDK activity to the browser console. */\n  debug?: boolean;\n  user?: OAIQUser;\n};\n\n/**\n * Fourth argument of `oaiq(\"measure\", ...)`. Required for custom events (carries\n * `custom_event_name`); optional for standard events.\n */\nexport type MeasureOptions = {\n  /** Shared with the Conversions API to deduplicate the same conversion across browser and server. */\n  event_id?: string;\n  /** Required for custom events; 1-64 chars of letters, numbers, underscores, or dashes. */\n  custom_event_name?: string;\n  /** When true, opts the event out of user-level personalization. */\n  opt_out?: boolean;\n};\n\nexport interface OAIQ {\n  oaiq(command: 'init', config: InitConfig): void;\n  oaiq<T extends StandardEvent>(\n    command: 'measure',\n    event: T,\n    data: StandardEvents[T],\n    options?: MeasureOptions\n  ): void;\n  oaiq(\n    command: 'measure',\n    event: 'custom',\n    data: CustomEventData,\n    options: MeasureOptions & { custom_event_name: string }\n  ): void;\n}\n\n/**\n * Currencies whose minor unit has 0 or 3 decimal places; everything else uses 2.\n * Follows Stripe's zero-decimal convention (e.g., MGA is treated as 0, ISK is included),\n * which can differ from strict ISO 4217 exponents.\n * https://docs.stripe.com/currencies#zero-decimal\n */\nconst ZERO_DECIMAL_CURRENCIES = new Set([\n  'BIF',\n  'CLP',\n  'DJF',\n  'GNF',\n  'ISK',\n  'JPY',\n  'KMF',\n  'KRW',\n  'MGA',\n  'PYG',\n  'RWF',\n  'UGX',\n  'VND',\n  'VUV',\n  'XAF',\n  'XOF',\n  'XPF',\n]);\nconst THREE_DECIMAL_CURRENCIES = new Set(['BHD', 'IQD', 'JOD', 'KWD', 'LYD', 'OMR', 'TND']);\n\n/**\n * Convert a major-unit amount (e.g., 129.99) into ISO 4217 minor units (e.g., 12,999). None\n * without a currency: the minor unit depends on it, and OpenAI requires a `currency` with every\n * `amount` — an amount alone would be invalid, not just imprecise.\n */\nexport function toMinorUnits(value?: number | null, currency?: string): number | undefined {\n  if (value === undefined || value === null || Number.isNaN(value)) return undefined;\n  const code = currency?.toUpperCase();\n  if (!code) return undefined;\n  const exponent =\n    code && ZERO_DECIMAL_CURRENCIES.has(code)\n      ? 0\n      : code && THREE_DECIMAL_CURRENCIES.has(code)\n        ? 3\n        : 2;\n  return Math.round(value * 10 ** exponent);\n}\n\nexport function mapContents(items?: Item[], currency?: string): ContentItem[] | undefined {\n  if (!items || items.length === 0) return undefined;\n  const code = currency?.toUpperCase();\n  return items.map((item) => {\n    const amount = toMinorUnits(item.price, currency);\n    return {\n      id: item.item_id,\n      name: item.item_name,\n      content_type: item.item_category,\n      quantity: item.quantity,\n      amount,\n      currency: amount !== undefined ? code : undefined,\n    };\n  });\n}\n\n/** Safely read a property off loosely typed track properties without widening to `any`. */\nfunction prop(properties: unknown, key: string): unknown {\n  return typeof properties === 'object' && properties !== null\n    ? (properties as Record<string, unknown>)[key]\n    : undefined;\n}\n\nfunction readValue(properties: unknown): number | undefined {\n  const value = prop(properties, 'value');\n  return typeof value === 'number' ? value : undefined;\n}\n\nfunction readCurrency(properties: unknown): string | undefined {\n  const currency = prop(properties, 'currency');\n  return typeof currency === 'string' ? currency : undefined;\n}\n\nfunction readItems(properties: unknown): Item[] | undefined {\n  const items = prop(properties, 'items');\n  return Array.isArray(items) ? (items as Item[]) : undefined;\n}\n\nfunction contentsData(properties: unknown): ContentsData {\n  const currency = readCurrency(properties);\n  return {\n    type: 'contents',\n    amount: toMinorUnits(readValue(properties), currency),\n    currency: currency?.toUpperCase(),\n    contents: mapContents(readItems(properties), currency),\n  };\n}\n\nfunction customerActionData(properties: unknown): CustomerActionData {\n  const currency = readCurrency(properties);\n  return {\n    type: 'customer_action',\n    amount: toMinorUnits(readValue(properties), currency),\n    currency: currency?.toUpperCase(),\n  };\n}\n\nfunction planEnrollmentData(properties: unknown): PlanEnrollmentData {\n  const currency = readCurrency(properties);\n  const items = readItems(properties);\n  return {\n    type: 'plan_enrollment',\n    plan_id: items?.[0]?.item_id,\n    amount: toMinorUnits(readValue(properties), currency),\n    currency: currency?.toUpperCase(),\n    contents: mapContents(items, currency),\n  };\n}\n\nexport type MappedOAIEvent = {\n  type: StandardEvent | 'custom';\n  data: EventData;\n};\n\n/** Map an internal track event onto an OpenAI standard (or custom) conversion event. */\nexport function mapOAIEvent<T extends EventName>(\n  name: TrackName<T>,\n  properties?: TrackProperties<T>\n): MappedOAIEvent {\n  switch (name) {\n    case 'page_view':\n      return { type: 'page_viewed', data: contentsData(properties) };\n    case 'view_item':\n    case 'view_item_list':\n      return { type: 'contents_viewed', data: contentsData(properties) };\n    case 'begin_checkout':\n      return { type: 'checkout_started', data: contentsData(properties) };\n    case 'add_to_cart':\n      return { type: 'items_added', data: contentsData(properties) };\n    case 'purchase':\n      return { type: 'order_created', data: contentsData(properties) };\n    case 'generate_lead':\n    case 'qualify_lead':\n      return { type: 'lead_created', data: customerActionData(properties) };\n    case 'sign_up':\n    case 'login':\n      return { type: 'registration_completed', data: customerActionData(properties) };\n    case 'schedule':\n      return { type: 'appointment_scheduled', data: customerActionData(properties) };\n    case 'subscribe':\n      return { type: 'subscription_created', data: planEnrollmentData(properties) };\n    case 'trial_begin':\n      return { type: 'trial_started', data: planEnrollmentData(properties) };\n    default: {\n      const currency = readCurrency(properties);\n      return {\n        type: 'custom',\n        data: {\n          type: 'custom',\n          amount: toMinorUnits(readValue(properties), currency),\n          currency: currency?.toUpperCase(),\n          contents: mapContents(readItems(properties), currency),\n        },\n      };\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/track/oaiq.d.cts

@@ -59,20 +59,42 @@ export type StandardEvents = {
 };
 export type StandardEvent = keyof StandardEvents;
 /**
- * Identity fields passed to `oaiq("init", ...)` for conversion matching. Email and external id
- * must be pre-hashed as lowercase 64-char SHA-256 hex strings; the rest are sent as raw values.
- * https://developers.openai.com/ads/measurement-pixel
+ * A track name as an OpenAI `custom_event_name`: 1–64 letters, digits, underscores or hyphens,
+ * starting and ending with a letter or digit, not a standard event name; the API lowercases it.
+ * Anything else becomes an underscore, so `Sign Up.Clicked` is `sign_up_clicked`. Undefined when
+ * nothing usable is left — the event is then not sent at all. The pixel and the server both name
+ * a custom event through this, so the two still deduplicate.
+ * https://developers.openai.com/ads/supported-events
+ */
+export declare function oaiCustomEventName(name: string): string | undefined;
+/**
+ * Identity fields passed to `oaiq("init", ...)` for conversion matching. Identifiers are
+ * normalized, then sent as lowercase 64-char SHA-256 hex strings; geographic values are raw.
+ * https://developers.openai.com/ads/measurement-pixel#send-user-data
  */
 export type OAIQUser = {
   email_sha256?: string;
+  /** 8–15 digits with the country code, no leading `+` or zeroes (`normalizeOAIPhone`). */
+  phone_number_sha256?: string;
   external_id_sha256?: string;
+  /** Lowercase, without whitespace or ASCII punctuation (`normalizeOAIName`). */
+  first_name_sha256?: string;
+  last_name_sha256?: string;
   /** Two-letter ISO 3166-1 country code (e.g. "US"). */
   country?: string;
-  /** Lowercased, max 128 characters. */
+  /** Max 128 characters; OpenAI trims and lowercases it. */
   city?: string;
-  /** Max 32 characters. */
-  zip_code?: string;
+  /** State, province or region, max 128 characters. */
+  region?: string;
+  postal_code?: string;
 };
+/**
+ * A phone number as OpenAI hashes it: whitespace, parentheses, periods and hyphens removed, then
+ * the leading `+` and zeroes; 8–15 digits with the country code, else not a usable number.
+ */
+export declare function normalizeOAIPhone(phone: string): string | undefined;
+/** A name as OpenAI hashes it: lowercase, no whitespace or ASCII punctuation, accents kept. */
+export declare function normalizeOAIName(name: string | undefined): string | undefined;
 export type InitConfig = {
   pixelId: string;
   /** Log SDK activity to the browser console. */
@@ -98,7 +120,11 @@ export interface OAIQ {
     custom_event_name: string;
   }): void;
 }
-/** Convert a major-unit amount (e.g., 129.99) into ISO 4217 minor units (e.g., 12,999). */
+/**
+ * Convert a major-unit amount (e.g., 129.99) into ISO 4217 minor units (e.g., 12,999). None
+ * without a currency: the minor unit depends on it, and OpenAI requires a `currency` with every
+ * `amount` — an amount alone would be invalid, not just imprecise.
+ */
 export declare function toMinorUnits(value?: number | null, currency?: string): number | undefined;
 export declare function mapContents(items?: Item[], currency?: string): ContentItem[] | undefined;
 export type MappedOAIEvent = {

package/dist/track/oaiq.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"oaiq.d.cts","names":[],"sources":["../../src/track/oaiq.ts"],"mappings":";;;qBAGa;;;;;YAiBD;EACV;EACA;EACA;EACA;;EAEA;EACA;;YAGU;EACV;;EAEA;EACA;EACA,WAAW;;YAGD;EACV;EACA;EACA;;YAGU;EACV;EACA;EACA;EACA;EACA,WAAW;;YAGD;EACV;EACA;EACA;EACA,WAAW;;YAGD,YAAY,eAAe,qBAAqB,qBAAqB;;;;;YAMrE;EACV,uBAAuB;EACvB,kBAAkB;EAClB,iBAAiB;EACjB,aAAa;EACb,cAAc;EACd,eAAe;EACf,aAAa;EACb,wBAAwB;EACxB,sBAAsB;EACtB,eAAe;;YAGL,sBAAsB;;;;;;YAOtB;EACV;EACA;;EAEA;;EAEA;;EAEA;;YAGU;EACV;;EAEA;EACA,OAAO;;;;;;YAOG;;EAEV;;EAEA;;EAEA;;iBAGe;EACf,KAAK,iBAAiB,QAAQ;EAC9B,KAAK,UAAU,eACb,oBACA,OAAO,GACP,MAAM,eAAe,IACrB,UAAU;EAEZ,KACE,oBACA,iBACA,MAAM,iBACN,SAAS;IAAmB;;;;wBAgChB,aAAa,uBAAuB;wBAYpC,YAAY,QAAQ,QAAQ,oBAAoB;YAkEpD;EACV,MAAM;EACN,MAAM;;;wBAIQ,YAAY,UAAU,WACpC,MAAM,UAAU,IAChB,aAAa,gBAAgB,KAC5B"}
+{"version":3,"file":"oaiq.d.cts","names":[],"sources":["../../src/track/oaiq.ts"],"mappings":";;;qBAGa;;;;;YAiBD;EACV;EACA;EACA;EACA;;EAEA;EACA;;YAGU;EACV;;EAEA;EACA;EACA,WAAW;;YAGD;EACV;EACA;EACA;;YAGU;EACV;EACA;EACA;EACA;EACA,WAAW;;YAGD;EACV;EACA;EACA;EACA,WAAW;;YAGD,YAAY,eAAe,qBAAqB,qBAAqB;;;;;YAMrE;EACV,uBAAuB;EACvB,kBAAkB;EAClB,iBAAiB;EACjB,aAAa;EACb,cAAc;EACd,eAAe;EACf,aAAa;EACb,wBAAwB;EACxB,sBAAsB;EACtB,eAAe;;YAGL,sBAAsB;;;;;;;;;wBAuBlB,mBAAmB;;;;;;YAevB;EACV;;EAEA;EACA;;EAEA;EACA;;EAEA;;EAEA;;EAEA;EACA;;;;;;wBAOc,kBAAkB;;wBASlB,iBAAiB;YAIrB;EACV;;EAEA;EACA,OAAO;;;;;;YAOG;;EAEV;;EAEA;;EAEA;;iBAGe;EACf,KAAK,iBAAiB,QAAQ;EAC9B,KAAK,UAAU,eACb,oBACA,OAAO,GACP,MAAM,eAAe,IACrB,UAAU;EAEZ,KACE,oBACA,iBACA,MAAM,iBACN,SAAS;IAAmB;;;;;;;;wBAoChB,aAAa,uBAAuB;wBAapC,YAAY,QAAQ,QAAQ,oBAAoB;YAqEpD;EACV,MAAM;EACN,MAAM;;;wBAIQ,YAAY,UAAU,WACpC,MAAM,UAAU,IAChB,aAAa,gBAAgB,KAC5B"}