saasco-sdk 0.1.13 → 0.1.15

package/README.md

@@ -33,9 +33,14 @@ import { Saasco } from 'saasco-sdk';
 export const saasco = new Saasco({ projectId: 'YOUR-PROJECT-ID' });
 ```
 
-## Init Automatic Page View Tracking
+## 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
 
-When you initiate 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 out of automatic page tracking. For most use cases you don't need to do this.
 
 ```ts
@@ -168,7 +173,7 @@ saasco.debug(true);
 ## Reserved Properties
 
 Saasco has reserved some properties that have semantic meanings for contacts and, and will handle them in special ways.
-For example, Saasco always expects email to be a string of the user’s email address, this is important for when sending emails using the marketing app.
+For example, Saasco always expects email to be a string of the user's email address, this is important for when sending emails using the marketing app.
 The SDK will do its best to match these properties, eg (created_at will be mapped to createdAt), but if possible you should use the reserved properties.
 
 ### Reserved Contact Properties
@@ -177,8 +182,8 @@ The SDK will do its best to match these properties, eg (created_at will be mappe
 | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
 | age         | Number | Age of a user                                                                                                     |
 | avatar      | String | URL to an avatar image for the user                                                                               |
-| birthday    | Date   | User’s birthday                                                                                                   |
-| createdAt   | Date   | Date the user’s account was first created. We recomend recommend using ISO-8601 date strings.                     |
+| birthday    | Date   | User's birthday                                                                                                   |
+| createdAt   | Date   | Date the user's account was first created. We recomend recommend using ISO-8601 date strings.                     |
 | description | String | Description of the user                                                                                           |
 | email       | String | Email address of a user                                                                                           |
 | firstName   | String | First name of a user                                                                                              |
@@ -187,8 +192,8 @@ The SDK will do its best to match these properties, eg (created_at will be mappe
 | lastName    | String | Last name of a user                                                                                               |
 | name        | String | Full name of a user. If you only pass a first and last name Segment automatically fills in the full name for you. |
 | phone       | String | Phone number of a user                                                                                            |
-| title       | String | Title of a user, usually related to their position at a specific company. Example: “VP of Engineering”            |
-| username    | String | User’s username. This should be unique to each user, like the usernames of Twitter or GitHub.                     |
+| title       | String | Title of a user, usually related to their position at a specific company. Example: "VP of Engineering"            |
+| username    | String | User's username. This should be unique to each user, like the usernames of Twitter or GitHub.                     |
 | website     | String | Website of a user                                                                                                 |
 
 ### Default Contact Properties
@@ -227,6 +232,13 @@ Any property that starts with `$` is a property that has been generated by the S
 | $initialUtmContent      | Initial UTM Content         | The initial UTM content tag from the URL a customer clicked to arrive at your domain.  |
 | $utmContent             | Last Touch UTM Content      | The UTM content tag from the URL a customer clicked during their last interaction.     |
 | $unsubscribed           | Unsubscribed                | Whether the user has unsubscribed from all notifications                               |
+| $unsubscribeReason      | Unsubscribe Reason          | The reason the user was unsubscribed - eg complained, bounced, requested               |
+
+### Reserved Integration Properties
+
+| Property          | Display Name       | Description                                      |
+| ----------------- | ------------------ | ------------------------------------------------ |
+| $stripeCustomerId | Stripe Customer Id | The Stripe customer ID associated with this user |
 
 ### Reserved event properties
 

package/index.cjs.js

@@ -6,6 +6,8 @@ var tslib = require('tslib');
 var uuid = require('@lukeed/uuid');
 var zod = require('zod');
 
+var version = "0.1.15";
+
 const timezones = {
   'Asia/Barnaul': 'RU',
   'Africa/Nouakchott': 'MR',
@@ -434,10 +436,39 @@ const timezones = {
   'Asia/Calcutta': 'IN'
 };
 
-var version = "0.1.13";
+function getBrowserContext() {
+  var _a;
+  const isBrowser = typeof window !== 'undefined';
+  if (!isBrowser) return;
+  const customNavigator = navigator;
+  const $locale = (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.languages) && (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.languages.length) ? customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.languages[0] : (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.userLanguage) || (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.language) || (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.browserLanguage) || 'en';
+  // https://caniuse.com/?search=Intl.DateTimeFormat().resolvedOptions().timeZone
+  // Only has 96.63% global support, so we need to check for undefined
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const $location = timezones[timezone] || ((_a = $locale === null || $locale === void 0 ? void 0 : $locale.split('-')) === null || _a === void 0 ? void 0 : _a[1]) || 'undefined';
+  const $href = window.location.href;
+  const $pathname = window.location.pathname;
+  const $referrer = document.referrer;
+  const $screenDPI = window.devicePixelRatio;
+  const $screenHeight = screen.height;
+  const $screenWidth = screen.width;
+  const $title = document.title;
+  const $userAgent = window.navigator.userAgent;
+  return {
+    $locale,
+    $location,
+    $href,
+    $pathname,
+    $referrer,
+    $screenDPI,
+    $screenHeight,
+    $screenWidth,
+    $title,
+    $userAgent
+  };
+}
 
 const isBrowser = typeof window !== 'undefined';
-let userId = null;
 const PREF = 'saasco-sdk';
 const data = {};
 function storeData(key, value, ttl) {
@@ -503,35 +534,11 @@ function setAnonmousId({
   storeData(`anonymous-id`, anonymousId, 1000 * 60 * 60 * 24 * 365);
   return anonymousId;
 }
-function getBrowserContext() {
-  var _a;
-  if (!isBrowser) return {};
-  const customNavigator = navigator;
-  const $locale = (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.languages) && (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.languages.length) ? customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.languages[0] : (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.userLanguage) || (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.language) || (customNavigator === null || customNavigator === void 0 ? void 0 : customNavigator.browserLanguage) || 'en';
-  // https://caniuse.com/?search=Intl.DateTimeFormat().resolvedOptions().timeZone
-  // Only has 96.63% global support, so we need to check for undefined
-  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-  const $location = timezones[timezone] || ((_a = $locale === null || $locale === void 0 ? void 0 : $locale.split('-')) === null || _a === void 0 ? void 0 : _a[1]) || 'undefined';
-  const $href = window.location.href;
-  const $pathname = window.location.pathname;
-  const $referrer = document.referrer;
-  const $screenDPI = window.devicePixelRatio;
-  const $screenHeight = screen.height;
-  const $screenWidth = screen.width;
-  const $title = document.title;
-  const $userAgent = window.navigator.userAgent;
-  return {
-    $locale,
-    $location,
-    $href,
-    $pathname,
-    $referrer,
-    $screenDPI,
-    $screenHeight,
-    $screenWidth,
-    $title,
-    $userAgent
-  };
+function getUserId() {
+  return retrieveData(`user-id`);
+}
+function setUserId(userId) {
+  storeData(`user-id`, userId, 1000 * 60 * 60 * 24 * 365);
 }
 class Saasco {
   /**
@@ -542,10 +549,12 @@ class Saasco {
    * @param config.autoPageTracking Whether to automatically track page views. Default is false.
    * @param config.enabled Whether analytics is enabled. Default is true. Set to false for development and staging envioronments. Will still allow debug mode to be true, just no events will be sent
    * @param config.debug Whether to log debug information. Default is false.
+   * @param config.trackUrlParams Whether to track URL parameters. Default is true.
+   * @param config.trackHashChanges Whether to track hash changes. Default is true.
    */
   constructor(config) {
     this.config = config;
-    this.lastPageViewHref = '';
+    this.lastPageViewPath = '';
     this.isInitialized = false;
     if (!config.projectId) {
       this.error("Project ID is required but has not been provided. If you are using an env variable make sure it's set correctly.");
@@ -553,6 +562,9 @@ 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;
   }
   init() {
     if (this.isInitialized) {
@@ -590,16 +602,6 @@ class Saasco {
     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.");
     }
-    // Prevent duplicate Page View tracking
-    if (name === 'Page View') {
-      if (!isBrowser) {
-        console.warn('Saasco page tracking is only available in the browser');
-        return;
-      }
-      const pageViewHref = window.location.href;
-      if (pageViewHref === this.lastPageViewHref) return;
-      this.lastPageViewHref = pageViewHref;
-    }
     setSessionId();
     setAnonmousId();
     const browserContext = getBrowserContext();
@@ -610,9 +612,9 @@ class Saasco {
       version,
       sessionId: getSessionId(),
       anonymousId: getAnonymousId(),
-      distinctId: userId,
+      distinctId: getUserId(),
       projectId: this.config.projectId,
-      payload: JSON.stringify(Object.assign(Object.assign({}, browserContext), {
+      payload: JSON.stringify(Object.assign(Object.assign({}, browserContext || {}), {
         properties: properties || {}
       })),
       context: JSON.stringify(context || {})
@@ -626,6 +628,23 @@ class Saasco {
    * Before implementing this make sure you have disabled the autoPageTracking in the config or you will get duplicate page views
    */
   page() {
+    if (!isBrowser) {
+      console.warn('Saasco page tracking is only available in the browser');
+      return;
+    }
+    const url = new URL(window.location.href);
+    let pathToCompare = url.pathname;
+    // Include search params if configured
+    if (this.config.trackUrlParams) {
+      pathToCompare += url.search;
+    }
+    // Include hash if configured
+    if (this.config.trackHashChanges) {
+      pathToCompare += url.hash;
+    }
+    // Only track if the path has changed
+    if (pathToCompare === this.lastPageViewPath) return;
+    this.lastPageViewPath = pathToCompare;
     return this.track('Page View');
   }
   identify(distinctIdOrProperties, propertiesOrContext, contextOrNothing) {
@@ -639,7 +658,7 @@ 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 === null && !!userId;
+    const userIdChangedToNull = distinctId === null && !!getUserId();
     if (userIdChangedToNull) this.log('User ID change to null. Session reset');
     const reset = userIdChangedToNull;
     setSessionId({
@@ -649,7 +668,7 @@ class Saasco {
       reset
     });
     // set the distinct Id to the userId
-    userId = distinctId;
+    setUserId(distinctId);
     // No distinctId provided so we don't track the user
     if (!distinctId) return;
     const data = {
@@ -809,6 +828,9 @@ function coerceReservedProperties(properties) {
   }, {
     key: 'displayName',
     coerceFrom: ['display_name', 'displayName', 'user_display_name', 'userDisplayName', 'full_name', 'fullName', 'user_full_name', 'userFullName', 'complete_name', 'completeName', 'user_complete_name', 'userCompleteName', 'name', 'username']
+  }, {
+    key: '$stripeCustomerId',
+    coerceFrom: ['stripe_customer_id', 'stripeCustomerId', 'stripe_customer_id', 'stripeCustomerId', 'stripe_customer_id', 'stripeCustomerId', 'stripe_customer_id', 'stripeCustomerId', 'stripe_customer_id', 'stripeCustomerId']
   }];
   return coerce.reduce((acc, {
     key,
@@ -856,6 +878,61 @@ function coerceValue(properties, keys, schema) {
   return coercedValue;
 }
 
+const browserContextSchema = zod.z.object({
+  $locale: zod.z.string(),
+  $location: zod.z.string(),
+  $href: zod.z.string(),
+  $pathname: zod.z.string(),
+  $referrer: zod.z.string(),
+  $screenDPI: zod.z.number(),
+  $screenHeight: zod.z.number(),
+  $screenWidth: zod.z.number(),
+  $title: zod.z.string(),
+  $userAgent: zod.z.string()
+});
+const serverContextSchema = zod.z.object({
+  $city: zod.z.string().optional(),
+  $country: zod.z.string().optional(),
+  $continent: zod.z.string().optional(),
+  $latitude: zod.z.number().optional(),
+  $longitude: zod.z.number().optional(),
+  $timezone: zod.z.string().optional(),
+  $userAgent: zod.z.string().optional(),
+  $referrer: zod.z.string().optional(),
+  $ip: zod.z.string().optional(),
+  $processedAt: zod.z.string().datetime().optional(),
+  $identityHash: zod.z.string().optional()
+});
+const trackedEventTypesSchema = zod.z.enum(['SHORTLINK_REDIRECT']);
+const trackedEventSchema = zod.z.object({
+  id: zod.z.string().uuid(),
+  timestamp: zod.z.string().datetime(),
+  projectId: zod.z.string(),
+  version: zod.z.string(),
+  type: trackedEventTypesSchema,
+  payload: zod.z.object({
+    browserContext: browserContextSchema.optional(),
+    serverContext: serverContextSchema.optional(),
+    properties: zod.z.record(zod.z.string(), zod.z.any()).optional()
+  })
+});
+/**
+ * Creates a zod for tracking any type of event.
+ * Includes the base tracking schema and extends with any new schema
+ * @param type
+ * @param payloadSchema
+ * @returns
+ */
+function createTrackedEventTypeSchema(type, payloadSchema) {
+  const typeSchema = zod.z.literal(type);
+  return trackedEventSchema.extend({
+    type: typeSchema,
+    payload: zod.z.object(Object.assign(Object.assign({}, trackedEventSchema.shape.payload.shape), {
+      properties: payloadSchema
+    }))
+  });
+}
+
 const tbAny = zod.z.union([zod.z.string(), zod.z.number(), zod.z.array(zod.z.union([zod.z.string(), zod.z.number()]))]);
 const tinyBirdBaseSchema = zod.z.object({
   meta: zod.z.array(zod.z.object({
@@ -895,7 +972,9 @@ const TinybirdJobResponseSchema = zod.z.object({
 const latestEventsRequestSchema = zod.z.object({
   projectId: zod.z.string(),
   limit: zod.z.number().optional(),
-  payload: zod.z.boolean().optional()
+  payload: zod.z.boolean().optional(),
+  distinctId: zod.z.string().optional(),
+  action: zod.z.string().optional()
 });
 const latestEventItemSchema = zod.z.object({
   id: zod.z.string(),
@@ -906,7 +985,9 @@ const latestEventItemSchema = zod.z.object({
   href: zod.z.string(),
   device: zod.z.string(),
   browser: zod.z.string(),
-  payload: zod.z.string().optional()
+  payload: zod.z.string().optional(),
+  distinctId: zod.z.string().optional(),
+  unique: zod.z.boolean().optional()
 });
 const latestEventsResponseSchema = tinyBirdBaseSchema.extend({
   data: zod.z.array(latestEventItemSchema)
@@ -1018,7 +1099,7 @@ const currentUsersResponseSchema = tinyBirdBaseSchema.extend({
   }))
 });
 const reservedPropertiesSchema = zod.z.object({
-  age: zod.z.number().or(zod.z.string()).nullish(),
+  age: zod.z.number().nullish(),
   avatar: zod.z.string().url().nullish(),
   birthday: zod.z.string().nullish(),
   createdAt: zod.z.string().nullish(),
@@ -1033,8 +1114,17 @@ const reservedPropertiesSchema = zod.z.object({
   title: zod.z.string().nullish(),
   username: zod.z.string().nullish(),
   website: zod.z.string().nullish(),
+  // Default Properties
   $id: zod.z.string().nullish(),
-  $lastSeen: zod.z.string().nullish()
+  $lastSeen: zod.z.string().nullish(),
+  $unsubscribed: zod.z.boolean().nullish(),
+  $unsubscribeReason: zod.z.enum(['manual', 'complained', 'bounced']).nullish(),
+  // Stripe Properties
+  $stripeCustomerId: zod.z.string().nullish(),
+  $stripeTotalPayments: zod.z.number().or(zod.z.string()).nullish(),
+  $stripeTotalSpent: zod.z.number().or(zod.z.string()).nullish(),
+  // Internal properties
+  $_toDelete: zod.z.boolean().nullish()
 });
 const contactPropertiesSchema = reservedPropertiesSchema.optional().and(zod.z.record(zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean(), zod.z.date(), zod.z.null(), zod.z.array(zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean(), zod.z.date(), zod.z.null()]))])));
 const analyticsUserRawSchema = zod.z.object({
@@ -1085,11 +1175,14 @@ exports.analyticsEventSchema = analyticsEventSchema;
 exports.analyticsUserRawSchema = analyticsUserRawSchema;
 exports.analyticsUserSchema = analyticsUserSchema;
 exports.baseTopRequestSchema = baseTopRequestSchema;
+exports.browserContextSchema = browserContextSchema;
 exports.coerceReservedProperties = coerceReservedProperties;
 exports.contactPropertiesSchema = contactPropertiesSchema;
+exports.createTrackedEventTypeSchema = createTrackedEventTypeSchema;
 exports.currentUsersRequestSchema = currentUsersRequestSchema;
 exports.currentUsersResponseSchema = currentUsersResponseSchema;
 exports.getAnalyticsUserParamsSchema = getAnalyticsUserParamsSchema;
+exports.getBrowserContext = getBrowserContext;
 exports.idenfitySchema = idenfitySchema;
 exports.kpiSchema = kpiSchema;
 exports.kpisRequestSchema = kpisRequestSchema;
@@ -1101,6 +1194,7 @@ exports.latestIdentifiesRequestSchema = latestIdentifiesRequestSchema;
 exports.latestIdentifiesResponseSchema = latestIdentifiesResponseSchema;
 exports.listUsersParamsSchema = listUsersParamsSchema;
 exports.reservedPropertiesSchema = reservedPropertiesSchema;
+exports.serverContextSchema = serverContextSchema;
 exports.tbAny = tbAny;
 exports.timezones = timezones;
 exports.tinyBirdBaseSchema = tinyBirdBaseSchema;
@@ -1111,4 +1205,6 @@ exports.topLocationsResponseSchema = topLocationsResponseSchema;
 exports.topPagesResponseSchema = topPagesResponseSchema;
 exports.topSourcesResponseSchema = topSourcesResponseSchema;
 exports.topSourcesSchema = topSourcesSchema;
+exports.trackedEventSchema = trackedEventSchema;
+exports.trackedEventTypesSchema = trackedEventTypesSchema;
 exports.userEventsResponseSchema = userEventsResponseSchema;