saasco-sdk 0.1.21 → 0.1.23

package/README.md

@@ -54,7 +54,7 @@ You can also [manually track pages](https://www.notion.so/Manual-Page-Tracking-i
 
 ## Tracking Events
 
-With events you can track custom actions users are taking on your site with event properties.
+With events you can track custom actions users are taking on your site with event properties. The track method supports both client-side (oarameter-style) and server-side (object-style) usage patterns.
 
 Each event has 2 components:
 
@@ -66,6 +66,11 @@ _We like to follow segments [Object Action Framework](https://segment.com/academ
 
 We currently have limited support for properties, but in the future we will support complex querying and actions based on event properties.
 
+### Client Usage
+
+For client-side tracking, use the Segment-compatible syntax.
+This will automatically assign userId based on identify calls during the session
+
 ```tsx
 // Import saasco
 import { saasco } from '../lib/saasco.ts';
@@ -80,6 +85,24 @@ saasco.track("Searched Movies", {
 });
 ```
 
+### Server Usage (Object Style)
+
+For server-side tracking, use the object-style syntax.
+You must provide a userId for server side tracking events.
+
+```tsx
+// Import saasco
+import { saasco } from '../lib/saasco.ts';
+
+// Track an event with full control
+saasco.track({
+  event: "User Signed Up",
+  userId: "user_123",
+  properties: { plan: "Pro" },
+  context: { source: "server" },
+});
+```
+
 ## Identifying Users
 
 By default Saasco does not track any identifiable data about users, just anonymous user ids and session ids. However if you want to tie events to users you can identify users which will connect events to users in your CRM and power tools like drip campaigns and customer support.

package/index.cjs.js

@@ -6,7 +6,7 @@ var tslib = require('tslib');
 var uuid = require('@lukeed/uuid');
 var zod = require('zod');
 
-var version = "0.1.21";
+var version = "0.1.23";
 
 const timezones = {
   'Asia/Barnaul': 'RU',
@@ -469,6 +469,7 @@ function getBrowserContext() {
 }
 
 const isBrowser = typeof window !== 'undefined';
+const isServer = !isBrowser;
 const PREF = 'saasco-sdk';
 const data = {};
 function storeData(key, value, ttl) {
@@ -476,7 +477,7 @@ function storeData(key, value, ttl) {
     value,
     expiry: new Date().getTime() + ttl
   };
-  if (!isBrowser) {
+  if (isServer) {
     if (value === undefined) {
       delete data[key];
       return;
@@ -489,7 +490,7 @@ function storeData(key, value, ttl) {
   localStorage.setItem(fullKey, JSON.stringify(item));
 }
 function retrieveData(key) {
-  if (!isBrowser) {
+  if (isServer) {
     const item = data[key];
     if (!item) return null;
     if (Date.now() > item.expiry) {
@@ -592,37 +593,46 @@ class Saasco {
     this.config.debug = true;
     this.log('Debug mode activated.');
   }
-  /**
-   * The track method lets you record the actions your users perform.
-   * Its good to keep a conistent naming convention for your events.
-   * We like the Object Action Framework from segment:
-   * https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/
-   *
-   * @param name The name of the event eg "Song Played"
-   * @param properties The properties of the event eg { genre: "Classics", song: "Never Gonna Give You Up" }
-   */
-  track(name,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  properties, context) {
+  track(actionOrPayload, propertiesOrNothing, contextOrNothing) {
     if (!this.config.projectId) {
       const response = this.error("Unable to track event. Project ID is required but has not been provided. If you are using an env variable make sure it's set correctly.");
       return Promise.resolve(response);
     }
     setSessionId();
     setAnonmousId();
-    const browserContext = getBrowserContext();
+    const hasAction = typeof actionOrPayload === 'string';
+    const hasPayload = typeof actionOrPayload === 'object';
+    // Must do payload on the server
+    if (isServer && hasAction) {
+      const response = this.error('When calling track from the server you must pass a payload object with a userId in order to track events. For example: track({ event: "Song Played", userId: "user_123", properties: { song: "Song Name" } })');
+      return Promise.resolve(response);
+    }
+    // On server events we require a userId or an anonymousId
+    if (isServer && hasPayload && !actionOrPayload.userId && !actionOrPayload.anonymousId) {
+      const response = this.error('When calling track from the server you must pass a payload object with either a userId or an anonymousId in order to track events. For example:\n\ntrack({ event: "Song Played", userId: "user_123", properties: { song: "Song Name" } }). \n\nIf providing an anonymousId this must be provided from the client side otherwise we will not have a user to connect the event to.');
+      return Promise.resolve(response);
+    }
+    const action = hasAction ? actionOrPayload : actionOrPayload.event;
+    const properties = hasAction ? propertiesOrNothing : actionOrPayload.properties;
+    const context = hasAction ? contextOrNothing : actionOrPayload.context;
+    const sessionId = (hasAction ? undefined : actionOrPayload.sessionId) || getSessionId();
+    const anonymousId = (hasAction ? undefined : actionOrPayload.anonymousId) || getAnonymousId();
+    const distinctId = (hasAction ? undefined : actionOrPayload.userId) || getUserId();
+    // Only gets browser context if in the browser
+    const browserContext = isBrowser ? getBrowserContext() || {} : {};
     const data = {
       id: uuid.v4(),
       timestamp: new Date().toISOString(),
-      action: name,
+      action,
       version,
-      sessionId: getSessionId(),
-      anonymousId: getAnonymousId(),
-      distinctId: getUserId(),
+      sessionId,
+      anonymousId,
+      distinctId,
       projectId: this.config.projectId,
-      payload: JSON.stringify(Object.assign(Object.assign({}, browserContext || {}), {
+      payload: JSON.stringify(Object.assign(Object.assign({}, browserContext), {
         properties: properties || {}
       })),
+      source: isBrowser ? 'client' : 'server',
       context: JSON.stringify(context || {})
     };
     return this.doRequest('events', data);
@@ -635,7 +645,7 @@ class Saasco {
    */
   page() {
     var _a, _b;
-    if (!isBrowser) {
+    if (isServer) {
       console.warn('Saasco page tracking is only available in the browser');
       return;
     }
@@ -782,7 +792,7 @@ class Saasco {
     // Disable auto page tracking if the config is set to false
     if (!((_a = this.config.autoPageTracking) === null || _a === void 0 ? void 0 : _a.enabled)) return;
     // Prevent running on the server
-    if (!isBrowser) return console.warn('Saasco auto page tracking is only available in the browser');
+    if (isServer) return console.warn('Saasco auto page tracking is only available in the browser');
     // Prevent intitializing auto page tracking more than once
     if (window.saascoAutoPageTrackingActive) {
       this.log('Auto Page Tracking already enabled');

package/index.esm.js

@@ -2,7 +2,7 @@ import { __awaiter } from 'tslib';
 import { v4 } from '@lukeed/uuid';
 import { z } from 'zod';
 
-var version = "0.1.21";
+var version = "0.1.23";
 
 const timezones = {
   'Asia/Barnaul': 'RU',
@@ -465,6 +465,7 @@ function getBrowserContext() {
 }
 
 const isBrowser = typeof window !== 'undefined';
+const isServer = !isBrowser;
 const PREF = 'saasco-sdk';
 const data = {};
 function storeData(key, value, ttl) {
@@ -472,7 +473,7 @@ function storeData(key, value, ttl) {
     value,
     expiry: new Date().getTime() + ttl
   };
-  if (!isBrowser) {
+  if (isServer) {
     if (value === undefined) {
       delete data[key];
       return;
@@ -485,7 +486,7 @@ function storeData(key, value, ttl) {
   localStorage.setItem(fullKey, JSON.stringify(item));
 }
 function retrieveData(key) {
-  if (!isBrowser) {
+  if (isServer) {
     const item = data[key];
     if (!item) return null;
     if (Date.now() > item.expiry) {
@@ -588,37 +589,46 @@ class Saasco {
     this.config.debug = true;
     this.log('Debug mode activated.');
   }
-  /**
-   * The track method lets you record the actions your users perform.
-   * Its good to keep a conistent naming convention for your events.
-   * We like the Object Action Framework from segment:
-   * https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/
-   *
-   * @param name The name of the event eg "Song Played"
-   * @param properties The properties of the event eg { genre: "Classics", song: "Never Gonna Give You Up" }
-   */
-  track(name,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  properties, context) {
+  track(actionOrPayload, propertiesOrNothing, contextOrNothing) {
     if (!this.config.projectId) {
       const response = this.error("Unable to track event. Project ID is required but has not been provided. If you are using an env variable make sure it's set correctly.");
       return Promise.resolve(response);
     }
     setSessionId();
     setAnonmousId();
-    const browserContext = getBrowserContext();
+    const hasAction = typeof actionOrPayload === 'string';
+    const hasPayload = typeof actionOrPayload === 'object';
+    // Must do payload on the server
+    if (isServer && hasAction) {
+      const response = this.error('When calling track from the server you must pass a payload object with a userId in order to track events. For example: track({ event: "Song Played", userId: "user_123", properties: { song: "Song Name" } })');
+      return Promise.resolve(response);
+    }
+    // On server events we require a userId or an anonymousId
+    if (isServer && hasPayload && !actionOrPayload.userId && !actionOrPayload.anonymousId) {
+      const response = this.error('When calling track from the server you must pass a payload object with either a userId or an anonymousId in order to track events. For example:\n\ntrack({ event: "Song Played", userId: "user_123", properties: { song: "Song Name" } }). \n\nIf providing an anonymousId this must be provided from the client side otherwise we will not have a user to connect the event to.');
+      return Promise.resolve(response);
+    }
+    const action = hasAction ? actionOrPayload : actionOrPayload.event;
+    const properties = hasAction ? propertiesOrNothing : actionOrPayload.properties;
+    const context = hasAction ? contextOrNothing : actionOrPayload.context;
+    const sessionId = (hasAction ? undefined : actionOrPayload.sessionId) || getSessionId();
+    const anonymousId = (hasAction ? undefined : actionOrPayload.anonymousId) || getAnonymousId();
+    const distinctId = (hasAction ? undefined : actionOrPayload.userId) || getUserId();
+    // Only gets browser context if in the browser
+    const browserContext = isBrowser ? getBrowserContext() || {} : {};
     const data = {
       id: v4(),
       timestamp: new Date().toISOString(),
-      action: name,
+      action,
       version,
-      sessionId: getSessionId(),
-      anonymousId: getAnonymousId(),
-      distinctId: getUserId(),
+      sessionId,
+      anonymousId,
+      distinctId,
       projectId: this.config.projectId,
-      payload: JSON.stringify(Object.assign(Object.assign({}, browserContext || {}), {
+      payload: JSON.stringify(Object.assign(Object.assign({}, browserContext), {
         properties: properties || {}
       })),
+      source: isBrowser ? 'client' : 'server',
       context: JSON.stringify(context || {})
     };
     return this.doRequest('events', data);
@@ -631,7 +641,7 @@ class Saasco {
    */
   page() {
     var _a, _b;
-    if (!isBrowser) {
+    if (isServer) {
       console.warn('Saasco page tracking is only available in the browser');
       return;
     }
@@ -778,7 +788,7 @@ class Saasco {
     // Disable auto page tracking if the config is set to false
     if (!((_a = this.config.autoPageTracking) === null || _a === void 0 ? void 0 : _a.enabled)) return;
     // Prevent running on the server
-    if (!isBrowser) return console.warn('Saasco auto page tracking is only available in the browser');
+    if (isServer) return console.warn('Saasco auto page tracking is only available in the browser');
     // Prevent intitializing auto page tracking more than once
     if (window.saascoAutoPageTrackingActive) {
       this.log('Auto Page Tracking already enabled');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasco-sdk",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "dependencies": {
     "tslib": "^2.3.0",
     "@lukeed/uuid": "^2.0.1",

package/src/lib/analytics.d.ts

@@ -4,6 +4,19 @@ declare global {
         saasco: Saasco;
     }
 }
+type Identity = {
+    userId: string | number;
+    anonymousId?: string | number;
+} | {
+    anonymousId: string | number;
+    userId?: string | number;
+};
+type TrackPayload = Identity & {
+    event: string;
+    sessionId?: string;
+    properties?: Record<string, any>;
+    context?: Record<string, any>;
+};
 type DoRequestResponse = {
     success: boolean;
     message: string;
@@ -38,17 +51,14 @@ export declare class Saasco {
     disableDebug(): void;
     enableDebug(): void;
     /**
-     * The track method lets you record the actions your users perform.
-     * Its good to keep a conistent naming convention for your events.
-     * We like the Object Action Framework from segment:
-     * https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/
-     *
-     * @param name The name of the event eg "Song Played"
-     * @param properties The properties of the event eg { genre: "Classics", song: "Never Gonna Give You Up" }
+     * Track events with support for both client (Segment-style) and server (object-style) usage
+     * Client: track('User Signed Up', { plan: 'Pro' }, { source: 'client' })
+     * Server: track({ event: 'User Signed Up', userId: 'user_123', properties: { plan: 'Pro' } })
      */
-    track(name: string, properties?: Record<string, any>, context?: {
+    track(action: string, properties?: Record<string, any>, context?: {
         active?: boolean;
     }): Promise<DoRequestResponse>;
+    track(payload: TrackPayload): Promise<DoRequestResponse>;
     /**
      * The page method lets you record page views on your website
      * This records the page title and path and names the event useing the reserved property "Page Viewed"