# TimeSafari Test Apps Setup Guide

## Overview

This guide creates minimal Capacitor test apps for validating the TimeSafari Daily Notification Plugin integration across all target platforms. The test apps demonstrate TimeSafari's community-building features, Endorser.ch API integration, and notification patterns.

## Directory Structure

```
test-apps/
├── android-test/          # Android test app
├── ios-test/              # iOS test app  
├── electron-test/         # Electron test app
├── test-api/              # TimeSafari Test API server
├── shared/                # Shared configuration and utilities
│   └── config-loader.ts   # Configuration loader and mock services
├── config/                # Configuration files
│   └── timesafari-config.json
├── setup-android.sh       # Android setup script
├── setup-ios.sh           # iOS setup script
├── setup-electron.sh      # Electron setup script
├── check-environment.sh   # Environment verification
├── SETUP_GUIDE.md         # Enhanced setup guide
└── README.md              # This guide
```

## Prerequisites

- Node.js 18+
- Capacitor CLI: `npm install -g @capacitor/cli`
- Android Studio (for Android)
- Xcode (for iOS)
- Platform-specific SDKs
- Understanding of TimeSafari's community-building purpose
- Familiarity with Endorser.ch API patterns

## Quick Start

### Option 1: Automated Setup (Recommended)
```bash
# Navigate to test-apps directory first
cd test-apps

# Setup all platforms (run from test-apps directory)
./setup-android.sh
./setup-ios.sh  
./setup-electron.sh
```

**⚠️ Important**: Run setup scripts from the `test-apps` directory, not from individual platform directories.

### Option 2: Manual Setup
See [Enhanced Setup Guide](SETUP_GUIDE.md) for detailed manual setup instructions and troubleshooting.

### Prerequisites Check
```bash
# Check your environment before setup
./check-environment.sh
```

**Required Software**:
- **Node.js 18+**: Required for all platforms
- **Android Studio**: Required for Android testing
- **Xcode**: Required for iOS testing (macOS only)
- **No additional requirements**: For Electron testing

## Test App Features

Each test app includes:
- **TimeSafari Configuration**: Test community-focused notification settings
- **Endorser.ch API Integration**: Test real API patterns with pagination
- **Community Notification Scheduling**: Test offers, projects, people, and items notifications
- **Platform-Specific Features**: 
  - Android: Exact alarm permissions, reboot recovery
  - iOS: Rolling window management, BGTaskScheduler
  - Electron: Mock implementations, IPC communication
- **Performance Monitoring**: Metrics collection and display
- **Error Handling**: Comprehensive error testing
- **Debug Information**: Platform-specific debug data

## TimeSafari Test API Server

A comprehensive REST API server (`test-api/`) simulates Endorser.ch API endpoints for testing the plugin's TimeSafari-specific functionality:

### Quick Start
```bash
# Start the TimeSafari Test API server
cd test-apps/test-api
npm install
npm start

# Test the API
npm run demo
```

### Key Features
- **Endorser.ch API Simulation**: Mock endpoints for offers, projects, and pagination
- **TimeSafari Notification Bundle**: Single route for bundled notifications
- **Community Analytics**: Analytics endpoint for community events
- **Pagination Support**: Full afterId/beforeId pagination testing
- **ETag Support**: HTTP caching with conditional requests
- **Error Simulation**: Test various error scenarios
- **Metrics**: Monitor API usage and performance
- **CORS Enabled**: Cross-origin requests supported

### API Endpoints

#### Endorser.ch API Endpoints
- `GET /api/v2/report/offers` - Get offers to person
- `GET /api/v2/report/offersToPlansOwnedByMe` - Get offers to user's projects
- `POST /api/v2/report/plansLastUpdatedBetween` - Get changes to starred projects

#### TimeSafari API Endpoints
- `GET /api/v2/report/notifications/bundle` - Get bundled notifications
- `POST /api/analytics/community-events` - Send community analytics

