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

package/src/review/ReviewTimingManager.ts

@@ -0,0 +1,265 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+/**
+ * Configuration for review timing logic
+ */
+export interface ReviewTimingConfig {
+  /** Minimum number of days since app install before requesting review */
+  minDaysSinceInstall?: number;
+  /** Minimum number of app sessions before requesting review */
+  minSessionCount?: number;
+  /** Minimum number of significant events (e.g., purchases, completed actions) */
+  minSignificantEvents?: number;
+  /** Days to wait after a user dismisses a review prompt */
+  cooldownAfterDismissal?: number;
+  /** Maximum number of review requests to show to a user */
+  maxRequestsPerUser?: number;
+  /** Enable automatic timing checks */
+  enableAutomaticTiming?: boolean;
+}
+
+/**
+ * Timing data stored locally
+ */
+interface ReviewTimingData {
+  installDate: string;
+  sessionCount: number;
+  significantEventCount: number;
+  lastRequestDate?: string;
+  lastDismissalDate?: string;
+  totalRequestCount: number;
+  lastReviewCompletedDate?: string;
+}
+
+const STORAGE_KEY = '@billdog_review_timing';
+
+/**
+ * Default timing configuration
+ */
+const DEFAULT_CONFIG: Required<ReviewTimingConfig> = {
+  minDaysSinceInstall: 7,
+  minSessionCount: 5,
+  minSignificantEvents: 3,
+  cooldownAfterDismissal: 30,
+  maxRequestsPerUser: 3,
+  enableAutomaticTiming: true,
+};
+
+/**
+ * Manager for smart review timing logic
+ * Determines optimal moments to request reviews based on user behavior
+ */
+export class ReviewTimingManager {
+  private config: Required<ReviewTimingConfig>;
+  private timingData: ReviewTimingData | null = null;
+
+  constructor(config: ReviewTimingConfig = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Initialize timing data (call on app launch)
+   */
+  async initialize(): Promise<void> {
+    try {
+      const stored = await AsyncStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        this.timingData = JSON.parse(stored);
+      } else {
+        // First time - create initial data
+        this.timingData = {
+          installDate: new Date().toISOString(),
+          sessionCount: 0,
+          significantEventCount: 0,
+          totalRequestCount: 0,
+        };
+        await this.saveTimingData();
+      }
+    } catch (error) {
+      console.error('Error initializing review timing:', error);
+      // Fallback to in-memory only
+      this.timingData = {
+        installDate: new Date().toISOString(),
+        sessionCount: 0,
+        significantEventCount: 0,
+        totalRequestCount: 0,
+      };
+    }
+  }
+
+  /**
+   * Record a new app session
+   */
+  async recordSession(): Promise<void> {
+    if (!this.timingData) await this.initialize();
+    if (this.timingData) {
+      this.timingData.sessionCount++;
+      await this.saveTimingData();
+    }
+  }
+
+  /**
+   * Record a significant event (e.g., purchase, completed action)
+   */
+  async recordSignificantEvent(): Promise<void> {
+    if (!this.timingData) await this.initialize();
+    if (this.timingData) {
+      this.timingData.significantEventCount++;
+      await this.saveTimingData();
+    }
+  }
+
+  /**
+   * Record that a review was requested
+   */
+  async recordReviewRequested(): Promise<void> {
+    if (!this.timingData) await this.initialize();
+    if (this.timingData) {
+      this.timingData.lastRequestDate = new Date().toISOString();
+      this.timingData.totalRequestCount++;
+      await this.saveTimingData();
+    }
+  }
+
+  /**
+   * Record that a review was dismissed by the user
+   */
+  async recordReviewDismissed(): Promise<void> {
+    if (!this.timingData) await this.initialize();
+    if (this.timingData) {
+      this.timingData.lastDismissalDate = new Date().toISOString();
+      await this.saveTimingData();
+    }
+  }
+
+  /**
+   * Record that a review was completed by the user
+   */
+  async recordReviewCompleted(): Promise<void> {
+    if (!this.timingData) await this.initialize();
+    if (this.timingData) {
+      this.timingData.lastReviewCompletedDate = new Date().toISOString();
+      await this.saveTimingData();
+    }
+  }
+
+  /**
+   * Check if it's a good time to request a review
+   * Returns true if all timing conditions are met
+   */
+  async shouldRequestReview(): Promise<{
+    shouldRequest: boolean;
+    reason?: string;
+    timingData?: ReviewTimingData;
+  }> {
+    if (!this.config.enableAutomaticTiming) {
+      return { shouldRequest: true, reason: 'Automatic timing disabled' };
+    }
+
+    if (!this.timingData) await this.initialize();
+    if (!this.timingData) {
+      return { shouldRequest: false, reason: 'Timing data not available' };
+    }
+
+    // Check if user has already completed a review
+    if (this.timingData.lastReviewCompletedDate) {
+      return { 
+        shouldRequest: false, 
+        reason: 'User has already completed a review',
+        timingData: this.timingData 
+      };
+    }
+
+    // Check max requests limit
+    if (this.timingData.totalRequestCount >= this.config.maxRequestsPerUser) {
+      return { 
+        shouldRequest: false, 
+        reason: `Maximum review requests (${this.config.maxRequestsPerUser}) reached`,
+        timingData: this.timingData 
+      };
+    }
+
+    // Check days since install
+    const daysSinceInstall = this.getDaysSince(new Date(this.timingData.installDate));
+    if (daysSinceInstall < this.config.minDaysSinceInstall) {
+      return { 
+        shouldRequest: false, 
+        reason: `Only ${daysSinceInstall} days since install (need ${this.config.minDaysSinceInstall})`,
+        timingData: this.timingData 
+      };
+    }
+
+    // Check session count
+    if (this.timingData.sessionCount < this.config.minSessionCount) {
+      return { 
+        shouldRequest: false, 
+        reason: `Only ${this.timingData.sessionCount} sessions (need ${this.config.minSessionCount})`,
+        timingData: this.timingData 
+      };
+    }
+
+    // Check significant events
+    if (this.timingData.significantEventCount < this.config.minSignificantEvents) {
+      return { 
+        shouldRequest: false, 
+        reason: `Only ${this.timingData.significantEventCount} significant events (need ${this.config.minSignificantEvents})`,
+        timingData: this.timingData 
+      };
+    }
+
+    // Check cooldown after dismissal
+    if (this.timingData.lastDismissalDate) {
+      const daysSinceDismissal = this.getDaysSince(new Date(this.timingData.lastDismissalDate));
+      if (daysSinceDismissal < this.config.cooldownAfterDismissal) {
+        return { 
+          shouldRequest: false, 
+          reason: `Only ${daysSinceDismissal} days since last dismissal (need ${this.config.cooldownAfterDismissal})`,
+          timingData: this.timingData 
+        };
+      }
+    }
+
+    // All conditions met!
+    return { 
+      shouldRequest: true, 
+      reason: 'All timing conditions met',
+      timingData: this.timingData 
+    };
+  }
+
+  /**
+   * Get current timing data
+   */
+  async getTimingData(): Promise<ReviewTimingData | null> {
+    if (!this.timingData) await this.initialize();
+    return this.timingData;
+  }
+
+  /**
+   * Reset timing data (useful for testing)
+   */
+  async resetTimingData(): Promise<void> {
+    this.timingData = {
+      installDate: new Date().toISOString(),
+      sessionCount: 0,
+      significantEventCount: 0,
+      totalRequestCount: 0,
+    };
+    await this.saveTimingData();
+  }
+
+  private async saveTimingData(): Promise<void> {
+    if (!this.timingData) return;
+    try {
+      await AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(this.timingData));
+    } catch (error) {
+      console.error('Error saving review timing data:', error);
+    }
+  }
+
+  private getDaysSince(date: Date): number {
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+  }
+}

