Automate User Onboarding 🚀

// Real-time state in Redis, async sync to analytics
class StateManager {
  async updateProgress(userId: string, step: number) {
    // 1. Update Redis immediately (< 10ms)
    await redis.set(
      `onboarding:${userId}:step`,
      step,
      { EX: 2592000 } // 30 days
    );
    
    // 2. Queue analytics update (non-blocking)
    await analyticsQueue.add('track', {
      userId,
      event: 'Step Completed',
      properties: { step },
    });
    
    // 3. Check for nudge triggers on fresh data
    const state = await this.getRealtimeState(userId);
    if (this.shouldNudge(state)) {
      await this.sendNudge(userId, state);
    }
  }
}

# Platform-agnostic state management
import redis
import json

class CrossPlatformState:
    def __init__(self, user_id: str):
        self.user_id = user_id
        self.redis = redis.Redis()
        self.state_key = f'onboarding:{user_id}'  # No platform suffix
    
    def get_state(self, platform: str = None) -> dict:
        """Get state regardless of platform"""
        state_json = self.redis.get(self.state_key)
        if not state_json:
            return self.initialize_state()
        
        state = json.loads(state_json)
        # Add platform context for logging only
        state['last_platform'] = platform
        return state
    
    def update_state(self, updates: dict, platform: str):
        """Update from any platform"""
        state = self.get_state()
        state.update(updates)
        state['last_platform'] = platform
        state['last_updated'] = datetime.now().isoformat()
        
        # Atomic update with optimistic locking
        self.redis.set(self.state_key, json.dumps(state))
        
        # Broadcast to other platforms via pub/sub
        self.redis.publish(
            f'onboarding:updates:{self.user_id}',
            json.dumps({'platform': platform, 'updates': updates})
        )

# Usage across platforms
state_manager = CrossPlatformState('usr_abc123')

# Web completes step 3
state_manager.update_state({'current_step': 3}, platform='web')

# Mobile immediately sees step 3
mobile_state = state_manager.get_state(platform='mobile')
print(mobile_state['current_step'])  # 3, not 0

// Dynamic onboarding based on feature flags
import { LDClient } from 'launchdarkly-node-server-sdk';

const ldClient = LDClient.init(process.env.LAUNCHDARKLY_SDK_KEY!);

interface OnboardingStep {
  id: string;
  title: string;
  feature_flag?: string;
  fallback_step?: string;
}

async function filterStepsByFlags(
  userId: string,
  userContext: any,
  steps: OnboardingStep[]
): Promise<OnboardingStep[]> {
  const availableSteps: OnboardingStep[] = [];
  
  for (const step of steps) {
    if (!step.feature_flag) {
      // No flag = always show
      availableSteps.push(step);
      continue;
    }
    
    // Check if user has access to feature
    const hasAccess = await ldClient.variation(
      step.feature_flag,
      userContext,
      false // default = hidden
    );
    
    if (hasAccess) {
      availableSteps.push(step);
    } else if (step.fallback_step) {
      // Show fallback if feature not available
      const fallback = steps.find(s => s.id === step.fallback_step);
      if (fallback) availableSteps.push(fallback);
    }
  }
  
  return availableSteps;
}

// Usage
const allSteps = [
  { id: 'import_data', title: 'Import Data' },
  {
    id: 'setup_ai_assistant',
    title: 'Set Up AI Assistant',
    feature_flag: 'ai_assistant_enabled',
    fallback_step: 'manual_setup',
  },
  { id: 'manual_setup', title: 'Manual Setup' },
];

const userSteps = await filterStepsByFlags(
  'usr_abc123',
  { key: 'usr_abc123', plan: 'enterprise' },
  allSteps
);

// Enterprise user sees AI assistant step
// Free user sees manual setup instead

# Timezone-aware nudge scheduling
from datetime import datetime, timedelta
import pytz
from timezonefinder import TimezoneFinder
import geoip2.database