#### Legacy Endpoints
- `GET /health` - Health check
- `GET /api/content/:slotId` - Get notification content
- `GET /api/metrics` - API metrics

### Platform-Specific URLs
- **Web/Electron**: `http://localhost:3001`
- **Android Emulator**: `http://10.0.2.2:3001`
- **iOS Simulator**: `http://localhost:3001`
- **Physical Devices**: `http://[YOUR_IP]:3001`

## Platform-Specific Testing

### Android Test App
- **TimeSafari Configuration**: Test community notification settings
- **Endorser.ch API Integration**: Test parallel API requests
- **Exact Alarm Status**: Check permission and capability
- **Permission Requests**: Test exact alarm permission flow
- **Performance Metrics**: Monitor Android-specific optimizations
- **Reboot Recovery**: Validate system restart handling

### iOS Test App  
- **TimeSafari Configuration**: Test iOS community features
- **Rolling Window**: Test notification limit management
- **Endorser.ch API Integration**: Test pagination patterns
- **Background Tasks**: Validate BGTaskScheduler integration
- **Performance Metrics**: Monitor iOS-specific optimizations
- **Memory Management**: Test object pooling and cleanup

### Electron Test App
- **TimeSafari Configuration**: Test Electron community features
- **Mock Implementations**: Test web platform compatibility
- **Endorser.ch API Integration**: Test API patterns
- **IPC Communication**: Validate Electron-specific APIs
- **Development Workflow**: Test plugin integration
- **Debug Information**: Platform-specific status display

## Running the Test Apps

### Android
```bash
cd android-test
npm run dev          # Web development server
npx cap open android # Open in Android Studio
npx cap run android  # Run on device/emulator
```

### iOS
```bash
cd ios-test
npm run dev         # Web development server
npx cap open ios    # Open in Xcode
npx cap run ios     # Run on device/simulator
```

### Electron
```bash
cd electron-test
npm start           # Run Electron app
npm run dev         # Run in development mode
```

## Testing Checklist

### Core Functionality
- [ ] TimeSafari configuration works
- [ ] Community notification scheduling succeeds
- [ ] Endorser.ch API integration functions properly
- [ ] Error handling functions properly
- [ ] Performance metrics are accurate

### Platform-Specific
- [ ] Android exact alarm permissions
- [ ] iOS rolling window management
- [ ] Electron mock implementations
- [ ] Cross-platform API consistency

### TimeSafari Integration
- [ ] Plugin loads without errors
- [ ] Configuration persists across sessions
- [ ] Endorser.ch API pagination works
- [ ] Community notification types process correctly
- [ ] Performance optimizations active
- [ ] Debug information accessible

## Troubleshooting

### Common Issues
1. **"Unknown command: cap"** → Install Capacitor CLI: `npm install -g @capacitor/cli`
2. **"android platform has not been added yet"** → Run `npx cap add android` first
3. **Build failures** → Check Node.js version (18+) and clear cache: `npm cache clean --force`
4. **Platform errors** → Verify platform-specific SDKs are installed
5. **API connection errors** → Ensure test API server is running on port 3001

### Quick Fixes
```bash
# Check environment
./check-environment.sh

# Reinstall dependencies
rm -rf node_modules && npm install

# Clear Capacitor cache
npx cap clean

# Re-sync platforms
npx cap sync

# Restart test API server
cd test-api && npm start
```

### Detailed Help
See [Enhanced Setup Guide](SETUP_GUIDE.md) for comprehensive troubleshooting and platform-specific solutions.

## Next Steps

1. **Run Setup Scripts**: Execute platform-specific setup
2. **Start Test API Server**: Run the TimeSafari Test API server
3. **Test Core Features**: Validate basic TimeSafari functionality
4. **Test Platform Features**: Verify platform-specific capabilities
5. **Test Endorser.ch Integration**: Validate API patterns and pagination
6. **Integration Testing**: Test with actual plugin implementation
7. **Performance Validation**: Monitor metrics and optimizations