@splendidlabz/tracking 0.2.10 → 0.2.12

package/lib/fb/node.js

@@ -8,24 +8,71 @@ 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, ...rest } = props
+      const { pixel_id, test_event_code, user_data, ...rest } = props
+      const { context } = options
+
+      const {
+        p: { fbc, fbp },
+        o: userProps,
+      } = splitObject(user_data, ['fbc', 'fbp'])
+
+      const data = {
+        ...rest,
+        user_data: await normalizeUserData({
+          context,
+          framework,
+          userProps,
+          fbc,
+          fbp,
+        }),
+      }
+
       const body = {
-        data: [omitEmpty(rest)],
+        data: [omitEmpty(data)],
         test_event_code: test_event_code || testEventCode,
       }
       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)
@@ -44,8 +91,11 @@ export default function FB({ pixelID, testEventCode, accessToken, framework }) {
         )
       }
 
-      if (framework !== 'astro') {
-        throw new Error('Currently we only support the Astro framework')
+      const supportedFrameworks = ['astro', 'express', 'fastify', 'koa']
+      if (!supportedFrameworks.includes(framework)) {
+        throw new Error(
+          `Unsupported framework: ${framework}. Supported frameworks: ${supportedFrameworks.join(', ')}`,
+        )
       }
 
       const normalizedUserData = await normalizeUserData({
@@ -72,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
@@ -97,6 +167,20 @@ 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),
@@ -106,13 +190,78 @@ 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') {
+    return context.protocol + '://' + context.get('host') + context.originalUrl
+  }
+  if (framework === 'fastify') {
+    return context.protocol + '://' + context.hostname + context.url
+  }
+  if (framework === 'koa') {
+    return context.protocol + '://' + context.host + context.url
+  }
 }
 
