@billdog.io/react-native 1.0.0-beta.2

package/src/modules/ABTest.ts

@@ -0,0 +1,131 @@
+/**
+ * @billdog.io/react-native — A/B Testing Module
+ * 
+ * Native bridge to BillDogABTest (iOS) / billdog-abtest (Android).
+ * Provides experiment assignment, variant retrieval, and conversion tracking.
+ * 
+ * Types and methods align 1:1 with the native SDK surface.
+ */
+
+import { NativeModules, NativeEventEmitter } from 'react-native';
+
+const { BillDogABTest } = NativeModules;
+const eventEmitter = BillDogABTest ? new NativeEventEmitter(BillDogABTest) : null;
+
+// MARK: - Types (matching native SDK contracts)
+
+export interface ExperimentAssignment {
+  experimentId: string;
+  variantId: string;
+  variantName: string;
+  config: Record<string, any>;
+  isControl: boolean;
+}
+
+// MARK: - A/B Test Manager
+
+export class ABTestManager {
+  private static instance: ABTestManager | null = null;
+  private initialized = false;
+
+  private constructor() {}
+
+  static getInstance(): ABTestManager {
+    if (!ABTestManager.instance) {
+      ABTestManager.instance = new ABTestManager();
+    }
+    return ABTestManager.instance;
+  }
+
+  /**
+   * Initialize the A/B Testing module.
+   */
+  async initialize(): Promise<void> {
+    if (!BillDogABTest) {
+      console.warn('[BillDogABTest] Native module not linked. A/B Testing will be no-op.');
+      return;
+    }
+    await BillDogABTest.initialize();
+    this.initialized = true;
+  }
+
+  /**
+   * Get the variant assignment for an experiment.
+   * Returns the cached assignment if available, otherwise fetches from the server.
+   */
+  async getVariant(experimentId: string): Promise<ExperimentAssignment | null> {
+    if (!this.initialized || !BillDogABTest) return null;
+    return await BillDogABTest.getVariant(experimentId);
+  }
+
+  /**
+   * Track a conversion event for an experiment.
+   */
+  async trackConversion(
+    experimentId: string,
+    value?: number,
+    metadata?: Record<string, any>
+  ): Promise<void> {
+    if (!this.initialized || !BillDogABTest) return;
+    await BillDogABTest.trackConversion(experimentId, value ?? 1, metadata ?? {});
+  }
+
+  /**
+   * Track an impression event for an experiment.
+   */
+  async trackImpression(experimentId: string): Promise<void> {
+    if (!this.initialized || !BillDogABTest) return;
+    await BillDogABTest.trackImpression(experimentId);
+  }
+
+  /**
+   * Set the user ID for server-side experiment assignment.
+   * Triggers automatic experiment refresh (matching native behavior).
+   */
+  async setUserId(id: string): Promise<void> {
+    if (!BillDogABTest) return;
+    await BillDogABTest.setUserId(id);
+  }
+
+  /**
+   * Set user attributes for experiment targeting.
+   */
+  async setAttributes(attributes: Record<string, any>): Promise<void> {
+    if (!BillDogABTest) return;
+    await BillDogABTest.setAttributes(attributes);
+  }
+
+  /**
+   * Get a feature flag value.
+   */
+  async getFeatureFlag(key: string): Promise<any> {
+    if (!this.initialized || !BillDogABTest) return null;
+    return await BillDogABTest.getFeatureFlag(key);
+  }
+
+  /**
+   * Refresh experiment assignments from the server.
+   */
+  async refreshExperiments(): Promise<void> {
+    if (!this.initialized || !BillDogABTest) return;
+    await BillDogABTest.refreshExperiments();
+  }
+
+  /**
+   * Reset all experiment state and cached assignments.
+   */
+  async reset(): Promise<void> {
+    if (!BillDogABTest) return;
+    await BillDogABTest.reset();
+    this.initialized = false;
+  }
+
+  /**
+   * Listen to assignment changes (e.g., after refresh).
+   */
+  onAssignmentChanged(callback: (assignment: ExperimentAssignment) => void) {
+    return eventEmitter?.addListener('onExperimentAssignmentChanged', callback);
+  }
+}
+
+export default ABTestManager.getInstance();

