diff --git a/docs/getting-valid-plan-ids.md b/docs/getting-valid-plan-ids.md new file mode 100644 index 0000000..28938aa --- /dev/null +++ b/docs/getting-valid-plan-ids.md @@ -0,0 +1,175 @@ +# Getting Valid Plan Handle IDs for Testing + +**Author**: Matthew Raymer +**Version**: 1.0.0 +**Status**: Testing Setup Guide + +## Overview + +Plan handle IDs must match the format used by your TimeSafari database. The placeholder IDs (`test_project_1`, etc.) are not valid. This guide explains how to obtain real plan handle IDs for testing. + +## Methods to Get Valid Plan Handle IDs + +### Method 1: Create Projects in TimeSafari App + +1. **Start TimeSafari app** (development or test app) +2. **Create a project** via the UI +3. **Get the plan handle ID**: + - Open browser DevTools (F12) + - Check Network tab for API responses when creating/loading projects + - Look for the `handleId` field in API responses + - Or check localStorage/database for the plan record + +### Method 2: Query Your Local Database + +If you have access to your local TimeSafari database: + +```sql +-- SQLite example +SELECT handleId FROM plans LIMIT 5; + +-- Or check what format handleIds use +SELECT handleId, name FROM plans WHERE name IS NOT NULL LIMIT 10; +``` + +### Method 3: Use Starred Projects from Account Settings + +1. **Open TimeSafari app** +2. **Star some projects** in the UI +3. **Check account settings**: + ```javascript + // In browser console or app + const settings = await $accountSettings(); + console.log(settings.starredPlanHandleIds); + ``` + +### Method 4: Check API Responses + +1. **Query your localhost API**: + ```bash + curl http://localhost:3000/api/v2/report/plans?planHandleIds=[] + ``` +2. **Look for existing projects** in the response + +### Method 5: Extract from Crowd-Master Database + +If you're using crowd-master for testing: + +```bash +cd /home/matthew/projects/timesafari/crowd-master +# Check your local database or API for actual plan handle IDs +``` + +## Plan Handle ID Format + +Plan handle IDs can have different formats depending on your TimeSafari backend: + +- **UUID format**: `550e8400-e29b-41d4-a716-446655440000` +- **Hash format**: `abc123def456789` +- **Sequential**: `plan_001`, `plan_002` +- **Custom format**: Whatever your backend generates + +**Important**: Check your actual TimeSafari API/database to determine the correct format. + +## Updating Test Configuration + +Once you have valid plan handle IDs: + +### Update Test Config + +Edit `test-apps/daily-notification-test/src/config/test-user-zero.ts`: + +```typescript +starredProjects: { + planIds: [ + "your-real-plan-id-1", // Replace with actual IDs + "your-real-plan-id-2", + "your-real-plan-id-3" + ], + // ... +} +``` + +### Update Seed Script Defaults + +Edit `scripts/seed-test-projects.js`: + +```javascript +const DEFAULT_TEST_PROJECT_IDS = [ + "your-real-plan-id-1", // Replace with actual IDs + "your-real-plan-id-2", + "your-real-plan-id-3" +]; +``` + +### Pass IDs via Command Line + +You can also provide IDs when starting the test server: + +```bash +# Start test server with your real plan IDs +node scripts/test-api-server-with-seed.js 3000 "id1,id2,id3" + +# Or when seeding +node scripts/seed-test-projects.js seed http://localhost:3000 "id1,id2,id3" +``` + +## Quick Setup Workflow + +1. **Start your local TimeSafari API** (if you have one) +2. **Create 3-5 test projects** via the UI or API +3. **Note the plan handle IDs** from the responses +4. **Update test-user-zero.ts** with those IDs +5. **Restart test server** with real IDs + +## Using Placeholder IDs (Limited) + +The placeholder IDs (`PLACEHOLDER_ID_1`, etc.) will work for testing the **structure and flow** of the prefetch system, but: + +- ❌ Won't match real projects in your database +- ❌ API responses will be empty or fail validation +- ❌ Can't test actual starred projects querying + +For full testing, you **must** use real plan handle IDs. + +## Troubleshooting + +### "Invalid plan handle ID" errors + +- Check the format matches your database +- Verify IDs exist in your TimeSafari database +- Check API logs for validation errors + +### Empty API responses + +- Plan IDs don't exist in database +- IDs are in wrong format +- Database query is failing + +### Cannot find plan IDs + +- Check Network tab in DevTools when creating projects +- Query database directly +- Check localStorage/IndexedDB for plan records +- Look at API response when loading projects list + +## Example: Finding IDs via Browser DevTools + +1. Open TimeSafari app in browser +2. Open DevTools → Network tab +3. Create a new project +4. Look for POST/GET requests to `/api/v2/plans` or similar +5. Check response JSON for `handleId` field +6. Copy the `handleId` value + +Example response might look like: +```json +{ + "handleId": "abc123def456789", + "name": "My Test Project", + ... +} +``` + +Use that `handleId` in your test configuration. + diff --git a/scripts/seed-test-projects.js b/scripts/seed-test-projects.js index 07d4dcd..c6464be 100755 --- a/scripts/seed-test-projects.js +++ b/scripts/seed-test-projects.js @@ -70,13 +70,27 @@ function generateTestProjectWithClaim(handleId, index = 0) { /** * Default test project IDs from config + * + * NOTE: These are placeholder IDs. For real testing, replace with valid plan handle IDs + * from your TimeSafari database. Valid plan IDs can be obtained by: + * + * 1. Creating a project in the TimeSafari app and noting its handleId + * 2. Querying your local database for existing plan handleIds + * 3. Using the plan handleIds from your starred projects in account settings + * + * Plan handle IDs typically follow the format used by your TimeSafari backend. + * If your localhost has no projects, you may need to create test projects first + * or use the IDs from your staging/production environment. */ const DEFAULT_TEST_PROJECT_IDS = [ - "test_project_1", - "test_project_2", - "test_project_3", - "demo_project_alpha", - "demo_project_beta" + // Replace these with actual plan handle IDs from your TimeSafari setup + // Example formats (check your actual database for real IDs): + // - UUID format: "550e8400-e29b-41d4-a716-446655440000" + // - Hash format: "abc123def456" + // - Or whatever format your TimeSafari API uses + "PLACEHOLDER_ID_1", + "PLACEHOLDER_ID_2", + "PLACEHOLDER_ID_3" ]; /** @@ -205,6 +219,16 @@ if (require.main === module) { { const filename = args[1] || 'test-projects.json'; const projectIds = args[2] ? args[2].split(',') : DEFAULT_TEST_PROJECT_IDS; + + if (projectIds.some(id => id.startsWith('PLACEHOLDER'))) { + console.warn('⚠️ WARNING: Using placeholder IDs. Replace with real plan handle IDs from your TimeSafari database.'); + console.warn(' To get valid IDs:'); + console.warn(' 1. Create projects in TimeSafari app'); + console.warn(' 2. Query your database for plan handleIds'); + console.warn(' 3. Use IDs from starred projects in account settings'); + console.warn(''); + } + exportToJSON(filename, projectIds); } break; @@ -213,6 +237,14 @@ if (require.main === module) { { const apiUrl = args[1] || 'http://localhost:3000'; const projectIds = args[2] ? args[2].split(',') : DEFAULT_TEST_PROJECT_IDS; + + if (projectIds.some(id => id.startsWith('PLACEHOLDER'))) { + console.error('❌ ERROR: Cannot seed with placeholder IDs. Please provide valid plan handle IDs.'); + console.error(' Usage: node scripts/seed-test-projects.js seed ",,"'); + console.error(' Example: node scripts/seed-test-projects.js seed http://localhost:3000 "550e8400-e29b-41d4-a716-446655440000,abc123def456"'); + process.exit(1); + } + seedToLocalhost(apiUrl, projectIds) .then(() => { console.log('✅ Seeding complete'); @@ -229,6 +261,11 @@ if (require.main === module) { default: { const projectIds = args[1] ? args[1].split(',') : DEFAULT_TEST_PROJECT_IDS; + + if (projectIds.some(id => id.startsWith('PLACEHOLDER'))) { + console.warn('⚠️ WARNING: Using placeholder IDs. These need to be replaced with real plan handle IDs.'); + } + const projects = generateAllTestProjects(projectIds); console.log(JSON.stringify({ data: projects }, null, 2)); } diff --git a/scripts/test-api-server-with-seed.js b/scripts/test-api-server-with-seed.js index cd476e7..847471e 100755 --- a/scripts/test-api-server-with-seed.js +++ b/scripts/test-api-server-with-seed.js @@ -38,11 +38,33 @@ app.use((req, res, next) => { * Seed test projects on startup */ function seedProjects(projectIds = DEFAULT_TEST_PROJECT_IDS) { + // Check if using placeholder IDs + if (projectIds.some(id => id.startsWith('PLACEHOLDER'))) { + console.warn(''); + console.warn('⚠️ WARNING: Using placeholder plan handle IDs!'); + console.warn(' The test server will work, but you need to:'); + console.warn(' 1. Get valid plan handle IDs from your TimeSafari database'); + console.warn(' 2. Update test-user-zero.ts with real plan IDs'); + console.warn(' 3. Or provide valid IDs via command line:'); + console.warn(' node scripts/test-api-server-with-seed.js [port] "id1,id2,id3"'); + console.warn(''); + console.warn(' For now, the server will use placeholder IDs for testing structure only.'); + console.warn(''); + } + seededProjects = generateAllTestProjects(projectIds); console.log(`🌱 Seeded ${seededProjects.length} test projects:`); seededProjects.forEach((project, index) => { console.log(` ${index + 1}. ${project.planSummary.handleId} - ${project.planSummary.name}`); }); + + if (projectIds.some(id => id.startsWith('PLACEHOLDER'))) { + console.log(''); + console.log('📝 To use real plan IDs, update:'); + console.log(' test-apps/daily-notification-test/src/config/test-user-zero.ts'); + console.log(' starredProjects.planIds = ["your", "real", "plan", "ids"]'); + console.log(''); + } } /** @@ -143,7 +165,11 @@ app.get('/api/test/health', (req, res) => { }); // Start server -seedProjects(); // Seed on startup +// Allow plan IDs to be passed as command line argument +const planIdsArg = process.argv[3]; +const planIdsToUse = planIdsArg ? planIdsArg.split(',') : DEFAULT_TEST_PROJECT_IDS; + +seedProjects(planIdsToUse); // Seed on startup app.listen(PORT, () => { console.log(''); diff --git a/test-apps/daily-notification-test/src/config/test-user-zero.ts b/test-apps/daily-notification-test/src/config/test-user-zero.ts index 84b9457..f73754a 100644 --- a/test-apps/daily-notification-test/src/config/test-user-zero.ts +++ b/test-apps/daily-notification-test/src/config/test-user-zero.ts @@ -81,13 +81,26 @@ export const TEST_USER_ZERO_CONFIG = { // Test Starred Projects (mock data for testing) starredProjects: { - // Sample starred project IDs for testing + // IMPORTANT: Replace these with valid plan handle IDs from your TimeSafari database + // + // To get valid plan IDs: + // 1. Create projects in TimeSafari app and note their handleId from API responses + // 2. Query your local database: SELECT handleId FROM plans LIMIT 5 + // 3. Check starred projects in account settings: settings.starredPlanHandleIds + // 4. See docs/getting-valid-plan-ids.md for detailed instructions + // + // Plan handle IDs can be: + // - UUIDs: "550e8400-e29b-41d4-a716-446655440000" + // - Hashes: "abc123def456789" + // - Or any format your TimeSafari backend uses + // + // For localhost testing with no projects, you can: + // - Use the test API server: node scripts/test-api-server-with-seed.js + // - Or create test projects first, then use their IDs here planIds: [ - "test_project_1", - "test_project_2", - "test_project_3", - "demo_project_alpha", - "demo_project_beta" + "PLACEHOLDER_ID_1", // Replace with real plan handle ID + "PLACEHOLDER_ID_2", // Replace with real plan handle ID + "PLACEHOLDER_ID_3" // Replace with real plan handle ID ], // Last acknowledged JWT ID (for pagination testing)