-async function normalizeUserData({ context, framework, userProps, fbc, fbp }) {
-  let ip, userAgent
+/**
+ * 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')
+    return context.ip || context.connection?.remoteAddress
+  if (framework === 'fastify') return context.ip
+  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')
+  if (framework === 'fastify') return context.headers['user-agent']
+  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]
+  if (framework === 'fastify') return context.cookies?.[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,
     USER_PROPERTIES_TO_HASH,
@@ -120,13 +269,11 @@ async function normalizeUserData({ context, framework, userProps, fbc, fbp }) {
 
   const hashedProps = await formatUserData(userPropsToHash, sha256Hash)
 
-  // Get other client data
-  if (framework === 'astro') {
-    ip = context.clientAddress
-    userAgent = context.request.headers.get('user-agent')
-    if (!fbp) fbp = context.cookies.get('_fbp')?.value
-    if (!fbc) fbc = context.cookies.get('_fbc')?.value
-  }
+  // Get client data from context
+  const ip = getIP(framework, context)
+  const userAgent = getUserAgent(framework, context)
+  if (!fbp) fbp = getCookie(framework, context, '_fbp')
+  if (!fbc) fbc = getCookie(framework, context, '_fbc')
 
   const userData = omitEmpty({
     ...hashedProps,

package/lib/fb/readme.md

@@ -1,42 +1,43 @@
-Shared config
+Designed to provide a unified interface for Facebook Pixel and Conversion API.
+
+## Setup
+
+Config
 
 ```js
 export default {
   fb: {
     pixelID: 'PIXEL ID',
     testEventCode: 'TEST EVENT CODE',
+    capiEndpoint: '/api/tracking/facebook/',
+    accessToken: import.meta.env.FB_CAPI_TOKEN,
+    framework: 'astro', // or 'express', 'fastify', 'koa'
   },
 }
 ```
 
-Setup
+Browser
 
 ```js
 import FB from '@splendidlabz/tracking/fb/web'
-import config from './shared'
-
-export const fb = FB({
-  ...config.fb,
-  capiEndpoint: '/api/tracking/facebook/',
-})
+import config from './config'
+export const fb = FB(config.fb)
 ```
 
 Server
 
 ```js
 import FB from '@splendidlabz/tracking/fb/node'
-import config from './shared'
-
-export const fb = FB({
-  ...config.fb,
-  framework: 'astro',
-  accessToken: import.meta.env.FB_CAPI_TOKEN,
-})
+import config from './config'
+export const fb = FB(config.fb)
 ```
 
-Ads server for dedupe events
+Include API to dedupe events through CAPI
+
+**Astro:**
 
 ```js
+// /api/tracking/facebook/
 import { fb } from '@/services/tracking/node'
 import { JSONResponse, parseData } from '@splendidlabz/astro/server'
 export const prerender = false
@@ -49,6 +50,143 @@ export async function POST(context) {
 }
 ```
 
-Other stuff necessary.... well... check Facebook docs ba.
-Perhaps should include a standard event list , or link to the docs.
-Should also notify that `PageView` is going to be tracked as a custom event.
+**Express:**
+
+```js
+// Requires cookie-parser middleware for cookie support
+import express from 'express'
+import cookieParser from 'cookie-parser'
+import { fb } from './services/tracking/node.js'
+
+const app = express()
+app.use(express.json())
+app.use(cookieParser())
+
+app.post('/api/tracking/facebook', async (req, res) => {
+  const { response, error } = await fb.sendEvent(req.body)
+  if (response) return res.status(200).json(response.body)
+  if (error) return res.status(500).json(error)
+})
+```
+
+**Fastify:**
+
+```js
+// Requires @fastify/cookie plugin for cookie support
+import Fastify from 'fastify'
+import fastifyCookie from '@fastify/cookie'
+import { fb } from './services/tracking/node.js'
+
+const fastify = Fastify()
+await fastify.register(fastifyCookie)
+
+fastify.post('/api/tracking/facebook', async (request, reply) => {
+  const { response, error } = await fb.sendEvent(request.body)
+  if (response) return reply.status(200).send(response.body)
+  if (error) return reply.status(500).send(error)
+})
+```
+
+**Koa:**
+
+```js
+// Requires koa-bodyparser and koa-cookie middleware
+import Koa from 'koa'
+import bodyParser from 'koa-bodyparser'
+import cookie from 'koa-cookie'
+import { fb } from './services/tracking/node.js'
+
+const app = new Koa()
+app.use(bodyParser())
+app.use(cookie())
+
+app.use(async (ctx) => {
+  if (ctx.path === '/api/tracking/facebook' && ctx.method === 'POST') {
+    const { response, error } = await fb.sendEvent(ctx.request.body)
+    if (response) {
+      ctx.status = 200
+      ctx.body = response.body
+    }
+    if (error) {
+      ctx.status = 500
+      ctx.body = error
+    }
+  }
+})
+```
+
+## Usage
+
+Browser:
+
+```js
+fb.track('event_name', { ...props })
+```
+
+Node (requires passing the request context):
+
+**Astro:**
+
+```js
+fb.track('event_name', { context, ...props })
+```
+
+**Express:**
+
+```js
+app.post('/some-route', async (req, res) => {
+  await fb.track('event_name', { context: req, ...props })
+  res.json({ success: true })
+})
+```
+
+**Fastify:**
+
+```js
+fastify.post('/some-route', async (request, reply) => {
+  await fb.track('event_name', { context: request, ...props })
+  reply.send({ success: true })
+})
+```
+
+**Koa:**
+
+```js
+app.use(async (ctx) => {
+  if (ctx.path === '/some-route' && ctx.method === 'POST') {
+    await fb.track('event_name', { context: ctx, ...props })
+    ctx.body = { success: true }
+  }
+})
+```
+
+## Event Reference
+
+- [Standard Event Reference](https://developers.facebook.com/docs/meta-pixel/reference#standard-events)
+- [Advanced Matching Reference](https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/)
+- [Conversion API Params Reference](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters)
+
+## Testing Your Implementation
+
+Go to `Events Manager > Datasets > Test Events` and copy your event tracking code. Add it to your config.
+
+**IMPORTANT**: Remove `testEventCode` after your tests! You don't want this in your production code.
+
+```js
+export default {
+  fb: {
+    pixelID: 'PIXEL ID',
+    testEventCode: 'TEST EVENT CODE',
+    // ...
+  },
+}
+```
+
+Under the same `Test Events` tab, enter a website to test with.
+
+- Note that localhost cannot be used for browser-testing — FB requires a valid domain
+- To test if server & browser events are deduplicated, use a local tunnel like ngrok.
+- Make sure your website — and your tunnel — is listed under your Pixel's allow list under
+  `Dataset > Settings > Allow list`. Feel free to remove the tunnel from the allow list after testing.
+
+- Context is to automatically get Client IP Address and User Agent.

package/lib/fb/web.js

@@ -1,18 +1,46 @@
 import { notEmpty, splitObject } from '@splendidlabz/utils'
 import { getCookie, randomString, sha256Hash } from '@splendidlabz/utils/dom'
+import zlFetch from 'zl-fetch'
 import {
   STANDARD_EVENTS,
   USER_PROPERTIES,
   USER_PROPERTIES_TO_HASH,
 } from './consts.js'
-
-import zlFetch from 'zl-fetch'
 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
@@ -61,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(
@@ -78,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)
@@ -109,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.10",
+  "version": "0.2.12",
   "description": "Simple Tracking Helper",
   "type": "module",
   "files": [