class TimezoneAwareScheduler:
    def __init__(self):
        self.tf = TimezoneFinder()
        self.geoip = geoip2.database.Reader('GeoLite2-City.mmdb')
    
    def get_user_timezone(self, user_id: str, signup_ip: str) -> str:
        """Determine user timezone from IP or stored preference"""
        # Check if user set timezone explicitly
        stored_tz = redis.get(f'user:{user_id}:timezone')
        if stored_tz:
            return stored_tz.decode()
        
        # Fallback to IP geolocation
        try:
            response = self.geoip.city(signup_ip)
            lat, lng = response.location.latitude, response.location.longitude
            timezone = self.tf.timezone_at(lat=lat, lng=lng)
            
            # Cache for future use
            redis.set(f'user:{user_id}:timezone', timezone)
            return timezone
        except:
            return 'America/New_York'  # Default fallback
    
    def schedule_nudge(
        self,
        user_id: str,
        signup_ip: str,
        nudge_type: str,
        delay_hours: int
    ):
        """Schedule nudge for optimal local time"""
        user_tz = self.get_user_timezone(user_id, signup_ip)
        user_time = datetime.now(pytz.timezone(user_tz))
        
        # Calculate target time (delay_hours from now)
        target_time = user_time + timedelta(hours=delay_hours)
        
        # Adjust to business hours (9 AM - 8 PM)
        if target_time.hour < 9:
            target_time = target_time.replace(hour=9, minute=0)
        elif target_time.hour >= 20:
            # Push to next day 9 AM
            target_time = (target_time + timedelta(days=1)).replace(hour=9, minute=0)
        
        # Convert to UTC for queue
        target_utc = target_time.astimezone(pytz.UTC)
        delay_seconds = int((target_utc - datetime.now(pytz.UTC)).total_seconds())
        
        # Schedule in queue
        nudge_queue.add(
            nudge_type,
            {'user_id': user_id},
            delay=delay_seconds * 1000  # BullMQ uses milliseconds
        )
        
        return target_time.isoformat()

# Usage
scheduler = TimezoneAwareScheduler()

# Schedule "no progress" email for 1 hour from now
# But adjust to user's business hours
scheduled_time = scheduler.schedule_nudge(
    user_id='usr_abc123',
    signup_ip='203.0.113.42',
    nudge_type='no_progress_1hour',
    delay_hours=1
)

print(f"Nudge scheduled for {scheduled_time} user local time")

// Frequency cap enforcement
import { Redis } from 'ioredis';

interface FrequencyCap {
  channel: string;
  max_count: number;
  window_seconds: number;
}

const FREQUENCY_CAPS: FrequencyCap[] = [
  { channel: 'in_app', max_count: 2, window_seconds: 3600 }, // 2 per hour
  { channel: 'email', max_count: 1, window_seconds: 86400 }, // 1 per day
  { channel: 'sms', max_count: 1, window_seconds: 604800 }, // 1 per week
  { channel: 'push', max_count: 3, window_seconds: 86400 }, // 3 per day
];

class NudgeFrequencyManager {
  private redis: Redis;

  constructor() {
    this.redis = new Redis(process.env.REDIS_URL);
  }

  async canSendNudge(
    userId: string,
    channel: string
  ): Promise<{ allowed: boolean; reason?: string; retry_after?: number }> {
    const cap = FREQUENCY_CAPS.find((c) => c.channel === channel);
    if (!cap) return { allowed: true }; // No cap = always allow

    const key = `nudge_freq:${userId}:${channel}`;
    const count = await this.redis.get(key);

    if (!count) {
      // First nudge in window
      return { allowed: true };
    }

    const currentCount = parseInt(count, 10);
    if (currentCount >= cap.max_count) {
      const ttl = await this.redis.ttl(key);
      return {
        allowed: false,
        reason: `Frequency cap reached: ${currentCount}/${cap.max_count} in ${cap.window_seconds}s`,
        retry_after: ttl,
      };
    }

    return { allowed: true };
  }

  async recordNudge(userId: string, channel: string): Promise<void> {
    const cap = FREQUENCY_CAPS.find((c) => c.channel === channel);
    if (!cap) return;

    const key = `nudge_freq:${userId}:${channel}`;
    const current = await this.redis.get(key);

    if (!current) {
      // First nudge - set with expiry
      await this.redis.setex(key, cap.window_seconds, '1');
    } else {
      // Increment existing counter
      await this.redis.incr(key);
    }
  }

  async getNudgeHistory(
    userId: string,
    channel?: string
  ): Promise<{ channel: string; count: number; window_remaining: number }[]> {
    const pattern = channel
      ? `nudge_freq:${userId}:${channel}`
      : `nudge_freq:${userId}:*`;

    const keys = await this.redis.keys(pattern);
    const history = [];

    for (const key of keys) {
      const [, , , channelName] = key.split(':');
      const count = parseInt((await this.redis.get(key)) || '0', 10);
      const ttl = await this.redis.ttl(key);

      history.push({
        channel: channelName,
        count,
        window_remaining: ttl,
      });
    }

    return history;
  }
}

// Usage
const freqManager = new NudgeFrequencyManager();

// Before sending nudge
const canSend = await freqManager.canSendNudge('usr_abc123', 'email');

if (canSend.allowed) {
  // Send the nudge
  await sendEmailNudge('usr_abc123', nudgeContent);
  
  // Record that we sent it
  await freqManager.recordNudge('usr_abc123', 'email');
} else {
  console.log(`Skipped nudge: ${canSend.reason}`);
  console.log(`Retry after ${canSend.retry_after} seconds`);
}

// Check user's nudge history
const history = await freqManager.getNudgeHistory('usr_abc123');
console.log('Recent nudges:', history);
// Output: [{ channel: 'email', count: 1, window_remaining: 82341 }]