saasco-sdk 0.1.23 → 0.1.25

package/README.md

@@ -3,8 +3,8 @@
 ---
 
 - [Privacy](#privacy)
-- [Getting Started](#initiate-the-lib)
-- [Init Automatic Page View Tracking](#init-automatic-page-view-tracking)
+- [Getting Started](#getting-started)
+- [Automatic Page View Tracking](#automatic-page-view-tracking)
 - [Tracking Events](#tracking-events)
 - [Identifying Users](#identifying-users)
 - [Debugging and Dev](#debugging-and-dev)
@@ -12,7 +12,7 @@
 
 <br />
 
-## 🔒 Privacy
+## 🔒 Privacy
 
 By default Saasco is privacy friendly, using no cookies and obscuring all activity behind Anonymous IDs. However if you want to power more complex user tracking you can identify users and then all events they do will be attributed to them in your CRM. This can assist with customer support but also for things like drip campaigns and other marketing activities.
 
@@ -22,9 +22,9 @@ Install by running:
 `npm install saasco-sdk`
 
 Copy your Project ID from the project settings page in Saasco:
-[https://saasco.com/your-project/settings/project](https://saasco.com/your-projects/settings/project)
+[https://www.saasco.com/projects/your-project/apps/dashboard/settings/project](https://www.saasco.com/projects/your-project/apps/dashboard/settings/project)
 
-Then import Saasco and initiate the lib with your Project ID.
+Then import Saasco and initialize the lib with your Project ID.
 
 ```ts
 // lib/saasco.ts
@@ -35,7 +35,7 @@ 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 `autoPageTracking` configuration object:
+When you initialize 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({
@@ -54,15 +54,15 @@ 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. The track method supports both client-side (oarameter-style) and server-side (object-style) usage patterns.
+With events you can track custom actions users are taking on your site with event properties. The track method supports both client-side (parameter-style) and server-side (object-style) usage patterns.
 
 Each event has 2 components:
 
 **Name** - this is the name of the action that was taken.
 
-_We like to follow segments [Object Action Framework](https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/) for naming events._
+_We like to follow Segment's [Object Action Framework](https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/) for naming events._
 
-**Properties** - This is an object with the values of the event. Such as a the value, currency, or query.
+**Properties** - This is an object with the values of the event. Such as the value, currency, or query.
 
 We currently have limited support for properties, but in the future we will support complex querying and actions based on event properties.
 
@@ -88,18 +88,19 @@ 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.
+You must provide a userId for server side tracking events so there is a contact to connect the events to.
 
 ```tsx
 // Import saasco
 import { saasco } from '../lib/saasco.ts';
 
-// Track an event with full control
+// Track an event and associate it with a user
 saasco.track({
-  event: "User Signed Up",
+  event: "Signed Up",
   userId: "user_123",
-  properties: { plan: "Pro" },
-  context: { source: "server" },
+  properties: {
+    provider: 'email',
+  }
 });
 ```
 
@@ -133,7 +134,7 @@ function signedOut(){
 
 ### Identifying users who don't have an ID
 
-Often times you have a users contact details before they sign up for your site. This could be part of the signup flow, or if they were to subscribe to marketing emails before they sign up as a customer
+Often times you have a user's contact details before they sign up for your site. This could be part of the signup flow, or if they were to subscribe to marketing emails before they sign up as a customer
 
 Saasco allows identifying users without an id by simply skipping the `ID` part of the identify call. This will add contacts to the CRM for email marketing and other tools before users register.
 
@@ -152,7 +153,7 @@ By doing this users will get tracked and added to your contacts, and as soon as
 
 ### Soft vs Full identify
 
-When users are identified without a `ID` we call this is a "Soft Identify". Users who are soft identified can also be called "Leads".
+When users are identified without an `ID` we call this a "Soft Identify". Users who are soft identified can also be called "Leads".
 Once a user signs up and you identify them with an `ID` they will be fully registered and can be called "Customers"
 
 In the CRM when you identify a user, either soft or full, they become a contact.
@@ -175,43 +176,50 @@ export const saasco = new Saasco({
 
 #### Debugging
 
-You can turn on debugging when you initiate the repo or by running saasco.debug(true) in your code or the browser.
+You can turn on debugging when you initialize the repo or by running `saasco.enableDebug()` in your code or the browser.
 
 ```tsx
 export const saasco = new Saasco({
     projectId: 'YOUR-PROJECT-ID',
     enabled: process.env['NODE_ENV'] === 'production',
     // Set to true to console log analytics events.
-    // This works even when enabled is false - it just wont send the data
+    // This works even when enabled is false - it just won't send the data
     debug: true,
 });
 ```
 
-You can also enable debug mode by calling `saasco.debug(true)` anywhere in your code.
+You can also enable debug mode by calling `saasco.enableDebug()` anywhere in your code.
 
 ```tsx
-saasco.debug(true);
+saasco.enableDebug();
 // will console log "debug mode activated"
 ```
 
+You can disable debug mode by calling `saasco.disableDebug()`.
+
+```tsx
+saasco.disableDebug();
+// will console log "debug mode deactivated"
+```
+
 ## Reserved Properties
 
-Saasco has reserved some properties that have semantic meanings for contacts and, and will handle them in special ways.
+Saasco has reserved some properties that have semantic meanings for contacts 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.
 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
 
-| PROPTERTY   | TYPE   | DESCRIPTION                                                                                                       |
+| PROPERTY    | TYPE   | DESCRIPTION                                                                                                       |
 | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
 | 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.                     |
+| createdAt   | Date   | Date the user's account was first created. We 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                                                                                              |
-| displayName | String | The prefered users display name, will default to "firstName lastName"                                             |
+| displayName | String | The preferred user's display name, will default to "firstName lastName"                                           |
 | gender      | String | Gender of a user                                                                                                  |
 | 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. |
@@ -236,11 +244,11 @@ Any property that starts with `$` is a property that has been generated by the S
 | $locale                 | Locale                      | The most recent preferred language of the user.                                        |
 | $screenHeight           | Screen Height               | The most recent height of the device screen in pixels                                  |
 | $screenWidth            | Screen Width                | The most recent width of the device screen in pixels                                   |
-| $screenDpi              | Screen DPI                  | The most recent Pixel density of the device screen.                                    |
+| $screenDpi              | Screen DPI                  | The most recent pixel density of the device screen.                                    |
 | $lastSeen               | Last Seen                   | The last time a user was identified while active was not false in the context          |
 | $os                     | Operating System            | The most recent OS of the user.                                                        |
 | $browser                | Browser                     | The most recent browser of the user.                                                   |
-| $browserVersion         | Browser Version             | The most recent bowser version of the user.                                            |
+| $browserVersion         | Browser Version             | The most recent browser version of the user.                                           |
 | $initialReferrer        | Initial Referrer            | Referring URL when the user first arrived on your site. Defaults to "direct"           |
 | $referrer               | Last Touch Referrer         | Referring URL when the user last interacted with your site. Defaults to "direct"       |
 | $initialReferringDomain | Initial Referring Domain    | Referring domain at first arrival. Defaults to "direct"                                |
@@ -272,11 +280,11 @@ Properties used to calculate revenue for different traffic sources and LTV for u
 | -------- | ------ | ----------------------------------------------------------------------------------------- |
 | revenue  | Number | Amount of revenue an event resulted in. This should be a decimal value                    |
 | currency | String | Currency of the revenue an event resulted in. This should be sent in the ISO 4127 format. |
-| value    | Number | An abstract numerical value used internally to score eventsm such as lead scoring.        |
+| value    | Number | An abstract numerical value used internally to score events, such as lead scoring.        |
 
 ### Default Event Properties
 
-Our SDKs automatically collect certain properties on every event or user profile. The default properties begin with a `$` and can be overwritten with your own identify calls, so we recomend avoiding leading `$` in your identify call properties to avoid conflicts.
+Our SDKs automatically collect certain properties on every event or user profile. The default properties begin with a `$` and can be overwritten with your own identify calls, so we recommend avoiding leading `$` in your identify call properties to avoid conflicts.
 
 | Property         | Display Name                | Description                                                                      |
 | ---------------- | --------------------------- | -------------------------------------------------------------------------------- |
@@ -343,16 +351,19 @@ saasco.track('Signed Up', {
 Event triggered when a user signs in.
 | Property | Description |
 |----------|--------------------------------------------------|
-| `method` | The method used for signing in (e.g., email, social media). |
+| `provider` | The provider used for signing in (e.g., email, github, google). |
 
 Example:
 
 ```jsx
 saasco.track('Signed In', {
-  method: 'email',
+  provider: 'email',
 });
 ```
 
+Note:
+When tracking Signed In events call identify('user_id', {email: '...'}) before the event to connect to the user.
+
 #### Signed Out
 
 Event triggered when a user signs out.
@@ -364,13 +375,16 @@ Example:
 saasco.track('Signed Out');
 ```
 
+Note:
+When tracking Signed Out events call identify(null) _after_ tracking the event to reset the session.
+
 #### Trial Started
 
 Event triggered when a user starts a trial.
 | Property | Description |
 |-------------------|---------------------------------------------------------------------|
 | `duration` | The duration of the trial in days |
-| `type`| Values can be `optIn` for then the user didn't provide a cc or `optOut` when the user provided a cc and it will automatically start and the end of the trial period|
+| `type`| Values can be `optIn` for when the user didn't provide a cc or `optOut` when the user provided a cc and it will automatically start at the end of the trial period|
 
 Example:
 
@@ -380,10 +394,10 @@ saasco.track('Trial Started', { duration: 14, type: 'optOut' });
 
 #### Trial Ended
 
-Event triggered when a users trial ends.
+Event triggered when a user's trial ends.
 | Property | Description |
 |-------------------|---------------------------------------------------------------------|
-| `daysLeftInTrial`| If a user manual upgrades before the end of the trial you can record this here|
+| `daysLeftInTrial`| If a user manually upgrades before the end of the trial you can record this here|
 
 Example:
 
@@ -391,10 +405,10 @@ Example:
 saasco.track('Trial Ended', { daysLeftInTrial: 4 });
 ```
 
-#### Payment Ended
+#### Payment Completed
 
 Event triggered when a payment is completed.
-This is may be called on the server side after a confirmation webhook.
+This may be called on the server side after a confirmation webhook.
 This is helpful for recording ongoing subscription payments.
 
 | Property   | Description                                         |
@@ -458,7 +472,7 @@ Event triggered when a subscription is upgraded.
 Example:
 
 ```jsx
-saasco.track('Subscription Cancelled', {
+saasco.track('Subscription Upgraded', {
   fromPlan: 'Monthly',
   toPlan: 'Annual',
   previousRevenue: 29,
@@ -475,13 +489,13 @@ Event triggered when a subscription is downgraded.
 | `toPlan` | The new plan. |
 | `previousRevenue` | The revenue from the previous plan. |
 | `newRevenue` | The revenue from the new plan. |
-| `revenue` | If the customer is refunded immediately then include a revenue number here, in the case of a downgrade this will be a negtive value. Only include the revenue here if it's not tracked on your backend or with a webhook |
+| `revenue` | If the customer is refunded immediately then include a revenue number here, in the case of a downgrade this will be a negative value. Only include the revenue here if it's not tracked on your backend or with a webhook |
 | `currency` | The currency of the payment, assumed to be USD unless otherwise specified. |
 
 Example:
 
 ```jsx
-saasco.track('Subscription Cancelled', {
+saasco.track('Subscription Downgraded', {
   fromPlan: 'Annual',
   toPlan: 'Monthly',
   previousRevenue: 129,
@@ -503,7 +517,7 @@ All properties should be added as data attributes in the format data-[prop name]
 ></script>
 ```
 
-All the properties for initiating the sdk can be passed in like this:
+All the properties for initializing the sdk can be passed in like this:
 
 ```jsx
 <script

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.23";
+var version = "0.1.25";
 
 const timezones = {
   'Asia/Barnaul': 'RU',
@@ -526,7 +526,7 @@ function setSessionId({
 function getAnonymousId() {
   return retrieveData(`anonymous-id`);
 }
-function setAnonmousId({
+function setAnonymousId({
   reset
 } = {
   reset: false
@@ -582,7 +582,7 @@ class Saasco {
     this.log('Saasco initialized', this.config);
     if (this.config.debug) this.log('Debug mode active. This will log all events to the console.');
     if (!this.config.enabled) this.log('Analytics is disabled. No requests will be sent to the server.');
-    this.initiAutoPageTracking();
+    this.initAutoPageTracking();
     this.isInitialized = true;
   }
   disableDebug() {
@@ -599,7 +599,7 @@ class Saasco {
       return Promise.resolve(response);
     }
     setSessionId();
-    setAnonmousId();
+    setAnonymousId();
     const hasAction = typeof actionOrPayload === 'string';
     const hasPayload = typeof actionOrPayload === 'object';
     // Must do payload on the server
@@ -682,7 +682,7 @@ class Saasco {
     setSessionId({
       reset
     });
-    const anonymousId = setAnonmousId({
+    const anonymousId = setAnonymousId({
       reset
     });
     // set the distinct Id to the userId
@@ -787,7 +787,7 @@ class Saasco {
    * It listens to url changes to track new pages every time the url changes
    * @returns
    */
-  initiAutoPageTracking() {
+  initAutoPageTracking() {
     var _a, _b;
     // 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;

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.23";
+var version = "0.1.25";
 
 const timezones = {
   'Asia/Barnaul': 'RU',
@@ -522,7 +522,7 @@ function setSessionId({
 function getAnonymousId() {
   return retrieveData(`anonymous-id`);
 }
-function setAnonmousId({
+function setAnonymousId({
   reset
 } = {
   reset: false
@@ -578,7 +578,7 @@ class Saasco {
     this.log('Saasco initialized', this.config);
     if (this.config.debug) this.log('Debug mode active. This will log all events to the console.');
     if (!this.config.enabled) this.log('Analytics is disabled. No requests will be sent to the server.');
-    this.initiAutoPageTracking();
+    this.initAutoPageTracking();
     this.isInitialized = true;
   }
   disableDebug() {
@@ -595,7 +595,7 @@ class Saasco {
       return Promise.resolve(response);
     }
     setSessionId();
-    setAnonmousId();
+    setAnonymousId();
     const hasAction = typeof actionOrPayload === 'string';
     const hasPayload = typeof actionOrPayload === 'object';
     // Must do payload on the server
@@ -678,7 +678,7 @@ class Saasco {
     setSessionId({
       reset
     });
-    const anonymousId = setAnonmousId({
+    const anonymousId = setAnonymousId({
       reset
     });
     // set the distinct Id to the userId
@@ -783,7 +783,7 @@ class Saasco {
    * It listens to url changes to track new pages every time the url changes
    * @returns
    */
-  initiAutoPageTracking() {
+  initAutoPageTracking() {
     var _a, _b;
     // 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;

package/package.json

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

package/src/lib/analytics.d.ts

@@ -11,11 +11,14 @@ type Identity = {
     anonymousId: string | number;
     userId?: string | number;
 };
+type Context = {
+    active?: boolean;
+};
 type TrackPayload = Identity & {
     event: string;
     sessionId?: string;
     properties?: Record<string, any>;
-    context?: Record<string, any>;
+    context?: Context;
 };
 type DoRequestResponse = {
     success: boolean;
@@ -55,9 +58,7 @@ export declare class Saasco {
      * Client: track('User Signed Up', { plan: 'Pro' }, { source: 'client' })
      * Server: track({ event: 'User Signed Up', userId: 'user_123', properties: { plan: 'Pro' } })
      */
-    track(action: string, properties?: Record<string, any>, context?: {
-        active?: boolean;
-    }): Promise<DoRequestResponse>;
+    track(action: string, properties?: Record<string, any>, context?: Context): Promise<DoRequestResponse>;
     track(payload: TrackPayload): Promise<DoRequestResponse>;
     /**
      * The page method lets you record page views on your website
@@ -75,12 +76,8 @@ export declare class Saasco {
      * @param properties A dictionary of traits you know about the user like their email, name, plan etc.
      * @param context Context for the identify call such as whether the user is active.
      */
-    identify(properties: Record<string, any>, context?: {
-        active?: boolean;
-    }): Promise<DoRequestResponse>;
-    identify(distinctId: string | number | null, properties?: Record<string, any>, context?: {
-        active?: boolean;
-    }): Promise<DoRequestResponse>;
+    identify(properties: Record<string, any>, context?: Context): Promise<DoRequestResponse>;
+    identify(distinctId: string | number | null, properties?: Record<string, any>, context?: Context): Promise<DoRequestResponse>;
     /**
      * This should only be called when the user logs out
      * It will reset the session, anonymous id, and user id
@@ -109,6 +106,6 @@ export declare class Saasco {
      * It listens to url changes to track new pages every time the url changes
      * @returns
      */
-    private initiAutoPageTracking;
+    private initAutoPageTracking;
 }
 export {};