@formo/analytics-react-native 0.1.3 → 0.1.6

package/src/solana/address.ts

@@ -0,0 +1,122 @@
+/**
+ * Solana address validation utilities
+ *
+ * Solana uses Base58 encoded 32-byte public keys as addresses.
+ * Format: FDKJvWcJNe6wecbgDYDFPCfgs14aJnVsUfWQRYWLn4Tn (32-44 characters)
+ *
+ * @see https://solana.com/developers/courses/intro-to-solana/interact-with-wallets
+ */
+
+import { SolanaPublicKey } from "./types";
+
+/**
+ * Base58 alphabet used by Solana (Bitcoin alphabet)
+ */
+const BASE58_ALPHABET =
+  "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+const BASE58_CHAR_SET = new Set(BASE58_ALPHABET);
+
+const MIN_SOLANA_ADDRESS_LENGTH = 32;
+const MAX_SOLANA_ADDRESS_LENGTH = 44;
+
+/**
+ * System program addresses and other special Solana addresses
+ * These are valid addresses but may not represent user wallets
+ */
+export const SOLANA_SYSTEM_ADDRESSES = {
+  SYSTEM_PROGRAM: "11111111111111111111111111111111",
+  TOKEN_PROGRAM: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+  TOKEN_2022_PROGRAM: "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
+  ASSOCIATED_TOKEN_PROGRAM: "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+  RENT_SYSVAR: "SysvarRent111111111111111111111111111111111",
+  CLOCK_SYSVAR: "SysvarC1ock11111111111111111111111111111111",
+} as const;
+
+function isValidBase58String(str: string): boolean {
+  for (const ch of str) {
+    if (!BASE58_CHAR_SET.has(ch)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Check if a string is a valid Solana address format
+ *
+ * Performs format validation only (length and character set). Does not
+ * verify that the address is a valid point on the Ed25519 curve.
+ */
+export function isSolanaAddress(value: unknown): value is string {
+  if (typeof value !== "string") {
+    return false;
+  }
+
+  const trimmed = value.trim();
+
+  if (
+    trimmed.length < MIN_SOLANA_ADDRESS_LENGTH ||
+    trimmed.length > MAX_SOLANA_ADDRESS_LENGTH
+  ) {
+    return false;
+  }
+
+  return isValidBase58String(trimmed);
+}
+
+/**
+ * Get a valid Solana address from a string or PublicKey
+ */
+export function getValidSolanaAddress(
+  address: string | SolanaPublicKey | null | undefined
+): string | null {
+  if (!address) {
+    return null;
+  }
+
+  if (typeof address === "object" && "toBase58" in address) {
+    try {
+      const base58 = address.toBase58();
+      return isSolanaAddress(base58) ? base58 : null;
+    } catch {
+      return null;
+    }
+  }
+
+  if (typeof address === "string") {
+    const trimmed = address.trim();
+    return isSolanaAddress(trimmed) ? trimmed : null;
+  }
+
+  return null;
+}
+
+/**
+ * Check if a Solana address is a system program or well-known program address
+ */
+export function isSolanaSystemAddress(address: string): boolean {
+  const validAddress = getValidSolanaAddress(address);
+  if (!validAddress) {
+    return false;
+  }
+
+  return Object.values(SOLANA_SYSTEM_ADDRESSES).includes(
+    validAddress as (typeof SOLANA_SYSTEM_ADDRESSES)[keyof typeof SOLANA_SYSTEM_ADDRESSES]
+  );
+}
+
+/**
+ * Check if a Solana address is blocked (should not emit events).
+ * Blocks system program addresses since they don't represent user wallets.
+ */
+export function isBlockedSolanaAddress(
+  address: string | SolanaPublicKey | null | undefined
+): boolean {
+  const validAddress = getValidSolanaAddress(address);
+  if (!validAddress) {
+    return false;
+  }
+
+  return isSolanaSystemAddress(validAddress);
+}

package/src/solana/index.ts

@@ -0,0 +1,2 @@
+export * from "./address";
+export * from "./types";

package/src/solana/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Solana-specific type definitions
+ */
+
+/**
+ * Solana cluster/network types
+ * Solana doesn't use chainId like EVM, instead it uses cluster names
+ */
+export type SolanaCluster = "mainnet-beta" | "testnet" | "devnet" | "localnet";
+
+/**
+ * Mapping of Solana clusters to numeric chain IDs for consistency with EVM events
+ * These IDs are non-standard but provide a way to identify Solana networks in our analytics
+ *
+ * Using high numbers (900000+) to avoid collision with EVM chain IDs
+ */
+export const SOLANA_CHAIN_IDS: Record<SolanaCluster, number> = {
+  "mainnet-beta": 900001,
+  testnet: 900002,
+  devnet: 900003,
+  localnet: 900004,
+} as const;
+
+/**
+ * Default Solana chain ID (mainnet-beta)
+ */
+export const DEFAULT_SOLANA_CHAIN_ID = SOLANA_CHAIN_IDS["mainnet-beta"];
+
+/**
+ * Check if a chain ID belongs to a Solana network.
+ */
+export function isSolanaChainId(chainId: number | undefined | null): boolean {
+  if (chainId === undefined || chainId === null) return false;
+  return Object.values(SOLANA_CHAIN_IDS).includes(chainId);
+}
+
+/**
+ * Solana PublicKey interface
+ * Used by address validation utilities.
+ */
+export interface SolanaPublicKey {
+  toBase58(): string;
+  toString(): string;
+  toBytes(): Uint8Array;
+  equals(other: SolanaPublicKey): boolean;
+}

package/src/types/base.ts

@@ -56,7 +56,6 @@ export interface IFormoAnalytics {
       chainId?: ChainID;
       address: Address;
       message: string;
-      signatureHash?: string;
     },
     properties?: IFormoEventProperties,
     context?: IFormoEventContext,
@@ -161,6 +160,36 @@ export interface AutocaptureOptions {
   lifecycle?: boolean;
 }
 
+/**
+ * Configuration options for attribution capture.
+ *
+ * Attribution is not an event type — it's context enrichment that decorates
+ * every tracked event with `utm_*`, `ref`, and `referrer` fields. These
+ * options control the SDK's automatic attribution data sources.
+ */
+export interface AttributionOptions {
+  /**
+   * Capture traffic source from deep links via React Native's Linking API.
+   * When enabled, the SDK calls Linking.getInitialURL() on init and subscribes
+   * to the `url` event, parsing UTM parameters and referral codes into the
+   * event context.
+   * @default true
+   */
+  deeplinks?: boolean;
+
+  /**
+   * Capture install-time attribution from the platform on first launch:
+   * - Android: Google Play Install Referrer API (requires react-native-play-install-referrer)
+   * - iOS: AdServices attribution token (requires react-native-ad-services-attribution)
+   *
+   * Resolved once on first successful fetch and cached; subsequent launches
+   * skip the native call. Silently no-ops when the optional native module
+   * is not installed.
+   * @default true
+   */
+  installReferrer?: boolean;
+}
+
 /**
  * Configuration options for Wagmi integration
  * Allows the SDK to hook into Wagmi v2 wallet events
@@ -230,6 +259,16 @@ export interface Options {
    * @default true
    */
   autocapture?: boolean | AutocaptureOptions;
+  /**
+   * Control attribution context capture (deep links and install referrer).
+   * Attribution decorates every tracked event with `utm_*`, `ref`, and
+   * `referrer` fields — it is not itself an event type.
+   * - `false`: Disable all attribution capture
+   * - `true`: Enable all attribution sources (default)
+   * - `AttributionOptions`: Granular control over specific sources
+   * @default true
+   */
+  attribution?: boolean | AttributionOptions;
   /**
    * Wagmi integration configuration
    * When provided, the SDK will hook into Wagmi's event system

package/src/types/events.ts

@@ -85,7 +85,6 @@ export interface SignatureAPIEvent {
   chainId?: ChainID;
   address: Address;
   message: string;
-  signatureHash?: string;
 }
 
 export interface ConnectAPIEvent {

package/src/utils/address.ts

@@ -1,11 +1,19 @@
 /**
  * Address validation and checksum utilities
  *
- * Uses ethereum-cryptography for proper EIP-55 checksum computation
+ * Supports both EVM and Solana addresses.
+ *
+ * Uses ethereum-cryptography for proper EIP-55 checksum computation.
  */
 
 import { keccak256 } from "ethereum-cryptography/keccak.js";
 import { utf8ToBytes } from "ethereum-cryptography/utils.js";
+import {
+  isSolanaAddress,
+  getValidSolanaAddress,
+  isBlockedSolanaAddress,
+} from "../solana/address";
+import { isSolanaChainId } from "../solana/types";
 
 /**
  * Convert Uint8Array to hex string
@@ -17,7 +25,7 @@ function toHex(bytes: Uint8Array): string {
 }
 
 /**
- * Check if a string is a valid Ethereum address
+ * Check if a string is a valid Ethereum (EVM) address
  */
 export function isValidAddress(address: string): boolean {
   if (!address) return false;
@@ -56,7 +64,7 @@ export function toChecksumAddress(address: string): string {
 }
 
 /**
- * Get valid address or null
+ * Get a valid (trimmed) EVM address, or null if invalid.
  */
 export function getValidAddress(
   address: string | undefined | null
@@ -68,7 +76,52 @@ export function getValidAddress(
 }
 
 /**
- * Blocked addresses that should not emit events
+ * Validates an EVM address and returns it in checksummed format.
+ */
+export function validateAndChecksumAddress(
+  address: string
+): string | undefined {
+  const validAddress = getValidAddress(address);
+  return validAddress ? toChecksumAddress(validAddress) : undefined;
+}
+
+/**
+ * Validates an address for both EVM and Solana chains.
+ *
+ * For EVM addresses, returns checksummed format.
+ * For Solana addresses, returns the Base58 address as-is.
+ *
+ * When chainId is explicitly provided, validation is strict:
+ * - Solana chainId → only Solana validation
+ * - Non-Solana chainId → only EVM validation
+ *
+ * When chainId is omitted, EVM is tried first with Solana fallback.
+ */
+export function validateAddress(
+  address: string,
+  chainId?: number | null
+): string | undefined {
+  // Explicit Solana chainId → validate ONLY as Solana
+  if (chainId !== undefined && chainId !== null && isSolanaChainId(chainId)) {
+    return getValidSolanaAddress(address) || undefined;
+  }
+
+  // Explicit non-Solana chainId → validate ONLY as EVM
+  if (chainId !== undefined && chainId !== null) {
+    return validateAndChecksumAddress(address);
+  }
+
+  // No chainId → try EVM first, then Solana fallback
+  const validEvmAddress = validateAndChecksumAddress(address);
+  if (validEvmAddress) {
+    return validEvmAddress;
+  }
+
+  return getValidSolanaAddress(address) || undefined;
+}
+
+/**
+ * Blocked EVM addresses that should not emit events
  * (zero address, dead address)
  */
 const BLOCKED_ADDRESSES = new Set<string>([
@@ -77,8 +130,21 @@ const BLOCKED_ADDRESSES = new Set<string>([
 ]);
 
 /**
- * Check if address is in blocked list
+ * Check if an address is in a blocked list.
+ * Handles both EVM (zero/dead addresses) and Solana (system program) blocks.
  */
 export function isBlockedAddress(address: string): boolean {
-  return BLOCKED_ADDRESSES.has(address.toLowerCase());
+  if (!address || typeof address !== "string") return false;
+
+  const trimmed = address.trim();
+
+  if (isValidAddress(trimmed)) {
+    return BLOCKED_ADDRESSES.has(trimmed.toLowerCase());
+  }
+
+  if (isSolanaAddress(trimmed)) {
+    return isBlockedSolanaAddress(trimmed);
+  }
+
+  return false;
 }

package/src/utils/trafficSource.ts

@@ -151,3 +151,76 @@ export function mergeWithStoredTrafficSource(
     ...(context || {}),
   };
 }
+
+/** All traffic-source keys used for merge operations. */
+const TRAFFIC_SOURCE_KEYS: (keyof ITrafficSource)[] = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_term",
+  "utm_content",
+  "ref",
+  "referrer",
+];
+
+/**
+ * Update stored traffic source with incoming values. Per-field last-touch with
+ * fallback: non-empty incoming fields win, empty incoming fields preserve the
+ * previously stored value. This matches the Formo web SDK's behavior and
+ * prevents a non-marketing deep link (e.g. "myapp://home" with only a referrer
+ * and no UTM/ref) from destroying existing attribution data written by the
+ * Install Referrer flow or an earlier marketing deep link.
+ */
+export function updateStoredTrafficSource(
+  incoming: Partial<ITrafficSource>
+): void {
+  try {
+    const existing = getStoredTrafficSource() || {};
+    const merged: Partial<ITrafficSource> = {};
+
+    for (const key of TRAFFIC_SOURCE_KEYS) {
+      const incomingVal = incoming[key];
+      const existingVal = existing[key];
+      if (incomingVal) {
+        merged[key] = incomingVal;
+      } else if (existingVal) {
+        merged[key] = existingVal;
+      }
+    }
+
+    storeTrafficSource(merged);
+  } catch (error) {
+    logger.error("Error updating traffic source:", error);
+  }
+}
+
+/**
+ * Merge a partial traffic source into the stored one, only filling in fields
+ * that are currently empty. Used by the Install Referrer flow so campaign data
+ * from the Play Store / Apple AdServices cannot clobber a deep-link attribution
+ * that arrived earlier in the same cold start.
+ */
+export function mergeTrafficSourceFill(
+  incoming: Partial<ITrafficSource>
+): void {
+  try {
+    const existing = getStoredTrafficSource() || {};
+    const merged: Partial<ITrafficSource> = { ...existing };
+    let changed = false;
+
+    for (const [key, value] of Object.entries(incoming)) {
+      if (!value) continue; // skip empty/undefined incoming values
+      const existing = merged[key as keyof ITrafficSource];
+      if (existing === undefined || existing === null || existing === "") {
+        merged[key as keyof ITrafficSource] = String(value);
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      storeTrafficSource(merged);
+    }
+  } catch (error) {
+    logger.error("Error merging traffic source:", error);
+  }
+}

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-export const version = '0.1.3';
+export const version = '0.1.6';