@splendidlabz/tracking 0.1.22 → 0.2.0

package/lib/posthog/node.js

@@ -0,0 +1,140 @@
+import { omitEmpty } from '@splendidlabz/utils'
+import { PostHog } from 'posthog-node'
+
+// Posthog Persistence docs: https://posthog.com/docs/libraries/js/persistence
+
+/**
+ * Creates a PostHog analytics client wrapper for server-side tracking
+ * @param {Object} config - Configuration object
+ * @param {string} config.apiKey - PostHog API key
+ * @param {string} config.host - PostHog host URL
+ * @param {string} config.framework - Framework name (currently only 'astro' is supported)
+ * @param {boolean} [config.trackEvents=true] - Whether to track events. Set to false in development mode to avoid sending events to PostHog.
+ * @param {...*} config.rest - Additional PostHog client options
+ * @return {Object} PostHog client wrapper
+ * @property {Function} capture - Captures analytics events
+ * @property {Function} setPersonProperties - Sets person properties
+ * @property {Function} removePersonProperties - Removes person properties
+ * @property {Function} shutdown - Shuts down the PostHog client
+ * @throws {Error} When framework is not 'astro'
+ */
+export default function (config = {}) {
+  const { framework, apiKey, host, trackEvents = true, ...rest } = config
+  const cookieName = `ph_${apiKey}_posthog`
+
+  if (framework !== 'astro') {
+    throw new Error('Only Astro framework is supported at the moment')
+  }
+  const client = new PostHog(apiKey, { host, ...rest })
+
+  /**
+   * Gets the distinct ID for tracking, prioritizing email, then userId, then cookie-based ID
+   * @param {Object} params - Parameters object
+   * @param {string} params.email - User email address
+   * @param {string} params.userId - User ID
+   * @param {Object} params.context - Request context (for cookie access)
+   * @param {string} params.framework - Framework name
+   * @return {string|undefined} The distinct ID for tracking
+   */
+  function getDistinctId({ email, userId, context, framework }) {
+    if (email) return email
+    if (userId) return userId
+    return getDistinctIdFromCookie({ context, framework })
+  }
+
+  // This assumes posthog web is used as well.
+  // If not used, we need to generate and store the distinct_id in a cookie instead — maybe in the future.
+  // - Need a database to store distinct_id?
+  // - Need to use userId or email from the database?
+  /**
+   * Extracts distinct ID from PostHog cookie (assumes PostHog web client is also used)
+   * @param {Object} params - Parameters object
+   * @param {Object} params.context - Request context with cookies access
+   * @param {string} params.framework - Framework name
+   * @return {string|undefined} The distinct ID from cookie, or undefined if not found
+   */
+  function getDistinctIdFromCookie({ context, framework }) {
+    if (framework === 'astro') {
+      const cookie = context.cookies.get(cookieName)
+      if (cookie) {
+        const { distinct_id } = JSON.parse(cookie.value)
+        return distinct_id
+      }
+    }
+  }
+
+  return {
+    /**
+     * Captures an analytics event
+     * @param {string} event - Event name to track
+     * @param {Object} [properties={}] - Event properties and user identification
+     * @param {string} [properties.email] - User email (used for distinct ID)
+     * @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
+     */
+    capture(event, properties = {}) {
+      if (!trackEvents) return
+      const { email, userId, context, ...rest } = properties
+
+      const distinctId = getDistinctId({ email, userId, context, framework })
+
+      const data = omitEmpty({ event, distinctId, ...rest })
+      return client.capture(data)
+    },
+
+    /**
+     * 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
+     */
+    setPersonProperties(set = {}, once = {}) {
+      if (!trackEvents) return
+      return client.capture({
+        event: '$set',
+        properties: omitEmpty({
+          $set: set,
+          $set_once: once,
+        }),
+      })
+    },
+
+    /**
+     * 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
+     */
+    removePersonProperties(properties) {
+      if (!trackEvents) return
+      return client.capture({
+        event: '$unset',
+        properties: {
+          $unset: properties,
+        },
+      })
+    },
+
+    // identify(distinctId, properties = {}) {
+    //   return client.identify({ distinctId, properties })
+    // },
+
+    // alias(alias, distinctId) {
+    //   return client.alias({ alias, distinctId })
+    // },
+
+    // // Not sure about this yet
+    // group(groupType, groupKey, properties = {}) {
+    //   return client.group({ groupType, groupKey, properties })
+    // },
+
+    /**
+     * Shuts down the PostHog client and flushes any pending events
+     * @return {Promise} Promise that resolves when shutdown is complete
+     */
+    shutdown() {
+      return client.shutdown()
+    },
+  }
+}

