@formo/analytics 1.23.0 → 1.24.0

package/README.md

@@ -17,7 +17,7 @@
 
 ## Installation
 
-The Formo Web SDK is a Javascript library that allows you to track and analyze user interactions on your dapp. 
+The Formo Web SDK is a Javascript library that allows you to track user event data from your website and app. 
 
 You can install Formo on:
 - [Websites](https://docs.formo.so/install#website)
@@ -36,7 +36,80 @@ Learn how Formo handles [onchain attribution](https://docs.formo.so/data/attribu
 
 Join the [Formo community Slack channel](https://formo.so/slack) for help and questions.
 
+## Development
+
+### Building the SDK
+
+```bash
+pnpm install
+pnpm build
+```
+
+### Running Tests
+
+```bash
+pnpm test
+```
+
+### Publishing a New Release
+
+This project uses **OIDC Trusted Publishing** for secure, automated npm releases. No manual token management required!
+
+1. **(Optional) Preview release notes**:
+   ```bash
+   pnpm preview-release
+   ```
+   This shows what the release notes will look like based on commits since the last tag.
+
+2. **Update the version** in `package.json`:
+   ```bash
+   npm version patch  # For bug fixes (1.24.0 → 1.24.1)
+   npm version minor  # For new features (1.24.0 → 1.25.0)
+   npm version major  # For breaking changes (1.24.0 → 2.0.0)
+   ```
+   
+   > **Note**: `npm version` automatically:
+   > - Updates `package.json` with the new version
+   > - Updates `src/version.ts` with the new version (via the `version` script)
+   > - Creates a git commit with the changes
+   > - Creates a version tag (e.g., `v1.24.1`)
+
+3. **Push the commit and tag**:
+   ```bash
+   git push --follow-tags
+   # or separately:
+   # git push && git push --tags
+   ```
+   
+   > **Important**: You must push both the commit AND the tag. Use `--follow-tags` to push both in one command.
+
+4. **Automatic workflow execution**:
+   - GitHub Actions workflow triggers on the `v*` tag
+   - Builds and tests the package
+   - Publishes to npm using OIDC (no tokens needed!)
+   - Creates a GitHub release with:
+     - Changelog from git commits
+     - Installation instructions
+     - CDN usage examples
+     - SRI hash for secure CDN usage
+
+#### What Gets Published
+
+- **npm**: `@formo/analytics@<version>`
+- **GitHub Release**: Tagged release with changelog and SRI hash
+- **CDN**: `https://cdn.formo.so/analytics@<version>`
+- **Provenance**: Automatically generated cryptographic attestations
+
+#### Security Features
+
+✅ **OIDC Trusted Publishing** - No long-lived tokens  
+✅ **Automatic Provenance** - Cryptographic proof of build authenticity  
+✅ **SRI Hash** - Subresource integrity for CDN usage  
+✅ **Secure by Default** - Short-lived, workflow-specific credentials
+
+Learn more: [npm Trusted Publishing Documentation](https://docs.npmjs.com/trusted-publishers)
+
 ## Contributing
 
-[Contributions](https://github.com/getformo/sdk/blob/main/CONTRIBUTING.md) are welcome! Feel free to open fixes and feature suggestions.
+Contributions are welcome! Feel free to open fixes and feature suggestions.
 

package/dist/cjs/src/FormoAnalytics.js

@@ -126,7 +126,7 @@ var FormoAnalytics = /** @class */ (function () {
             retryCount: options.retryCount,
             maxQueueSize: options.maxQueueSize,
             flushInterval: options.flushInterval,
-        }));
+        }), options);
         // Check consent status on initialization
         if (this.hasOptedOutTracking()) {
             lib_1.logger.info("User has previously opted out of tracking");

package/dist/cjs/src/lib/event/EventFactory.d.ts

@@ -1,6 +1,9 @@
-import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, SignatureStatus, TransactionStatus } from "../../types";
+import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, Options, SignatureStatus, TransactionStatus } from "../../types";
 import { IEventFactory } from "./type";
 declare class EventFactory implements IEventFactory {
+    private options?;
+    private compiledPathPattern?;
+    constructor(options?: Options);
     private getTimezone;
     private getLocation;
     private getLanguage;
@@ -8,6 +11,7 @@ declare class EventFactory implements IEventFactory {
     private extractUTMParameters;
     private extractReferralParameter;
     private getTrafficSources;
+    private getScreen;
     private generateContext;
     /**
      * Add any missing default page properties using values from options and defaults

package/dist/cjs/src/lib/event/EventFactory.js

@@ -59,13 +59,14 @@ var validators_1 = require("../../validators");
 var logger_1 = require("../logger");
 var mergeDeepRight_1 = __importDefault(require("../ramda/mergeDeepRight"));
 var storage_1 = require("../storage");
-var version_1 = require("../version");
+var version_1 = require("../../version");
 var constants_2 = require("./constants");
 var utils_2 = require("./utils");
 var browsers_1 = require("../browser/browsers");
 var EventFactory = /** @class */ (function () {
-    function EventFactory() {
+    function EventFactory(options) {
         var _this = this;
+        var _a;
         this.extractUTMParameters = function (url) {
             var result = {
                 utm_campaign: "",
@@ -87,14 +88,33 @@ var EventFactory = /** @class */ (function () {
             return result;
         };
         this.extractReferralParameter = function (urlObj) {
-            var _a;
-            var referralParams = ["ref", "referral", "refcode"];
+            var _a, _b, _c;
+            // Strategy: Check query params first, then check path pattern if configured
+            // Query params logic:
+            // - If no referral config exists → use defaults
+            // - If referral config exists but queryParams is undefined → use defaults
+            // - If referral config exists with queryParams → use those
+            var defaultParams = ["ref", "referral", "refcode"];
+            var referralParams = !((_a = _this.options) === null || _a === void 0 ? void 0 : _a.referral)
+                ? defaultParams // No referral config at all → use defaults
+                : ((_b = _this.options.referral.queryParams) !== null && _b !== void 0 ? _b : defaultParams); // Has config → use queryParams or defaults
+            // Check query parameters (if any configured)
             for (var _i = 0, referralParams_1 = referralParams; _i < referralParams_1.length; _i++) {
                 var param = referralParams_1[_i];
-                var value = (_a = urlObj.searchParams.get(param)) === null || _a === void 0 ? void 0 : _a.trim();
+                var value = (_c = urlObj.searchParams.get(param)) === null || _c === void 0 ? void 0 : _c.trim();
                 if (value)
                     return value;
             }
+            // Check URL path pattern if configured
+            if (_this.compiledPathPattern) {
+                var pathname = urlObj.pathname;
+                var match = pathname.match(_this.compiledPathPattern);
+                if (match && match[1]) {
+                    var referralCode = match[1].trim();
+                    if (referralCode)
+                        return referralCode;
+                }
+            }
             return "";
         };
         this.getTrafficSources = function (url) {
@@ -148,6 +168,16 @@ var EventFactory = /** @class */ (function () {
             }
             return pageProps;
         };
+        this.options = options;
+        // Compile regex pattern once for better performance
+        if ((_a = options === null || options === void 0 ? void 0 : options.referral) === null || _a === void 0 ? void 0 : _a.pathPattern) {
+            try {
+                this.compiledPathPattern = new RegExp(options.referral.pathPattern);
+            }
+            catch (error) {
+                logger_1.logger.warn("Invalid referral path pattern: ".concat(options.referral.pathPattern, ". Error: ").concat(error));
+            }
+        }
     }
     EventFactory.prototype.getTimezone = function () {
         try {
@@ -184,6 +214,31 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.getLibraryVersion = function () {
         return version_1.version;
     };
+    // Get screen dimensions and pixel density
+    // Returns safe defaults if any error occurs to ensure event creation continues
+    EventFactory.prototype.getScreen = function () {
+        var _a, _b;
+        var safeDefaults = {
+            screen_width: 0,
+            screen_height: 0,
+            screen_density: 1,
+            viewport_width: 0,
+            viewport_height: 0,
+        };
+        try {
+            return {
+                screen_width: ((_a = globalThis.screen) === null || _a === void 0 ? void 0 : _a.width) || 0,
+                screen_height: ((_b = globalThis.screen) === null || _b === void 0 ? void 0 : _b.height) || 0,
+                screen_density: globalThis.devicePixelRatio || 1,
+                viewport_width: globalThis.innerWidth || 0,
+                viewport_height: globalThis.innerHeight || 0,
+            };
+        }
+        catch (error) {
+            logger_1.logger.error("Error resolving screen properties:", error);
+            return safeDefaults;
+        }
+    };
     // Contextual fields that are automatically collected and populated by the Formo SDK
     EventFactory.prototype.generateContext = function (context) {
         return __awaiter(this, void 0, void 0, function () {
@@ -199,7 +254,7 @@ var EventFactory = /** @class */ (function () {
                         timezone = this.getTimezone();
                         location = this.getLocation();
                         library_version = this.getLibraryVersion();
-                        defaultContext = __assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(globalThis.location.href)), { page_path: path, page_title: document.title, page_url: globalThis.location.href, library_name: "Formo Web SDK", library_version: library_version, browser: browserName });
+                        defaultContext = __assign(__assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(globalThis.location.href)), { page_path: path, page_title: document.title, page_url: globalThis.location.href, library_name: "Formo Web SDK", library_version: library_version, browser: browserName }), this.getScreen());
                         mergedContext = (0, mergeDeepRight_1.default)(defaultContext, context || {});
                         return [2 /*return*/, mergedContext];
                 }

package/dist/cjs/src/lib/event/EventManager.d.ts

@@ -1,4 +1,4 @@
-import { Address, APIEvent } from "../../types";
+import { Address, APIEvent, Options } from "../../types";
 import { IEventQueue } from "../queue";
 import { IEventFactory, IEventManager } from "./type";
 /**
@@ -10,8 +10,9 @@ declare class EventManager implements IEventManager {
     /**
      *
      * @param eventQueue Event queue instance
+     * @param options Optional configuration (referral parsing, etc.)
      */
-    constructor(eventQueue: IEventQueue);
+    constructor(eventQueue: IEventQueue, options?: Options);
     /**
      * Consumes a new incoming event
      * @param event Incoming event data

package/dist/cjs/src/lib/event/EventManager.js

@@ -58,10 +58,11 @@ var EventManager = /** @class */ (function () {
     /**
      *
      * @param eventQueue Event queue instance
+     * @param options Optional configuration (referral parsing, etc.)
      */
-    function EventManager(eventQueue) {
+    function EventManager(eventQueue, options) {
         this.eventQueue = eventQueue;
-        this.eventFactory = new EventFactory_1.EventFactory();
+        this.eventFactory = new EventFactory_1.EventFactory(options);
     }
     /**
      * Consumes a new incoming event

package/dist/cjs/src/types/base.d.ts

@@ -94,6 +94,24 @@ export interface AutocaptureOptions {
      */
     chain?: boolean;
 }
+/**
+ * Configuration options for referral parameter parsing
+ */
+export interface ReferralOptions {
+    /**
+     * Custom query parameter names to check for referral codes
+     * @default ["ref", "referral", "refcode"]
+     * @example ["via", "referrer", "source"] - will check ?via=CODE, ?referrer=CODE, ?source=CODE
+     */
+    queryParams?: string[];
+    /**
+     * URL path pattern to extract referral code from
+     * Should be a regex string that matches the path segment containing the referral code
+     * The first capture group will be used as the referral code
+     * @example "/r/([^/]+)" - will extract "01K17FKB" from "https://glider.fi/r/01K17FKB"
+     */
+    pathPattern?: string;
+}
 export interface Options {
     provider?: EIP1193Provider;
     tracking?: boolean | TrackingOptions;
@@ -122,6 +140,12 @@ export interface Options {
         enabled?: boolean;
         levels?: LogLevel[];
     };
+    /**
+     * Configuration for referral parameter parsing from URLs
+     * Allows customizing how referral codes are detected from query parameters and URL paths
+     * @example { queryParams: ["via"], pathPattern: "/r/([^/]+)" }
+     */
+    referral?: ReferralOptions;
     ready?: (formo: IFormoAnalytics) => void;
 }
 export interface FormoAnalyticsProviderProps {

package/dist/cjs/src/version.d.ts

@@ -0,0 +1,2 @@
+export declare const version = "1.24.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/cjs/src/version.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.version = void 0;
+// This file is auto-generated by scripts/update-version.js during npm version
+// Do not edit manually - it will be overwritten
+exports.version = '1.24.0';
+//# sourceMappingURL=version.js.map

package/dist/esm/src/FormoAnalytics.js

@@ -123,7 +123,7 @@ var FormoAnalytics = /** @class */ (function () {
             retryCount: options.retryCount,
             maxQueueSize: options.maxQueueSize,
             flushInterval: options.flushInterval,
-        }));
+        }), options);
         // Check consent status on initialization
         if (this.hasOptedOutTracking()) {
             logger.info("User has previously opted out of tracking");

package/dist/esm/src/lib/event/EventFactory.d.ts

@@ -1,6 +1,9 @@
-import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, SignatureStatus, TransactionStatus } from "../../types";
+import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, Options, SignatureStatus, TransactionStatus } from "../../types";
 import { IEventFactory } from "./type";
 declare class EventFactory implements IEventFactory {
+    private options?;
+    private compiledPathPattern?;
+    constructor(options?: Options);
     private getTimezone;
     private getLocation;
     private getLanguage;
@@ -8,6 +11,7 @@ declare class EventFactory implements IEventFactory {
     private extractUTMParameters;
     private extractReferralParameter;
     private getTrafficSources;
+    private getScreen;
     private generateContext;
     /**
      * Add any missing default page properties using values from options and defaults

package/dist/esm/src/lib/event/EventFactory.js

@@ -53,13 +53,14 @@ import { isUndefined } from "../../validators";
 import { logger } from "../logger";
 import mergeDeepRight from "../ramda/mergeDeepRight";
 import { session } from "../storage";
-import { version } from "../version";
+import { version } from "../../version";
 import { CHANNEL, VERSION } from "./constants";
 import { generateAnonymousId } from "./utils";
 import { detectBrowser } from "../browser/browsers";
 var EventFactory = /** @class */ (function () {
-    function EventFactory() {
+    function EventFactory(options) {
         var _this = this;
+        var _a;
         this.extractUTMParameters = function (url) {
             var result = {
                 utm_campaign: "",
@@ -81,14 +82,33 @@ var EventFactory = /** @class */ (function () {
             return result;
         };
         this.extractReferralParameter = function (urlObj) {
-            var _a;
-            var referralParams = ["ref", "referral", "refcode"];
+            var _a, _b, _c;
+            // Strategy: Check query params first, then check path pattern if configured
+            // Query params logic:
+            // - If no referral config exists → use defaults
+            // - If referral config exists but queryParams is undefined → use defaults
+            // - If referral config exists with queryParams → use those
+            var defaultParams = ["ref", "referral", "refcode"];
+            var referralParams = !((_a = _this.options) === null || _a === void 0 ? void 0 : _a.referral)
+                ? defaultParams // No referral config at all → use defaults
+                : ((_b = _this.options.referral.queryParams) !== null && _b !== void 0 ? _b : defaultParams); // Has config → use queryParams or defaults
+            // Check query parameters (if any configured)
             for (var _i = 0, referralParams_1 = referralParams; _i < referralParams_1.length; _i++) {
                 var param = referralParams_1[_i];
-                var value = (_a = urlObj.searchParams.get(param)) === null || _a === void 0 ? void 0 : _a.trim();
+                var value = (_c = urlObj.searchParams.get(param)) === null || _c === void 0 ? void 0 : _c.trim();
                 if (value)
                     return value;
             }
+            // Check URL path pattern if configured
+            if (_this.compiledPathPattern) {
+                var pathname = urlObj.pathname;
+                var match = pathname.match(_this.compiledPathPattern);
+                if (match && match[1]) {
+                    var referralCode = match[1].trim();
+                    if (referralCode)
+                        return referralCode;
+                }
+            }
             return "";
         };
         this.getTrafficSources = function (url) {
@@ -142,6 +162,16 @@ var EventFactory = /** @class */ (function () {
             }
             return pageProps;
         };
+        this.options = options;
+        // Compile regex pattern once for better performance
+        if ((_a = options === null || options === void 0 ? void 0 : options.referral) === null || _a === void 0 ? void 0 : _a.pathPattern) {
+            try {
+                this.compiledPathPattern = new RegExp(options.referral.pathPattern);
+            }
+            catch (error) {
+                logger.warn("Invalid referral path pattern: ".concat(options.referral.pathPattern, ". Error: ").concat(error));
+            }
+        }
     }
     EventFactory.prototype.getTimezone = function () {
         try {
@@ -178,6 +208,31 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.getLibraryVersion = function () {
         return version;
     };
+    // Get screen dimensions and pixel density
+    // Returns safe defaults if any error occurs to ensure event creation continues
+    EventFactory.prototype.getScreen = function () {
+        var _a, _b;
+        var safeDefaults = {
+            screen_width: 0,
+            screen_height: 0,
+            screen_density: 1,
+            viewport_width: 0,
+            viewport_height: 0,
+        };
+        try {
+            return {
+                screen_width: ((_a = globalThis.screen) === null || _a === void 0 ? void 0 : _a.width) || 0,
+                screen_height: ((_b = globalThis.screen) === null || _b === void 0 ? void 0 : _b.height) || 0,
+                screen_density: globalThis.devicePixelRatio || 1,
+                viewport_width: globalThis.innerWidth || 0,
+                viewport_height: globalThis.innerHeight || 0,
+            };
+        }
+        catch (error) {
+            logger.error("Error resolving screen properties:", error);
+            return safeDefaults;
+        }
+    };
     // Contextual fields that are automatically collected and populated by the Formo SDK
     EventFactory.prototype.generateContext = function (context) {
         return __awaiter(this, void 0, void 0, function () {
@@ -193,7 +248,7 @@ var EventFactory = /** @class */ (function () {
                         timezone = this.getTimezone();
                         location = this.getLocation();
                         library_version = this.getLibraryVersion();
-                        defaultContext = __assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(globalThis.location.href)), { page_path: path, page_title: document.title, page_url: globalThis.location.href, library_name: "Formo Web SDK", library_version: library_version, browser: browserName });
+                        defaultContext = __assign(__assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(globalThis.location.href)), { page_path: path, page_title: document.title, page_url: globalThis.location.href, library_name: "Formo Web SDK", library_version: library_version, browser: browserName }), this.getScreen());
                         mergedContext = mergeDeepRight(defaultContext, context || {});
                         return [2 /*return*/, mergedContext];
                 }

package/dist/esm/src/lib/event/EventManager.d.ts

@@ -1,4 +1,4 @@
-import { Address, APIEvent } from "../../types";
+import { Address, APIEvent, Options } from "../../types";
 import { IEventQueue } from "../queue";
 import { IEventFactory, IEventManager } from "./type";
 /**
@@ -10,8 +10,9 @@ declare class EventManager implements IEventManager {
     /**
      *
      * @param eventQueue Event queue instance
+     * @param options Optional configuration (referral parsing, etc.)
      */
-    constructor(eventQueue: IEventQueue);
+    constructor(eventQueue: IEventQueue, options?: Options);
     /**
      * Consumes a new incoming event
      * @param event Incoming event data

package/dist/esm/src/lib/event/EventManager.js

@@ -55,10 +55,11 @@ var EventManager = /** @class */ (function () {
     /**
      *
      * @param eventQueue Event queue instance
+     * @param options Optional configuration (referral parsing, etc.)
      */
-    function EventManager(eventQueue) {
+    function EventManager(eventQueue, options) {
         this.eventQueue = eventQueue;
-        this.eventFactory = new EventFactory();
+        this.eventFactory = new EventFactory(options);
     }
     /**
      * Consumes a new incoming event

package/dist/esm/src/types/base.d.ts

@@ -94,6 +94,24 @@ export interface AutocaptureOptions {
      */
     chain?: boolean;
 }
+/**
+ * Configuration options for referral parameter parsing
+ */
+export interface ReferralOptions {
+    /**
+     * Custom query parameter names to check for referral codes
+     * @default ["ref", "referral", "refcode"]
+     * @example ["via", "referrer", "source"] - will check ?via=CODE, ?referrer=CODE, ?source=CODE
+     */
+    queryParams?: string[];
+    /**
+     * URL path pattern to extract referral code from
+     * Should be a regex string that matches the path segment containing the referral code
+     * The first capture group will be used as the referral code
+     * @example "/r/([^/]+)" - will extract "01K17FKB" from "https://glider.fi/r/01K17FKB"
+     */
+    pathPattern?: string;
+}
 export interface Options {
     provider?: EIP1193Provider;
     tracking?: boolean | TrackingOptions;
@@ -122,6 +140,12 @@ export interface Options {
         enabled?: boolean;
         levels?: LogLevel[];
     };
+    /**
+     * Configuration for referral parameter parsing from URLs
+     * Allows customizing how referral codes are detected from query parameters and URL paths
+     * @example { queryParams: ["via"], pathPattern: "/r/([^/]+)" }
+     */
+    referral?: ReferralOptions;
     ready?: (formo: IFormoAnalytics) => void;
 }
 export interface FormoAnalyticsProviderProps {

package/dist/esm/src/version.d.ts

@@ -0,0 +1,2 @@
+export declare const version = "1.24.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/esm/src/version.js

@@ -0,0 +1,4 @@
+// This file is auto-generated by scripts/update-version.js during npm version
+// Do not edit manually - it will be overwritten
+export var version = '1.24.0';
+//# sourceMappingURL=version.js.map