@surfside/surfside-events 0.0.1

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2021 Michael Blanche, Surfside Solutions Inc, Snowplow Analytics Ltd, 2010 Anthon Pang
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,45 @@
+# Surfside Digital Analytics
+
+### Setup repository
+
+```bash
+clone repo
+npm install -g @microsoft/rush 
+rush update
+```
+
+## Package Installation
+
+With npm:
+
+```bash
+npm install @surfside/surfside-events
+```
+
+## Usage
+
+Use the available functions from this package to track to all trackers which have been initialized with this plugin:
+
+```js
+import { addProduct, addPromo, setAction } from '@surfside/browser-plugin-surfside';
+
+addProduct({
+  id: 'P12345',
+  name: 'Blue T-Shirt',
+  list: 'Search Results',
+  brand: 'The T-Shirt Company',
+  category: 'Apparel/T-Shirts',
+  variant: 'Black',
+  quantity: 1,
+});
+
+addPromo({
+  id: 'PROMO_1234',
+  name: 'Summer Sale',
+  creative: 'summer_banner2',
+  position: 'banner_slot1',
+});
+
+setAction({ action: 'purchase' });
+
+```

package/dist/index.module.d.ts

@@ -0,0 +1,245 @@
+import { BrowserPlugin } from '@surfside/browser-core';
+import { CommonEventProperties } from '@surfside/digital-core';
+declare function SurfsideCommercePlugin(): BrowserPlugin;
+/**
+ * A Commerce Action
+ * Used when tracking an Surfside Commerce Action with all stored Commerce contexts
+ */
+interface commerceAction {
+    /** Actions specify how to interpret product and promotion data */
+    action?: string;
+}
+/**
+ * Track a Commerce Action with all stored Commerce contexts
+ *
+ * @param event
+ * @param trackers
+ */
+declare function setCommerceAction(event?: commerceAction & CommonEventProperties, trackers?: Array<string>): void;
+/**
+ * The Commerce Transaction Context
+ * Represents information about an ecommerce related action that has taken place.
+ */
+interface commerceTransactionContext {
+    /** The transaction id */
+    id?: string;
+    /** The store of affiliation from which this transaction occured */
+    affiliation?: string;
+    /** Specifies the total revenue or grand total associated with the transaction */
+    revenue?: string;
+    /** The total tax associated with the transaction. */
+    tax?: number;
+    /** The shipping cost associated with the transaction. */
+    shipping?: number;
+    /** The transaction coupon redeemed with the transaction. */
+    coupon?: string;
+    /** The list that the associated products belong to. */
+    list?: string;
+    /**	A number representing a step in the checkout process. Optional on `checkout` actions.  */
+    step?: number;
+    /** Additional field for checkout and checkout_option actions that can describe option information on the checkout page, like selected payment method. */
+    option?: string;
+    /** The currency of the transactoin */
+    currency?: string;
+}
+/**
+ * Adds a Commerce Transaction Context to an Action
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+declare function addTransaction(context?: commerceTransactionContext, trackers?: Array<string>): void;
+/**
+ * A Commerce Impression Context
+ */
+interface commerceImpressionContext {
+    /** The product ID or SKU */
+    id?: string;
+    /** The name of the product */
+    name?: string;
+    /** The list or collection to which the product belongs */
+    list?: string;
+    /** The brand associated with the product */
+    brand?: string;
+    /** The category to which the product belongs */
+    category?: string;
+    /** The variant of the product */
+    variant?: string;
+    /** The product's position in a list or collection */
+    position?: number;
+    /** The price of a product  */
+    price?: string;
+    /** The currency of a product  */
+    currency?: string;
+}
+/**
+ * Adds a Commerce Impression Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+declare function addImpression(context?: commerceImpressionContext, trackers?: Array<string>): void;
+/**
+ * A Commerce Product Context
+ */
+interface commerceProductContext {
+    /** The product ID or SKU */
+    id?: string;
+    /** The name of the product */
+    name?: string;
+    /** The list or collection to which the product belongs */
+    list?: string;
+    /** The brand associated with the product */
+    brand?: string;
+    /** The category to which the product belongs  */
+    category?: string;
+    /** The variant of the product */
+    variant?: string;
+    /** The price of a product */
+    price?: number;
+    /** The quantity of a product */
+    quantity?: number;
+    /** The coupon code associated with a product */
+    coupon?: string;
+    /** The product's position in a list or collection */
+    position?: number;
+    /** The currency of the product */
+    currency?: string;
+}
+/**
+ * Adds a Commerce Product Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+declare function addProduct(context?: commerceProductContext, trackers?: Array<string>): void;
+/**
+ * A Commerce Promotion Context
+ */
+interface commercePromoContext {
+    /** The promotion ID */
+    id?: string;
+    /** The name of the promotion */
+    name?: string;
+    /** The creative associated with the promotion */
+    creative?: string;
+    /** The position of the creative */
+    position?: string;
+    /** The currency of the product */
+    currency?: string;
+}
+/**
+ * Adds a Commerce Promotion Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+declare function addPromotion(context?: commercePromoContext, trackers?: Array<string>): void;
+/** SURFSIDE CORE CONTEXTS **/
+/**
+ * A Surfside Source Context
+ */
+interface sourceContext {
+    /** The Account ID */
+    accountId?: string;
+    /** The Source ID */
+    sourceId?: string;
+}
+/**
+ * Adds a Surfside Source Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+declare function source(context?: sourceContext, trackers?: Array<string>): void;
+/**
+ * A Surfside Segment Context
+ */
+interface segmentContext {
+    /** The Segment ID */
+    segmentId?: string;
+    /** The Segment Value */
+    segmentVal?: string;
+}
+/**
+ * Adds a Surfside Segment Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+declare function segment(context?: segmentContext, trackers?: Array<string>): void;
+/**
+ * A Surfside User Context
+ */
+interface userContext {
+    /** The address of the user */
+    address?: string;
+    /** The age of the user */
+    age?: string;
+    /** The company of the user */
+    company?: string;
+    /** The created timstamp of the user */
+    createdAt?: string;
+    /** The date of birth of the user */
+    dateOfBirth?: string;
+    /** The email of the user */
+    email?: string;
+    /** The first name of the user */
+    firstName?: string;
+    /** The gender of the user */
+    gender?: string;
+    /** The user ID of the user */
+    userId?: string;
+    /** The last name of the user */
+    lastName?: string;
+}
+/**
+ * Adds a Surfside User Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+declare function setUser(context?: userContext, trackers?: Array<string>): void;
+/**
+ * A Surfside User Context
+ */
+interface identifyUserContext {
+    /** The ID of the user */
+    id?: string;
+    /** The address of the user */
+    address?: string;
+    /** The age of the user */
+    age?: string;
+    /** The company of the user */
+    company?: string;
+    /** The created timstamp of the user */
+    createdAt?: string;
+    /** The date of birth of the user */
+    dateOfBirth?: string;
+    /** The email of the user */
+    email?: string;
+    /** The first name of the user */
+    firstName?: string;
+    /** The gender of the user */
+    gender?: string;
+    /** The user ID of the user */
+    userId?: string;
+    /** The last name of the user */
+    lastName?: string;
+    /** The name of the user */
+    name?: string;
+    /** The phone of the user */
+    phone?: string;
+    /** The title of the user */
+    title?: string;
+    /** The username of the user */
+    username?: string;
+}
+/**
+ * Adds a Surfside  Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+declare function identifyUser(context?: identifyUserContext, trackers?: Array<string>): void;
+export { SurfsideCommercePlugin, commerceAction, setCommerceAction, commerceTransactionContext, addTransaction, commerceImpressionContext, addImpression, commerceProductContext, addProduct, commercePromoContext, addPromotion, sourceContext, source, segmentContext, segment, userContext, setUser, identifyUserContext, identifyUser };

package/dist/index.module.js

@@ -0,0 +1,298 @@
+/*!
+ * Surfside Digital Analytics v0.0.1 (https://surfside.io)
+ * Copyright 2022 Surfside Solutions Inc, Snowplow Analytics Ltd, 2010 Anthon Pang
+ */
+
+import { dispatchToTrackersInCollection, parseAndValidateFloat, parseAndValidateInt } from '@surfside/browser-core';
+import { buildSelfDescribingEvent } from '@surfside/digital-core';
+
+/*
+ * Copyright (c) 2022 Surfside Solutions Inc, Snowplow Analytics Ltd, 2010 Anthon Pang
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ *    list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+var _trackers = {};
+var _context = {};
+function SurfsideCommercePlugin() {
+    return {
+        activateBrowserPlugin: function (tracker) {
+            _trackers[tracker.id] = tracker;
+            _context[tracker.id] = [];
+        }
+    };
+}
+/**
+ * Track a Commerce Action with all stored Commerce contexts
+ *
+ * @param event
+ * @param trackers
+ */
+function setCommerceAction(event, trackers) {
+    if (event === void 0) { event = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    dispatchToTrackersInCollection(trackers, _trackers, function (t) {
+        var combinedContexts = _context[t.id].concat(event.context || []);
+        _context[t.id].length = 0;
+        t.core.track(buildSelfDescribingEvent({
+            event: {
+                schema: 'iglu:io.surfside.commerce/action/jsonschema/1-0-0',
+                data: {
+                    action: event
+                }
+            }
+        }), combinedContexts, event.timestamp);
+    });
+}
+/**
+ * Adds a Commerce Transaction Context to an Action
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+function addTransaction(context, trackers) {
+    if (context === void 0) { context = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    var id = context.id, affiliation = context.affiliation, revenue = context.revenue, tax = context.tax, shipping = context.shipping, coupon = context.coupon, list = context.list, step = context.step, option = context.option, currency = context.currency;
+    trackers.forEach(function (trackerId) {
+        if (_context[trackerId]) {
+            _context[trackerId].push({
+                schema: 'iglu:io.surfside.commerce/transaction/jsonschema/1-0-0',
+                data: {
+                    id: id,
+                    affiliation: affiliation,
+                    revenue: parseAndValidateFloat(revenue),
+                    tax: parseAndValidateFloat(tax),
+                    shipping: parseAndValidateFloat(shipping),
+                    coupon: coupon,
+                    list: list,
+                    step: parseAndValidateInt(step),
+                    option: option,
+                    currency: currency
+                }
+            });
+        }
+    });
+}
+/**
+ * Adds a Commerce Impression Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+function addImpression(context, trackers) {
+    if (context === void 0) { context = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    var id = context.id, name = context.name, list = context.list, brand = context.brand, category = context.category, variant = context.variant, position = context.position, price = context.price, currency = context.currency;
+    trackers.forEach(function (trackerId) {
+        if (_context[trackerId]) {
+            _context[trackerId].push({
+                schema: 'iglu:io.surfside.commerce/impression/jsonschema/1-0-0',
+                data: {
+                    id: id,
+                    name: name,
+                    list: list,
+                    brand: brand,
+                    category: category,
+                    variant: variant,
+                    position: parseAndValidateInt(position),
+                    price: parseAndValidateFloat(price),
+                    currency: currency
+                }
+            });
+        }
+    });
+}
+/**
+ * Adds a Commerce Product Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+function addProduct(context, trackers) {
+    if (context === void 0) { context = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    var id = context.id, name = context.name, list = context.list, brand = context.brand, category = context.category, variant = context.variant, price = context.price, quantity = context.quantity, coupon = context.coupon, position = context.position, currency = context.currency;
+    trackers.forEach(function (trackerId) {
+        if (_context[trackerId]) {
+            _context[trackerId].push({
+                schema: 'iglu:io.surfside.commerce/product/jsonschema/1-0-0',
+                data: {
+                    id: id,
+                    name: name,
+                    list: list,
+                    brand: brand,
+                    category: category,
+                    variant: variant,
+                    price: parseAndValidateFloat(price),
+                    quantity: parseAndValidateInt(quantity),
+                    coupon: coupon,
+                    position: parseAndValidateInt(position),
+                    currency: currency
+                }
+            });
+        }
+    });
+}
+/**
+ * Adds a Commerce Promotion Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+function addPromotion(context, trackers) {
+    if (context === void 0) { context = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    var id = context.id, name = context.name, creative = context.creative, position = context.position, currency = context.currency;
+    trackers.forEach(function (trackerId) {
+        if (_context[trackerId]) {
+            _context[trackerId].push({
+                schema: 'iglu:io.surfside.commerce/promotion/jsonschema/1-0-0',
+                data: {
+                    id: id,
+                    name: name,
+                    creative: creative,
+                    position: position,
+                    currency: currency
+                }
+            });
+        }
+    });
+}
+/**
+ * Adds a Surfside Source Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+function source(context, trackers) {
+    if (context === void 0) { context = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    var accountId = context.accountId, sourceId = context.sourceId;
+    dispatchToTrackersInCollection(trackers, _trackers, function (t) {
+        _context[t.id].length = 0;
+        t.core.addGlobalContexts([
+            {
+                schema: 'iglu:io.surfside/context/jsonschema/1-0-0',
+                data: {
+                    accountId: accountId,
+                    sourceId: sourceId
+                }
+            },
+        ]);
+    });
+}
+/**
+ * Adds a Surfside Segment Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+function segment(context, trackers) {
+    if (context === void 0) { context = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    var segmentId = context.segmentId, segmentVal = context.segmentVal;
+    dispatchToTrackersInCollection(trackers, _trackers, function (t) {
+        _context[t.id].length = 0;
+        t.core.addGlobalContexts([
+            {
+                schema: 'iglu:io.surfside/segment/jsonschema/1-0-0',
+                data: {
+                    segmentId: segmentId,
+                    segmentVal: segmentVal
+                }
+            },
+        ]);
+    });
+}
+/**
+ * Adds a Surfside User Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+function setUser(context, trackers) {
+    if (context === void 0) { context = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    var address = context.address, age = context.age, company = context.company, createdAt = context.createdAt, dateOfBirth = context.dateOfBirth, email = context.email, firstName = context.firstName, gender = context.gender, userId = context.userId, lastName = context.lastName;
+    trackers.forEach(function (trackerId) {
+        if (_context[trackerId]) {
+            _context[trackerId].push({
+                schema: 'iglu:io.surfside.identity/user/jsonschema/1-0-0',
+                data: {
+                    address: address,
+                    age: age,
+                    company: company,
+                    createdAt: createdAt,
+                    dateOfBirth: dateOfBirth,
+                    email: email,
+                    firstName: firstName,
+                    gender: gender,
+                    userId: userId,
+                    lastName: lastName
+                }
+            });
+        }
+    });
+}
+/**
+ * Adds a Surfside  Context
+ *
+ * @param context - The context to be stored
+ * @param trackers - The tracker identifiers which the context will be stored against
+ */
+function identifyUser(context, trackers) {
+    if (context === void 0) { context = {}; }
+    if (trackers === void 0) { trackers = Object.keys(_trackers); }
+    var id = context.id, address = context.address, age = context.age, company = context.company, createdAt = context.createdAt, dateOfBirth = context.dateOfBirth, email = context.email, firstName = context.firstName, gender = context.gender, userId = context.userId, lastName = context.lastName, name = context.name, phone = context.phone, title = context.title, username = context.username;
+    trackers.forEach(function (trackerId) {
+        if (_context[trackerId]) {
+            _context[trackerId].push({
+                schema: 'iglu:io.surfside.identity/user/jsonschema/1-0-0',
+                data: {
+                    id: id,
+                    address: address,
+                    age: age,
+                    company: company,
+                    createdAt: createdAt,
+                    dateOfBirth: dateOfBirth,
+                    email: email,
+                    firstName: firstName,
+                    gender: gender,
+                    userId: userId,
+                    lastName: lastName,
+                    name: name,
+                    phone: phone,
+                    title: title,
+                    username: username
+                }
+            });
+        }
+    });
+}
+
+export { SurfsideCommercePlugin, addImpression, addProduct, addPromotion, addTransaction, identifyUser, segment, setCommerceAction, setUser, source };
+//# sourceMappingURL=index.module.js.map