package/src/survey-core/types.ts

@@ -0,0 +1,244 @@
+/**
+ * BDSurvey Types — Standalone survey SDK types
+ *
+ * These types are the canonical definitions for the BDSurvey system.
+ * The BillDog SDK re-exports these for backward compatibility.
+ */
+
+// ============= Survey Configuration (from bdsurvey-fetch) =============
+
+export type SurveyQuestionType =
+  | 'multiple_choice'
+  | 'multi_select'
+  | 'text'
+  | 'rating'
+  | 'nps'
+  | 'boolean'
+  | 'dropdown'
+  | 'matrix'
+  | 'ranking'
+  | 'slider'
+  // PostHog-parity question types (added):
+  | 'emoji'   // emoji-scale rating; config: { scale?: number; emojis?: string[]; labels?: { low?: string; high?: string } }
+  | 'thumbs'  // thumbs up/down; answered via answer_number (1 = up, 0 = down) or boolean
+  | 'link';   // call-to-action question; config: { url: string; buttonText?: string }
+
+export interface SurveyChoice {
+  id: string;
+  label: string;
+  value: string | null;
+  is_other: boolean;
+  choice_order: number;
+  image_url?: string | null;
+  metadata: Record<string, unknown>;
+}
+
+export type SurveyLogicOperator =
+  | 'equals'
+  | 'not_equals'
+  | 'contains'
+  | 'is_any_of'
+  | 'greater_than'
+  | 'less_than';
+
+export interface SurveyLogicCondition {
+  operator: SurveyLogicOperator;
+  value?: string | number;
+  choice_id?: string;
+}
+
+export interface SurveyLogicRule {
+  id: string;
+  /**
+   * Single condition (legacy / simple rules). Retained for backward compatibility.
+   * When `conditions` is present and non-empty it takes precedence over `condition`.
+   */
+  condition?: SurveyLogicCondition;
+  /**
+   * Compound conditions (PostHog-parity, added). Combined per `condition_logic`.
+   * Evaluators prefer this over `condition` when present.
+   */
+  conditions?: SurveyLogicCondition[];
+  /** How to combine `conditions`. Defaults to 'and'. */
+  condition_logic?: 'and' | 'or';
+  action_type: 'skip_to_question' | 'skip_to_page' | 'end_survey';
+  target_id?: string;
+  rule_order: number;
+}
+
+export interface SurveyQuestion {
+  id: string;
+  type: SurveyQuestionType;
+  text: string;
+  description: string | null;
+  is_required: boolean;
+  question_order: number;
+  config: Record<string, unknown>;
+  settings: Record<string, unknown>;
+  choices: SurveyChoice[];
+  logic_rules?: SurveyLogicRule[];
+}
+
+export interface SurveyPage {
+  id: string;
+  title: string | null;
+  description: string | null;
+  page_order: number;
+  settings: Record<string, unknown>;
+  questions: SurveyQuestion[];
+}
+
+export interface SurveyMobileDisplayConfig {
+  displayStyle?: 'full_screen' | 'sheet' | 'push_navigation' | 'no_transition' | 'side_drawer' | 'overlay_popup';
+  allowScrolling?: boolean;
+  interceptBackButton?: boolean;
+  accessControl?: 'restricted' | 'unrestricted';
+  safeAreaInsets?: boolean;
+  sheetConfig?: { heightPercent?: number; cornerRadius?: number };
+  popupConfig?: { widthPercent?: number; heightPercent?: number; cornerRadius?: number };
+  drawerConfig?: { widthPercent?: number; cornerRadius?: number };
+}
+
+export interface SurveyConfiguration {
+  id: string;
+  name: string;
+  description: string | null;
+  type: string;
+  settings: SurveySettings;
+  pages: SurveyPage[];
+  mobile_display?: SurveyMobileDisplayConfig;
+  version?: number;
+  variant_group?: string | null;
+  variant_name?: string | null;
+  should_show?: boolean;
+  presentation_percentage?: number;
+  /** Display/targeting conditions (PostHog-parity, added). */
+  display_conditions?: SurveyDisplayConditions;
+}
+
+/**
+ * Display/targeting conditions evaluated client-side before a survey is shown
+ * (PostHog-parity, added). All present conditions must pass (logical AND).
+ */
+export interface SurveyDisplayConditions {
+  /** Restrict to device categories. Empty/undefined = all devices. */
+  device_types?: SurveyDeviceType[];
+  /** Only show when a feature flag is enabled (optionally a specific variant). */
+  feature_flag?: { key: string; variant?: string | null };
+  /** Web/screen targeting: match the current URL/route. */
+  url_match?: { operator: 'exact' | 'contains' | 'regex' | 'not_contains'; value: string };
+  /** Only show after an event fires during the session (optional property filters). */
+  event_trigger?: { event_name: string; property_filters?: Record<string, unknown> };
+  /** Delay before showing, in milliseconds. */
+  delay_ms?: number;
+  [key: string]: unknown;
+}
+
+export type SurveyDeviceType = 'phone' | 'tablet' | 'desktop' | 'tv' | 'watch';
+
+/**
+ * Recurrence/repeat policy (PostHog-parity, added).
+ * `show_once` is the legacy single-show flag; `recurring` supersedes it when enabled.
+ */
+export interface SurveyRecurrence {
+  enabled: boolean;
+  /** Maximum number of times the survey may be shown to a user. */
+  max_repeats?: number;
+  /** Minimum days between repeated showings. */
+  interval_days?: number;
+  /** Re-show every time the trigger event fires (ignores interval_days when true). */
+  on_every_trigger?: boolean;
+}
+
+export interface SurveySettings {
+  show_once?: boolean;
+  shuffle_options?: boolean;
+  /** Randomize question order (PostHog-parity, added). */
+  shuffle_questions?: boolean;
+  /** Recurring/repeat policy (PostHog-parity, added). */
+  recurring?: SurveyRecurrence;
+  /** Global wait period: don't show if the user saw ANY survey in the last N days (added). */
+  wait_period_days?: number;
+  presentation_percentage?: number;
+  locale?: string | null;
+  theme?: SurveyTheme;
+  thankYouMessage?: { title: string; body?: string | null } | null;
+  welcomeScreen?: {
+    title: string;
+    body?: string | null;
+    buttonText?: string | null;
+  } | null;
+  [key: string]: unknown;
+}
+
+export interface SurveyTheme {
+  primaryColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  borderRadius?: number;
+  fontFamily?: string;
+  [key: string]: unknown;
+}
+
+// ============= Survey Answers (for bdsurvey-submit) =============
+
+export interface SurveyAnswer {
+  question_id: string;
+  choice_id?: string | null;
+  answer_text?: string | null;
+  answer_number?: number | null;
+  answer_json?: Record<string, unknown> | null;
+}
+
+export interface SurveyContext {
+  customer_id?: string;
+  anonymous_id?: string;
+  platform?: string;
+  session_id?: string;
+  device_info?: Record<string, unknown>;
+  custom_variables?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export interface SurveySubmitResult {
+  respondent_id: string;
+  survey_id: string;
+  status: string;
+  /** Submitted answers — included so host apps can implement conditional post-submit flows */
+  answers?: SurveyAnswer[];
+}
+
+// ============= Presentation Options =============
+
+export interface SurveyPresentationOptions {
+  customerId?: string;
+  anonymousId?: string;
+  platform?: string;
+  customVariables?: Record<string, string>;
+  onPresent?: (surveyId: string) => void;
+  onDismiss?: (surveyId: string) => void;
+  onComplete?: (surveyId: string, result: SurveySubmitResult) => void;
+  onError?: (error: Error) => void;
+  onAnswerChanged?: (answer: SurveyAnswer) => void;
+}
+
+// ============= Cache Entry =============
+
+export interface SurveyCacheEntry {
+  config: SurveyConfiguration;
+  fetchedAt: number;
+}
+
+// ============= Survey List (from bdsurvey-list) =============
+
+export interface SurveyListItem {
+  id: string;
+  name: string;
+  description: string | null;
+  type: string;
+  status: string;
+}
+
+export interface SurveyListResult {
+  surveys: SurveyListItem[];
+}

package/src/types/ambient.d.ts

@@ -0,0 +1,9 @@
+// Ambient module declarations for OPTIONAL native peer dependencies that are
+// not installed by default in this package. These are runtime-optional deps;
+// consumers who use the notification / icon features are expected to install
+// them. Declaring them as `any` modules is the standard approach for optional
+// peers so the type build does not fail when they are absent.
+
+declare module 'react-native-push-notification';
+declare module '@react-native-community/push-notification-ios';
+declare module 'lucide-react-native';