@splendidlabz/tracking 0.2.11 → 0.2.13

package/lib/fb/node.js

@@ -8,15 +8,36 @@ import {
 } from './consts.js'
 import { formatUserData } from './utils.js'
 
-// https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/
+/**
+ * Creates a Facebook Conversions API tracker for server-side tracking
+ * @param {Object} config - Configuration options
+ * @param {string} config.pixelID - Facebook Pixel ID
+ * @param {string} [config.testEventCode] - Test event code for debugging
+ * @param {string} config.accessToken - Facebook Access Token (required)
+ * @param {string} config.framework - Framework being used (astro, express, fastify, koa)
+ * @return {Object} FB tracking instance
+ * @property {Function} sendEvent - Send a pre-formatted event to CAPI
+ * @property {Function} createEvent - Create an event payload
+ * @property {Function} track - Track an event and send to CAPI
+ * @property {Function} sendCAPIRequest - Send raw request to CAPI
+ * @see https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/
+ */
 export default function FB({ pixelID, testEventCode, accessToken, framework }) {
   framework = framework.toLowerCase()
 
   if (!accessToken) throw new Error('Facebook Access Token required')
 
   return {
-    // When used as API call — frontend would have done all the work
-    // So we can just send the body to the CAPI request
+    /**
+     * Sends a pre-formatted event to Facebook CAPI
+     * Used when frontend has already prepared the event data
+     * @param {Object} [props={}] - Event properties including pixel_id, test_event_code, user_data
+     * @param {Object} [options={}] - Additional options
+     * @param {Object} [options.context] - Framework-specific request context
+     * @param {boolean} [options.debug] - Enable debug logging
+     * @param {boolean} [options.dryRun] - Skip actual API call
+     * @return {Promise<Object>} CAPI response
+     */
     async sendEvent(props = {}, options = {}) {
       const { pixel_id, test_event_code, user_data, ...rest } = props
       const { context } = options
@@ -44,6 +65,14 @@ export default function FB({ pixelID, testEventCode, accessToken, framework }) {
       return this.sendCAPIRequest(body, { ...options, pixel_id })
     },
 
+    /**
+     * Creates a Facebook CAPI event payload
+     * @param {string} eventName - Name of the event to track
+     * @param {Object} [props={}] - Event properties and user data
+     * @param {Object} [props.context] - Framework-specific request context (required for auto-filled properties)
+     * @param {Object} [options={}] - Additional options
+     * @return {Promise<Object>} Event payload ready to send to CAPI
+     */
     async createEvent(eventName, props = {}, options = {}) {
       const { context, ...p } = props
       const { p: eventParams, o: r1 } = splitObject(p, SERVER_EVENT_PARAMS)
@@ -93,12 +122,32 @@ export default function FB({ pixelID, testEventCode, accessToken, framework }) {
       return body
     },
 
-    // When used directly via backend
+    /**
+     * Tracks an event and sends it to Facebook CAPI
+     * Combines createEvent and sendCAPIRequest
+     * @param {string} eventName - Name of the event to track
+     * @param {Object} [props={}] - Event properties and user data
+     * @param {Object} [props.context] - Framework-specific request context
+     * @param {Object} [options={}] - Additional options
+     * @param {boolean} [options.debug] - Enable debug logging
+     * @param {boolean} [options.dryRun] - Skip actual API call
+     * @param {string} [options.pixel_id] - Override default pixel ID
+     * @return {Promise<Object>} CAPI response
+     */
     async track(eventName, props = {}, options = {}) {
       const body = await this.createEvent(eventName, props, options)
       return this.sendCAPIRequest(body, options)
     },
 
+    /**
+     * Sends a raw request to Facebook Conversions API
+     * @param {Object} body - Request body containing event data
+     * @param {Object} [options={}] - Request options
+     * @param {boolean} [options.debug] - Log request body
+     * @param {boolean} [options.dryRun] - Skip actual API call
+     * @param {string} [options.pixel_id] - Override default pixel ID
+     * @return {Promise<Object>} CAPI response
+     */
     async sendCAPIRequest(body, options) {
       const { debug = false, dryRun = false, pixel_id } = options
       const pixel = pixel_id || pixelID
@@ -121,6 +170,17 @@ export default function FB({ pixelID, testEventCode, accessToken, framework }) {
 // ========================
 // Helper Functions
 // ========================
+
+/**
+ * Gets default event parameters based on the framework and context
+ * @param {string} framework - Framework name (astro, express, fastify, koa)
+ * @param {Object} context - Framework-specific request context
+ * @return {Object} Default event parameters
+ * @property {string} event_id - Randomly generated event ID
+ * @property {string} action_source - Always set to 'website'
+ * @property {number} event_time - Unix timestamp in seconds
+ * @property {string} event_source_url - Full URL of the request
+ */
 function getEventParamDefaults(framework, context) {
   return {
     event_id: randomString(10),
@@ -130,6 +190,12 @@ function getEventParamDefaults(framework, context) {
   }
 }
 
+/**
+ * Extracts the full URL from framework-specific context
+ * @param {string} framework - Framework name (astro, express, fastify, koa)
+ * @param {Object} context - Framework-specific request context
+ * @return {string} Full URL including protocol, host, and path
+ */
 function getUrl(framework, context) {
   if (framework === 'astro') return context.url.href
   if (framework === 'express') {
@@ -143,6 +209,12 @@ function getUrl(framework, context) {
   }
 }
 
+/**
+ * Extracts client IP address from framework-specific context
+ * @param {string} framework - Framework name (astro, express, fastify, koa)
+ * @param {Object} context - Framework-specific request context
+ * @return {string} Client IP address
+ */
 function getIP(framework, context) {
   if (framework === 'astro') return context.clientAddress
   if (framework === 'express')
@@ -151,6 +223,12 @@ function getIP(framework, context) {
   if (framework === 'koa') return context.ip
 }
 
+/**
+ * Extracts user agent string from framework-specific context
+ * @param {string} framework - Framework name (astro, express, fastify, koa)
+ * @param {Object} context - Framework-specific request context
+ * @return {string} User agent string
+ */
 function getUserAgent(framework, context) {
   if (framework === 'astro') return context.request.headers.get('user-agent')
   if (framework === 'express') return context.get('user-agent')
@@ -158,6 +236,13 @@ function getUserAgent(framework, context) {
   if (framework === 'koa') return context.get('user-agent')
 }
 
+/**
+ * Extracts cookie value from framework-specific context
+ * @param {string} framework - Framework name (astro, express, fastify, koa)
+ * @param {Object} context - Framework-specific request context
+ * @param {string} name - Cookie name
+ * @return {string} Cookie value
+ */
 function getCookie(framework, context, name) {
   if (framework === 'astro') return context.cookies.get(name)?.value
   if (framework === 'express') return context.cookies?.[name]
@@ -165,6 +250,17 @@ function getCookie(framework, context, name) {
   if (framework === 'koa') return context.cookies?.get(name)
 }
 
+/**
+ * Normalizes and enriches user data for Facebook CAPI
+ * Hashes required properties and adds client information from request context
+ * @param {Object} params - Parameters object
+ * @param {Object} params.context - Framework-specific request context
+ * @param {string} params.framework - Framework name (astro, express, fastify, koa)
+ * @param {Object} params.userProps - User properties to normalize
+ * @param {string} [params.fbc] - Facebook click ID cookie
+ * @param {string} [params.fbp] - Facebook browser ID cookie
+ * @return {Promise<Object>} Normalized user data with hashed properties and client info
+ */
 async function normalizeUserData({ context, framework, userProps, fbc, fbp }) {
   const { p: userPropsToHash, o: otherUserProps } = splitObject(
     userProps,

package/lib/fb/web.js

@@ -8,10 +8,39 @@ import {
 } from './consts.js'
 import { formatUserData } from './utils.js'
 
+/**
+ * Creates a Facebook Pixel and CAPI tracker for client-side tracking
+ * @param {Object} config - Configuration options
+ * @param {string} config.pixelID - Facebook Pixel ID
+ * @param {string} [config.testEventCode] - Test event code for debugging
+ * @param {string} config.capiEndpoint - API endpoint for sending CAPI requests
+ * @return {Object} FB tracking instance
+ * @property {Function} init - Initialize Facebook Pixel
+ * @property {Function} createEvent - Create event data for both Pixel and CAPI
+ * @property {Function} track - Track event via both Pixel and CAPI
+ * @property {Function} sendPixelEvent - Send event to Facebook Pixel
+ * @property {Function} sendCAPIRequest - Send event to CAPI endpoint
+ */
 export default function FB({ pixelID, testEventCode, capiEndpoint }) {
   return {
+    /**
+     * Initializes the Facebook Pixel on the page
+     * @return {void}
+     */
     init: _ => initPixel(pixelID),
 
+    /**
+     * Creates event data for both Facebook Pixel and CAPI
+     * @param {string} event_name - Name of the event to track
+     * @param {Object} [props={}] - Event properties and user data
+     * @param {string} [props.eventURL] - Custom URL for the event (defaults to current page)
+     * @param {string} [props.actionSource] - Action source (defaults to 'website')
+     * @param {Object} [options={}] - Additional options
+     * @param {boolean} [options.debug] - Enable debug logging
+     * @return {Promise<Object>} Object containing pixelData and capiData
+     * @property {Object} pixelData - Data formatted for Facebook Pixel
+     * @property {Object} capiData - Data formatted for CAPI
+     */
     async createEvent(event_name, props = {}, options = {}) {
       const { debug = false } = options
       const { eventURL, actionSource, ...r } = props
@@ -60,6 +89,15 @@ export default function FB({ pixelID, testEventCode, capiEndpoint }) {
       return { pixelData, capiData }
     },
 
+    /**
+     * Tracks an event by sending to both Facebook Pixel and CAPI
+     * @param {string} event_name - Name of the event to track
+     * @param {Object} [props={}] - Event properties and user data
+     * @param {Object} [options={}] - Additional options
+     * @param {boolean} [options.debug] - Enable debug logging
+     * @param {boolean} [options.dryRun] - Skip actual tracking (for testing)
+     * @return {Promise<Object>} CAPI response body
+     */
     async track(event_name, props = {}, options = {}) {
       const { debug = false, dryRun = false } = options
       const { pixelData, capiData } = await this.createEvent(
@@ -77,11 +115,20 @@ export default function FB({ pixelID, testEventCode, capiEndpoint }) {
       return response.body
     },
 
-    // Facebook Pixel Code
-    // Pixel Standard Reference
-    // https://developers.facebook.com/docs/meta-pixel/reference#standard-events
-    // For Advanced Matching when user data is available
-    // https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/
+    /**
+     * Sends an event to Facebook Pixel
+     * Supports standard events, custom events, and advanced matching
+     * @param {Object} data - Event data
+     * @param {string} data.pixelID - Pixel ID
+     * @param {string} data.eventID - Event ID for deduplication
+     * @param {string} data.event_name - Event name (use 'init' to initialize pixel)
+     * @param {Object} [data.user_data] - User data for advanced matching
+     * @param {Object} [options] - Options
+     * @param {boolean} [options.debug] - Enable debug logging
+     * @return {void}
+     * @see https://developers.facebook.com/docs/meta-pixel/reference#standard-events
+     * @see https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/
+     */
     sendPixelEvent(data, { debug = false }) {
       const { pixelID, eventID, event_name, user_data = {}, ...rest } = data
       const hasUserData = notEmpty(user_data)
@@ -108,13 +155,24 @@ export default function FB({ pixelID, testEventCode, capiEndpoint }) {
       }
     },
 
-    // CAPI Parameters: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+    /**
+     * Sends a request to the CAPI endpoint
+     * @param {Object} data - CAPI event data
+     * @return {Promise<Object>} Response from CAPI endpoint
+     * @see https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+     */
     sendCAPIRequest(data) {
       return zlFetch.post(capiEndpoint, { body: data })
     },
   }
 }
 
+/**
+ * Initializes the Facebook Pixel by loading the fbevents.js script
+ * @param {string} pixelID - Facebook Pixel ID
+ * @return {void}
+ * @throws {Error} If called outside of browser environment
+ */
 function initPixel(pixelID) {
   // eslint-disable-next-line
   !(function (f, b, e, v, n, t, s) {

package/lib/posthog/node.js

@@ -72,7 +72,7 @@ export default function (config = {}) {
      * @param {string} [properties.userId] - User ID (used for distinct ID)
      * @param {Object} [properties.context] - Request context (for cookie access)
      * @param {...*} properties.rest - Additional event properties
-     * @return {Promise|undefined} PostHog capture promise, or undefined if trackDevEvents is true
+     * @return {Promise|undefined} PostHog capture promise, or undefined if trackEvents is false
      */
     capture(event, properties = {}) {
       if (!trackEvents) return
@@ -88,7 +88,7 @@ export default function (config = {}) {
      * Sets person properties on the current user
      * @param {Object} [set={}] - Properties to set (will overwrite existing values)
      * @param {Object} [once={}] - Properties to set only once (won't overwrite existing values)
-     * @return {Promise|undefined} PostHog capture promise, or undefined if trackDevEvents is true
+     * @return {Promise|undefined} PostHog capture promise, or undefined if trackEvents is false
      */
     setPersonProperties(set = {}, once = {}) {
       if (!trackEvents) return
@@ -104,7 +104,7 @@ export default function (config = {}) {
     /**
      * Removes person properties from the current user
      * @param {string[]} properties - List of property names to remove
-     * @return {Promise|undefined} PostHog capture promise, or undefined if trackDevEvents is true
+     * @return {Promise|undefined} PostHog capture promise, or undefined if trackEvents is false
      */
     removePersonProperties(properties) {
       if (!trackEvents) return

package/lib/posthog/readme.md

@@ -15,3 +15,11 @@ This package assumes you're using Posthog for both web and node.js.
 
 - Get distinct_id from cookies on the backend automatically when using Astro — just provide context.
 - Use `trackEvents:false` to disable tracking completely when developing.
+
+## Filtering out local development environments
+
+You can create filters which include more than one value by separating values with a comma. We use such a filter to exclude events from local development environments, for example:
+
+Host ≠ (doesn’t equal) localhost:8000,localhost:5000,127.0.0.1:8000
+
+You can also create filters based on pre-prepared cohorts of users, which is especially useful if you’re using cohorts with Feature Flags or to run Experiments. To do this, simply select the cohort you wish to add to your internal and test user list.

package/lib/posthog/web.js

@@ -41,7 +41,8 @@ export default function (config = {}) {
 
     /**
      * Set properties for the current person
-     * @param {...any} props - Properties to set for the person
+     * @param {object} [set={}] - Properties to set (will overwrite existing values)
+     * @param {object} [once={}] - Properties to set only once (won't overwrite existing values)
      * @returns {void}
      */
     setPersonProperties(set = {}, once = {}) {
@@ -50,8 +51,9 @@ export default function (config = {}) {
     },
 
     /**
+     * Identify a user with PostHog. If the distinctId differs from the existing cookie ID, creates a new identity; otherwise updates properties.
      * @param {string} distinctId - New unique identifier for the user (email, userId, etc.)
-     * @param {object} properties - The properties to set for the user
+     * @param {object} [properties={}] - The properties to set for the user
      * @returns {void}
      */
     identify(distinctId, properties = {}) {
@@ -67,6 +69,7 @@ export default function (config = {}) {
     },
 
     /**
+     * Create an alias for a user, linking two distinct IDs together
      * @param {string} distinctId - New unique identifier for the user
      * @param {string} aliasId - Alias for the user
      * @returns {void}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splendidlabz/tracking",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Simple Tracking Helper",
   "type": "module",
   "files": [
@@ -10,7 +10,7 @@
     "lib/convertkit"
   ],
   "exports": {
-    "./*": "./lib/*"
+    "./*": "./lib/*.js"
   },
   "scripts": {
     "test": "vitest",