Add iOS prefetch testing guide with detailed procedures, log checklists,
and behavior classification. Enhance iOS test app requirements with
security constraints, sign-off checklists, and changelog structure.
Update main directive with testing strategy and method behavior mapping.
Changes:
- Add IOS_PREFETCH_TESTING.md with simulator/device test plans, log
diagnostics, telemetry expectations, and test run templates
- Add DailyNotificationBackgroundTaskTestHarness.swift as reference
implementation for BGTaskScheduler testing
- Enhance IOS_TEST_APP_REQUIREMENTS.md with security/privacy constraints,
review checklists, CI hints, and glossary cross-links
- Update 0003-iOS-Android-Parity-Directive.md with testing strategy
section, method behavior classification, and validation matrix updates
All documents now include changelog stubs, cross-references, and
completion criteria for Phase 1 implementation and testing.
Fixed scheduleDailyNotification to read parameters directly from CAPPluginCall
(matching Android pattern) instead of looking for wrapped "options" object.
Improved BGTaskScheduler error handling to clearly indicate simulator limitations.
Changes:
- Read parameters directly from call (call.getString("time"), etc.) instead of
call.getObject("options") - Capacitor passes options object directly as call data
- Improved BGTaskScheduler error handling with clear simulator limitation message
- Added priority parameter extraction (was missing)
- Error handling doesn't fail notification scheduling if background fetch fails
BGTaskScheduler Simulator Limitation:
- BGTaskSchedulerErrorDomain Code=1 (notPermitted) is expected on simulator
- Background fetch scheduling fails on simulator but works on real devices
- Notification scheduling still works correctly; prefetch won't run on simulator
- Error messages now clearly indicate this is expected behavior
Result: scheduleDailyNotification now works correctly. Notification scheduling
verified working on simulator. Background fetch error is expected and documented.
Files modified:
- ios/Plugin/DailyNotificationPlugin.swift: Parameter reading fix, error handling
- doc/directives/0003-iOS-Android-Parity-Directive.md: Implementation details documented
Capacitor iOS was not discovering DailyNotificationPlugin because it did not
conform to the CAPBridgedPlugin protocol required for runtime discovery.
Changes:
- Add @objc extension to DailyNotificationPlugin implementing CAPBridgedPlugin
with identifier, jsName, and pluginMethods properties
- Force-load plugin framework in AppDelegate before Capacitor initializes
- Remove duplicate BGTaskScheduler registration from AppDelegate (plugin handles it)
- Update podspec to use dynamic framework (static_framework = false)
- Add diagnostic logging to verify plugin discovery
Result: Plugin is now discovered by Capacitor and all methods are accessible
from JavaScript. Verified working with checkPermissionStatus() method.
Files modified:
- ios/Plugin/DailyNotificationPlugin.swift: Added CAPBridgedPlugin extension
- test-apps/ios-test-app/ios/App/App/AppDelegate.swift: Force-load + diagnostics
- ios/DailyNotificationPlugin.podspec: Dynamic framework setting
- doc/directives/0003-iOS-Android-Parity-Directive.md: Documented solution
Fix three critical issues in the Android notification system:
1. configureNativeFetcher() now actually calls nativeFetcher.configure() method
- Previously only stored config in database without configuring fetcher instance
- Added synchronous configure() call with proper error handling
- Stores valid but empty config entry if configure() fails to prevent downstream errors
- Adds FETCHER|CONFIGURE_START and FETCHER|CONFIGURE_COMPLETE instrumentation logs
2. Prefetch operations now use DailyNotificationFetchWorker instead of legacy FetchWorker
- Replaced FetchWorker.scheduleDelayedFetch() with WorkManager scheduling
- Uses correct input data format (scheduled_time, fetch_time, retry_count, immediate)
- Enables native fetcher SPI to be used for prefetch operations
- Handles both delayed and immediate prefetch scenarios
3. Notification dismiss now cancels notification from NotificationManager
- Added notification cancellation before removing from storage
- Uses notificationId.hashCode() to match display notification ID
- Ensures notification disappears immediately when dismiss button is clicked
- Adds DN|DISMISS_CANCEL_NOTIF instrumentation log
Version bump: 1.0.8 → 1.0.11
Fix issue where prefetch worker saved content to ContentCache but didn't
create NotificationContentEntity, causing notification worker to skip
notifications with "content_not_found" error.
Changes:
- Extract notificationTime from input data in doWork()
- Create NotificationContentEntity with matching notification_id when
notificationTime > 0 (prefetch operations)
- Add parsePayload() helper to extract title/body from JSON or plain text
- Save entity to Room database so notification worker can find it
The notification_id format matches NotifyReceiver.kt: "notify_${notificationTime}",
ensuring the notification worker can retrieve content when the alarm fires.
Fixes issue where alarms triggered correctly but notifications were skipped
because DailyNotificationWorker couldn't find content in storage.
Fix reflection-based permission check that was failing with NoSuchMethodException.
Add multiple fallback strategies to ensure permission check works reliably.
Changes:
- Add getDeclaredMethod() fallback when getMethod() fails
- Add heuristic fallback: if exact alarms not allowed, assume they can be requested
- Improve error handling: catch NoSuchMethodException separately from other exceptions
- Add debug logging to track which reflection path is taken
- Change reflection failure log level from ERROR to WARNING (we have fallback)
The heuristic fallback is safe because:
- If exact alarms are not currently allowed, we should try to request them
- Only edge case is permanently denied (rare), worst case is unnecessary Settings redirect
- Better than failing silently or blocking permission requests
Fixes reflection failures seen in logcat where Settings.canRequestScheduleExactAlarms()
method lookup was failing, causing unnecessary Settings redirects.
Add comprehensive exact alarm permission handling for Android 12+ (API 31+)
and fix critical bugs preventing notifications from triggering.
Features:
- Add checkExactAlarmPermission() and requestExactAlarmPermission() plugin methods
- Add canScheduleExactAlarms() and canRequestExactAlarmPermission() helper methods
- Update all scheduling methods to check/request permission before scheduling
- Use reflection for canRequestScheduleExactAlarms() to avoid compilation issues
Bug Fixes:
- Fix receiver mismatch: change alarm intents from NotifyReceiver to DailyNotificationReceiver
- Fix coroutine compilation error: wrap getLatest() suspend call in runBlocking
- Store notification content in database before scheduling alarms
- Update intent action to match manifest registration
The permission request flow opens Settings intent when SCHEDULE_EXACT_ALARM
permission is not granted, providing clear user guidance. All scheduling
methods now check permission status and request it if needed before proceeding.
Version bumped to 1.0.8
- Add cancelAllNotifications() method to DailyNotificationPlugin
- Cancels all AlarmManager alarms (exact and inexact)
- Cancels all WorkManager prefetch/fetch jobs by tag
- Clears notification schedules from database (sets enabled=false)
- Idempotent - safe to call multiple times
- Implementation details:
- Reads scheduled notifications from database
- Uses NotifyReceiver.cancelNotification() for each scheduled alarm
- Includes fallback cleanup for orphaned alarms
- Cancels WorkManager jobs with tags: prefetch, daily_notification_fetch,
daily_notification_maintenance, soft_refetch, daily_notification_display,
daily_notification_dismiss
- Disables all notification and fetch schedules in database
- Add required imports:
- android.app.PendingIntent for alarm cancellation
- androidx.work.WorkManager for job cancellation
- Error handling:
- Gracefully handles missing alarms/jobs (logs warnings, doesn't fail)
- Continues cleanup even if individual operations fail
- Comprehensive logging for debugging
Fixes:
- 'not implemented' error when host app calls cancelAllNotifications()
- Enables users to update notification time without errors
- Allows users to disable notifications completely
- Prevents orphaned alarms and jobs after cancellation
The method matches TypeScript interface and is ready for use.
- Fix MainActivity ClassNotFoundException by using dynamic package launcher intent
- Replace hardcoded MainActivity class references with getLaunchIntent() helper
- Uses packageManager.getLaunchIntentForPackage() to work with any host app
- Removes dependency on specific MainActivity package/class name
- Fixes 3 occurrences in NotifyReceiver.kt (alarm clock, notification click, reminder click)
- Add exact alarm permission check before scheduling (Android 12+)
- Add canScheduleExactAlarms() helper to check SCHEDULE_EXACT_ALARM permission
- Check permission before scheduling exact alarms in scheduleExactNotification()
- Gracefully fall back to inexact alarms when permission not granted
- Prevents SecurityException and provides clear logging
- Bump version to 1.0.2
Fixes:
- ClassNotFoundException when plugin tries to resolve hardcoded MainActivity path
- SecurityException on Android 12+ when exact alarm permission not granted
- Plugin now works with any host app regardless of MainActivity package/class
All changes maintain backward compatibility and improve reliability.
The Vue test app was missing the NotifyReceiver registration in
AndroidManifest.xml, preventing alarm broadcasts from being delivered
to the BroadcastReceiver. This caused notifications scheduled via
setAlarmClock() to fire but not display.
Added NotifyReceiver registration matching the working android-test-app
configuration. Also includes supporting improvements:
- Enhanced alarm scheduling with setAlarmClock() for Doze exemption
- Unique request codes based on trigger time to prevent PendingIntent conflicts
- Diagnostic methods (isAlarmScheduled, getNextAlarmTime, testAlarm)
- TypeScript definitions for new methods
Verified: Notification successfully fired at 09:41:00 and was displayed.
- Add handleOnResume() fallback to resolve permission requests when
Capacitor Bridge doesn't route results (requestCode 1001)
- Implement checkPermissions() with override modifier for Capacitor
standard PermissionStatus format
- Implement getExactAlarmStatus() to return exact alarm capability info
- Implement updateStarredPlans() to store plan IDs in SharedPreferences
- Fix requestPermissions() override to properly delegate to
requestNotificationPermissions()
- Fix handleRequestPermissionsResult() return type to Unit
These changes ensure permission requests resolve correctly even when
Capacitor's Bridge doesn't recognize our custom request code, and
implement all missing methods called by the test application.
- Fix cron parsing to correctly calculate next run time based on hour/minute
- Always schedule prefetch 5 minutes before notification (even without URL)
- Make notifications dismissable with setAutoCancel(true)
- Add click action to launch app when notification is tapped
- Conditionally require network only when URL is provided for prefetch
- Generate mock content when no URL is specified
These changes ensure notifications fire at the correct time, are
user-friendly (dismissable and clickable), and prefetch works reliably
even without a content URL.
Restructure Android project from nested module layout to standard
Capacitor plugin structure following community conventions.
Structure Changes:
- Move plugin code from android/plugin/ to android/src/main/java/
- Move test app from android/app/ to test-apps/android-test-app/app/
- Remove nested android/plugin module structure
- Remove nested android/app test app structure
Build Infrastructure:
- Add Gradle wrapper files (gradlew, gradlew.bat, gradle/wrapper/)
- Transform android/build.gradle from root project to library module
- Update android/settings.gradle for standalone plugin builds
- Add android/gradle.properties with AndroidX configuration
- Add android/consumer-rules.pro for ProGuard rules
Configuration Updates:
- Add prepare script to package.json for automatic builds on npm install
- Update package.json version to 1.0.1
- Update android/build.gradle to properly resolve Capacitor dependencies
- Update test-apps/android-test-app/settings.gradle with correct paths
- Remove android/variables.gradle (hardcode values in build.gradle)
Documentation:
- Update BUILDING.md with new structure and build process
- Update INTEGRATION_GUIDE.md to reflect standard structure
- Update README.md to remove path fix warnings
- Add test-apps/BUILD_PROCESS.md documenting test app build flows
Test App Configuration:
- Fix android-test-app to correctly reference plugin and Capacitor
- Remove capacitor-cordova-android-plugins dependency (not needed)
- Update capacitor.settings.gradle path verification in fix script
BREAKING CHANGE: Plugin now uses standard Capacitor Android structure.
Consuming apps must update their capacitor.settings.gradle to reference
android/ instead of android/plugin/. This is automatically handled by
Capacitor CLI for apps using standard plugin installation.
The /api/v2/report/plansLastUpdatedBetween endpoint requires the afterId
parameter. When no previous jwtId is stored, default to "0" for the first
request. This ensures afterId is always present and never null/omitted.
Fix resolves "afterId parameter is required" API errors. Verified working:
prefetch execution shows request body includes afterId: "0" and API returns
HTTP 200 successfully.
Remove the aud (audience) claim from JWT payloads. The server's did-jwt
verification requires an audience option when aud is present, but the server
isn't configured to validate it, causing "JWT audience is required but your
app address has not been configured" errors.
Changes:
- Removed aud claim from JWT payload in generateEndorserJWT()
- Updated key derivation to User Zero's specific path (m/84737769'/0'/0'/0')
- Added public key verification against expected User Zero key
- Enhanced JWT diagnostics logging throughout
- Added alarm deduplication optimization (prevent duplicate alarms for same time)
Verified: JWT validation now passes (token length 360→333 chars, no audience
error). New error is API parameter validation (afterId required - separate issue).
Move native fetcher configuration from App.vue mounted() to HomeView.vue
onMounted() because App.vue's mounted hook was not executing reliably,
likely due to Vue router lifecycle timing.
Changes:
- App.vue: Remove non-executing configuration code, add note explaining move
- HomeView.vue: Add configureNativeFetcher() function with full configuration
flow including ES256K JWT generation, API URL setup, and starred plans update
- Add nativeFetcherConfigured ref to prevent duplicate configuration attempts
- Wrap starred plans update in try-catch (non-blocking if it fails)
This fixes the issue where TestNativeFetcher was not being configured,
causing all prefetch operations to fail with "Not configured" error and
fall back to emergency content.
Verified: Configuration now executes successfully on HomeView mount,
TestNativeFetcher shows "Configured with API" in logcat.
Add detailed logging when cancelling existing alarms to aid in
debugging notification scheduling issues. Logs now indicate whether
an existing alarm was found and cancelled, or if no alarm existed.
This improves observability when investigating duplicate notifications
or scheduling conflicts.
Implement unique work names to prevent duplicate WorkManager tasks
from being enqueued when multiple notifications are scheduled for
the same time or when the receiver is triggered multiple times.
Changes:
- DailyNotificationReceiver: Use enqueueUniqueWork with unique names
("display_{id}", "dismiss_{id}") and ExistingWorkPolicy.KEEP/REPLACE
- DailyNotificationFetcher: Use unique work names based on scheduled
time rounded to minutes ("fetch_{minutes}") with ExistingWorkPolicy.REPLACE
This resolves the issue where ~25+ concurrent workers were being
enqueued for the same notification, leading to race conditions and
resource waste. Now only one worker processes each notification/fetch
at a time.
Verified in logcat: Worker count reduced from 25+ to 1 per notification.
- Update JWT section to reflect current status:
- JWT Generation: ✅ COMPLETE (TypeScript generates ES256K correctly)
- JWT Verification: 🟡 PARTIAL (generation works, server verification fails)
- Document verification issue:
- Error: 'no matching public key found'
- Root cause: Server cannot resolve DID to get public key
- JWT signature is cryptographically valid
- Issue is DID resolution, not JWT generation
- Add verification status table:
- Component-level status breakdown
- Clear distinction between generation (✅) and verification (❌)
- Add next steps checklist:
- Verify DID registration on resolver
- Test with known DID
- Check server resolver config
- Verify test API server supports DID-based JWT verification
- Update implementation status:
- Mark TypeScript JWT generation as complete
- Mark DID resolution as pending verification
- Remove outdated HMAC-SHA256 references
- Fix TestNativeFetcher to read from same SharedPreferences as plugin
- Changed PREFS_NAME from 'DailyNotificationPrefs' to 'daily_notification_timesafari'
- Changed KEY_STARRED_PLAN_IDS from 'starred_plan_ids' to 'starredPlanIds'
- Updated getStarredPlanIds() to read from plugin's SharedPreferences location
- Added diagnostic logging for plan ID loading
- Add updateStarredPlans() call in App.vue mounted() hook
- Ensures starred plan IDs are persisted to native storage on app startup
- Allows native fetcher to read plan IDs from SharedPreferences
- Added diagnostic logging for configuration flow
- Document cross-platform storage pattern
- Created docs/CROSS_PLATFORM_STORAGE_PATTERN.md with architecture flow
- Documented TypeScript → Capacitor bridge → Plugin → Native storage → Native fetcher flow
- Added iOS implementation checklist with code examples
- Clarified why native storage is needed (background workers can't use bridge)
- Add JWT generation logging to test-user-zero.ts
- Log JWT algorithm (ES256K) and DID when token is generated
- Helps diagnose JWT verification issues
Fixes:
- Empty planIds array in native fetcher requests
- SharedPreferences key mismatch between plugin and native fetcher
- Missing documentation for iOS implementation
All changes maintain backward compatibility.
- Move native fetcher configuration from HomeView.vue to App.vue mounted() hook
- Single source of truth for configuration on app startup
- Removed duplicate configuration logic from HomeView
- Added diagnostic logging to trace configuration flow
- Fix ES module compatibility issue with Capacitor CLI
- Replace direct logger import with lazy async loading in test-user-zero.ts
- Prevents 'exports is not defined' error when Capacitor CLI loads config
- Update refreshToken() and setBaseUrl() methods to async for logger access
- Add centralized logger utility (src/lib/logger.ts)
- Single ESLint whitelist location for console usage
- Structured logging with levels and emoji support
- Updated router/index.ts and stores/app.ts to use logger
- Enhance Android notification deduplication
- Add within-batch duplicate detection in fetch workers
- Improve storage deduplication with alarm cancellation
- Cancel alarms for removed duplicate notifications
- Update UserZeroView.vue to await async refreshToken() call
Fixes:
- npx cap sync android ES module error
- Duplicate notification accumulation
- Console statement lint warnings
All changes maintain backward compatibility and improve debugging visibility.
Fix critical bug where NotificationContent deserializer was corrupting
notification data every time storage was loaded:
1. Deserializer was creating new NotificationContent() which:
- Generated new random UUIDs (losing original IDs)
- Set fetchedAt to current time (losing original timestamps)
- Caused excessive debug logging (40+ log lines per load)
2. This caused:
- Notifications to appear as 'new' on every app restart
- Duplicate notification detection to fail (different IDs)
- Log spam making debugging difficult
- 40+ notifications accumulating over time
Changes:
- Add package-private constructor NotificationContent(id, fetchedAt) to
preserve original data during deserialization
- Update NotificationContentDeserializer to read fetchedAt from JSON
and use new constructor to preserve original values
- Remove excessive constructor logging that caused log spam
- Preserve notification IDs during deserialization
This ensures notifications maintain their original identity and timestamps
when loaded from persistent storage, preventing data corruption and
duplicate accumulation.
Fixes issue where prefetch correctly skipped but 40+ notifications
accumulated due to deserializer corruption.
Add eslint-disable-next-line comments for intentional console.log statements
in test configuration and router files. These console statements are
intentional for debugging and testing purposes.
Files updated:
- test-user-zero.ts: 5 console statements suppressed
- router/index.ts: 2 console statements suppressed
All lint warnings resolved.
Add configureNativeFetcher() plugin method to enable TypeScript configuration
of native fetchers with API credentials. This provides a cross-platform
mechanism for passing configuration from JavaScript to native code without
relying on platform-specific storage.
- Add configure() method to NativeNotificationContentFetcher interface
(optional, defaults to no-op for fetchers that don't need config)
- Add configureNativeFetcher plugin method in DailyNotificationPlugin
- Add TypeScript definitions and comprehensive JSDoc
- Create NATIVE_FETCHER_CONFIGURATION.md documentation
- Update TestNativeFetcher to use real API endpoint (10.0.2.2:3000)
- Update DemoNativeFetcher Javadoc explaining configure() is optional
- Add configureNativeFetcher() call to demo app's configurePlugin()
Enables host apps to configure native fetchers from TypeScript, keeping
the interface consistent across Android, iOS, and web platforms.
Add duplicate checking in handleSuccessfulFetch() to ensure one prefetch
creates at most one notification per scheduled time. This prevents prefetch
from creating duplicate notifications when a manual notification already
exists for the same time.
- Check existing notifications before saving prefetch-created content
- Skip notification creation if duplicate found (within 1 minute tolerance)
- Add null check for fetcher in scheduleBackgroundFetch() with error logging
- Log skipped duplicates for debugging
Ensures one prefetch → one notification pairing and prevents duplicate
notifications from firing at the same time.
Update www/index.html scheduleNotification() function to calculate and display
both prefetch time (5 minutes before) and notification time in the success message,
matching the behavior added to the development app assets version.
This provides users with clear visibility into when the PBS prefetch will run
and when the notification will actually fire.
Add INTEGRATION_REFACTOR_CONTEXT.md that maps current codebase to the
Integration Point Refactor plan, including:
- Current state analysis and what needs to be created/modified
- Dependency mapping and implementation checklists
- Testing strategy and open questions
Also update AndroidManifest.xml files to register Application classes.
Clean up eslint-disable comments in test app TypeScript files:
- Remove unnecessary comments from test-user-zero.ts
- Remove unnecessary comments from router/index.ts
- Keep only intentional console.log statements with proper eslint-disable comments
Add host app implementation of NativeNotificationContentFetcher for development app:
- Create PluginApplication extends Application to register fetcher on app startup
- Create DemoNativeFetcher implementing NativeNotificationContentFetcher interface
- Register PluginApplication in AndroidManifest.xml
- DemoNativeFetcher returns mock notification content for testing
This demonstrates the SPI pattern where host apps provide their own
content fetching implementation to the plugin for background workers.
When a notification is displayed and rescheduled for the next occurrence,
now also schedule a background fetch to prefetch content 5 minutes before
the next notification time.
- Add DailyNotificationFetcher import to DailyNotificationWorker
- In scheduleNextNotification(), after successfully scheduling notification,
calculate fetch time (5 minutes before next scheduled time)
- Create DailyNotificationFetcher instance and schedule prefetch
- Add logging with DN|RESCHEDULE_PREFETCH_SCHEDULED tag for observability
- Fall back to immediate fetch if fetch time is in the past
This ensures the prefetch → cache → schedule → display pipeline continues
for subsequent notifications, not just the initial scheduling.
PR2: Background Workers implementation
- Update DailyNotificationFetchWorker to use NativeNotificationContentFetcher SPI
- Remove TimeSafari coordination checks from worker (moved to host app)
- Add fetchContentWithTimeout() method that calls native fetcher via SPI
- Add fallback to legacy fetcher if no native fetcher is registered
- Update handleSuccessfulFetch() to process List<NotificationContent>
- Simplify retry logic to use SchedulingPolicy for exponential backoff
- Remove all TimeSafari-specific coordination methods from worker
- Add static getter in DailyNotificationPlugin for worker access to native fetcher
This completes the worker-side implementation of the dual-path SPI,
allowing background workers to reliably fetch content using native code.
- Add NativeNotificationContentFetcher interface for host app implementations
- Add FetchContext class to pass fetch parameters (trigger, scheduledTime, fetchTime)
- Add SchedulingPolicy class for retry backoff configuration
- Add TypeScript definitions for content fetcher SPI in src/definitions.ts
- Export SPI types from src/index.ts
This enables host apps to provide their own content fetching implementation
for background workers, following the Integration Point Refactor (PR2).
Add comprehensive documentation and implementation artifacts for refactoring
the plugin to use app-provided content fetchers instead of hardcoded TimeSafari
integration.
Changes:
- Add integration-point-refactor-analysis.md with complete ADR, interfaces,
migration plan, and 7-PR breakdown
- Add INTEGRATION_REFACTOR_QUICK_START.md for quick reference on new machines
- Add src/types/content-fetcher.ts with TypeScript SPI interfaces
- Add examples/native-fetcher-android.kt with Kotlin implementation skeleton
- Add examples/js-fetcher-typescript.ts with TypeScript implementation skeleton
- Add tests/fixtures/test-contract.json for golden contract testing
Architecture Decisions:
- Dual-path SPI: Native Fetcher (background) + JS Fetcher (foreground only)
- Background reliability: Native SPI only, no JS bridging in workers
- Reversibility: Legacy code behind feature flag for one minor release
- Test contract: Single JSON fixture for both fetcher paths
This provides complete specification for implementing the refactor in 7 PRs,
starting with SPI shell and progressing through background workers, deduplication,
failure policies, and finally legacy code removal.
All documentation is self-contained and ready for implementation on any machine.
Add comprehensive implementation guide for creating PlanAction claims
via hydratePlan() function pattern, following established hydrateGive()
and hydrateOffer() patterns.
Changes:
- Add hydrate-plan-implementation-guide.md with complete implementation
details, usage examples, and testing recommendations
- Link implementation guide from getting-valid-plan-ids.md Method 6
- Link implementation guide from localhost-testing-guide.md Option B
The guide provides:
- Complete hydratePlan() function implementation
- PlanActionClaim interface structure
- Helper functions (createAndSubmitPlan, editAndSubmitPlan)
- Usage examples and edge cases
- Testing recommendations and security considerations
This complements plan creation documentation by showing how to
programmatically construct valid PlanAction JWTs for POST /api/v2/claim.
Plans are created by importing JWT claims with @type: PlanAction via
POST /api/v2/claim, not through a dedicated plan creation endpoint.
Changes:
- Document POST /api/v2/claim route in localhost-testing-guide.md
- Add Method 6 (PlanAction JWT import) to getting-valid-plan-ids.md
- Update seed-test-projects.js with warnings about PlanAction JWT requirements
- Clarify that seed script cannot create plans (requires DID signing)
This reflects the actual TimeSafari API architecture where plans are
created as a side effect of importing PlanAction claims.
- Update plan handle ID format to match TimeSafari specification
- Default format: https://endorser.ch/entity/{26-char-ULID}
- ULID: 26 characters, Crockford base32 encoded
- Validates RFC 3986 URI format
- Add ULID generation functions
- generateULID() creates 26-character Crockford base32 strings
- generateValidPlanHandleId() creates full URI format IDs
- Auto-generates valid IDs for testing
- Update DEFAULT_TEST_PROJECT_IDS
- Now generates valid URI format IDs automatically
- Removes placeholder warnings (IDs are now valid format)
- Add URI validation to seed scripts
- Validates plan IDs match RFC 3986 URI format
- Error messages with format examples
- Blocks seeding with invalid formats
- Update test-user-zero.ts config
- Auto-generates valid URI format plan IDs
- Clear documentation of required format
- Note that real IDs from database should replace test IDs
- Update documentation
- Document default URI format specification
- Explain ULID structure and encoding
- Show examples of valid formats
This ensures all test project IDs match the actual TimeSafari plan
handle ID format, preventing validation errors during prefetch testing.
- Replace placeholder plan IDs with explicit warnings
- Change from test_project_X to PLACEHOLDER_ID_X
- Add validation to prevent seeding with placeholders
- Add helpful error messages with usage examples
- Add comprehensive guide for getting valid plan IDs
- Methods: Create projects, query database, check account settings
- Format examples: UUID, hash, custom formats
- Step-by-step instructions for each method
- Troubleshooting common issues
- Update test-user-zero.ts with placeholder warnings
- Clear instructions on how to get real plan IDs
- Links to documentation
- Notes about plan ID format variations
- Improve test server startup
- Warn when using placeholder IDs
- Allow plan IDs via command line argument
- Provide guidance on updating config
The previous test_project_X IDs were not valid for real TimeSafari
databases. Users must now provide actual plan handle IDs from their
TimeSafari setup, making testing more realistic and avoiding silent
failures with invalid IDs.
