P-1925 P-1926 Enhance analytics API with optional parameters and referral config (#2)

* Fix API signature inconsistencies and code quality issues for web SDK parity

- Make signature() chainId optional to match web SDK (chain-agnostic signatures)
- Add function_name and function_args to transaction() for contract call tracking
- Add optional category parameter to screen() matching web page() API
- Consolidate FormoAnalyticsProviderProps into single complete type
- Replace require() with static import in setTrafficSourceFromUrl
- Add errorHandler option to Options for global error handling
- Add ReferralOptions for configurable referral query parameter parsing
- Update tests for new optional chainId behavior

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Add package-lock.json for dependency version locking

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Fix screen() test to pass properties as third arg after category param

The screen() signature changed to screen(name, category?, properties?, ...),
so the test needs to pass undefined for category before the properties object.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Address review feedback: backward-compat screen(), implement pathPattern, dedup refParams

- Revert screen() to original (name, properties?, context?, callback?) signature
  to avoid breaking existing callers. Category is passed via properties.category.
- Implement pathPattern support in parseTrafficSource so ReferralOptions.pathPattern
  actually extracts referral codes from URL paths via regex capture group.
- Deduplicate referral query params using Set to avoid redundant lookups.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Guard errorHandler callback with try/catch to prevent consumer errors from bubbling

A throwing errorHandler would cause trackEvent to reject, turning telemetry
failures into app-level failures. Now secondary handler errors are logged
instead of propagated.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Add category as positional parameter to screen() for web SDK parity

Since this is v1.0.0 with no existing consumers, use the clean signature
screen(name, category?, properties?, context?, callback?) instead of the
properties.category workaround. Matches web SDK's page(category?, name?).

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Add application lifecycle event tracking (installed, updated, opened, backgrounded)

Implements the Segment/RudderStack mobile lifecycle spec using a JS-side
approach (no native modules required, works in Expo Go):

- Application Installed: first launch (no stored version in AsyncStorage)
- Application Updated: version or build changed from stored values
- Application Opened: every cold start (from_background: false) and
  foreground return (from_background: true), includes deep link URL
- Application Backgrounded: app goes to background

Detection compares stored app version/build in AsyncStorage against
current values from react-native-device-info, expo-application, or
options.app config.

Controlled via autocapture.lifecycle option (default: true).
Adds AppLifecycleManager with its own AppState listener, separate from
EventQueue's flush-on-background listener.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Guard lifecycle install/update detection against non-persistent storage

When AsyncStorage is not provided, the SDK falls back to MemoryStorage
which is empty on every cold start. Without this guard, detectInstallOrUpdate
would false-positive as "Application Installed" on every launch.

Now checks if AsyncStorage adapter is actually available before comparing
stored version/build. Skips install/update events (with warning) if only
MemoryStorage is available. Application Opened/Backgrounded still fire.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Fix persistent storage check that was defeated by MemoryStorage fallback

StorageManager.getStorage("asyncStorage") silently falls back to
MemoryStorage when AsyncStorage hasn't been initialized, and
MemoryStorage.isAvailable() always returns true. This made the
lifecycle guard ineffective — install events would still fire on
every cold start without AsyncStorage.

Fix: Add StorageManager.hasPersistentStorage() that checks if an
initialized AsyncStorage adapter exists in the storages map, bypassing
the fallback logic in getStorage().

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Await async storage persistence for app version to prevent duplicate install events

storage().set() writes to the in-memory cache synchronously but persists
to AsyncStorage asynchronously without being awaited. If the app crashes
or is force-quit before the async write completes, the version data is
lost and the next launch would fire a duplicate "Application Installed"
event. Switch to awaiting setAsync() to ensure persistence completes.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Wrap lifecycle init in try-catch to prevent SDK init failure

A transient AsyncStorage write failure in lifecycle tracking (e.g.,
storage full, permission error) would reject the init() promise and
leave the SDK uninitialized with no-op methods for the entire session.
Lifecycle tracking is non-critical — it should not block the core
analytics SDK from functioning.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Fix hasPersistentStorage() to use instanceof check against fallback

getStorage("asyncStorage") caches a MemoryStorage fallback at the
asyncStorage slot when AsyncStorage hasn't been initialized. The
previous check (stored !== undefined && stored.isAvailable()) would
pass for this cached MemoryStorage since MemoryStorage.isAvailable()
always returns true.

Use instanceof AsyncStorageAdapter to ensure we're checking the real
persistent adapter, not a MemoryStorage fallback cached at that slot.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Preserve function_args key casing from toSnakeCase conversion

The toSnakeCase utility recursively converts all object keys, which
corrupts function_args values that represent smart contract ABI
parameter names (e.g., "tokenId" becomes "token_id"). Extract
function_args before conversion and re-attach after to preserve
the original key casing.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

* Apply pnpm supply chain security recommendations

Upgrade pnpm from 9.0.0 to 10.27.0 and add security settings
per https://pnpm.io/supply-chain-security:

1. onlyBuiltDependencies: [] — block lifecycle scripts by default,
   only explicitly approved packages can run postinstall scripts
2. blockExoticSubdeps: true — prevent transitive deps from using
   git repos or direct tarball URLs
3. minimumReleaseAge: 1440 — wait 24h before installing newly
   published versions to avoid the malware exposure window
4. trustPolicy: no-downgrade — prevent installation if a package's
   trust level has decreased from previous releases

Also removes package-lock.json (npm artifact) in favor of
pnpm-lock.yaml.

https://claude.ai/code/session_0117WwRELH1nzVbxRj7Kmm5N

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: yosriady

package.json

@@ -2,7 +2,7 @@
   "name": "@formo/react-native-analytics",
   "version": "1.0.0",
   "description": "Formo Analytics SDK for React Native - Track wallet events and user analytics in mobile dApps",
-  "packageManager": "pnpm@9.0.0",
+  "packageManager": "pnpm@10.27.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/getformo/sdk.git",

pnpm-workspace.yaml

@@ -0,0 +1,21 @@
+# Supply chain security settings
+# See: https://pnpm.io/supply-chain-security
+
+# 1. Block lifecycle scripts by default
+# Only explicitly approved packages can run postinstall scripts.
+# Use `pnpm approve-builds` to manage this list.
+onlyBuiltDependencies: []
+
+# 2. Block exotic subdependencies
+# Prevents transitive deps from using git repos or direct tarball URLs.
+blockExoticSubdeps: true
+
+# 3. Minimum release age (in minutes)
+# Wait 24 hours before installing newly published versions.
+# Malware is usually detected quickly, so this avoids the exposure window.
+minimumReleaseAge: 1440
+
+# 4. Trust policy
+# Prevent installation if a package's trust level has decreased
+# (e.g., was published by trusted publisher, now only has provenance).
+trustPolicy: no-downgrade

src/FormoAnalytics.ts

@@ -22,6 +22,7 @@ import {
 } from "./lib/consent";
 import { FormoAnalyticsSession } from "./lib/session";
 import { WagmiEventHandler } from "./lib/wagmi";
+import { AppLifecycleManager } from "./lib/lifecycle";
 import {
   Address,
   ChainID,
@@ -35,12 +36,14 @@ import {
   TransactionStatus,
 } from "./types";
 import { toChecksumAddress, getValidAddress } from "./utils";
+import { parseTrafficSource, storeTrafficSource } from "./utils/trafficSource";
 
 export class FormoAnalytics implements IFormoAnalytics {
   private session: FormoAnalyticsSession;
   private eventManager: IEventManager;
   private eventQueue: EventQueue;
   private wagmiHandler?: WagmiEventHandler;
+  private lifecycleManager?: AppLifecycleManager;
 
   config: Config;
   currentChainId?: ChainID;
@@ -125,6 +128,17 @@ export class FormoAnalytics implements IFormoAnalytics {
 
     const analytics = new FormoAnalytics(writeKey, options);
 
+    // Initialize lifecycle tracking if enabled
+    // Wrapped in try-catch so a transient storage failure doesn't prevent SDK init
+    if (analytics.isAutocaptureEnabled("lifecycle")) {
+      try {
+        analytics.lifecycleManager = new AppLifecycleManager(analytics);
+        await analytics.lifecycleManager.start(options?.app);
+      } catch (error) {
+        logger.error("FormoAnalytics: Failed to initialize lifecycle tracking", error);
+      }
+    }
+
     // Call ready callback
     if (options?.ready) {
       options.ready(analytics);
@@ -138,14 +152,15 @@ export class FormoAnalytics implements IFormoAnalytics {
    */
   public async screen(
     name: string,
+    category?: string,
     properties?: IFormoEventProperties,
     context?: IFormoEventContext,
     callback?: (...args: unknown[]) => void
   ): Promise<void> {
     // Note: shouldTrack() is called in trackEvent() - no need to check here
     await this.trackEvent(
       EventType.SCREEN,
-      { name },
+      { name, ...(category && { category }) },
       properties,
       context,
       callback
@@ -175,8 +190,11 @@ export class FormoAnalytics implements IFormoAnalytics {
    * ```
    */
   public setTrafficSourceFromUrl(url: string): void {
-    const { parseTrafficSource, storeTrafficSource } = require("./utils/trafficSource");
-    const trafficSource = parseTrafficSource(url);
+    const trafficSource = parseTrafficSource(
+      url,
+      this.options.referral?.queryParams,
+      this.options.referral?.pathPattern
+    );
     storeTrafficSource(trafficSource);
     logger.debug("Traffic source set from URL:", trafficSource);
   }
@@ -197,6 +215,11 @@ export class FormoAnalytics implements IFormoAnalytics {
   public async cleanup(): Promise<void> {
     logger.info("FormoAnalytics: Cleaning up resources");
 
+    if (this.lifecycleManager) {
+      this.lifecycleManager.cleanup();
+      this.lifecycleManager = undefined;
+    }
+
     if (this.wagmiHandler) {
       this.wagmiHandler.cleanup();
       this.wagmiHandler = undefined;
@@ -325,7 +348,7 @@ export class FormoAnalytics implements IFormoAnalytics {
       signatureHash,
     }: {
       status: SignatureStatus;
-      chainId: ChainID;
+      chainId?: ChainID;
       address: Address;
       message: string;
       signatureHash?: string;
@@ -334,10 +357,6 @@ export class FormoAnalytics implements IFormoAnalytics {
     context?: IFormoEventContext,
     callback?: (...args: unknown[]) => void
   ): Promise<void> {
-    if (chainId === null || chainId === undefined || Number(chainId) === 0) {
-      logger.warn("Signature: Chain ID cannot be null, undefined, or 0");
-      return;
-    }
     if (!address) {
       logger.warn("Signature: Address cannot be empty");
       return;
@@ -346,7 +365,7 @@ export class FormoAnalytics implements IFormoAnalytics {
       EventType.SIGNATURE,
       {
         status,
-        chainId,
+        ...(chainId !== undefined && chainId !== null && { chainId }),
         address,
         message,
         ...(signatureHash && { signatureHash }),
@@ -369,6 +388,8 @@ export class FormoAnalytics implements IFormoAnalytics {
       to,
       value,
       transactionHash,
+      function_name,
+      function_args,
     }: {
       status: TransactionStatus;
       chainId: ChainID;
@@ -377,6 +398,8 @@ export class FormoAnalytics implements IFormoAnalytics {
       to?: string;
       value?: string;
       transactionHash?: string;
+      function_name?: string;
+      function_args?: Record<string, unknown>;
     },
     properties?: IFormoEventProperties,
     context?: IFormoEventContext,
@@ -400,6 +423,8 @@ export class FormoAnalytics implements IFormoAnalytics {
         to,
         value,
         ...(transactionHash && { transactionHash }),
+        ...(function_name && { function_name }),
+        ...(function_args && { function_args }),
       },
       properties,
       context,
@@ -544,7 +569,7 @@ export class FormoAnalytics implements IFormoAnalytics {
    * Check if autocapture is enabled for event type
    */
   public isAutocaptureEnabled(
-    eventType: "connect" | "disconnect" | "signature" | "transaction" | "chain"
+    eventType: "connect" | "disconnect" | "signature" | "transaction" | "chain" | "lifecycle"
   ): boolean {
     if (this.options.autocapture === undefined) {
       return true;
@@ -596,6 +621,13 @@ export class FormoAnalytics implements IFormoAnalytics {
       );
     } catch (error) {
       logger.error("Error tracking event:", error);
+      if (this.options.errorHandler) {
+        try {
+          this.options.errorHandler(error instanceof Error ? error : new Error(String(error)));
+        } catch (handlerError) {
+          logger.error("Error in errorHandler callback:", handlerError);
+        }
+      }
     }
   }
 

src/FormoAnalyticsProvider.tsx

@@ -8,7 +8,7 @@ import React, {
   FC,
 } from "react";
 import { FormoAnalytics } from "./FormoAnalytics";
-import { initStorageManager, AsyncStorageInterface } from "./lib/storage";
+import { initStorageManager } from "./lib/storage";
 import { logger } from "./lib/logger";
 import { FormoAnalyticsProviderProps, IFormoAnalytics } from "./types";
 
@@ -34,25 +34,6 @@ const defaultContext: IFormoAnalytics = {
 export const FormoAnalyticsContext =
   createContext<IFormoAnalytics>(defaultContext);
 
-export interface FormoAnalyticsProviderPropsWithStorage
-  extends FormoAnalyticsProviderProps {
-  /**
-   * AsyncStorage instance from @react-native-async-storage/async-storage
-   * Required for persistent storage
-   */
-  asyncStorage?: AsyncStorageInterface;
-  /**
-   * Callback when SDK is ready
-   * Note: Use useCallback to avoid re-initialization on every render
-   */
-  onReady?: (sdk: IFormoAnalytics) => void;
-  /**
-   * Callback when SDK initialization fails
-   * Note: Use useCallback to avoid re-initialization on every render
-   */
-  onError?: (error: Error) => void;
-}
-
 /**
  * Formo Analytics Provider for React Native
  *
@@ -76,7 +57,7 @@ export interface FormoAnalyticsProviderPropsWithStorage
  * }
  * ```
  */
-export const FormoAnalyticsProvider: FC<FormoAnalyticsProviderPropsWithStorage> = (
+export const FormoAnalyticsProvider: FC<FormoAnalyticsProviderProps> = (
   props
 ) => {
   const { writeKey, disabled = false, children } = props;
@@ -102,7 +83,7 @@ export const FormoAnalyticsProvider: FC<FormoAnalyticsProviderPropsWithStorage>
   return <InitializedAnalytics {...props} />;
 };
 
-const InitializedAnalytics: FC<FormoAnalyticsProviderPropsWithStorage> = ({
+const InitializedAnalytics: FC<FormoAnalyticsProviderProps> = ({
   writeKey,
   options,
   asyncStorage,

src/__tests__/FormoAnalytics.test.ts

@@ -58,6 +58,16 @@ jest.mock('../lib/consent', () => ({
   removeConsentFlag: jest.fn(),
 }));
 
+const mockLifecycleManager = {
+  start: jest.fn(),
+  cleanup: jest.fn(),
+};
+
+jest.mock('../lib/lifecycle', () => ({
+  __esModule: true,
+  AppLifecycleManager: jest.fn(),
+}));
+
 jest.mock('../lib/logger', () => ({
   __esModule: true,
   logger: {
@@ -78,6 +88,7 @@ import { initStorageManager, storage } from '../lib/storage';
 import { EventManager, EventQueue } from '../lib/event';
 import { FormoAnalyticsSession } from '../lib/session';
 import { setConsentFlag, getConsentFlag, removeConsentFlag } from '../lib/consent';
+import { AppLifecycleManager } from '../lib/lifecycle';
 
 // Helper to setup all mock implementations
 const setupMocks = () => {
@@ -114,6 +125,11 @@ const setupMocks = () => {
 
   // Consent mocks
   (getConsentFlag as jest.Mock).mockReturnValue(null);
+
+  // Lifecycle mocks
+  mockLifecycleManager.start.mockResolvedValue(undefined);
+  mockLifecycleManager.cleanup.mockReturnValue(undefined);
+  (AppLifecycleManager as jest.Mock).mockImplementation(() => mockLifecycleManager);
 };
 
 describe('FormoAnalytics', () => {
@@ -260,15 +276,25 @@ describe('FormoAnalytics', () => {
   });
 
   describe('signature()', () => {
-    it('should not track if chainId is invalid', async () => {
+    it('should track signature with chainId 0 (chainId is optional)', async () => {
       await analytics.signature({
         status: SignatureStatus.REQUESTED,
         chainId: 0,
         address: '0x742d35cc6634c0532925a3b844bc9e7595f3f6d2',
         message: 'test message',
       });
 
-      expect(mockEventManager.addEvent).not.toHaveBeenCalled();
+      expect(mockEventManager.addEvent).toHaveBeenCalled();
+    });
+
+    it('should track signature without chainId', async () => {
+      await analytics.signature({
+        status: SignatureStatus.REQUESTED,
+        address: '0x742d35cc6634c0532925a3b844bc9e7595f3f6d2',
+        message: 'test message',
+      });
+
+      expect(mockEventManager.addEvent).toHaveBeenCalled();
     });
 
     it('should not track if address is empty', async () => {
@@ -339,7 +365,7 @@ describe('FormoAnalytics', () => {
 
   describe('screen()', () => {
     it('should track screen views', async () => {
-      await analytics.screen('HomeScreen', { section: 'featured' });
+      await analytics.screen('HomeScreen', undefined, { section: 'featured' });
 
       expect(mockEventManager.addEvent).toHaveBeenCalled();
     });