package/lib/posthog/readme.md

@@ -0,0 +1,17 @@
+Ok. This is quite complex. So let's break it down.
+
+This package assumes you're using Posthog for both web and node.js.
+
+## Initializing
+
+## Steps
+
+1. Init on frontend — everywhere. This will allow posthog to track via their web sdk.
+2. On the backend — use ph.capture as necessary.
+3. When user logs in, or when you have a way to identify the user, use ph.identify on the frontend. (Don't identify on the backend).
+4. No need to alias. ph will replace merge any new `distinct_id` with the one you provided, if any.
+
+## Couple of enhancements
+
+- Get distinct_id from cookies on the backend automatically when using Astro — just provide context.
+- Use `trackEvents:false` to disable tracking completely when developing.

package/lib/posthog/web.js

@@ -0,0 +1,79 @@
+import { getCookie } from '@splendidlabz/utils/dom'
+import posthog from 'posthog-js'
+
+/**
+ * Creates a PostHog wrapper for web browser tracking
+ * @param {object} config - Configuration object
+ * @param {string} config.apiKey - PostHog API key
+ * @param {string} config.host - PostHog host URL
+ * @param {boolean} [config.trackEvents=true] - Whether to track events. Set to false in development mode to avoid sending events to PostHog.
+ * @returns {object} PostHog wrapper object with tracking methods
+ */
+export default function (config = {}) {
+  const { apiKey, host, trackEvents = true, ...rest } = config
+  const cookieName = `ph_${apiKey}_posthog`
+
+  return {
+    ...posthog,
+
+    /**
+     * Initialize PostHog tracking
+     * @returns {void}
+     */
+    init() {
+      if (!trackEvents) return
+      posthog.init(apiKey, {
+        api_host: host,
+        ...rest,
+      })
+    },
+
+    /**
+     * Capture a tracking event
+     * @param {string} event - Name of the event to track
+     * @param {object} [properties={}] - Event properties to send
+     * @returns {void}
+     */
+    capture(event, properties = {}) {
+      if (!trackEvents) return
+      return posthog.capture(event, properties)
+    },
+
+    /**
+     * Set properties for the current person
+     * @param {...any} props - Properties to set for the person
+     * @returns {void}
+     */
+    setPersonProperties(set = {}, once = {}) {
+      if (!trackEvents) return
+      return posthog.setPersonProperties(set, once)
+    },
+
+    /**
+     * @param {string} distinctId - New unique identifier for the user (email, userId, etc.)
+     * @param {object} properties - The properties to set for the user
+     * @returns {void}
+     */
+    identify(distinctId, properties = {}) {
+      if (!trackEvents) return
+      const cookie = getCookie(cookieName)
+      const existingId = cookie?.distinct_id
+
+      if (existingId !== distinctId) {
+        return posthog.identify(distinctId, properties)
+      } else {
+        return this.setPersonProperties(properties)
+      }
+    },
+
+    /**
+     * @param {string} distinctId - New unique identifier for the user
+     * @param {string} aliasId - Alias for the user
+     * @returns {void}
+     */
+    alias(distinctId, aliasId) {
+      if (!trackEvents) return
+      return posthog.alias(distinctId, aliasId)
+    },
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splendidlabz/tracking",
-  "version": "0.1.22",
+  "version": "0.2.0",
   "description": "Simple Tracking Helper",
   "type": "module",
   "files": [
@@ -20,17 +20,17 @@
   },
   "author": "Zell Liew <zellwk@gmail.com> (https://zellwk.com/)",
   "dependencies": {
-    "@splendidlabz/utils": "1.5.1",
+    "@splendidlabz/utils": "1.6.0",
     "posthog-js": "^1.234.6",
-    "posthog-node": "^3.6.3",
+    "posthog-node": "^5.5.1",
     "zl-fetch": "^6.0.6"
   },
   "devDependencies": {
-    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
-    "jsdom": "^24.0.0",
+    "jsdom": "^26.1.0",
     "np": "^10.2.0",
-    "rollup": "^4.39.0",
+    "rollup": "^4.45.1",
     "rollup-plugin-commonjs": "^10.1.0",
     "rollup-plugin-filesize": "^10.0.0",
     "vitest": "^3.1.1"