vibefast-cli 1.1.3 → 1.2.1

package/recipes/onboarding/apps/native/src/features/onboarding/services/onboarding-analytics.ts

@@ -0,0 +1,432 @@
+import type { AnalyticsService } from '@/core/analytics';
+
+/**
+ * Onboarding step configuration for analytics tracking
+ */
+export type OnboardingStepConfig = {
+  id: string;
+  name: string;
+  index: number;
+  isOptional?: boolean;
+  category?: string; // e.g., 'intro', 'personalization', 'setup'
+};
+
+/**
+ * Onboarding flow configuration for analytics
+ */
+export type OnboardingFlowConfig = {
+  flowId: string;
+  flowName: string;
+  version?: string;
+  steps: OnboardingStepConfig[];
+  variant?: string; // For A/B testing different flows
+};
+
+/**
+ * Onboarding step interaction types
+ */
+export type OnboardingStepAction =
+  | 'viewed'
+  | 'completed'
+  | 'skipped'
+  | 'retried'
+  | 'back_navigation'
+  | 'help_accessed';
+
+/**
+ * Onboarding session data for tracking user journey
+ */
+export type OnboardingSession = {
+  sessionId: string;
+  flowConfig: OnboardingFlowConfig;
+  startTime: number;
+  currentStepIndex: number;
+  completedSteps: string[];
+  skippedSteps: string[];
+  userType?: 'new' | 'returning' | 'migrated';
+};
+
+/**
+ * Analytics events for onboarding tracking
+ */
+export const OnboardingAnalyticsEvents = {
+  // Flow-level events
+  FLOW_STARTED: 'onboarding_flow_started',
+  FLOW_COMPLETED: 'onboarding_flow_completed',
+  FLOW_ABANDONED: 'onboarding_flow_abandoned',
+  FLOW_RESUMED: 'onboarding_flow_resumed',
+
+  // Step-level events
+  STEP_VIEWED: 'onboarding_step_viewed',
+  STEP_COMPLETED: 'onboarding_step_completed',
+  STEP_SKIPPED: 'onboarding_step_skipped',
+  STEP_RETRIED: 'onboarding_step_retried',
+  STEP_HELP_ACCESSED: 'onboarding_step_help_accessed',
+
+  // Navigation events
+  NAVIGATION_BACK: 'onboarding_navigation_back',
+  NAVIGATION_FORWARD: 'onboarding_navigation_forward',
+} as const;
+
+/**
+ * Service for tracking onboarding analytics with automatic step discovery
+ * and scalable event tracking that adapts to any onboarding flow configuration.
+ */
+export class OnboardingAnalyticsService {
+  private analytics: AnalyticsService;
+  private currentSession: OnboardingSession | null = null;
+  private stepStartTimes: Map<string, number> = new Map();
+
+  constructor(analyticsService: AnalyticsService) {
+    this.analytics = analyticsService;
+  }
+
+  /**
+   * Start tracking an onboarding flow
+   */
+  async startFlow(
+    flowConfig: OnboardingFlowConfig,
+    userType?: 'new' | 'returning' | 'migrated',
+  ): Promise<string> {
+    const sessionId = `onboarding_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+    this.currentSession = {
+      sessionId,
+      flowConfig,
+      startTime: Date.now(),
+      currentStepIndex: 0,
+      completedSteps: [],
+      skippedSteps: [],
+      userType,
+    };
+
+    await this.analytics.track(OnboardingAnalyticsEvents.FLOW_STARTED, {
+      session_id: sessionId,
+      flow_id: flowConfig.flowId,
+      flow_name: flowConfig.flowName,
+      flow_version: flowConfig.version || '1.0',
+      flow_variant: flowConfig.variant,
+      total_steps: flowConfig.steps.length,
+      user_type: userType || 'unknown',
+      optional_steps_count: flowConfig.steps.filter((step) => step.isOptional)
+        .length,
+      step_categories: [
+        ...new Set(
+          flowConfig.steps.map((step) => step.category).filter(Boolean),
+        ),
+      ].join(','),
+    });
+
+    return sessionId;
+  }
+
+  /**
+   * Track when a user views a specific onboarding step
+   */
+  async trackStepViewed(
+    stepId: string,
+    additionalProperties?: Record<string, any>,
+  ): Promise<void> {
+    if (!this.currentSession) {
+      console.warn('[OnboardingAnalytics] No active session for step viewed');
+      return;
+    }
+
+    const step = this.currentSession.flowConfig.steps.find(
+      (s) => s.id === stepId,
+    );
+    if (!step) {
+      console.warn(
+        `[OnboardingAnalytics] Step ${stepId} not found in flow configuration`,
+      );
+      return;
+    }
+
+    // Update session state
+    this.currentSession.currentStepIndex = step.index;
+    this.stepStartTimes.set(stepId, Date.now());
+
+    await this.analytics.track(OnboardingAnalyticsEvents.STEP_VIEWED, {
+      session_id: this.currentSession.sessionId,
+      flow_id: this.currentSession.flowConfig.flowId,
+      step_id: stepId,
+      step_name: step.name,
+      step_index: step.index,
+      step_category: step.category,
+      is_optional: step.isOptional || false,
+      session_duration_ms: Date.now() - this.currentSession.startTime,
+      is_first_step: step.index === 0,
+      is_last_step:
+        step.index === this.currentSession.flowConfig.steps.length - 1,
+      ...additionalProperties,
+    });
+  }
+
+  /**
+   * Track when a user completes a specific onboarding step
+   */
+  async trackStepCompleted(
+    stepId: string,
+    additionalProperties?: Record<string, any>,
+  ): Promise<void> {
+    if (!this.currentSession) {
+      console.warn(
+        '[OnboardingAnalytics] No active session for step completion',
+      );
+      return;
+    }
+
+    const step = this.currentSession.flowConfig.steps.find(
+      (s) => s.id === stepId,
+    );
+    if (!step) {
+      console.warn(
+        `[OnboardingAnalytics] Step ${stepId} not found in flow configuration`,
+      );
+      return;
+    }
+
+    // Calculate step duration
+    const stepStartTime = this.stepStartTimes.get(stepId);
+    const stepDuration = stepStartTime ? Date.now() - stepStartTime : 0;
+
+    // Update session state
+    this.currentSession.completedSteps.push(stepId);
+
+    await this.analytics.track(OnboardingAnalyticsEvents.STEP_COMPLETED, {
+      session_id: this.currentSession.sessionId,
+      flow_id: this.currentSession.flowConfig.flowId,
+      step_id: stepId,
+      step_name: step.name,
+      step_index: step.index,
+      step_category: step.category,
+      is_optional: step.isOptional || false,
+      step_duration_ms: stepDuration,
+      session_duration_ms: Date.now() - this.currentSession.startTime,
+      completion_rate:
+        this.currentSession.completedSteps.length /
+        this.currentSession.flowConfig.steps.length,
+      is_last_step:
+        step.index === this.currentSession.flowConfig.steps.length - 1,
+      ...additionalProperties,
+    });
+
+    // Check if this was the last step
+    if (step.index === this.currentSession.flowConfig.steps.length - 1) {
+      await this.trackFlowCompleted();
+    }
+  }
+
+  /**
+   * Track when a user skips a step
+   */
+  async trackStepSkipped(
+    stepId: string,
+    reason?: string,
+    additionalProperties?: Record<string, any>,
+  ): Promise<void> {
+    if (!this.currentSession) {
+      console.warn('[OnboardingAnalytics] No active session for step skip');
+      return;
+    }
+
+    const step = this.currentSession.flowConfig.steps.find(
+      (s) => s.id === stepId,
+    );
+    if (!step) {
+      console.warn(
+        `[OnboardingAnalytics] Step ${stepId} not found in flow configuration`,
+      );
+      return;
+    }
+
+    // Update session state
+    this.currentSession.skippedSteps.push(stepId);
+
+    await this.analytics.track(OnboardingAnalyticsEvents.STEP_SKIPPED, {
+      session_id: this.currentSession.sessionId,
+      flow_id: this.currentSession.flowConfig.flowId,
+      step_id: stepId,
+      step_name: step.name,
+      step_index: step.index,
+      step_category: step.category,
+      is_optional: step.isOptional || false,
+      skip_reason: reason || 'user_choice',
+      session_duration_ms: Date.now() - this.currentSession.startTime,
+      ...additionalProperties,
+    });
+  }
+
+  /**
+   * Track step retry attempts
+   */
+  async trackStepRetried(
+    stepId: string,
+    attempt: number,
+    additionalProperties?: Record<string, any>,
+  ): Promise<void> {
+    if (!this.currentSession) return;
+
+    const step = this.currentSession.flowConfig.steps.find(
+      (s) => s.id === stepId,
+    );
+    if (!step) return;
+
+    await this.analytics.track(OnboardingAnalyticsEvents.STEP_RETRIED, {
+      session_id: this.currentSession.sessionId,
+      flow_id: this.currentSession.flowConfig.flowId,
+      step_id: stepId,
+      step_name: step.name,
+      step_index: step.index,
+      attempt_number: attempt,
+      ...additionalProperties,
+    });
+  }
+
+  /**
+   * Track when user accesses help during onboarding
+   */
+  async trackStepHelpAccessed(
+    stepId: string,
+    helpType?: string,
+    additionalProperties?: Record<string, any>,
+  ): Promise<void> {
+    if (!this.currentSession) return;
+
+    const step = this.currentSession.flowConfig.steps.find(
+      (s) => s.id === stepId,
+    );
+    if (!step) return;
+
+    await this.analytics.track(OnboardingAnalyticsEvents.STEP_HELP_ACCESSED, {
+      session_id: this.currentSession.sessionId,
+      flow_id: this.currentSession.flowConfig.flowId,
+      step_id: stepId,
+      step_name: step.name,
+      step_index: step.index,
+      help_type: helpType || 'general',
+      ...additionalProperties,
+    });
+  }
+
+  /**
+   * Track navigation events (back/forward)
+   */
+  async trackNavigation(
+    direction: 'back' | 'forward',
+    fromStepId: string,
+    toStepId: string,
+  ): Promise<void> {
+    if (!this.currentSession) return;
+
+    const event =
+      direction === 'back'
+        ? OnboardingAnalyticsEvents.NAVIGATION_BACK
+        : OnboardingAnalyticsEvents.NAVIGATION_FORWARD;
+
+    await this.analytics.track(event, {
+      session_id: this.currentSession.sessionId,
+      flow_id: this.currentSession.flowConfig.flowId,
+      from_step_id: fromStepId,
+      to_step_id: toStepId,
+      direction,
+      session_duration_ms: Date.now() - this.currentSession.startTime,
+    });
+  }
+
+  /**
+   * Track successful flow completion
+   */
+  async trackFlowCompleted(): Promise<void> {
+    if (!this.currentSession) return;
+
+    const totalDuration = Date.now() - this.currentSession.startTime;
+    const totalSteps = this.currentSession.flowConfig.steps.length;
+    const completedSteps = this.currentSession.completedSteps.length;
+    const skippedSteps = this.currentSession.skippedSteps.length;
+
+    await this.analytics.track(OnboardingAnalyticsEvents.FLOW_COMPLETED, {
+      session_id: this.currentSession.sessionId,
+      flow_id: this.currentSession.flowConfig.flowId,
+      flow_name: this.currentSession.flowConfig.flowName,
+      flow_version: this.currentSession.flowConfig.version || '1.0',
+      flow_variant: this.currentSession.flowConfig.variant,
+      total_duration_ms: totalDuration,
+      total_steps: totalSteps,
+      completed_steps: completedSteps,
+      skipped_steps: skippedSteps,
+      completion_rate: completedSteps / totalSteps,
+      skip_rate: skippedSteps / totalSteps,
+      user_type: this.currentSession.userType,
+      completed_step_ids: this.currentSession.completedSteps.join(','),
+      skipped_step_ids: this.currentSession.skippedSteps.join(','),
+    });
+
+    // Clear session
+    this.currentSession = null;
+    this.stepStartTimes.clear();
+  }
+
+  /**
+   * Track flow abandonment
+   */
+  async trackFlowAbandoned(reason?: string): Promise<void> {
+    if (!this.currentSession) return;
+
+    const totalDuration = Date.now() - this.currentSession.startTime;
+    const currentStep =
+      this.currentSession.flowConfig.steps[
+        this.currentSession.currentStepIndex
+      ];
+
+    await this.analytics.track(OnboardingAnalyticsEvents.FLOW_ABANDONED, {
+      session_id: this.currentSession.sessionId,
+      flow_id: this.currentSession.flowConfig.flowId,
+      flow_name: this.currentSession.flowConfig.flowName,
+      abandon_reason: reason || 'unknown',
+      last_step_id: currentStep?.id,
+      last_step_index: this.currentSession.currentStepIndex,
+      session_duration_ms: totalDuration,
+      completed_steps: this.currentSession.completedSteps.length,
+      completion_rate_at_abandon:
+        this.currentSession.completedSteps.length /
+        this.currentSession.flowConfig.steps.length,
+      completed_step_ids: this.currentSession.completedSteps.join(','),
+      skipped_step_ids: this.currentSession.skippedSteps.join(','),
+    });
+
+    // Clear session
+    this.currentSession = null;
+    this.stepStartTimes.clear();
+  }
+
+  /**
+   * Get current session information
+   */
+  getCurrentSession(): OnboardingSession | null {
+    return this.currentSession;
+  }
+
+  /**
+   * Get flow progress analytics
+   */
+  getFlowProgress(): {
+    totalSteps: number;
+    currentStep: number;
+    completedSteps: number;
+    skippedSteps: number;
+    completionRate: number;
+  } | null {
+    if (!this.currentSession) return null;
+
+    return {
+      totalSteps: this.currentSession.flowConfig.steps.length,
+      currentStep: this.currentSession.currentStepIndex,
+      completedSteps: this.currentSession.completedSteps.length,
+      skippedSteps: this.currentSession.skippedSteps.length,
+      completionRate:
+        this.currentSession.completedSteps.length /
+        this.currentSession.flowConfig.steps.length,
+    };
+  }
+}

package/recipes/onboarding/recipe.json

@@ -0,0 +1,15 @@
+{
+  "name": "onboarding",
+  "version": "1.0.0",
+  "description": "Premium onboarding flows (demo-one, expense-tracker)",
+  "copy": [
+    {
+      "from": "apps/native/src/features/onboarding",
+      "to": "apps/native/src/features/onboarding"
+    }
+  ],
+  "target": "native",
+  "dependencies": {
+    "expo": ["react-native-reanimated", "react-native-gesture-handler"]
+  }
+}

package/recipes/payments/recipe.json

@@ -1,10 +1,10 @@
 {
   "name": "payments",
-  "version": "1.1.0",
-  "description": "In-app purchases and subscriptions with RevenueCat",
+  "version": "1.0.0",
+  "description": "RevenueCat payments",
   "copy": [
     {
-      "from": "apps/native/src/app/(root)/(protected)/paywall",
+      "from": "apps/native/src/app/paywall",
       "to": "apps/native/src/app/(root)/(protected)/paywall"
     },
     {
@@ -15,87 +15,54 @@
       "from": "apps/native/src/api-client/payments.ts",
       "to": "apps/native/src/api-client/payments.ts"
     },
-    {
-      "from": "packages/backend/convex/payments",
-      "to": "packages/backend/convex/payments"
-    },
     {
       "from": "packages/backend/convex/payments.ts",
       "to": "packages/backend/convex/payments.ts"
+    },
+    {
+      "from": "packages/backend/convex/payments",
+      "to": "packages/backend/convex/payments"
     }
   ],
+  "configuration": {
+    "apiClient": {
+      "exports": ["export { type PaymentsApi, paymentsApi } from './payments';"]
+    }
+  },
   "nav": {
     "href": "/(root)/(protected)/paywall",
-    "label": "Paywall",
+    "label": "Payments",
     "icon": "💳",
-    "color": "#10B981"
+    "color": "#EC4899"
   },
   "target": "native",
   "dependencies": {
-    "expo": [
-      "react-native-purchases",
-      "react-native-purchases-ui"
-    ]
+    "expo": ["react-native-purchases", "react-native-purchases-ui"]
   },
   "env": [
     {
       "key": "REVENUECAT_API_KEY_APPLE",
-      "description": "RevenueCat public API key for iOS (client).",
-      "example": "revenuecat_apple_key",
-      "link": "https://app.revenuecat.com/settings/api-keys",
-      "file": "apps/native/.env.local"
+      "description": "RevenueCat API key for iOS",
+      "example": "appl_...",
+      "link": "https://app.revenuecat.com",
+      "required": true
     },
     {
       "key": "REVENUECAT_API_KEY_GOOGLE",
-      "description": "RevenueCat public API key for Android (client).",
-      "example": "revenuecat_google_key",
-      "link": "https://app.revenuecat.com/settings/api-keys",
-      "file": "apps/native/.env.local"
+      "description": "RevenueCat API key for Android",
+      "example": "goog_...",
+      "link": "https://app.revenuecat.com",
+      "required": true
     }
   ],
-  "configuration": {
-    "env": {
-      "client": {
-        "schema": [
-          "  REVENUECAT_API_KEY_APPLE: z.string(),",
-          "  REVENUECAT_API_KEY_GOOGLE: z.string(),"
-        ],
-        "env": [
-          "  REVENUECAT_API_KEY_APPLE: process.env.REVENUECAT_API_KEY_APPLE,",
-          "  REVENUECAT_API_KEY_GOOGLE: process.env.REVENUECAT_API_KEY_GOOGLE,"
-        ]
-      }
-    }
-  },
   "manualSteps": [
     {
-      "title": "Create RevenueCat Account",
-      "description": "Sign up at revenuecat.com and create a new project",
-      "link": "https://app.revenuecat.com/signup"
-    },
-    {
-      "title": "Configure App Stores",
-      "description": "Link your iOS (App Store Connect) and Android (Google Play) apps to RevenueCat",
-      "link": "https://www.revenuecat.com/docs/getting-started"
+      "title": "Configure RevenueCat",
+      "description": "1. Create a project at https://app.revenuecat.com\\n2. Add your app (iOS/Android)\\n3. Configure products/offerings\\n4. Copy API keys to .env.local"
     },
     {
-      "title": "Get API Keys",
-      "description": "Copy your public API keys (iOS and Android) from RevenueCat settings",
-      "link": "https://app.revenuecat.com/settings/api-keys"
-    },
-    {
-      "title": "Update API Keys",
-      "description": "Replace the API keys in the RevenueCat adapter",
-      "file": "apps/native/src/features/payments/services/revenuecat-adapter.ts",
-      "content": "const REVENUECAT_API_KEY_IOS = 'your_ios_key_here';\nconst REVENUECAT_API_KEY_ANDROID = 'your_android_key_here';"
-    },
-    {
-      "title": "Create Products & Entitlements",
-      "description": "Set up your subscription products and entitlements in RevenueCat dashboard",
-      "link": "https://www.revenuecat.com/docs/entitlements"
+      "title": "Setup App Store / Play Store",
+      "description": "1. Create in-app products in App Store Connect / Google Play Console\\n2. Link to RevenueCat\\n3. Configure entitlements"
     }
-  ],
-  "postInstall": {
-    "message": "💳 Payments feature installed! Configure RevenueCat API keys to enable subscriptions."
-  }
+  ]
 }