@shware/analytics 3.6.4 → 3.8.0

package/dist/track/fbq.d.mts

@@ -0,0 +1,280 @@
+import { Item } from "./gtag.mjs";
+import { EventName, TrackName, TrackProperties } from "./types.mjs";
+//#region src/track/fbq.d.ts
+type Content = {
+  id: string;
+  quantity: number;
+  item_price?: number;
+  title?: string;
+  description?: string;
+  brand?: string;
+  category?: string;
+  delivery_category?: string;
+};
+/**
+ * reference: https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching
+ * reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+ */
+type MatchingParameters = {
+  /** Email: Unhashed lowercase or hashed SHA-256 */
+  em?: string;
+  /** First Name: Lowercase letters */
+  fn?: string;
+  /** Last Name: Lowercase letters */
+  ln?: string;
+  /** Phone Number: Digits only including country code and area code */
+  ph?: string;
+  /**
+   * External ID: Any unique ID from the advertiser, such as loyalty membership ID, user ID, and
+   * external cookie ID.
+   */
+  external_id?: string;
+  /** Gender: Single lowercase letter, f or m, if unknown, leave blank */
+  ge?: 'f' | 'm' | '';
+  /** Birthdate: Digits only with birth year, month, then day, YYYYMMDD */
+  db?: number;
+  /** City: Lowercase with any spaces removed, e.g. "menlopark" */
+  ct?: string;
+  /** State or Province: Lowercase two-letter state or province code, e.g. "ca" */
+  st?: string;
+  /** Zip or Postal Code: String */
+  zp?: string;
+  /** Country: Lowercase two-letter country code, e.g. "us" */
+  country?: string;
+  /** Client IP Address: Do not hash. */
+  client_ip_address?: string;
+  /** Client User Agent: Do not hash. */
+  client_user_agent?: string;
+  /**
+   * Click ID: Do not hash.
+   * The Facebook click ID value is stored in the _fbc browser cookie under your domain. See
+   * Managing fbc and fbp Parameters for how to get this value or generate this value from a fbclid
+   * query parameter.
+   *
+   * The format is fb.${subdomain_index}.${creation_time}.${fbclid}.
+   */
+  fbc?: string;
+  /**
+   * Browser ID: Do not hash.
+   * The Facebook browser ID value is stored in the _fbp browser cookie under your domain. See
+   * Managing fbc and fbp Parameters for how to get this value.
+   *
+   * The format is fb.${subdomain_index}.${creation_time}.${random_number}.
+   */
+  fbp?: string;
+  /**
+   * Subscription ID: Do not hash.
+   * The subscription ID for the user in this transaction; it is similar to the order ID for an
+   * individual product.
+   */
+  subscription_id?: string;
+  /**
+   * Facebook Login ID: Do not hash.
+   * The ID issued by Meta when a person first logs into an instance of an app. This is also known
+   * as App-Scoped ID.
+   */
+  fb_login_id?: number;
+  /**
+   * Lead ID: Do not hash.
+   * The ID associated with a lead generated by [Meta's Lead Ads](https://developers.facebook.com/docs/marketing-api/guides/lead-ads).
+   */
+  lead_id?: number;
+  /**
+   * Install ID: Do not hash.
+   * Your install ID. This field represents unique application installation instances.
+   * Note: This parameter is for app events only.
+   */
+  anon_id?: string;
+  /**
+   * Your mobile advertiser ID, the advertising ID from an Android device or the Advertising
+   * Identifier (IDFA) from an Apple device.
+   */
+  madid?: string;
+  /**
+   * Page ID: Do not hash.
+   * Your Page ID. Specifies the page ID associated with the event. Use the Facebook page ID of the
+   * page associated with the bot.
+   */
+  page_id?: string;
+  /**
+   * Page Scoped User ID: Do not hash.
+   * Specifies the page-scoped user ID associated with the messenger bot that logs the event. Use
+   * the page-scoped user ID provided to your webhook.
+   */
+  page_scoped_user_id?: string;
+  /**
+   * Do not hash.
+   * Click ID generated by Meta for ads that click to WhatsApp.
+   */
+  ctwa_clid?: string;
+  /**
+   * Do not hash.
+   * Instagram Account ID that is associated with the business.
+   */
+  ig_account_id?: string;
+  /**
+   * Do not hash.
+   * Users who interact with Instagram are identified by Instagram-Scoped User IDs (IGSID). IGSID
+   * can be obtained from this webhook.
+   */
+  ig_sid?: string;
+};
+/**
+ * You can include the following predefined object properties with any custom events, and any
+ * standard events that support them. Format your parameter object data using JSON. Learn more about
+ * event parameters with Blueprint.
+ */
+type ObjectProperties = {
+  content_category?: string;
+  content_ids?: string[];
+  content_name?: string;
+  /**
+   * Either product or product_group based on the content_ids or contents being passed. If the IDs
+   * being passed in content_ids or contents parameter are IDs of products, then the value should be
+   * product. If product group IDs are being passed, then the value should be product_group.
+   *
+   * If no content_type is provided, Meta will match the event to every item that has the same ID,
+   * independent of its type.
+   */
+  content_type?: 'product' | 'product_group' | (string & {});
+  contents?: Content[];
+  delivery_category?: 'in_store' | 'curbside' | 'home_delivery';
+  currency?: string;
+  num_items?: number;
+  predicted_ltv?: number;
+  search_string?: string;
+  /** Used with the CompleteRegistration event, to show the status of the registration. */
+  status?: boolean;
+  value?: number;
+};
+/**
+ * reference: https://developers.facebook.com/docs/marketing-api/conversions-api/payload-helper
+ */
+type StandardEvents = {
+  AddPaymentInfo: {
+    content_ids?: string[];
+    contents?: Content[];
+    currency?: string;
+    value?: number;
+  };
+  AddToCart: {
+    content_ids?: string[];
+    content_type?: string;
+    contents?: Content[];
+    currency?: string;
+    value?: number;
+  };
+  AddToWishlist: {
+    content_ids?: string[];
+    contents?: Content[];
+    currency?: string;
+    value?: number;
+  };
+  CompleteRegistration: {
+    currency?: string;
+    value?: number;
+    method?: string;
+  };
+  Contact: {};
+  CustomizeProduct: {};
+  Donate: {};
+  FindLocation: {};
+  InitiateCheckout: {
+    content_ids?: string[];
+    contents?: Content[];
+    currency?: string;
+    num_items?: number;
+    value?: number;
+  };
+  Lead: {
+    currency?: string;
+    value?: number;
+  };
+  Purchase: {
+    content_ids?: string[];
+    content_type?: string;
+    contents?: Content[];
+    currency: string;
+    num_items?: number;
+    value: number;
+  };
+  Schedule: {};
+  Search: {
+    content_ids?: string[];
+    content_type?: string;
+    contents?: Content[];
+    currency?: string;
+    search_string?: string;
+    value?: number;
+  };
+  StartTrial: {
+    currency?: string;
+    predicted_ltv?: number;
+    value?: number;
+  };
+  SubmitApplication: {};
+  Subscribe: {
+    currency?: string;
+    predicted_ltv?: number;
+    value?: number;
+  };
+  ViewContent: {
+    content_ids?: string[];
+    content_type?: string;
+    contents?: Content[];
+    currency?: string;
+    value?: number;
+  };
+};
+type JSONValue = null | string | number | boolean | Array<JSONValue> | {
+  [value: string]: JSONValue;
+};
+type PixelId = `${number}`;
+type Options = {
+  eventID?: string;
+};
+/**
+ * reference: https://developers.facebook.com/docs/meta-pixel/reference#standard-events
+ *
+ * We determine if events are identical based on their ID and name. So, for an event to be deduplicated:
+ * - In corresponding events, a Meta Pixel's eventID must match the Conversion API's event_id.
+ * - In corresponding events, a Meta Pixel's event must match the Conversion API's event_name.
+ *
+ * reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+ */
+interface FBQ {
+  /**
+   * reference: https://stackoverflow.com/questions/62304291/sending-user-data-parameters-via-pixel
+   *
+   * Call init the normal default way first:
+   * `fbq('init', 'XXXXX')`
+   *
+   * And at a later point in time, when you have obtained additional user data, you can call init
+   * again basically enriching the already running fbq instance with additional data:
+   * `fbq('init', 'XXXXX', { external_id: 1234, em: 'abc@abc.com' } )`
+   *
+   * Only caveat is that you have to send an event after this additional init call, otherwise the
+   * provided data will not be sent to Facebook.
+   */
+  fbq(type: 'init', pixelId: PixelId, parameters?: MatchingParameters): void;
+  /** Enable Manual Only mode. (value = false) */
+  fbq(type: 'set', key: 'autoConfig', value: boolean, pixelId: PixelId): void;
+  fbq<T extends keyof StandardEvents>(type: 'track', event: T, properties?: StandardEvents[T] & ObjectProperties, options?: Options): void;
+  fbq(type: 'trackCustom', event: string, properties?: Record<string, JSONValue> & ObjectProperties, options?: Options): void;
+  /** https://developers.facebook.com/docs/meta-pixel/guides/track-multiple-events/ */
+  fbq<T extends keyof StandardEvents>(type: 'trackSingle', pixelId: PixelId, event: T, properties?: StandardEvents[T] & ObjectProperties, options?: Options): void;
+  /** https://developers.facebook.com/docs/meta-pixel/guides/track-multiple-events/ */
+  fbq(type: 'trackSingleCustom', pixelId: PixelId, event: string, properties?: Record<string, JSONValue> & ObjectProperties, options?: Options): void;
+}
+/**
+ * Please download this CSV filefor examples of properly normalized and hashed data for the
+ * parameters below.
+ */
+declare function normalize(parameters: MatchingParameters): MatchingParameters;
+declare function mapItems(items?: Item[]): ObjectProperties;
+type Mapped<F extends keyof StandardEvents> = ['track', F, StandardEvents[F] & ObjectProperties];
+type Missed<F extends string> = ['trackCustom', F, Record<string, JSONValue> & ObjectProperties];
+declare function mapFBEvent<T extends EventName>(name: TrackName<T>, properties?: TrackProperties<T>): Mapped<keyof StandardEvents> | Missed<TrackName<T>>;
+//#endregion
+export { Content, FBQ, MatchingParameters, ObjectProperties, Options, PixelId, StandardEvents, mapFBEvent, mapItems, normalize };
+//# sourceMappingURL=fbq.d.mts.map