package/src/modules/Analytics.ts

@@ -0,0 +1,227 @@
+/**
+ * @billdog.io/react-native — Analytics Module
+ * 
+ * Native bridge to BillDogAnalytics (iOS) / billdog-analytics (Android).
+ * The native SDKs handle server-driven config (batch size, flush interval, sampling, etc.)
+ * fetched from the `sdk-config` edge function at init time.
+ * Config priority: client override > server config > SDK defaults (20 batch, 30s flush).
+ */
+
+import { NativeModules, NativeEventEmitter } from 'react-native';
+
+const { BillDogAnalytics } = NativeModules;
+const eventEmitter = BillDogAnalytics ? new NativeEventEmitter(BillDogAnalytics) : null;
+
+// MARK: - Types
+
+export interface AnalyticsEvent {
+  name: string;
+  properties?: Record<string, any>;
+  timestamp?: number;
+}
+
+export interface RevenueEvent {
+  /** Revenue amount (in the currency's base unit, e.g., dollars not cents) */
+  amount: number;
+  /** ISO 4217 currency code */
+  currency?: string;
+  /** Product identifier */
+  productId?: string;
+  /** Additional properties */
+  properties?: Record<string, any>;
+}
+
+export interface UserProperties {
+  [key: string]: string | number | boolean | null;
+}
+
+export type UserPropertyOperation = '$set' | '$set_once' | '$add' | '$append' | '$remove' | '$unset';
+
+// MARK: - Analytics Manager
+
+export class AnalyticsManager {
+  private static instance: AnalyticsManager | null = null;
+  private initialized = false;
+
+  private constructor() {}
+
+  static getInstance(): AnalyticsManager {
+    if (!AnalyticsManager.instance) {
+      AnalyticsManager.instance = new AnalyticsManager();
+    }
+    return AnalyticsManager.instance;
+  }
+
+  /**
+   * Initialize the Analytics module.
+   * Called automatically when `BillDogConfiguration.configure()` includes `apiKey`.
+   */
+  async initialize(): Promise<void> {
+    if (!BillDogAnalytics) {
+      console.warn('[BillDogAnalytics] Native module not linked. Analytics will be no-op.');
+      return;
+    }
+    await BillDogAnalytics.initialize();
+    this.initialized = true;
+  }
+
+  /**
+   * Track a custom event.
+   */
+  async track(event: string | AnalyticsEvent, properties?: Record<string, any>): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+
+    const name = typeof event === 'string' ? event : event.name;
+    const props = typeof event === 'string' ? properties : event.properties;
+
+    await BillDogAnalytics.track(name, props || {});
+  }
+
+  /**
+   * Track a revenue event (standardized `$revenue` event).
+   */
+  async trackRevenue(revenue: RevenueEvent): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+
+    await BillDogAnalytics.trackRevenue(
+      revenue.amount,
+      revenue.currency || 'USD',
+      revenue.productId || null,
+      revenue.properties || {}
+    );
+  }
+
+  /**
+   * Identify a user.
+   */
+  async identify(userId: string, properties?: UserProperties): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.identify(userId, properties || {});
+  }
+
+  /**
+   * Set super properties (persisted, merged into every event).
+   */
+  async setSuperProperties(properties: Record<string, any>): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.setSuperProperties(properties);
+  }
+
+  /**
+   * Update user properties with a specific operation.
+   */
+  async updateUserProperties(
+    operation: UserPropertyOperation,
+    properties: Record<string, any>
+  ): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.updateUserProperties(operation, properties);
+  }
+
+  /**
+   * Flush pending events immediately.
+   */
+  async flush(): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.flush();
+  }
+
+  /** Opt out of analytics tracking (GDPR). */
+  async optOut(): Promise<void> {
+    if (!BillDogAnalytics) return;
+    await BillDogAnalytics.optOut();
+  }
+
+  /** Opt back in to analytics tracking. */
+  async optIn(): Promise<void> {
+    if (!BillDogAnalytics) return;
+    await BillDogAnalytics.optIn();
+  }
+
+  /** Reset analytics state (clears identity + super properties). */
+  async reset(): Promise<void> {
+    if (!BillDogAnalytics) return;
+    await BillDogAnalytics.reset();
+    this.initialized = false;
+  }
+
+  // ── Parity surface (Sev 2.3 fix) ─────────────────────────────────────
+  // Native (iOS/Android) BillDogAnalytics already implements all of these;
+  // the RN bridge simply needs to expose them.
+
+  /** Alias an anonymous user to a known identity. */
+  async alias(newId: string, originalId?: string): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.alias(newId, originalId ?? null);
+  }
+
+  /** Start timing an event — duration emitted on next track() of same name. */
+  async timeEvent(eventName: string): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.timeEvent(eventName);
+  }
+
+  /** Associate this user with a group (B2B analytics). */
+  async setGroup(groupType: string, groupId: string): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.setGroup(groupType, groupId);
+  }
+
+  async setGroupProperties(
+    groupType: string,
+    groupId: string,
+    properties: Record<string, any>,
+  ): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.setGroupProperties(groupType, groupId, properties);
+  }
+
+  /** Track a screen view manually. */
+  async trackScreen(screenName: string, properties?: Record<string, any>): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.trackScreen(screenName, properties ?? {});
+  }
+
+  /** Track a deep-link URL. */
+  async trackDeepLink(url: string): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.trackDeepLink(url);
+  }
+
+  async getDeviceId(): Promise<string | null> {
+    if (!BillDogAnalytics) return null;
+    return BillDogAnalytics.getDeviceId();
+  }
+
+  async getDistinctId(): Promise<string | null> {
+    if (!BillDogAnalytics) return null;
+    return BillDogAnalytics.getDistinctId();
+  }
+
+  async getSessionId(): Promise<string | null> {
+    if (!BillDogAnalytics) return null;
+    return BillDogAnalytics.getSessionId();
+  }
+
+  async registerSuperPropertiesOnce(properties: Record<string, any>): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.registerSuperPropertiesOnce(properties);
+  }
+
+  async unregisterSuperProperty(key: string): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.unregisterSuperProperty(key);
+  }
+
+  async clearSuperProperties(): Promise<void> {
+    if (!this.initialized || !BillDogAnalytics) return;
+    await BillDogAnalytics.clearSuperProperties();
+  }
+
+  /** Listen to flush events (debugging). */
+  onFlush(callback: (data: { eventCount: number }) => void) {
+    return eventEmitter?.addListener('onAnalyticsFlush', callback);
+  }
+}
+
+export default AnalyticsManager.getInstance();

