saasco-sdk 0.1.15 → 0.1.17

package/README.md

@@ -35,22 +35,23 @@ export const saasco = new Saasco({ projectId: 'YOUR-PROJECT-ID' });
 
 ## Automatic Page View Tracking
 
-When you initiate the lib Saasco will automatically start tracking all page views in your app. By default, it tracks all URL changes, including query parameters and hash changes. You can customize this behavior using the configuration options:
-
-- `autoPageTracking` (default: `true`): When set to `false`, will not automatically track any `Page View` events.
-- `trackUrlParams` (default: `true`): When set to `false`, changes to URL query parameters won't trigger a new page view
-- `trackHashChanges` (default: `true`): When set to `false`, changes to URL hash won't trigger a new page view
-
-You can also [manually track pages](https://www.notion.so/Manual-Page-Tracking-in-SPAs-2442fc7586dc4208ae8f669eb7561b1a?pvs=21) by opting out of automatic page tracking. For most use cases you don't need to do this.
-
-```ts
-// ./app/index
-import saasco from './lib/saasco';
+When you initiate the lib Saasco will automatically start tracking all page views in your app. By default, it tracks all URL changes, including query parameters and hash changes. You can customize this behavior using the `autoPageTracking` configuration object:
+
+```typescript
+const analytics = new Saasco({
+  projectId: 'your-project-id',
+  autoPageTracking: {
+    enabled: true, // Set to false to disable automatic page tracking
+    trackQueryParams: true, // Set to false to ignore URL query parameter changes
+    trackHash: true, // Set to false to ignore URL hash changes
+  },
+});
 
-// This should be called once in your app and will start auto page tracking if you have it enabled.
-saasco.init();
+analytics.init();
 ```
 
+You can also [manually track pages](https://www.notion.so/Manual-Page-Tracking-in-SPAs-2442fc7586dc4208ae8f669eb7561b1a?pvs=21) by disabling automatic page tracking (`enabled: false`). For most use cases you don't need to do this.
+
 ## Tracking Events
 
 With events you can track custom actions users are taking on your site with event properties.

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.15";
+var version = "0.1.17";
 
 const timezones = {
   'Asia/Barnaul': 'RU',
@@ -562,9 +562,12 @@ class Saasco {
     }
     // default enabled to true
     this.config.enabled = this.config.enabled === undefined ? true : this.config.enabled;
-    // default URL tracking options
-    this.config.trackUrlParams = this.config.trackUrlParams === undefined ? true : this.config.trackUrlParams;
-    this.config.trackHashChanges = this.config.trackHashChanges === undefined ? true : this.config.trackHashChanges;
+    // Set default auto page tracking config
+    this.config.autoPageTracking = Object.assign({
+      enabled: true,
+      trackQueryParams: true,
+      trackHash: true
+    }, this.config.autoPageTracking);
   }
   init() {
     if (this.isInitialized) {
@@ -600,7 +603,8 @@ class Saasco {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   properties, context) {
     if (!this.config.projectId) {
-      return 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.");
+      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();
@@ -628,6 +632,7 @@ class Saasco {
    * Before implementing this make sure you have disabled the autoPageTracking in the config or you will get duplicate page views
    */
   page() {
+    var _a, _b;
     if (!isBrowser) {
       console.warn('Saasco page tracking is only available in the browser');
       return;
@@ -635,11 +640,11 @@ class Saasco {
     const url = new URL(window.location.href);
     let pathToCompare = url.pathname;
     // Include search params if configured
-    if (this.config.trackUrlParams) {
+    if ((_a = this.config.autoPageTracking) === null || _a === void 0 ? void 0 : _a.trackQueryParams) {
       pathToCompare += url.search;
     }
     // Include hash if configured
-    if (this.config.trackHashChanges) {
+    if ((_b = this.config.autoPageTracking) === null || _b === void 0 ? void 0 : _b.trackHash) {
       pathToCompare += url.hash;
     }
     // Only track if the path has changed
@@ -649,7 +654,8 @@ class Saasco {
   }
   identify(distinctIdOrProperties, propertiesOrContext, contextOrNothing) {
     if (!this.config.projectId) {
-      return this.error("Unable to identify user. Project ID is required but has not been provided. If you are using an env variable make sure it's set correctly.");
+      const response = this.error("Unable to identify user. 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);
     }
     const hasId = typeof distinctIdOrProperties === 'string' || typeof distinctIdOrProperties === 'number' || distinctIdOrProperties === null;
     const distinctId = hasId ? distinctIdOrProperties === null || distinctIdOrProperties === void 0 ? void 0 : distinctIdOrProperties.toString() : `soft_${uuid.v4()}`;
@@ -670,7 +676,10 @@ class Saasco {
     // set the distinct Id to the userId
     setUserId(distinctId);
     // No distinctId provided so we don't track the user
-    if (!distinctId) return;
+    if (!distinctId) return Promise.resolve({
+      success: false,
+      message: 'No distinctId provided'
+    });
     const data = {
       id: uuid.v4(),
       timestamp: new Date().toISOString(),
@@ -697,7 +706,10 @@ class Saasco {
       : data.action || path;
       this.log(logMessage, data);
       // If analytics is disabled, don't send the request
-      if (this.config.enabled === false) return;
+      if (this.config.enabled === false) return {
+        success: false,
+        message: 'Analytics is disabled'
+      };
       try {
         const response = yield fetch(url, {
           method: 'POST',
@@ -706,14 +718,20 @@ class Saasco {
           },
           body: JSON.stringify(data)
         });
+        const responseBody = yield response.json();
         if (!response.ok) {
-          const errorBody = yield response.json();
-          throw new Error(`${errorBody.message}: ${errorBody.errors ? `[${errorBody.errors.join(', ')}]` : ''}` || JSON.stringify(errorBody));
+          throw new Error(`${responseBody.message}: ${responseBody.errors ? `[${responseBody.errors.join(', ')}]` : ''}` || JSON.stringify(responseBody));
         }
-        return response;
+        return {
+          success: true,
+          message: responseBody.message
+        };
       } catch (error) {
         this.error(`\nError Message: "${error.message}"`, `\nPath: "/${path}"`, `\nRequest Data: ${JSON.stringify(data, null, 2)}`);
-        return error.message;
+        return {
+          success: false,
+          message: error.message
+        };
       }
     });
   }
@@ -735,6 +753,10 @@ class Saasco {
     console.error(...[`\x1b[41m\x1b[37m ${message} \x1b[0m`,
     // Message highlighted for easy finding
     ...args]);
+    return {
+      success: false,
+      message: args.join(' ')
+    };
   }
   /**
    * If autoPageTracking is enabled, this will automatically track page views
@@ -742,9 +764,9 @@ class Saasco {
    * @returns
    */
   initiAutoPageTracking() {
+    var _a, _b;
     // Disable auto page tracking if the config is set to false
-    // Will run if undefined or true
-    if (this.config.autoPageTracking === false) return;
+    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');
     // Prevent intitializing auto page tracking more than once
@@ -756,8 +778,10 @@ class Saasco {
     this.log('Auto Page Tracking enabled');
     // Track initial page load
     this.page();
-    // Listen for hash changes
-    window.addEventListener('hashchange', () => this.page());
+    // Listen for hash changes if hash tracking is enabled
+    if ((_b = this.config.autoPageTracking) === null || _b === void 0 ? void 0 : _b.trackHash) {
+      window.addEventListener('hashchange', () => this.page());
+    }
     // Listen to popstate for back and forward navigation
     window.addEventListener('popstate', () => this.page());
     // Wrap history push state to listen for URL changes

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.15";
+var version = "0.1.17";
 
 const timezones = {
   'Asia/Barnaul': 'RU',
@@ -558,9 +558,12 @@ class Saasco {
     }
     // default enabled to true
     this.config.enabled = this.config.enabled === undefined ? true : this.config.enabled;
-    // default URL tracking options
-    this.config.trackUrlParams = this.config.trackUrlParams === undefined ? true : this.config.trackUrlParams;
-    this.config.trackHashChanges = this.config.trackHashChanges === undefined ? true : this.config.trackHashChanges;
+    // Set default auto page tracking config
+    this.config.autoPageTracking = Object.assign({
+      enabled: true,
+      trackQueryParams: true,
+      trackHash: true
+    }, this.config.autoPageTracking);
   }
   init() {
     if (this.isInitialized) {
@@ -596,7 +599,8 @@ class Saasco {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   properties, context) {
     if (!this.config.projectId) {
-      return 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.");
+      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();
@@ -624,6 +628,7 @@ class Saasco {
    * Before implementing this make sure you have disabled the autoPageTracking in the config or you will get duplicate page views
    */
   page() {
+    var _a, _b;
     if (!isBrowser) {
       console.warn('Saasco page tracking is only available in the browser');
       return;
@@ -631,11 +636,11 @@ class Saasco {
     const url = new URL(window.location.href);
     let pathToCompare = url.pathname;
     // Include search params if configured
-    if (this.config.trackUrlParams) {
+    if ((_a = this.config.autoPageTracking) === null || _a === void 0 ? void 0 : _a.trackQueryParams) {
       pathToCompare += url.search;
     }
     // Include hash if configured
-    if (this.config.trackHashChanges) {
+    if ((_b = this.config.autoPageTracking) === null || _b === void 0 ? void 0 : _b.trackHash) {
       pathToCompare += url.hash;
     }
     // Only track if the path has changed
@@ -645,7 +650,8 @@ class Saasco {
   }
   identify(distinctIdOrProperties, propertiesOrContext, contextOrNothing) {
     if (!this.config.projectId) {
-      return this.error("Unable to identify user. Project ID is required but has not been provided. If you are using an env variable make sure it's set correctly.");
+      const response = this.error("Unable to identify user. 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);
     }
     const hasId = typeof distinctIdOrProperties === 'string' || typeof distinctIdOrProperties === 'number' || distinctIdOrProperties === null;
     const distinctId = hasId ? distinctIdOrProperties === null || distinctIdOrProperties === void 0 ? void 0 : distinctIdOrProperties.toString() : `soft_${v4()}`;
@@ -666,7 +672,10 @@ class Saasco {
     // set the distinct Id to the userId
     setUserId(distinctId);
     // No distinctId provided so we don't track the user
-    if (!distinctId) return;
+    if (!distinctId) return Promise.resolve({
+      success: false,
+      message: 'No distinctId provided'
+    });
     const data = {
       id: v4(),
       timestamp: new Date().toISOString(),
@@ -693,7 +702,10 @@ class Saasco {
       : data.action || path;
       this.log(logMessage, data);
       // If analytics is disabled, don't send the request
-      if (this.config.enabled === false) return;
+      if (this.config.enabled === false) return {
+        success: false,
+        message: 'Analytics is disabled'
+      };
       try {
         const response = yield fetch(url, {
           method: 'POST',
@@ -702,14 +714,20 @@ class Saasco {
           },
           body: JSON.stringify(data)
         });
+        const responseBody = yield response.json();
         if (!response.ok) {
-          const errorBody = yield response.json();
-          throw new Error(`${errorBody.message}: ${errorBody.errors ? `[${errorBody.errors.join(', ')}]` : ''}` || JSON.stringify(errorBody));
+          throw new Error(`${responseBody.message}: ${responseBody.errors ? `[${responseBody.errors.join(', ')}]` : ''}` || JSON.stringify(responseBody));
         }
-        return response;
+        return {
+          success: true,
+          message: responseBody.message
+        };
       } catch (error) {
         this.error(`\nError Message: "${error.message}"`, `\nPath: "/${path}"`, `\nRequest Data: ${JSON.stringify(data, null, 2)}`);
-        return error.message;
+        return {
+          success: false,
+          message: error.message
+        };
       }
     });
   }
@@ -731,6 +749,10 @@ class Saasco {
     console.error(...[`\x1b[41m\x1b[37m ${message} \x1b[0m`,
     // Message highlighted for easy finding
     ...args]);
+    return {
+      success: false,
+      message: args.join(' ')
+    };
   }
   /**
    * If autoPageTracking is enabled, this will automatically track page views
@@ -738,9 +760,9 @@ class Saasco {
    * @returns
    */
   initiAutoPageTracking() {
+    var _a, _b;
     // Disable auto page tracking if the config is set to false
-    // Will run if undefined or true
-    if (this.config.autoPageTracking === false) return;
+    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');
     // Prevent intitializing auto page tracking more than once
@@ -752,8 +774,10 @@ class Saasco {
     this.log('Auto Page Tracking enabled');
     // Track initial page load
     this.page();
-    // Listen for hash changes
-    window.addEventListener('hashchange', () => this.page());
+    // Listen for hash changes if hash tracking is enabled
+    if ((_b = this.config.autoPageTracking) === null || _b === void 0 ? void 0 : _b.trackHash) {
+      window.addEventListener('hashchange', () => this.page());
+    }
     // Listen to popstate for back and forward navigation
     window.addEventListener('popstate', () => this.page());
     // Wrap history push state to listen for URL changes

package/package.json

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

package/src/lib/analytics.d.ts

@@ -4,6 +4,10 @@ declare global {
         saasco: Saasco;
     }
 }
+type DoRequestResponse = {
+    success: boolean;
+    message: string;
+};
 export declare class Saasco {
     private config;
     private lastPageViewPath;
@@ -22,11 +26,13 @@ export declare class Saasco {
     constructor(config: {
         projectId: string;
         proxy?: string;
-        autoPageTracking?: boolean;
+        autoPageTracking?: {
+            enabled: boolean;
+            trackQueryParams?: boolean;
+            trackHash?: boolean;
+        };
         enabled?: boolean;
         debug?: boolean;
-        trackUrlParams?: boolean;
-        trackHashChanges?: boolean;
     });
     init(): void;
     disableDebug(): void;
@@ -42,14 +48,14 @@ export declare class Saasco {
      */
     track(name: string, properties?: Record<string, any>, context?: {
         active?: boolean;
-    }): void | Promise<any>;
+    }): 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"
      *
      * Before implementing this make sure you have disabled the autoPageTracking in the config or you will get duplicate page views
      */
-    page(): void | Promise<any>;
+    page(): Promise<DoRequestResponse> | undefined;
     /**
      * The identify method lets you tie a user to their actions and record traits about them.
      * We recommend you call this when the user logs in and when any traits get updated.
@@ -61,10 +67,10 @@ export declare class Saasco {
      */
     identify(properties: Record<string, any>, context?: {
         active?: boolean;
-    }): void;
+    }): Promise<DoRequestResponse>;
     identify(distinctId: string | number | null, properties?: Record<string, any>, context?: {
         active?: boolean;
-    }): void;
+    }): Promise<DoRequestResponse>;
     /**
      * Handles sending data to the Saasco API
      * If you have a proxy set up, it will send the data to the proxy and you can handle forawrding the data to the Saasco events API
@@ -87,3 +93,4 @@ export declare class Saasco {
      */
     private initiAutoPageTracking;
 }
+export {};