package/dist/track/fbq.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fbq.d.mts","names":[],"sources":["../../src/track/fbq.ts"],"mappings":";;;KAIY;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;KAOU;;EAEV;;EAGA;;EAGA;;EAGA;;;;;EAMA;;EAGA;;EAGA;;EAGA;;EAGA;;EAGA;;EAGA;;EAGA;;EAGA;;;;;;;;;EAUA;;;;;;;;EASA;;;;;;EAOA;;;;;;EAOA;;;;;EAMA;;;;;;EAOA;;;;;EAMA;;;;;;EAOA;;;;;;EAOA;;;;;EAMA;;;;;EAMA;;;;;;EAOA;;;;;;;KAQU;EACV;EACA;EACA;;;;;;;;;EAUA;EACA,WAAW;EACX;EACA;EACA;EACA;EACA;;EAGA;EACA;;;;;KAMU;EACV;IACE;IACA,WAAW;IACX;IACA;;EAEF;IACE;IACA;IACA,WAAW;IACX;IACA;;EAEF;IACE;IACA,WAAW;IACX;IACA;;EAEF;IACE;IACA;IACA;;EAEF;EACA;EACA;EACA;EACA;IACE;IACA,WAAW;IACX;IACA;IACA;;EAEF;IACE;IACA;;EAEF;IACE;IACA;IACA,WAAW;IACX;IACA;IACA;;EAEF;EACA;IACE;IACA;IACA,WAAW;IACX;IACA;IACA;;EAEF;IACE;IACA;IACA;;EAEF;EACA;IACE;IACA;IACA;;EAEF;IACE;IACA;IACA,WAAW;IACX;IACA;;;KAIC,+CAKD,MAAM;GACH,gBAAgB;;KAEX;KACA;EAAY;;;;;;;;;;;UAWP;;;;;;;;;;;;;;EAcf,IAAI,cAAc,SAAS,SAAS,aAAa;;EAGjD,IAAI,aAAa,mBAAmB,gBAAgB,SAAS;EAE7D,IAAI,gBAAgB,gBAClB,eACA,OAAO,GACP,aAAa,eAAe,KAAK,kBACjC,UAAU;EAGZ,IACE,qBACA,eACA,aAAa,eAAe,aAAa,kBACzC,UAAU;;EAIZ,IAAI,gBAAgB,gBAClB,qBACA,SAAS,SACT,OAAO,GACP,aAAa,eAAe,KAAK,kBACjC,UAAU;;EAIZ,IACE,2BACA,SAAS,SACT,eACA,aAAa,eAAe,aAAa,kBACzC,UAAU;;;;;;iBAQE,UAAU,YAAY,qBAAqB;iBAiB3C,SAAS,QAAQ,SAAS;KAsBrC,OAAO,gBAAgB,4BAA4B,GAAG,eAAe,KAAK;KAC1E,OAAO,oCAAoC,GAAG,eAAe,aAAa;iBAE/D,WAAW,UAAU,WACnC,MAAM,UAAU,IAChB,aAAa,gBAAgB,KAC5B,aAAa,kBAAkB,OAAO,UAAU"}