package/src/modules/Survey.ts

@@ -0,0 +1,126 @@
+/**
+ * @billdog.io/react-native — Survey Module
+ * 
+ * Native bridge to BDSurvey (iOS) / billdog-survey (Android).
+ * Provides survey presentation, response collection, and template loading.
+ */
+
+import { NativeModules, NativeEventEmitter } from 'react-native';
+
+const { BillDogSurvey } = NativeModules;
+const eventEmitter = BillDogSurvey ? new NativeEventEmitter(BillDogSurvey) : null;
+
+// MARK: - Canonical Types (re-exported from survey-core)
+
+import type {
+  SurveyConfiguration,
+  SurveyPage,
+  SurveyQuestion,
+  SurveyChoice,
+  SurveyAnswer,
+  SurveyMobileDisplayConfig,
+  // Local copy of packages/survey-core/src/types (see src/survey-core/types.ts).
+  // Copied because tsc rootDir cannot span files outside this package. These are
+  // type-only imports (no runtime), so a local copy preserves exact type fidelity.
+} from '../survey-core/types';
+
+export type { SurveyConfiguration, SurveyPage, SurveyQuestion, SurveyChoice, SurveyAnswer, SurveyMobileDisplayConfig };
+
+/** Alias for backward compatibility */
+export type Survey = SurveyConfiguration;
+
+// MARK: - RN-Specific Types (bridge contracts, not canonical data)
+
+export interface SurveyResponse {
+  survey_id: string;
+  answers: SurveyAnswer[];
+  completed_at?: string;
+  duration_ms?: number;
+}
+
+export interface SurveyPresentationOptions {
+  /** Survey identifier to display */
+  surveyIdentifier: string;
+  /** Optional customer ID for response attribution */
+  customerId?: string;
+  /** Optional context data passed to the survey */
+  context?: Record<string, any>;
+  /** Whether the survey can be dismissed */
+  isDismissible?: boolean;
+}
+
+// MARK: - Survey Manager
+
+export class SurveyManager {
+  private static instance: SurveyManager | null = null;
+  private initialized = false;
+
+  private constructor() {}
+
+  static getInstance(): SurveyManager {
+    if (!SurveyManager.instance) {
+      SurveyManager.instance = new SurveyManager();
+    }
+    return SurveyManager.instance;
+  }
+
+  /**
+   * Initialize the Survey module.
+   */
+  async initialize(): Promise<void> {
+    if (!BillDogSurvey) {
+      console.warn('[BillDogSurvey] Native module not linked. Surveys will be no-op.');
+      return;
+    }
+    await BillDogSurvey.initialize();
+    this.initialized = true;
+  }
+
+  /**
+   * Present a survey to the user.
+   */
+  async presentSurvey(options: SurveyPresentationOptions): Promise<SurveyResponse | null> {
+    if (!this.initialized || !BillDogSurvey) return null;
+    return await BillDogSurvey.presentSurvey(options);
+  }
+
+  /**
+   * Fetch a survey configuration without presenting it.
+   */
+  async fetchSurvey(surveyIdentifier: string): Promise<Survey | null> {
+    if (!this.initialized || !BillDogSurvey) return null;
+    return await BillDogSurvey.fetchSurvey(surveyIdentifier);
+  }
+
+  /**
+   * Submit a survey response programmatically.
+   */
+  async submitResponse(response: SurveyResponse): Promise<boolean> {
+    if (!this.initialized || !BillDogSurvey) return false;
+    return await BillDogSurvey.submitResponse(response);
+  }
+
+  /**
+   * Check if a survey is eligible to be shown to the current user.
+   */
+  async canShowSurvey(surveyIdentifier: string): Promise<boolean> {
+    if (!this.initialized || !BillDogSurvey) return false;
+    return await BillDogSurvey.canShowSurvey(surveyIdentifier);
+  }
+
+  /**
+   * Listen to survey completion events.
+   */
+  onSurveyCompleted(callback: (response: SurveyResponse) => void) {
+    return eventEmitter?.addListener('onSurveyCompleted', callback);
+  }
+
+  /**
+   * Listen to survey dismissal events.
+   */
+  onSurveyDismissed(callback: (data: { surveyId: string; pageIndex: number }) => void) {
+    return eventEmitter?.addListener('onSurveyDismissed', callback);
+  }
+}
+
+export default SurveyManager.getInstance();

