saasco-sdk 0.1.9 → 0.1.11

package/README.md

@@ -4,7 +4,7 @@
 
 - [Privacy](#privacy)
 - [Getting Started](#initiate-the-lib)
-- [Automatic Page View Tracking](#automatic-page-view-tracking)
+- [Init Automatic Page View Tracking](#init-automatic-page-view-tracking)
 - [Tracking Events](#tracking-events)
 - [Identifying Users](#identifying-users)
 - [Debugging and Dev](#debugging-and-dev)
@@ -27,22 +27,25 @@ Copy your Project ID from the project settings page in Saasco:
 Then import Saasco and initiate the lib with your Project ID.
 
 ```ts
-
 // lib/saasco.ts
 import { Saasco } from 'saasco-sdk';
 
-// Initiate the lib
-const saasco = new Saasco({ projectId: "YOUR-PROJECT-ID" });
-saasco.init();
-
-export saasco;
+export const saasco = new Saasco({ projectId: 'YOUR-PROJECT-ID' });
 ```
 
-## Automatic Page View Tracking
+## Init Automatic Page View Tracking
 
-When you initial the lib live above Saasco will automatically start tracking all page views in your app. There is no other configuration. It will automatically track url changes, even for SPAs like NextJs and Vue.
+When you initial the lib Saasco will automatically start tracking all page views in your app. There is no other configuration. It will automatically track url changes, even for SPAs like NextJs and Vue.
 You can also [manually track pages](https://www.notion.so/Manual-Page-Tracking-in-SPAs-2442fc7586dc4208ae8f669eb7561b1a?pvs=21) by opting our of automatic page tracking. For most use cases you don't need to do this.
 
+```ts
+// ./app/index
+import saasco from './lib/saasco';
+
+// This should be called once in your app and will start auto page tracking if you have it enabled.
+saasco.init();
+```
+
 ## Tracking Events
 
 With events you can track custom actions users are taking on your site with event properties.

package/index.cjs.js

@@ -434,6 +434,8 @@ const timezones = {
   'Asia/Calcutta': 'IN'
 };
 
+var version = "0.1.11";
+
 const isBrowser = typeof window !== 'undefined';
 let userId = null;
 const PREF = 'saasco-sdk';
@@ -553,13 +555,21 @@ class Saasco {
       this.log('Saasco is already initialized. Please check your code to ensure that init() is not being called multiple times.');
       return;
     }
+    // Export Saasco to the window object for easy access and debugging
+    if (isBrowser) {
+      window.saasco = this;
+    }
     this.log('Saasco initialized', this.config);
     this.initiAutoPageTracking();
     this.isInitialized = true;
   }
-  debug(value) {
-    this.config.debug = value;
-    this.log(`Debug mode ${value ? 'activated' : 'deactivated'}.`);
+  disableDebug() {
+    this.log('Debug mode deactivated.');
+    this.config.debug = false;
+  }
+  enableDebug() {
+    this.config.debug = true;
+    this.log('Debug mode activated.');
   }
   /**
    * The track method lets you record the actions your users perform.
@@ -590,7 +600,7 @@ class Saasco {
       id: uuid.v4(),
       timestamp: new Date().toISOString(),
       action: name,
-      version: '2',
+      version,
       sessionId: getSessionId(),
       anonymousId: getAnonymousId(),
       distinctId: userId,
@@ -619,12 +629,9 @@ class Saasco {
     // When the user gets identified as null this will reset the users session and anonymous id
     // This should only be called when distinctId is null and there is an existing userId.
     // This means the user has logged out and we should reset the session and anonymous IDs
-    const userIdChangedToNull = !distinctId && !!userId;
+    const userIdChangedToNull = distinctId === null && !!userId;
     if (userIdChangedToNull) this.log('User ID change to null. Session reset');
-    // If we have a userId, but a new user ID is provided, we should reset the session and anonymous IDs
-    const userIdChanged = !!userId && distinctId !== userId;
-    if (userIdChanged) this.log('User ID changed. Session reset');
-    const reset = userIdChangedToNull || userIdChanged;
+    const reset = userIdChangedToNull;
     setSessionId({
       reset
     });
@@ -641,7 +648,7 @@ class Saasco {
       projectId: this.config.projectId,
       distinctId,
       anonymousId,
-      version: '2',
+      version,
       payload: properties || {},
       context: context || {}
     };
@@ -791,8 +798,15 @@ function coerceReservedProperties(properties) {
   }) => {
     const coercedValue = coerceValue(properties, coerceFrom, schema);
     if (coercedValue) acc[key] = coercedValue;
-    if (!coercedValue && key === 'displayName' && acc['firstName']) {
-      const displayName = `${acc['firstName'] || ''} ${acc['lastName'] || ''}`.trim();
+    if (!coercedValue && key === 'displayName') {
+      let displayName = '';
+      if (acc['firstName']) {
+        displayName = `${acc['firstName'] || ''} ${acc['lastName'] || ''}`.trim();
+      } else if (acc['username'] && typeof acc['username'] === 'string') {
+        displayName = acc['username'];
+      } else if (acc['name'] && typeof acc['name'] === 'string') {
+        displayName = acc['name'];
+      }
       if (displayName) acc[key] = displayName;
     }
     return acc;
@@ -885,16 +899,17 @@ const kpisRequestSchema = zod.z.object({
   referrer: zod.z.string().optional(),
   location: zod.z.string().optional()
 });
+const kpiSchema = zod.z.object({
+  date: zod.z.string(),
+  users: zod.z.number(),
+  sessions: zod.z.number(),
+  pageViews: zod.z.number(),
+  events: zod.z.number(),
+  bounceRate: zod.z.nullable(zod.z.number()),
+  avgSessionSec: zod.z.number()
+});
 const kpisResponseSchema = tinyBirdBaseSchema.extend({
-  data: zod.z.array(zod.z.object({
-    date: zod.z.string(),
-    users: zod.z.number(),
-    sessions: zod.z.number(),
-    pageViews: zod.z.number(),
-    events: zod.z.number(),
-    bounceRate: zod.z.nullable(zod.z.number()),
-    avgSessionSec: zod.z.number()
-  }))
+  data: zod.z.array(kpiSchema)
 });
 const baseTopRequestSchema = zod.z.object({
   projectId: zod.z.string(),
@@ -964,7 +979,7 @@ const analyticsEventSchema = zod.z.object({
   projectId: zod.z.string(),
   anonymousId: zod.z.string(),
   sessionId: zod.z.string(),
-  distinctId: zod.z.string().optional(),
+  distinctId: zod.z.string().nullable(),
   version: zod.z.string(),
   action: zod.z.string(),
   payload: zod.z.string()
@@ -974,7 +989,7 @@ const userEventsResponseSchema = tinyBirdBaseSchema.extend({
 });
 const currentUsersRequestSchema = zod.z.object({
   projectId: zod.z.string(),
-  minutes: zod.z.number().optional(),
+  minutes: zod.z.number(),
   referrer: zod.z.string().optional(),
   location: zod.z.string().optional()
 });
@@ -1057,6 +1072,7 @@ exports.currentUsersRequestSchema = currentUsersRequestSchema;
 exports.currentUsersResponseSchema = currentUsersResponseSchema;
 exports.getAnalyticsUserParamsSchema = getAnalyticsUserParamsSchema;
 exports.idenfitySchema = idenfitySchema;
+exports.kpiSchema = kpiSchema;
 exports.kpisRequestSchema = kpisRequestSchema;
 exports.kpisResponseSchema = kpisResponseSchema;
 exports.latestEventItemSchema = latestEventItemSchema;

package/index.esm.js

@@ -430,6 +430,8 @@ const timezones = {
   'Asia/Calcutta': 'IN'
 };
 
+var version = "0.1.11";
+
 const isBrowser = typeof window !== 'undefined';
 let userId = null;
 const PREF = 'saasco-sdk';
@@ -549,13 +551,21 @@ class Saasco {
       this.log('Saasco is already initialized. Please check your code to ensure that init() is not being called multiple times.');
       return;
     }
+    // Export Saasco to the window object for easy access and debugging
+    if (isBrowser) {
+      window.saasco = this;
+    }
     this.log('Saasco initialized', this.config);
     this.initiAutoPageTracking();
     this.isInitialized = true;
   }
-  debug(value) {
-    this.config.debug = value;
-    this.log(`Debug mode ${value ? 'activated' : 'deactivated'}.`);
+  disableDebug() {
+    this.log('Debug mode deactivated.');
+    this.config.debug = false;
+  }
+  enableDebug() {
+    this.config.debug = true;
+    this.log('Debug mode activated.');
   }
   /**
    * The track method lets you record the actions your users perform.
@@ -586,7 +596,7 @@ class Saasco {
       id: v4(),
       timestamp: new Date().toISOString(),
       action: name,
-      version: '2',
+      version,
       sessionId: getSessionId(),
       anonymousId: getAnonymousId(),
       distinctId: userId,
@@ -615,12 +625,9 @@ class Saasco {
     // When the user gets identified as null this will reset the users session and anonymous id
     // This should only be called when distinctId is null and there is an existing userId.
     // This means the user has logged out and we should reset the session and anonymous IDs
-    const userIdChangedToNull = !distinctId && !!userId;
+    const userIdChangedToNull = distinctId === null && !!userId;
     if (userIdChangedToNull) this.log('User ID change to null. Session reset');
-    // If we have a userId, but a new user ID is provided, we should reset the session and anonymous IDs
-    const userIdChanged = !!userId && distinctId !== userId;
-    if (userIdChanged) this.log('User ID changed. Session reset');
-    const reset = userIdChangedToNull || userIdChanged;
+    const reset = userIdChangedToNull;
     setSessionId({
       reset
     });
@@ -637,7 +644,7 @@ class Saasco {
       projectId: this.config.projectId,
       distinctId,
       anonymousId,
-      version: '2',
+      version,
       payload: properties || {},
       context: context || {}
     };
@@ -787,8 +794,15 @@ function coerceReservedProperties(properties) {
   }) => {
     const coercedValue = coerceValue(properties, coerceFrom, schema);
     if (coercedValue) acc[key] = coercedValue;
-    if (!coercedValue && key === 'displayName' && acc['firstName']) {
-      const displayName = `${acc['firstName'] || ''} ${acc['lastName'] || ''}`.trim();
+    if (!coercedValue && key === 'displayName') {
+      let displayName = '';
+      if (acc['firstName']) {
+        displayName = `${acc['firstName'] || ''} ${acc['lastName'] || ''}`.trim();
+      } else if (acc['username'] && typeof acc['username'] === 'string') {
+        displayName = acc['username'];
+      } else if (acc['name'] && typeof acc['name'] === 'string') {
+        displayName = acc['name'];
+      }
       if (displayName) acc[key] = displayName;
     }
     return acc;
@@ -881,16 +895,17 @@ const kpisRequestSchema = z.object({
   referrer: z.string().optional(),
   location: z.string().optional()
 });
+const kpiSchema = z.object({
+  date: z.string(),
+  users: z.number(),
+  sessions: z.number(),
+  pageViews: z.number(),
+  events: z.number(),
+  bounceRate: z.nullable(z.number()),
+  avgSessionSec: z.number()
+});
 const kpisResponseSchema = tinyBirdBaseSchema.extend({
-  data: z.array(z.object({
-    date: z.string(),
-    users: z.number(),
-    sessions: z.number(),
-    pageViews: z.number(),
-    events: z.number(),
-    bounceRate: z.nullable(z.number()),
-    avgSessionSec: z.number()
-  }))
+  data: z.array(kpiSchema)
 });
 const baseTopRequestSchema = z.object({
   projectId: z.string(),
@@ -960,7 +975,7 @@ const analyticsEventSchema = z.object({
   projectId: z.string(),
   anonymousId: z.string(),
   sessionId: z.string(),
-  distinctId: z.string().optional(),
+  distinctId: z.string().nullable(),
   version: z.string(),
   action: z.string(),
   payload: z.string()
@@ -970,7 +985,7 @@ const userEventsResponseSchema = tinyBirdBaseSchema.extend({
 });
 const currentUsersRequestSchema = z.object({
   projectId: z.string(),
-  minutes: z.number().optional(),
+  minutes: z.number(),
   referrer: z.string().optional(),
   location: z.string().optional()
 });
@@ -1041,4 +1056,4 @@ const latestIdentifiesResponseSchema = tinyBirdBaseSchema.extend({
   }))
 });
 
-export { Saasco, TinybirdJobResponseSchema, analyticsEventSchema, analyticsUserRawSchema, analyticsUserSchema, baseTopRequestSchema, coerceReservedProperties, contactPropertiesSchema, currentUsersRequestSchema, currentUsersResponseSchema, getAnalyticsUserParamsSchema, idenfitySchema, kpisRequestSchema, kpisResponseSchema, latestEventItemSchema, latestEventsRequestSchema, latestEventsResponseSchema, latestIdentifiesRequestSchema, latestIdentifiesResponseSchema, listUsersParamsSchema, reservedPropertiesSchema, tbAny, timezones, tinyBirdBaseSchema, topActionsResponseSchema, topBrowsersResponseSchema, topDevicesResponseSchema, topLocationsResponseSchema, topPagesResponseSchema, topSourcesResponseSchema, topSourcesSchema, userEventsResponseSchema };
+export { Saasco, TinybirdJobResponseSchema, analyticsEventSchema, analyticsUserRawSchema, analyticsUserSchema, baseTopRequestSchema, coerceReservedProperties, contactPropertiesSchema, currentUsersRequestSchema, currentUsersResponseSchema, getAnalyticsUserParamsSchema, idenfitySchema, kpiSchema, kpisRequestSchema, kpisResponseSchema, latestEventItemSchema, latestEventsRequestSchema, latestEventsResponseSchema, latestIdentifiesRequestSchema, latestIdentifiesResponseSchema, listUsersParamsSchema, reservedPropertiesSchema, tbAny, timezones, tinyBirdBaseSchema, topActionsResponseSchema, topBrowsersResponseSchema, topDevicesResponseSchema, topLocationsResponseSchema, topPagesResponseSchema, topSourcesResponseSchema, topSourcesSchema, userEventsResponseSchema };

package/package.json

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

package/src/lib/analytics.d.ts

@@ -24,7 +24,8 @@ export declare class Saasco {
         debug?: boolean;
     });
     init(): void;
-    debug(value: boolean): void;
+    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.

package/src/lib/types.d.ts

@@ -321,6 +321,32 @@ export declare const kpisRequestSchema: z.ZodObject<{
     dateFrom?: string | undefined;
 }>;
 export type KpisRequest = z.infer<typeof kpisRequestSchema>;
+export declare const kpiSchema: z.ZodObject<{
+    date: z.ZodString;
+    users: z.ZodNumber;
+    sessions: z.ZodNumber;
+    pageViews: z.ZodNumber;
+    events: z.ZodNumber;
+    bounceRate: z.ZodNullable<z.ZodNumber>;
+    avgSessionSec: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    date: string;
+    users: number;
+    sessions: number;
+    pageViews: number;
+    events: number;
+    bounceRate: number | null;
+    avgSessionSec: number;
+}, {
+    date: string;
+    users: number;
+    sessions: number;
+    pageViews: number;
+    events: number;
+    bounceRate: number | null;
+    avgSessionSec: number;
+}>;
+export type Kpi = z.infer<typeof kpiSchema>;
 export declare const kpisResponseSchema: z.ZodObject<z.objectUtil.extendShape<{
     meta: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -957,7 +983,7 @@ export declare const analyticsEventSchema: z.ZodObject<{
     projectId: z.ZodString;
     anonymousId: z.ZodString;
     sessionId: z.ZodString;
-    distinctId: z.ZodOptional<z.ZodString>;
+    distinctId: z.ZodNullable<z.ZodString>;
     version: z.ZodString;
     action: z.ZodString;
     payload: z.ZodString;
@@ -969,8 +995,8 @@ export declare const analyticsEventSchema: z.ZodObject<{
     action: string;
     anonymousId: string;
     sessionId: string;
+    distinctId: string | null;
     version: string;
-    distinctId?: string | undefined;
 }, {
     id: string;
     projectId: string;
@@ -979,8 +1005,8 @@ export declare const analyticsEventSchema: z.ZodObject<{
     action: string;
     anonymousId: string;
     sessionId: string;
+    distinctId: string | null;
     version: string;
-    distinctId?: string | undefined;
 }>;
 export type AnalyticsEvent = z.infer<typeof analyticsEventSchema>;
 export declare const userEventsResponseSchema: z.ZodObject<z.objectUtil.extendShape<{
@@ -1015,7 +1041,7 @@ export declare const userEventsResponseSchema: z.ZodObject<z.objectUtil.extendSh
         projectId: z.ZodString;
         anonymousId: z.ZodString;
         sessionId: z.ZodString;
-        distinctId: z.ZodOptional<z.ZodString>;
+        distinctId: z.ZodNullable<z.ZodString>;
         version: z.ZodString;
         action: z.ZodString;
         payload: z.ZodString;
@@ -1027,8 +1053,8 @@ export declare const userEventsResponseSchema: z.ZodObject<z.objectUtil.extendSh
         action: string;
         anonymousId: string;
         sessionId: string;
+        distinctId: string | null;
         version: string;
-        distinctId?: string | undefined;
     }, {
         id: string;
         projectId: string;
@@ -1037,8 +1063,8 @@ export declare const userEventsResponseSchema: z.ZodObject<z.objectUtil.extendSh
         action: string;
         anonymousId: string;
         sessionId: string;
+        distinctId: string | null;
         version: string;
-        distinctId?: string | undefined;
     }>, "many">;
 }>, "strip", z.ZodTypeAny, {
     meta: {
@@ -1059,8 +1085,8 @@ export declare const userEventsResponseSchema: z.ZodObject<z.objectUtil.extendSh
         action: string;
         anonymousId: string;
         sessionId: string;
+        distinctId: string | null;
         version: string;
-        distinctId?: string | undefined;
     }[];
 }, {
     meta: {
@@ -1081,26 +1107,26 @@ export declare const userEventsResponseSchema: z.ZodObject<z.objectUtil.extendSh
         action: string;
         anonymousId: string;
         sessionId: string;
+        distinctId: string | null;
         version: string;
-        distinctId?: string | undefined;
     }[];
 }>;
 export type UserEventsResponse = z.infer<typeof userEventsResponseSchema>;
 export declare const currentUsersRequestSchema: z.ZodObject<{
     projectId: z.ZodString;
-    minutes: z.ZodOptional<z.ZodNumber>;
+    minutes: z.ZodNumber;
     referrer: z.ZodOptional<z.ZodString>;
     location: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     projectId: string;
+    minutes: number;
     location?: string | undefined;
     referrer?: string | undefined;
-    minutes?: number | undefined;
 }, {
     projectId: string;
+    minutes: number;
     location?: string | undefined;
     referrer?: string | undefined;
-    minutes?: number | undefined;
 }>;
 export type CurrentUsersRequest = z.infer<typeof currentUsersRequestSchema>;
 export declare const currentUsersResponseSchema: z.ZodObject<z.objectUtil.extendShape<{