vibefast-cli 0.2.4 → 0.3.0

package/2/vf-agent/data/knowledge_base/starter-docs/push-notifications-reference.md

@@ -0,0 +1,453 @@
+# Push Notifications Reference
+
+> Frontend paths reference the Expo workspace (`apps/native/src/...`); backend paths reference `packages/backend/convex/...` when calling server functions.
+
+## Overview
+
+The VibeFast starter kit includes a complete, end-to-end push notification system with deep linking, local notifications, and notification history. It allows the app to register for notifications, securely store user tokens on the backend, send targeted notifications from server-side Convex actions, and handle user interactions with notifications.
+
+### Core Technologies
+
+- **[Expo Push Notifications](https://docs.expo.dev/push-notifications/overview/):** The entire system is built on Expo's push notification service. The frontend uses `expo-notifications` to get a token, and the backend sends messages via Expo's `https://exp.host/--/api/v2/push/send` HTTP endpoint.
+- **[Convex Actions & Mutations](https://docs.convex.dev/functions):** The backend logic for storing tokens and sending messages is encapsulated in Convex functions, ensuring that no sensitive credentials or logic are exposed on the client.
+- **[Expo Router Deep Linking](https://docs.expo.dev/router/reference/linking/):** Notifications can include deep link data to navigate users to specific screens when they tap on a notification.
+- **[AsyncStorage](https://react-native-async-storage.github.io/async-storage/):** Local notification history and preferences are stored securely on the device.
+
+## Getting Started
+
+The push notification system is ready to use out-of-the-box. It works on physical devices, not simulators. The necessary permissions will be requested from the user automatically when needed.
+
+### Setup
+
+1. **Add the NotificationProvider to your app root:**
+
+```tsx
+// apps/native/src/app/_layout.tsx
+import { NotificationProvider } from '@/providers/notification-provider';
+
+export default function RootLayout() {
+  return (
+    <NotificationProvider>
+      {/* Your existing app layout */}
+    </NotificationProvider>
+  );
+}
+```
+
+The `NotificationProvider` automatically:
+
+- Initializes notification listeners
+- Handles deep link navigation when notifications are tapped
+- Stores notification history locally
+- Manages notification permissions
+
+### Push Notification Flow
+
+1.  **Registration (Frontend):**
+    - The `usePushNotifications` hook is the central point for frontend logic.
+    - Its `registerForPushNotificationsAsync` function is called (e.g., when a user enables notifications in settings).
+    - The function requests permission from the user via the OS.
+    - If permission is granted, it calls `Notifications.getExpoPushTokenAsync()` to get the unique device token.
+    - It then calls the `recordPushToken` Convex mutation, sending the token to the backend to be stored securely.
+2.  **Storage (Backend):**
+    - The `recordPushToken` mutation receives the token and associates it with the currently authenticated user in the `pushTokens` table.
+    - This creates a link between a user in your database and a specific device that can receive notifications.
+3.  **Sending (Backend):**
+    - A Convex `action` (e.g., `sendPushNotification`) is called with a `userId`, message content, and optional deep link data.
+    - The action looks up the user's push token from the `pushTokens` table.
+    - It constructs a `POST` request to the Expo Push API with the user's token, message payload, and deep link data.
+    - Expo receives the request and delivers the notification to the user's device.
+4.  **User Interaction:**
+    - When the user taps on a notification, the `NotificationProvider` intercepts it.
+    - The `deepLinkHandler` validates and processes the deep link data.
+    - The user is navigated to the appropriate screen with the correct parameters.
+    - The notification is stored in local history and marked as read.
+
+## Key Components & Hooks
+
+### Core Hooks
+
+- **`usePushNotifications` (`apps/native/src/core/notifications/`):** This is the primary hook for all client-side push notification interactions. It abstracts away the entire registration process and provides simple functions to use in your UI components.
+  - `registerForPushNotificationsAsync()`: Handles the full registration flow.
+  - `toggleNotifications()`: Allows enabling or disabling notifications by calling the backend `togglePushNotifications` mutation.
+  - It also exposes the user's current notification status (`hasToken`, `paused`).
+
+### Core Providers
+
+- **`NotificationProvider` (`apps/native/src/providers/notification-provider.tsx`):** The central provider that manages all notification functionality. It should wrap your app root and handles:
+  - Notification listeners (foreground, background, tap events)
+  - Deep link navigation
+  - Notification history storage
+  - Permission management
+
+### Core Managers
+
+- **`localNotificationManager` (`apps/native/src/core/local-notifications/local-notification-manager.ts`):** Manages local notifications (scheduled on-device).
+  - `scheduleNotification()`: Schedule a notification with full control over timing and content.
+  - `scheduleNotificationWithDelay()`: Schedule a notification to fire after a delay (e.g., "in 1 hour").
+  - `scheduleNotificationForDate()`: Schedule a notification for a specific date/time.
+  - `cancelNotification()`: Cancel a scheduled notification.
+  - `cancelAllNotifications()`: Cancel all scheduled notifications.
+  - `getScheduledNotifications()`: Get all currently scheduled notifications.
+
+- **`deepLinkHandler` (`apps/native/src/core/navigation/deep-link-handler.ts`):** Handles deep link navigation from notifications.
+  - `handleNotificationPress()`: Process notification data and navigate to the appropriate screen.
+  - `validateDeepLink()`: Validate a deep link URL against allowed patterns.
+  - Supports internal navigation, external URLs, and custom actions.
+
+- **`notificationStorage` (`apps/native/src/core/storage/notification-storage.ts`):** Manages local notification history.
+  - `saveNotification()`: Store a notification in local history.
+  - `getAllNotifications()`: Get all stored notifications.
+  - `getUnreadCount()`: Get count of unread notifications.
+  - `markAsRead()`: Mark a notification as read.
+  - `clearAll()`: Clear all notification history.
+
+### Core Components
+
+- **`NotificationItem` (`apps/native/src/components/settings/`):** A ready-to-use settings component that allows the user to toggle push notifications on or off. It uses the `usePushNotifications` hook internally.
+
+- **`NotificationDemo` (`apps/native/src/components/demo/notification-demo.tsx`):** A comprehensive demo component for testing all notification features including push notifications, local notifications, deep links, and notification history.
+
+## How-To Guides
+
+### 1. Prompt a User to Enable Notifications
+
+You can use the `usePushNotifications` hook in any component to prompt the user to register.
+
+```tsx
+import { usePushNotifications } from '@/core/notifications';
+import { Button } from '@/components/ui';
+
+function MyComponent() {
+  const { registerForPushNotificationsAsync, status } = usePushNotifications();
+
+  // Don't show the button if they already have a token
+  if (status.hasToken) {
+    return null;
+  }
+
+  return (
+    <Button
+      label="Enable Notifications"
+      onPress={registerForPushNotificationsAsync}
+    />
+  );
+}
+```
+
+### 2. Send a Notification with Deep Links
+
+You can easily send a notification to a user from any Convex action with deep link data for navigation.
+
+```ts
+// packages/backend/convex/myFeature.ts
+import { action } from './_generated/server';
+import { api } from './_generated/api';
+import { v } from 'convex/values';
+
+export const doSomethingAndNotify = action({
+  args: {
+    userIdToNotify: v.id('users'),
+    chatId: v.string(),
+    message: v.string(),
+  },
+  handler: async (ctx, args) => {
+    // ... your feature's logic here ...
+
+    // After your logic is complete, send the notification with deep link
+    await ctx.runAction(api.pushNotificationFunctions.sendPushNotification, {
+      toUserId: args.userIdToNotify,
+      title: 'You have a new message!',
+      body: args.message,
+      data: {
+        type: 'deep_link',
+        url: `/chat/${args.chatId}`,
+        screen: 'chat',
+        params: { chatId: args.chatId },
+      },
+    });
+
+    // ...
+  },
+});
+```
+
+**Supported Deep Link Types:**
+
+- **Internal Navigation:** Navigate to a screen within the app
+
+  ```ts
+  data: {
+    type: 'deep_link',
+    url: '/profile/user-123',
+    screen: 'profile',
+    params: { userId: 'user-123' }
+  }
+  ```
+
+- **External URLs:** Open a URL in the browser
+
+  ```ts
+  data: {
+    type: 'external_url',
+    url: 'https://vibefast.app'
+  }
+  ```
+
+- **Custom Actions:** Trigger custom app actions
+  ```ts
+  data: {
+    type: 'action',
+    action: 'refresh',
+    params: { source: 'notification' }
+  }
+  ```
+
+### 3. Schedule Local Notifications
+
+Local notifications are scheduled on the device and don't require a backend call.
+
+```tsx
+import { localNotificationManager } from '@/core/local-notifications/local-notification-manager';
+
+function ReminderComponent() {
+  // Schedule for 1 hour from now
+  const scheduleReminder = async () => {
+    await localNotificationManager.scheduleNotificationWithDelay(
+      {
+        title: 'Medication Reminder',
+        body: 'Time to take your medication',
+        data: {
+          type: 'deep_link',
+          url: '/health/medications',
+          screen: 'medications',
+        },
+      },
+      60 * 60,
+    ); // 1 hour in seconds
+  };
+
+  // Schedule for specific date
+  const scheduleDailyCheckIn = async () => {
+    const tomorrow = new Date();
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    tomorrow.setHours(9, 0, 0, 0);
+
+    await localNotificationManager.scheduleNotificationForDate(
+      {
+        title: 'Daily Check-in',
+        body: 'Time for your daily check-in!',
+        data: {
+          type: 'deep_link',
+          url: '/checkin',
+        },
+      },
+      tomorrow,
+    );
+  };
+
+  return (
+    <View>
+      <Button title="Schedule Reminder" onPress={scheduleReminder} />
+      <Button title="Schedule Daily Check-in" onPress={scheduleDailyCheckIn} />
+    </View>
+  );
+}
+```
+
+**Note:** iOS limits scheduled notifications to 64. Use `getScheduledNotifications()` to check the current count.
+
+### 4. Handle Deep Links Manually
+
+The `NotificationProvider` handles deep links automatically, but you can also handle them manually:
+
+```tsx
+import { deepLinkHandler } from '@/core/navigation/deep-link-handler';
+
+function CustomHandler() {
+  const handleCustomNavigation = async () => {
+    // Navigate to specific screen
+    await deepLinkHandler.handleNotificationPress({
+      type: 'deep_link',
+      url: '/profile/123',
+      screen: 'profile',
+      params: { userId: '123' },
+    });
+
+    // Open external URL
+    await deepLinkHandler.handleNotificationPress({
+      type: 'external_url',
+      url: 'https://example.com',
+    });
+
+    // Execute custom action
+    await deepLinkHandler.handleNotificationPress({
+      type: 'action',
+      action: 'refresh',
+      params: { source: 'notification' },
+    });
+  };
+}
+```
+
+### 5. Access Notification History
+
+```tsx
+import { notificationStorage } from '@/core/storage/notification-storage';
+
+function NotificationHistoryScreen() {
+  const [notifications, setNotifications] = useState([]);
+  const [unreadCount, setUnreadCount] = useState(0);
+
+  useEffect(() => {
+    loadNotifications();
+  }, []);
+
+  const loadNotifications = async () => {
+    const history = await notificationStorage.getAllNotifications();
+    const count = await notificationStorage.getUnreadCount();
+    setNotifications(history);
+    setUnreadCount(count);
+  };
+
+  const markAsRead = async (id: string) => {
+    await notificationStorage.markAsRead(id);
+    loadNotifications();
+  };
+
+  return (
+    <View>
+      <Text>Unread: {unreadCount}</Text>
+      {notifications.map((notif) => (
+        <TouchableOpacity key={notif.id} onPress={() => markAsRead(notif.id)}>
+          <Text>{notif.title}</Text>
+          <Text>{notif.body}</Text>
+        </TouchableOpacity>
+      ))}
+    </View>
+  );
+}
+```
+
+## Backend (Convex)
+
+- **`packages/backend/convex/pushNotificationFunctions.ts`:** This file contains all the backend logic.
+  - `recordPushToken` (mutation): Securely stores or updates a user's Expo push token.
+  - `getNotificationStatus` (query): Fetches the current notification preferences for the logged-in user.
+  - `togglePushNotifications` (mutation): Allows users to pause or resume notifications.
+  - `sendPushNotification` (action): The core function for sending a message. It takes a `userId`, message content, and optional deep link data payload, and sends it to the Expo push service.
+  - `sendTestNotification` (action): A useful utility for developers to easily test if a user's device is correctly registered.
+
+## Testing
+
+### Use the Demo Component
+
+The `NotificationDemo` component provides a comprehensive testing interface:
+
+```tsx
+import { NotificationDemo } from '@/components/demo/notification-demo';
+
+function TestScreen() {
+  return <NotificationDemo />;
+}
+```
+
+Features:
+
+- Test push notifications with deep links
+- Schedule local notifications
+- Test deep link navigation
+- View notification history
+- Manage permissions
+
+### Test Deep Links in Development
+
+```bash
+# iOS Simulator
+xcrun simctl openurl booted "vibefast://chat/test-chat-id"
+
+# Android Emulator
+adb shell am start -W -a android.intent.action.VIEW -d "vibefast://chat/test-chat-id" com.your.package.id
+```
+
+## Security & Validation
+
+### URL Validation
+
+All deep link URLs are validated against allowed patterns in `deepLinkHandler`:
+
+- `/chat/*` - Chat screens
+- `/profile/*` - Profile screens
+- `/settings/*` - Settings screens
+- `/analysis/*` - Analysis screens
+- `/` - Home screen
+
+### External URL Handling
+
+External URLs show a confirmation dialog before opening to prevent phishing attacks.
+
+### Data Sanitization
+
+All notification data is type-validated in Convex functions using `v.object()` validators.
+
+## Platform-Specific Notes
+
+### iOS
+
+- Maximum 64 scheduled local notifications
+- Notification sounds limited to built-in sounds or custom sounds in app bundle
+- Background execution limited by iOS
+
+### Android
+
+- Requires `POST_NOTIFICATIONS` permission (Android 13+)
+- Supports custom notification sounds
+- Badge support varies by launcher
+
+## Best Practices
+
+1. **Always include deep link data** in push notifications for better user experience
+2. **Use relative scheduling** ("in 1 hour") instead of absolute times when possible
+3. **Limit scheduled notifications** to stay under iOS 64 limit
+4. **Test on both platforms** - notification behavior can differ significantly
+5. **Handle permissions gracefully** - some users may deny notifications
+6. **Use categories** to organize notification types
+7. **Don't rely on notifications for critical features** - they can be disabled by users
+8. **Store important notifications** in your backend database, not just locally
+9. **Validate deep link URLs** to prevent navigation to invalid screens
+10. **Log notification interactions** for analytics and debugging
+
+## Troubleshooting
+
+### Notifications not showing
+
+```tsx
+// Check permissions
+const status = await localNotificationManager.getPermissions();
+if (status !== 'granted') {
+  await localNotificationManager.requestPermissions();
+}
+```
+
+### Deep links not working
+
+```tsx
+// Verify URL format
+const isValid = deepLinkHandler.validateDeepLink('/chat/123');
+console.log('Is valid:', isValid);
+```
+
+### Local notifications not firing
+
+```tsx
+// Check scheduled count (iOS limit: 64)
+const scheduled = await localNotificationManager.getScheduledNotifications();
+console.log('Scheduled notifications:', scheduled.length);
+```
+
+## Additional Resources
+
+- [Expo Notifications Documentation](https://docs.expo.dev/versions/latest/sdk/notifications/)
+- [Expo Router Deep Linking](https://docs.expo.dev/router/reference/linking/)
+- [Convex Actions](https://docs.convex.dev/functions/actions)
+- Demo component: `apps/native/src/components/demo/notification-demo.tsx`

package/2/vf-agent/data/knowledge_base/starter-docs/quick-actions-reference.md

@@ -0,0 +1,253 @@
+# Quick Actions Reference
+
+> Frontend paths reference the Expo workspace (`apps/native/src/...`).
+
+## Quick Start
+
+The Quick Actions feature is automatically configured and ready to use. Here's everything you need to know:
+
+### Immediate Usage
+
+1. **Settings Management**: Go to Settings → Quick Actions to manage actions
+2. **Demo & Testing**: Visit Settings → Quick Actions Demo for interactive testing
+3. **Device Testing**: Long-press the app icon on your device to see quick actions
+
+### Default Actions
+
+The starter comes with 4 pre-configured quick actions:
+
+- **Home**: Navigate to home tab
+- **Profile**: Navigate to profile tab
+- **Settings**: Navigate to settings tab
+- **Search**: Navigate to home with search focus
+
+## Developer API
+
+### Basic Usage
+
+```tsx
+import {
+  quickActionsManager,
+  useQuickActionRouting,
+} from '@/features/quick-actions';
+
+// In your root layout (already configured)
+useQuickActionRouting();
+
+// Programmatic management
+await quickActionsManager.setActions([
+  {
+    id: 'custom',
+    title: 'Custom Action',
+    icon: 'symbol:star',
+    params: { href: '/custom-route' },
+  },
+]);
+```
+
+### Manager Methods
+
+```tsx
+// Set custom actions
+await quickActionsManager.setActions(actions);
+
+// Add single action
+await quickActionsManager.addAction(action);
+
+// Remove action by ID
+await quickActionsManager.removeAction('action-id');
+
+// Reset to defaults
+await quickActionsManager.resetToDefaults();
+
+// Set feature-specific actions
+await quickActionsManager.setFeatureActions();
+
+// Check support
+const isSupported = await quickActionsManager.isSupported();
+
+// Get max count
+const maxCount = quickActionsManager.getMaxCount();
+```
+
+### Hooks
+
+```tsx
+import {
+  useQuickActionRouting,
+  useCurrentQuickAction,
+  useSetupQuickActions,
+} from '@/features/quick-actions';
+
+// Enable automatic routing (use in root layout)
+useQuickActionRouting();
+
+// Get current quick action
+const currentAction = useCurrentQuickAction();
+
+// Set up actions on component mount
+useSetupQuickActions(myActions);
+```
+
+## Icon Reference
+
+### System Icons (Cross-platform)
+
+- `"home"`, `"search"`, `"add"`, `"contact"`
+- `"play"`, `"pause"`, `"share"`, `"favorite"`
+- `"mail"`, `"message"`, `"date"`, `"time"`
+
+### SF Symbols (iOS only)
+
+Use `"symbol:"` prefix:
+
+- `"symbol:heart.fill"`, `"symbol:star.fill"`
+- `"symbol:gear"`, `"symbol:person.fill"`
+- `"symbol:magnifyingglass"`, `"symbol:plus"`
+
+### Custom Assets
+
+Use `"asset:"` prefix:
+
+- `"asset:my-custom-icon"`
+- Requires configuration in app.config.ts
+
+## Configuration Examples
+
+### Basic Action
+
+```tsx
+{
+  id: 'home',
+  title: 'Home',
+  icon: 'home',
+  params: { href: '/(tabs)/' }
+}
+```
+
+### Advanced Action with Subtitle
+
+```tsx
+{
+  id: 'ai-chat',
+  title: 'AI Chat',
+  subtitle: 'Chat with AI assistant',
+  icon: 'symbol:message',
+  params: {
+    href: '/(root)/(protected)/chatbot/',
+    source: 'quick-action'
+  }
+}
+```
+
+### External Link Action
+
+```tsx
+{
+  id: 'support',
+  title: 'Support',
+  subtitle: 'Get help',
+  icon: 'symbol:questionmark.circle',
+  params: { href: 'mailto:support@myapp.com' }
+}
+```
+
+## Platform Differences
+
+### iOS
+
+- **Maximum**: 4 actions (Apple recommendation)
+- **Icons**: SF Symbols preferred, system icons supported
+- **Appearance**: 3D Touch/Haptic Touch menu
+- **Behavior**: Actions appear in consistent order
+
+### Android
+
+- **Maximum**: Variable (device dependent, typically 4-15)
+- **Icons**: Adaptive icons supported, system icons available
+- **Appearance**: Long-press context menu
+- **Behavior**: Actions can be pinned to home screen
+
+## Best Practices
+
+### Action Design
+
+1. **Limit Count**: Use 4 or fewer actions for optimal UX
+2. **Clear Titles**: Keep titles short and descriptive (max 2 words)
+3. **Meaningful Icons**: Use recognizable, consistent icons
+4. **Logical Order**: Place most important actions first
+
+### Technical Implementation
+
+1. **Deep Linking**: Always provide `href` params for navigation
+2. **Error Handling**: Gracefully handle unsupported devices
+3. **Performance**: Actions are cached, updates are efficient
+4. **Testing**: Test on both iOS and Android devices
+
+### User Experience
+
+1. **Discoverability**: Don't rely solely on quick actions for core features
+2. **Consistency**: Keep actions stable, avoid frequent changes
+3. **Accessibility**: Ensure titles are descriptive for screen readers
+4. **Feedback**: Provide visual feedback when actions are triggered
+
+## Troubleshooting
+
+### Actions Not Appearing
+
+- Check device support: `await quickActionsManager.isSupported()`
+- Verify app is built for device (not Expo Go)
+- Check console for error messages
+- Ensure actions array is not empty
+
+### Navigation Not Working
+
+- Verify routes exist in your app structure
+- Check `useQuickActionRouting()` is called in root layout
+- Validate `href` params in action configuration
+- Test navigation manually first
+
+### Icons Not Showing
+
+- Use valid system icon names or SF Symbols
+- For custom icons, configure in app.config.ts
+- Check platform-specific icon requirements
+- Test with system icons first
+
+## Advanced Usage
+
+### Custom Manager
+
+```tsx
+class CustomQuickActionsManager extends QuickActionsManager {
+  async setContextualActions(context: string) {
+    const actions = this.getActionsForContext(context);
+    await this.setActions(actions);
+  }
+}
+```
+
+### Analytics Integration
+
+```tsx
+useQuickActionCallback((action) => {
+  analytics.track('quick_action_used', {
+    action_id: action.id,
+    action_title: action.title,
+  });
+});
+```
+
+### Dynamic Actions
+
+```tsx
+useEffect(() => {
+  const updateActions = async () => {
+    const userRole = await getUserRole();
+    const actions = getActionsForRole(userRole);
+    await quickActionsManager.setActions(actions);
+  };
+
+  updateActions();
+}, [userRole]);
+```