package/src/modules/VirtualCurrency.ts

@@ -0,0 +1,223 @@
+/**
+ * @billdog.io/react-native — Virtual Currency Module
+ * Version: 1.0.0
+ */
+
+import { NativeModules, NativeEventEmitter } from 'react-native';
+import { BillDogConfiguration } from '../BillDogConfiguration';
+
+const { BillDogVirtualCurrency } = NativeModules;
+const eventEmitter = BillDogVirtualCurrency ? new NativeEventEmitter(BillDogVirtualCurrency) : null;
+
+/**
+ * Fail loud with a clear, actionable message when the native module is not linked
+ * (e.g. Expo Go, a JS-only Metro run, or a host app that hasn't rebuilt after
+ * adding the SDK) instead of a cryptic `Cannot read property '…' of undefined`.
+ * The native module is registered by `BillDogVirtualCurrencyPackage` on Android
+ * and `BillDogVirtualCurrencyBridge` on iOS — both require a native rebuild.
+ */
+function requireNative(): any {
+  if (!BillDogVirtualCurrency) {
+    throw new Error(
+      '[BillDogVirtualCurrency] Native module not linked. Rebuild the app with the ' +
+        'native SDK (npx expo prebuild + a dev-client/EAS build, or pod install + ' +
+        'gradle sync) — the Virtual Currency bridge is not available in Expo Go.',
+    );
+  }
+  return BillDogVirtualCurrency;
+}
+
+/**
+ * Normalize a native transaction row into the declared `VirtualCurrencyTransaction`
+ * shape. The native bridges resolve the backend row as-is, which is snake_case
+ * (`currency_id`, `created_at`); this maps both snake_case and camelCase so the
+ * public type is honest on iOS and Android alike.
+ */
+function normalizeTransaction(raw: any): VirtualCurrencyTransaction {
+  const ts =
+    typeof raw?.timestamp === 'number'
+      ? raw.timestamp
+      : raw?.created_at
+        ? Date.parse(raw.created_at) || 0
+        : 0;
+  return {
+    id: String(raw?.id ?? ''),
+    currencyId: raw?.currencyId ?? raw?.currency_id ?? '',
+    amount: Number(raw?.amount ?? 0),
+    type: (raw?.type ?? 'earn') as VirtualCurrencyTransaction['type'],
+    reason: raw?.reason ?? undefined,
+    timestamp: ts,
+    metadata: raw?.metadata ?? undefined,
+  };
+}
+
+/**
+ * Normalize a native currency row into the declared `VirtualCurrency` shape.
+ * The all-balances backend route returns `{ currency: {id,code,name,icon}, balance }`
+ * (nested; the display symbol lives in `icon`), so map that shape as well as a
+ * flat one. See supabase/functions/virtual-currency/index.ts (handleGetAllBalances).
+ */
+function normalizeCurrency(raw: any): VirtualCurrency {
+  const c = raw?.currency ?? raw;
+  return {
+    id: String(c?.id ?? ''),
+    name: c?.name ?? '',
+    code: c?.code ?? '',
+    symbol: c?.symbol ?? c?.icon ?? '',
+    balance: Number(raw?.balance ?? c?.balance ?? 0),
+  };
+}
+
+/**
+ * Normalize a native exchange result into the declared `ExchangeResult` shape.
+ * The iOS bridge resolves the raw backend payload (snake_case: `to_amount`,
+ * `exchange_rate`, `new_from_balance`); the Android bridge already emits
+ * camelCase. Accept both so the public type is honest on either platform.
+ */
+function normalizeExchange(
+  raw: any,
+  fromCurrencyId: string,
+  toCurrencyId: string,
+  fromAmount: number,
+): ExchangeResult {
+  const num = (a: any, b: any, d = 0): number => Number(a ?? b ?? d);
+  return {
+    success: raw?.success ?? !raw?.error,
+    fromCurrencyId: raw?.fromCurrencyId ?? raw?.from_currency_id ?? fromCurrencyId,
+    toCurrencyId: raw?.toCurrencyId ?? raw?.to_currency_id ?? toCurrencyId,
+    fromAmount: num(raw?.fromAmount, raw?.from_amount, fromAmount),
+    toAmount: num(raw?.toAmount, raw?.to_amount),
+    exchangeRate: num(raw?.exchangeRate, raw?.exchange_rate),
+    newFromBalance: num(raw?.newFromBalance, raw?.new_from_balance),
+    newToBalance: num(raw?.newToBalance, raw?.new_to_balance),
+    error: raw?.error ?? undefined,
+  };
+}
+
+export interface VirtualCurrency {
+  id: string;
+  name: string;
+  code: string;
+  symbol: string;
+  balance: number;
+}
+
+export interface VirtualCurrencyTransaction {
+  id: string;
+  currencyId: string;
+  amount: number;
+  type: 'earn' | 'spend' | 'grant' | 'exchange';
+  reason?: string;
+  timestamp: number;
+  metadata?: Record<string, any>;
+}
+
+export interface ExchangeResult {
+  success: boolean;
+  fromCurrencyId: string;
+  toCurrencyId: string;
+  fromAmount: number;
+  toAmount: number;
+  exchangeRate: number;
+  newFromBalance: number;
+  newToBalance: number;
+  error?: string;
+}
+
+export interface VirtualCurrencyConfig {
+  apiKey: string;
+  customerId: string;
+  enableLogging?: boolean;
+}
+
+export class VirtualCurrencyManager {
+  private static instance: VirtualCurrencyManager | null = null;
+  private config: VirtualCurrencyConfig | null = null;
+  
+  private constructor() {}
+  
+  static getInstance(): VirtualCurrencyManager {
+    if (!VirtualCurrencyManager.instance) {
+      VirtualCurrencyManager.instance = new VirtualCurrencyManager();
+    }
+    return VirtualCurrencyManager.instance;
+  }
+  
+  async initialize(config: VirtualCurrencyConfig): Promise<void> {
+    this.config = config;
+    // baseUrl is the single branded host (api.billdog.io/v1), not caller-supplied.
+    await requireNative().initialize({
+      ...config,
+      baseUrl: BillDogConfiguration.getApiBaseUrl(),
+    });
+  }
+
+  /** True when the native Virtual Currency bridge is linked into the host app. */
+  isAvailable(): boolean {
+    return !!BillDogVirtualCurrency;
+  }
+
+  async getBalance(currencyId: string): Promise<number> {
+    return await requireNative().getBalance(currencyId);
+  }
+
+  async addCurrency(
+    currencyId: string,
+    amount: number,
+    reason?: string,
+    metadata?: Record<string, any>
+  ): Promise<number> {
+    return await requireNative().addCurrency(currencyId, amount, reason, metadata);
+  }
+
+  async deductCurrency(
+    currencyId: string,
+    amount: number,
+    reason?: string,
+    metadata?: Record<string, any>
+  ): Promise<number> {
+    return await requireNative().deductCurrency(currencyId, amount, reason, metadata);
+  }
+
+  async grantCurrency(
+    currencyId: string,
+    amount: number,
+    reason?: string
+  ): Promise<number> {
+    return await requireNative().grantCurrency(currencyId, amount, reason);
+  }
+
+  async getTransactionHistory(
+    currencyId?: string,
+    limit: number = 50
+  ): Promise<VirtualCurrencyTransaction[]> {
+    const raw = await requireNative().getTransactionHistory(currencyId, limit);
+    return Array.isArray(raw) ? raw.map(normalizeTransaction) : [];
+  }
+
+  async exchangeCurrency(
+    fromCurrencyId: string,
+    toCurrencyId: string,
+    fromAmount: number
+  ): Promise<ExchangeResult> {
+    const raw = await requireNative().exchangeCurrency(fromCurrencyId, toCurrencyId, fromAmount);
+    return normalizeExchange(raw, fromCurrencyId, toCurrencyId, fromAmount);
+  }
+
+  async getAllCurrencies(): Promise<VirtualCurrency[]> {
+    const raw = await requireNative().getAllCurrencies();
+    return Array.isArray(raw) ? raw.map(normalizeCurrency) : [];
+  }
+  
+  onBalanceChanged(callback: (data: { currencyId: string; newBalance: number }) => void) {
+    if (!eventEmitter) return { remove() {} };
+    return eventEmitter.addListener('onBalanceChanged', callback);
+  }
+
+  onTransaction(callback: (transaction: VirtualCurrencyTransaction) => void) {
+    if (!eventEmitter) return { remove() {} };
+    return eventEmitter.addListener('onTransaction', callback);
+  }
+}
+
+export default VirtualCurrencyManager.getInstance();