package/dist/track/fbq.mjs

@@ -1,115 +1,183 @@
-// src/track/fbq.ts
+//#region src/track/fbq.ts
+/**
+* Please download this CSV filefor examples of properly normalized and hashed data for the
+* parameters below.
+*/
 function normalize(parameters) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i;
-  return {
-    ...parameters,
-    em: (_a = parameters.em) == null ? void 0 : _a.toLowerCase().trim(),
-    ph: (_b = parameters.ph) == null ? void 0 : _b.replace(/[-+()\s]/g, "").replace(/^0+/, ""),
-    zp: (_d = (_c = parameters.zp) == null ? void 0 : _c.split("-").at(0)) == null ? void 0 : _d.trim(),
-    fn: (_e = parameters.fn) == null ? void 0 : _e.toLowerCase().trim(),
-    ln: (_f = parameters.ln) == null ? void 0 : _f.toLowerCase().trim(),
-    ct: (_g = parameters.ct) == null ? void 0 : _g.toLowerCase().replace(/[s/-]/g, "").trim(),
-    st: (_h = parameters.st) == null ? void 0 : _h.toLowerCase().replace(/[s/-/,.]/g, "").trim(),
-    country: (_i = parameters.country) == null ? void 0 : _i.toLowerCase().replace(/[s/-]/g, "").trim()
-  };
+	return {
+		...parameters,
+		em: parameters.em?.toLowerCase().trim(),
+		ph: parameters.ph?.replace(/[-+()\s]/g, "").replace(/^0+/, ""),
+		zp: parameters.zp?.split("-").at(0)?.trim(),
+		fn: parameters.fn?.toLowerCase().trim(),
+		ln: parameters.ln?.toLowerCase().trim(),
+		ct: parameters.ct?.toLowerCase().replace(/[s/-]/g, "").trim(),
+		st: parameters.st?.toLowerCase().replace(/[s/-/,.]/g, "").trim(),
+		country: parameters.country?.toLowerCase().replace(/[s/-]/g, "").trim()
+	};
 }
 function mapItems(items) {
-  if (!items) return {};
-  const categories = Array.from(new Set(items.map((i) => i.item_category).filter(Boolean)));
-  const contents = items.map(
-    ({ item_id, quantity, price, item_name, item_brand, item_category, ..._others }) => ({
-      id: item_id,
-      quantity: quantity ?? 1,
-      item_price: price,
-      title: item_name,
-      brand: item_brand,
-      category: item_category
-    })
-  );
-  return {
-    content_category: categories.length === 1 ? categories.at(0) : void 0,
-    contents,
-    content_ids: contents.map((c) => c.id),
-    num_items: items.reduce((acc, i) => acc + (i.quantity ?? 1), 0)
-  };
+	if (!items) return {};
+	const categories = Array.from(new Set(items.map((i) => i.item_category).filter(Boolean)));
+	const contents = items.map(({ item_id, quantity, price, item_name, item_brand, item_category, ..._others }) => ({
+		id: item_id,
+		quantity: quantity ?? 1,
+		item_price: price,
+		title: item_name,
+		brand: item_brand,
+		category: item_category
+	}));
+	return {
+		content_category: categories.length === 1 ? categories.at(0) : void 0,
+		contents,
+		content_ids: contents.map((c) => c.id),
+		num_items: items.reduce((acc, i) => acc + (i.quantity ?? 1), 0)
+	};
 }
 function mapFBEvent(name, properties) {
-  if (name === "add_payment_info") {
-    const p = properties;
-    return [
-      "track",
-      "AddPaymentInfo",
-      { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) }
-    ];
-  } else if (name === "add_to_cart") {
-    const p = properties;
-    return [
-      "track",
-      "AddToCart",
-      { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) }
-    ];
-  } else if (name === "add_to_wishlist") {
-    const p = properties;
-    return [
-      "track",
-      "AddToWishlist",
-      { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) }
-    ];
-  } else if (name === "login") {
-    const p = properties;
-    return ["track", "CompleteRegistration", { method: p == null ? void 0 : p.method }];
-  } else if (name === "contact") {
-    return ["track", "Contact", {}];
-  } else if (name === "customize_product") {
-    return ["track", "CustomizeProduct", {}];
-  } else if (name === "donate") {
-    return ["track", "Donate", {}];
-  } else if (name === "find_location") {
-    return ["track", "FindLocation", {}];
-  } else if (name === "begin_checkout") {
-    const p = properties;
-    return [
-      "track",
-      "InitiateCheckout",
-      { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) }
-    ];
-  } else if (name === "generate_lead") {
-    const p = properties;
-    return ["track", "Lead", { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value }];
-  } else if (name === "purchase") {
-    const p = properties;
-    return [
-      "track",
-      "Purchase",
-      { currency: (p == null ? void 0 : p.currency) ?? "USD", value: (p == null ? void 0 : p.value) ?? 0, ...mapItems(p == null ? void 0 : p.items) }
-    ];
-  } else if (name === "schedule") {
-    return ["track", "Schedule", {}];
-  } else if (name === "search") {
-    const p = properties;
-    return ["track", "Search", { search_string: p == null ? void 0 : p.search_term }];
-  } else if (name === "trial_begin") {
-    const p = properties;
-    return ["track", "StartTrial", { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value }];
-  } else if (name === "submit_application") {
-    return ["track", "SubmitApplication", {}];
-  } else if (name === "subscribe") {
-    const p = properties;
-    return ["track", "Subscribe", { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value }];
-  } else if (name === "view_item") {
-    const p = properties;
-    return [
-      "track",
-      "ViewContent",
-      { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) }
-    ];
-  } else {
-    return ["trackCustom", name, properties ?? {}];
-  }
+	if (name === "add_payment_info") {
+		const p = properties;
+		return [
+			"track",
+			"AddPaymentInfo",
+			{
+				currency: p?.currency,
+				value: p?.value,
+				...mapItems(p?.items)
+			}
+		];
+	} else if (name === "add_to_cart") {
+		const p = properties;
+		return [
+			"track",
+			"AddToCart",
+			{
+				currency: p?.currency,
+				value: p?.value,
+				...mapItems(p?.items)
+			}
+		];
+	} else if (name === "add_to_wishlist") {
+		const p = properties;
+		return [
+			"track",
+			"AddToWishlist",
+			{
+				currency: p?.currency,
+				value: p?.value,
+				...mapItems(p?.items)
+			}
+		];
+	} else if (name === "login") return [
+		"track",
+		"CompleteRegistration",
+		{ method: properties?.method }
+	];
+	else if (name === "contact") return [
+		"track",
+		"Contact",
+		{}
+	];
+	else if (name === "customize_product") return [
+		"track",
+		"CustomizeProduct",
+		{}
+	];
+	else if (name === "donate") return [
+		"track",
+		"Donate",
+		{}
+	];
+	else if (name === "find_location") return [
+		"track",
+		"FindLocation",
+		{}
+	];
+	else if (name === "begin_checkout") {
+		const p = properties;
+		return [
+			"track",
+			"InitiateCheckout",
+			{
+				currency: p?.currency,
+				value: p?.value,
+				...mapItems(p?.items)
+			}
+		];
+	} else if (name === "generate_lead") {
+		const p = properties;
+		return [
+			"track",
+			"Lead",
+			{
+				currency: p?.currency,
+				value: p?.value
+			}
+		];
+	} else if (name === "purchase") {
+		const p = properties;
+		return [
+			"track",
+			"Purchase",
+			{
+				currency: p?.currency ?? "USD",
+				value: p?.value ?? 0,
+				...mapItems(p?.items)
+			}
+		];
+	} else if (name === "schedule") return [
+		"track",
+		"Schedule",
+		{}
+	];
+	else if (name === "search") return [
+		"track",
+		"Search",
+		{ search_string: properties?.search_term }
+	];
+	else if (name === "trial_begin") {
+		const p = properties;
+		return [
+			"track",
+			"StartTrial",
+			{
+				currency: p?.currency,
+				value: p?.value
+			}
+		];
+	} else if (name === "submit_application") return [
+		"track",
+		"SubmitApplication",
+		{}
+	];
+	else if (name === "subscribe") {
+		const p = properties;
+		return [
+			"track",
+			"Subscribe",
+			{
+				currency: p?.currency,
+				value: p?.value
+			}
+		];
+	} else if (name === "view_item") {
+		const p = properties;
+		return [
+			"track",
+			"ViewContent",
+			{
+				currency: p?.currency,
+				value: p?.value,
+				...mapItems(p?.items)
+			}
+		];
+	} else return [
+		"trackCustom",
+		name,
+		properties ?? {}
+	];
 }
-export {
-  mapFBEvent,
-  mapItems,
-  normalize
-};
+//#endregion
+export { mapFBEvent, mapItems, normalize };
+
 //# sourceMappingURL=fbq.mjs.map