@chordcommerce/analytics 1.5.1 → 1.7.0

package/README.md

@@ -1,4 +1,4 @@
-# `@chordcommerce/analytics`
+# @chordcommerce/analytics
 
 The `@chordcommerce/analytics` library provides simple methods for sending tracking events to Chord from your website, with an optional debugging mode to validate event properties.
 
@@ -6,11 +6,11 @@ The `@chordcommerce/analytics` library provides simple methods for sending track
 
 Visit [docs.chord.co](https://docs.chord.co/analytics-getting-started) for guides, examples, and an API reference.
 
-## **Requirements**
+## Requirements
 
 A CDP Javascript library must be installed in your project. Currently, only Segment's [analytics.js](https://www.npmjs.com/package/@segment/analytics-next) library is supported.
 
-## **Installation**
+## Installation
 
 To install `@chordcommerce/analytics`, run the following command in your project directory:
 
@@ -20,7 +20,7 @@ npm install @chordcommerce/analytics
 yarn add @chordcommerce/analytics
 ```
 
-## **Usage**
+## Usage
 
 First, ensure that a CDP Javascript library is installed and configured in your project. Then, initialize `@chordcommerce/analytics` as follows:
 
@@ -58,7 +58,7 @@ chord.trackCartViewed({ cart }) // sends a "Cart Viewed" event to the CDP
 | `metadata.platform.type`      | true     | The type of platform where the event originated. Either `web` or `pos`.                                                           |
 | `metadata.store.domain`       | true     | The domain of the site where the event originated. For Shopify, this should be the store slug that comes before `.myshopify.com`. |
 
-### **Formatters**
+### Formatters
 
 Formatters are Javascript functions that are used to construct tracking event properties. There are two types of formatters, objects and events. You must define object formatters. Event formatters are optional. See [Chord’s documentation](https://docs.chord.co/analytics-getting-started#fgWx7) for more details and example formatters.
 
@@ -77,10 +77,40 @@ A formatter must be provided for each of the four core data types that are used
 
 A formatter can be provided for each event. This formatter is used to transform the event properties of a specific event after Chord constructs the event, just before it's sent to the CDP. See [Chord’s documentation](https://docs.chord.co/analytics-getting-started#jquZe) for more details on event formatters.
 
+## Using with Typescript
+
+Optionally, you can instantiate `ChordAnalytics` with a custom type argument describing your data to improve type safety for formatters and SDK functions.
+
+For instance, if you're working with objects like `cart`, `product`, etc., from a Shopify storefront API query, you might already have types like `StorefrontCart` defined for the response. Instantiate `ChordAnalytics` with a type argument:
+
+```js
+interface ObjectTypes {
+  Cart: StorefrontCart
+  Checkout: StorefrontCart
+  LineItem: StorefrontLineItem
+  Product: StorefrontProduct
+}
+
+const chord = new ChordAnalytics<ObjectTypes>({ options })
+```
+
+Now, when you use an SDK method like `chord.trackCartViewed({ cart })`, `cart` has the `StorefrontCart` type.
+
+Formatter types also support an optional generic type parameter for the function argument:
+
+```js
+import type { CartFormatter } from '@chordcommerce/analytics'
+
+export const cartFormatter: CartFormatter<StorefrontCart> = (props) => {
+  const { cart } = props // `cart` has type `StorefrontCart`
+  return { ... }
+}
+```
+
 ## API Reference
 
 See [Chord’s documentation](https://docs.chord.co/analytics-getting-started) for a full API reference.
 
-## **Support**
+## Support
 
 For support with setup and configuration, please contact Chord directly at **help@chord.co**.

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
-import type { AnyAnalytics, EventProperties, Options, ValidateResult, ChordAnalyticsOptions, AnyOptions, CartViewedInput, IdentifyTraits, CheckoutStartedInput, EmailCapturedInput, ProductListViewedInput, ProductListFilteredInput, ProductAddedInput, ProductClickedInput, ProductRemovedInput, ProductViewedInput, ProductsSearchedInput, CouponAppliedInput, CouponDeniedInput, CouponEnteredInput, CouponRemovedInput, SignedInInput, SignedOutInput, SignedUpInput } from '../types/index.js';
+import type { AnyAnalytics, EventProperties, Options, ValidateResult, ChordAnalyticsOptions, AnyOptions, CartViewedInput, IdentifyTraits, CheckoutStartedInput, EmailCapturedInput, ProductListViewedInput, ProductListFilteredInput, ProductAddedInput, ProductClickedInput, ProductRemovedInput, ProductViewedInput, ProductsSearchedInput, CouponAppliedInput, CouponDeniedInput, CouponEnteredInput, CouponRemovedInput, SignedInInput, SignedOutInput, SignedUpInput, ObjectTypes } from '../types/index.js';
 export interface ChordAnalyticsSnippet {
-    _loadOptions: ChordAnalyticsOptions;
+    _loadOptions: ChordAnalyticsOptions<ObjectTypes>;
     invoked: boolean;
     methods: string[];
     queue: any[];
@@ -8,7 +8,7 @@ export interface ChordAnalyticsSnippet {
     load: () => void;
     SNIPPET_VERSION: string;
 }
-export declare class ChordAnalytics {
+export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
     /**
      * Allows snippet.js to detect whether this library has been initialized yet.
      */
@@ -20,8 +20,8 @@ export declare class ChordAnalytics {
     /**
      * Options for ChordAnalytics.
      */
-    options: ChordAnalyticsOptions;
-    constructor(options: ChordAnalyticsOptions);
+    options: ChordAnalyticsOptions<T>;
+    constructor(options: ChordAnalyticsOptions<T>);
     cdp: () => AnyAnalytics;
     logger: (message?: any, ...optionalParams: any[]) => void;
     /**
@@ -64,19 +64,19 @@ export declare class ChordAnalytics {
         (): void;
     };
     reset: () => void;
-    trackCartViewed: (props: CartViewedInput, options?: AnyOptions) => Promise<void>;
-    trackCheckoutStarted: (props: CheckoutStartedInput, options?: AnyOptions) => Promise<void>;
+    trackCartViewed: (props: CartViewedInput<T>, options?: AnyOptions) => Promise<void>;
+    trackCheckoutStarted: (props: CheckoutStartedInput<T>, options?: AnyOptions) => Promise<void>;
     trackCouponApplied: (props: CouponAppliedInput, options?: AnyOptions) => Promise<void>;
     trackCouponDenied: (props: CouponDeniedInput, options?: AnyOptions) => Promise<void>;
     trackCouponEntered: (props: CouponEnteredInput, options?: AnyOptions) => Promise<void>;
     trackCouponRemoved: (props: CouponRemovedInput, options?: AnyOptions) => Promise<void>;
     trackEmailCaptured: (props: EmailCapturedInput, options?: AnyOptions) => Promise<void>;
-    trackProductAdded: (props: ProductAddedInput, options?: AnyOptions) => Promise<void>;
-    trackProductClicked: (props: ProductClickedInput, options?: AnyOptions) => Promise<void>;
+    trackProductAdded: (props: ProductAddedInput<T>, options?: AnyOptions) => Promise<void>;
+    trackProductClicked: (props: ProductClickedInput<T>, options?: AnyOptions) => Promise<void>;
     trackProductListFiltered: (props: ProductListFilteredInput, options?: AnyOptions) => Promise<void>;
-    trackProductListViewed: (props: ProductListViewedInput, options?: AnyOptions) => Promise<void>;
-    trackProductRemoved: (props: ProductRemovedInput, options?: AnyOptions) => Promise<void>;
-    trackProductViewed: (props: ProductViewedInput, options?: AnyOptions) => Promise<void>;
+    trackProductListViewed: (props: ProductListViewedInput<T>, options?: AnyOptions) => Promise<void>;
+    trackProductRemoved: (props: ProductRemovedInput<T>, options?: AnyOptions) => Promise<void>;
+    trackProductViewed: (props: ProductViewedInput<T>, options?: AnyOptions) => Promise<void>;
     trackProductsSearched: (props: ProductsSearchedInput, options?: AnyOptions) => Promise<void>;
     trackSignedIn: (props: SignedInInput, options?: AnyOptions) => Promise<void>;
     trackSignedOut: (props?: SignedOutInput, options?: AnyOptions) => Promise<void>;

package/dist/types/client.d.ts

@@ -1,12 +1,16 @@
 import type { AnalyticsSnippet, Analytics, AnalyticsBrowser, Options } from '@segment/analytics-next';
-import type { Cart, Checkout, Product, LineItem } from './objects.js';
-import type { CartViewed, CheckoutStarted, CouponApplied, CouponDenied, CouponEntered, CouponRemoved, EmailCaptured, ProductAdded, ProductClicked, ProductListFiltered, ProductListViewed, ProductRemoved, ProductViewed, ProductsSearched, SignedIn, SignedOut, SignedUp } from './typewriter.js';
-import type { CartViewedInput, CheckoutStartedInput, EmailCapturedInput, ProductAddedInput, ProductClickedInput, ProductListFilteredInput, ProductListViewedInput, ProductRemovedInput, ProductViewedInput, ProductsSearchedInput, ProductInput, CartInput, CheckoutInput, LineItemInput, CouponAppliedInput, CouponDeniedInput, CouponEnteredInput, CouponRemovedInput, SignedInInput, SignedOutInput, SignedUpInput } from './input.js';
+import { ChordAnalyticsFormatters } from './formatters.js';
 export interface ValidateResult {
     success: boolean;
     error?: any[];
     data?: any;
 }
+export interface ObjectTypes {
+    Cart: any;
+    Checkout: any;
+    LineItem: any;
+    Product: any;
+}
 export type AnyAnalytics = AnalyticsSnippet | Analytics | AnalyticsBrowser;
 export type AnyOptions = Options;
 export type AnyProduct = {
@@ -22,37 +26,11 @@ export type AnyId = string | number;
 export type AnyLineItem = {
     [key: string]: unknown;
 };
-export interface ChordAnalyticsOptions {
+export interface ChordAnalyticsOptions<T extends ObjectTypes = ObjectTypes> {
     cdp?: AnyAnalytics | (() => AnyAnalytics);
     debug?: boolean;
     enableLogging?: boolean;
-    formatters: {
-        events?: {
-            cartViewed?: (props: CartViewedInput, event: CartViewed) => CartViewed;
-            checkoutStarted?: (props: CheckoutStartedInput, event: CheckoutStarted) => CheckoutStarted;
-            couponApplied?: (props: CouponAppliedInput, event: CouponApplied) => CouponApplied;
-            couponDenied?: (props: CouponDeniedInput, event: CouponDenied) => CouponDenied;
-            couponEntered?: (props: CouponEnteredInput, event: CouponEntered) => CouponEntered;
-            couponRemoved?: (props: CouponRemovedInput, event: CouponRemoved) => CouponRemoved;
-            emailCaptured?: (props: EmailCapturedInput, event: EmailCaptured) => EmailCaptured;
-            productAdded?: (props: ProductAddedInput, event: ProductAdded) => ProductAdded;
-            productClicked?: (props: ProductClickedInput, event: ProductClicked) => ProductClicked;
-            productListFiltered?: (props: ProductListFilteredInput, event: ProductListFiltered) => ProductListFiltered;
-            productListViewed?: (props: ProductListViewedInput, event: ProductListViewed) => ProductListViewed;
-            productRemoved?: (props: ProductRemovedInput, event: ProductRemoved) => ProductRemoved;
-            productViewed?: (props: ProductViewedInput, event: ProductViewed) => ProductViewed;
-            productsSearched?: (props: ProductsSearchedInput, event: ProductsSearched) => ProductsSearched;
-            signedIn?: (props: SignedInInput, event: SignedIn) => SignedIn;
-            signedOut?: (props: SignedOutInput, event: SignedOut) => SignedOut;
-            signedUp?: (props: SignedUpInput, event: SignedUp) => SignedUp;
-        };
-        objects: {
-            cart: (props: CartInput) => Cart;
-            checkout: (props: CheckoutInput) => Checkout;
-            lineItem: (props: LineItemInput) => LineItem;
-            product: (props: ProductInput) => Product;
-        };
-    };
+    formatters: ChordAnalyticsFormatters<T>;
     stripNull?: boolean;
     metadata: EventMetadata;
 }

package/dist/types/formatters.d.ts

@@ -0,0 +1,86 @@
+import type { CartViewed, CheckoutStarted, ProductAdded, ProductClicked, ProductViewed, ProductListViewed, CouponApplied, CouponDenied, CouponEntered, CouponRemoved, EmailCaptured, ProductListFiltered, ProductRemoved, ProductsSearched, SignedIn, SignedOut, SignedUp } from './typewriter.js';
+import type { Cart, Checkout, LineItem, Product } from './objects.js';
+import type { CartInput, CheckoutInput, LineItemInput, ProductInput, CartViewedInput, CheckoutStartedInput, ProductAddedInput, ProductClickedInput, ProductViewedInput, ProductListViewedInput, ProductListFilteredInput, ProductRemovedInput, CouponAppliedInput, CouponDeniedInput, CouponEnteredInput, CouponRemovedInput, EmailCapturedInput, ProductsSearchedInput, SignedInInput, SignedOutInput, SignedUpInput } from './input.js';
+import type { ObjectTypes } from './client.js';
+export type CartFormatter<T = ObjectTypes['Cart']> = (props: CartInput<T>) => Cart;
+export type CheckoutFormatter<T = ObjectTypes['Checkout']> = (props: CheckoutInput<T>) => Checkout;
+export type LineItemFormatter<T = ObjectTypes['LineItem']> = (props: LineItemInput<T>) => LineItem;
+export type ProductFormatter<T = ObjectTypes['Product']> = (props: ProductInput<T>) => Product;
+export interface CartViewedFormatter<T extends ObjectTypes = ObjectTypes> {
+    (props: CartViewedInput<T>, event: CartViewed): CartViewed;
+}
+export interface CheckoutStartedFormatter<T extends ObjectTypes = ObjectTypes> {
+    (props: CheckoutStartedInput<T>, event: CheckoutStarted): CheckoutStarted;
+}
+export interface CouponAppliedFormatter {
+    (props: CouponAppliedInput, event: CouponApplied): CouponApplied;
+}
+export interface CouponDeniedFormatter {
+    (props: CouponDeniedInput, event: CouponDenied): CouponDenied;
+}
+export interface CouponEnteredFormatter {
+    (props: CouponEnteredInput, event: CouponEntered): CouponEntered;
+}
+export interface CouponRemovedFormatter {
+    (props: CouponRemovedInput, event: CouponRemoved): CouponRemoved;
+}
+export interface EmailCapturedFormatter {
+    (props: EmailCapturedInput, event: EmailCaptured): EmailCaptured;
+}
+export interface ProductAddedFormatter<T extends ObjectTypes = ObjectTypes> {
+    (props: ProductAddedInput<T>, event: ProductAdded): ProductAdded;
+}
+export interface ProductClickedFormatter<T extends ObjectTypes = ObjectTypes> {
+    (props: ProductClickedInput<T>, event: ProductClicked): ProductClicked;
+}
+export interface ProductListFilteredFormatter {
+    (props: ProductListFilteredInput, event: ProductListFiltered): ProductListFiltered;
+}
+export interface ProductListViewedFormatter<T extends ObjectTypes = ObjectTypes> {
+    (props: ProductListViewedInput<T>, event: ProductListViewed): ProductListViewed;
+}
+export interface ProductRemovedFormatter<T extends ObjectTypes = ObjectTypes> {
+    (props: ProductRemovedInput<T>, event: ProductRemoved): ProductRemoved;
+}
+export interface ProductViewedFormatter<T extends ObjectTypes = ObjectTypes> {
+    (props: ProductViewedInput<T>, event: ProductViewed): ProductViewed;
+}
+export interface ProductsSearchedFormatter {
+    (props: ProductsSearchedInput, event: ProductsSearched): ProductsSearched;
+}
+export interface SignedInFormatter {
+    (props: SignedInInput, event: SignedIn): SignedIn;
+}
+export interface SignedOutFormatter {
+    (props: SignedOutInput, event: SignedOut): SignedOut;
+}
+export interface SignedUpFormatter {
+    (props: SignedUpInput, event: SignedUp): SignedUp;
+}
+export interface ChordAnalyticsFormatters<T extends ObjectTypes = ObjectTypes> {
+    events?: {
+        cartViewed?: CartViewedFormatter<T>;
+        checkoutStarted?: CheckoutStartedFormatter<T>;
+        couponApplied?: CouponAppliedFormatter;
+        couponDenied?: CouponDeniedFormatter;
+        couponEntered?: CouponEnteredFormatter;
+        couponRemoved?: CouponRemovedFormatter;
+        emailCaptured?: EmailCapturedFormatter;
+        productAdded?: ProductAddedFormatter<T>;
+        productClicked?: ProductClickedFormatter<T>;
+        productListFiltered?: ProductListFilteredFormatter;
+        productListViewed?: ProductListViewedFormatter<T>;
+        productRemoved?: ProductRemovedFormatter<T>;
+        productViewed?: ProductViewedFormatter<T>;
+        productsSearched?: ProductsSearchedFormatter;
+        signedIn?: SignedInFormatter;
+        signedOut?: SignedOutFormatter;
+        signedUp?: SignedUpFormatter;
+    };
+    objects: {
+        cart: CartFormatter<T['Cart']>;
+        checkout: CheckoutFormatter<T['Checkout']>;
+        lineItem: LineItemFormatter<T['LineItem']>;
+        product: ProductFormatter<T['Product']>;
+    };
+}

package/dist/types/formatters.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -3,3 +3,4 @@ export * from './objects.js';
 export * from './typewriter.js';
 export * from './client.js';
 export * from './input.js';
+export * from './formatters.js';

package/dist/types/index.js

@@ -2,3 +2,4 @@ export * from './objects.js';
 export * from './typewriter.js';
 export * from './client.js';
 export * from './input.js';
+export * from './formatters.js';

package/dist/types/input.d.ts

@@ -1,6 +1,6 @@
-import type { AnyCart, AnyCheckout, AnyId, AnyLineItem, AnyProduct } from './client.js';
+import type { AnyId, ObjectTypes } from './client.js';
 import type { Filter, Sort } from './typewriter.js';
-export interface ProductInput {
+export interface ProductInput<ProductType extends ObjectTypes['Product'] = ObjectTypes['Product']> {
     /**
      * The position in a list of the product that was added, if relevant.
      */
@@ -8,7 +8,7 @@ export interface ProductInput {
     /**
      * Product and variant details, like product name and variant SKUs.
      */
-    product: AnyProduct;
+    product: ProductType;
     /**
      * The quantity of the product involved in the tracking event. Sometimes quantity might
      * not be relevant to an event, and can be either omitted or defaulted to `1`.
@@ -22,35 +22,35 @@ export interface ProductInput {
      */
     variantId?: AnyId;
 }
-export interface CartInput {
+export interface CartInput<CartType extends ObjectTypes['Cart'] = ObjectTypes['Cart']> {
     /**
      * The current cart.
      */
-    cart: AnyCart;
+    cart: CartType;
 }
-export interface CheckoutInput {
+export interface CheckoutInput<CheckoutType extends ObjectTypes['Checkout'] = ObjectTypes['Checkout']> {
     /**
      * The current checkout.
      */
-    checkout: AnyCheckout;
+    checkout: CheckoutType;
 }
-export interface LineItemInput {
+export interface LineItemInput<LineItemType extends ObjectTypes['LineItem'] = ObjectTypes['LineItem']> {
     /**
      * The line item before it was removed.
      */
-    lineItem: AnyLineItem;
+    lineItem: LineItemType;
 }
-export interface CartViewedInput {
+export interface CartViewedInput<T extends ObjectTypes = ObjectTypes> {
     /**
      * The current cart.
      */
-    cart: AnyCart;
+    cart: T['Cart'];
 }
-export interface CheckoutStartedInput {
+export interface CheckoutStartedInput<T extends ObjectTypes = ObjectTypes> {
     /**
      * The current checkout.
      */
-    checkout: AnyCheckout;
+    checkout: T['Checkout'];
 }
 /**
  * Coupon was applied on a user's shopping cart or order
@@ -154,21 +154,21 @@ export interface EmailCapturedInput {
     placementComponent?: string;
     placementPage?: string;
 }
-export interface ProductAddedInput {
+export interface ProductAddedInput<T extends ObjectTypes = ObjectTypes> {
     /**
      * The current cart, after the product is added.
      */
-    cart: AnyCart;
-    product: ProductInput;
+    cart: T['Cart'];
+    product: ProductInput<T['Product']>;
 }
-export interface ProductClickedInput {
+export interface ProductClickedInput<T extends ObjectTypes = ObjectTypes> {
     /**
      * The current cart.
      */
-    cart: AnyCart;
+    cart: T['Cart'];
     listId?: AnyId;
     listName?: string;
-    product: ProductInput;
+    product: ProductInput<T['Product']>;
 }
 export interface ProductListFilteredInput {
     category?: string;
@@ -177,31 +177,31 @@ export interface ProductListFilteredInput {
     filters?: Filter[];
     sorts?: Sort[];
 }
-export interface ProductListViewedInput {
+export interface ProductListViewedInput<T extends ObjectTypes = ObjectTypes> {
     category?: string;
     listId?: string;
     listName?: string;
-    products: ProductInput[];
+    products: ProductInput<T['Product']>[];
 }
-export interface ProductRemovedInput {
+export interface ProductRemovedInput<T extends ObjectTypes = ObjectTypes> {
     /**
      * The current cart.
      */
-    cart: AnyCart;
+    cart: T['Cart'];
     /**
      * The line item before it was removed.
      */
-    lineItem: AnyLineItem;
+    lineItem: T['LineItem'];
 }
-export interface ProductViewedInput {
+export interface ProductViewedInput<T extends ObjectTypes = ObjectTypes> {
     /**
      * The current cart.
      */
-    cart: AnyCart;
+    cart: T['Cart'];
     /**
      * The product being viewed.
      */
-    product: ProductInput;
+    product: ProductInput<T['Product']>;
 }
 export interface ProductsSearchedInput {
     currency?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chordcommerce/analytics",
   "description": "Chord Commerce event tracking",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "author": "Chord Commerce <help@chord.co> (https://www.chord.co)",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,6 @@
     "zod": "^3.22.4"
   },
   "devDependencies": {
-    "@chordcommerce/eslint-config": "^1.0.1",
     "@types/jest": "^29.5.11",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",