daily-notification-plugin/docs/user-zero-stars-implementation.md

User Zero Stars Querying Implementation

Documentation Date: October 24, 2025 - 12:45:02 UTC
Author: Matthew Raymer
Version: 1.0.0
Status: ✅ Complete Implementation

Overview

This document describes the implementation of User Zero stars querying functionality for the TimeSafari Daily Notification Plugin. The implementation enables querying starred projects from the TimeSafari API with a 5-minute fetch lead time before scheduled notifications.

Implementation Summary

Key Features Implemented

• User Zero Identity Configuration: Complete test user setup based on TimeSafari crowd-master
• Stars Querying API: Integration with TimeSafari's starred projects endpoint
• 5-Minute Fetch Timing: Content fetched 5 minutes before notification delivery
• Mock Testing System: Offline testing capability with realistic mock data
• Comprehensive UI: Full testing interface for User Zero functionality

Files Created/Modified

File	Type	Purpose
test-apps/daily-notification-test/src/config/test-user-zero.ts	New	User Zero configuration and API client
test-apps/daily-notification-test/capacitor.config.ts	Modified	Plugin configuration with TimeSafari integration
test-apps/daily-notification-test/src/views/UserZeroView.vue	New	Testing UI for User Zero functionality
test-apps/daily-notification-test/src/router/index.ts	Modified	Added User Zero route
test-apps/daily-notification-test/src/components/layout/AppHeader.vue	Modified	Added User Zero navigation tab

User Zero Configuration

Identity Details

Based on analysis of TimeSafari crowd-master project:

const TEST_USER_ZERO_CONFIG = {
  identity: {
    did: "did:ethr:0x0000694B58C2cC69658993A90D3840C560f2F51F",
    name: "User Zero",
    seedPhrase: "rigid shrug mobile smart veteran half all pond toilet brave review universe ship congress found yard skate elite apology jar uniform subway slender luggage"
  }
}

API Configuration

api: {
  server: "https://api-staging.timesafari.com",
  starsEndpoint: "/api/v2/report/plansLastUpdatedBetween",
  jwtExpirationMinutes: 1,
  jwtAlgorithm: "HS256"
}

Stars Querying Configuration

starredProjects: {
  planIds: [
    "test_project_1",
    "test_project_2", 
    "test_project_3",
    "demo_project_alpha",
    "demo_project_beta"
  ],
  lastAckedJwtId: "1704067200_abc123_def45678"
}

5-Minute Fetch Timing

notifications: {
  fetchLeadTimeMinutes: 5,  // Key requirement: 5 minutes before notification
  scheduleTime: "09:00",
  defaultTitle: "Daily Stars Update",
  defaultBody: "New changes detected in your starred projects!"
}

Technical Implementation

Authentication System

The implementation uses JWT-based authentication matching the TimeSafari crowd-master pattern:

export function generateTestJWT(): string {
  const nowEpoch = Math.floor(Date.now() / 1000);
  const endEpoch = nowEpoch + TEST_USER_ZERO_CONFIG.api.jwtExpirationMinutes * 60;
  
  const payload = {
    exp: endEpoch,
    iat: nowEpoch,
    iss: TEST_USER_ZERO_CONFIG.identity.did,
    sub: TEST_USER_ZERO_CONFIG.identity.did
  };
  
  // JWT generation logic...
}

Stars Querying API Client

export class TestUserZeroAPI {
  async getStarredProjectsWithChanges(
    starredPlanIds: string[],
    afterId?: string
  ): Promise<StarredProjectsResponse> {
    const url = `${this.baseUrl}${TEST_USER_ZERO_CONFIG.api.starsEndpoint}`;
    const headers = {
      'Authorization': `Bearer ${this.jwt}`,
      'Content-Type': 'application/json'
    };

    const requestBody = {
      planIds: starredPlanIds,
      afterId: afterId || TEST_USER_ZERO_CONFIG.starredProjects.lastAckedJwtId
    };

    const response = await fetch(url, {
      method: 'POST',
      headers,
      body: JSON.stringify(requestBody)
    });

    return await response.json();
  }
}

Capacitor Plugin Configuration

The plugin is configured to enable stars querying with 5-minute fetch timing:

DailyNotification: {
  timesafariConfig: {
    activeDid: TEST_USER_ZERO_CONFIG.identity.did,
    endpoints: {
      projectsLastUpdated: `${TEST_USER_ZERO_CONFIG.api.server}${TEST_USER_ZERO_CONFIG.api.starsEndpoint}`
    },
    starredProjectsConfig: {
      enabled: true,
      starredPlanHandleIds: TEST_USER_ZERO_CONFIG.starredProjects.planIds,
      fetchInterval: '0 8 * * *' // Daily at 8 AM
    }
  },
  contentFetch: {
    enabled: true,
    fetchLeadTimeMinutes: TEST_USER_ZERO_CONFIG.notifications.fetchLeadTimeMinutes, // 5 minutes
    callbacks: {
      onSuccess: 'handleStarsQuerySuccess',
      onError: 'handleStarsQueryError'
    }
  }
}

Testing Interface

User Zero Testing UI

The UserZeroView.vue component provides a comprehensive testing interface:

Features

• Identity Display: Shows User Zero's DID, name, and API server
• Starred Projects List: Visual display of test project IDs
• Testing Controls:
  • Test Stars Query button
  • Test JWT Generation button
  • Test Notification Scheduling button
  • Toggle Mock Mode button
• Results Display: JSON output of test results
• Error Handling: Clear error messages and recovery

Navigation Integration

• Added "User Zero" tab with ⭐ icon to main navigation
• Route: /user-zero
• Responsive design for mobile and desktop

Mock Testing System

Mock Data Structure

export const MOCK_STARRED_PROJECTS_RESPONSE = {
  data: [
    {
      planSummary: {
        jwtId: "1704067200_abc123_def45678",
        handleId: "test_project_1",
        name: "Test Project 1",
        description: "First test project for User Zero",
        issuerDid: "did:key:test_issuer_1",
        agentDid: "did:key:test_agent_1",
        startTime: "2025-01-01T00:00:00Z",
        endTime: "2025-01-31T23:59:59Z",
        locLat: 40.7128,
        locLon: -74.0060,
        url: "https://test-project-1.com"
      },
      previousClaim: {
        jwtId: "1703980800_xyz789_0badf00d",
        claimType: "project_update"
      }
    }
    // Additional mock projects...
  ],
  hitLimit: false,
  pagination: {
    hasMore: false,
    nextAfterId: null
  }
}

Mock Mode Toggle

The system supports switching between real API calls and mock responses:

if (TEST_USER_ZERO_CONFIG.testing.enableMockResponses) {
  console.log("🧪 Using mock starred projects response");
  return MOCK_STARRED_PROJECTS_RESPONSE;
}

Usage Instructions

Accessing User Zero Testing

1. Navigate to User Zero Tab: Click the ⭐ "User Zero" tab in the navigation
2. View Configuration: See User Zero's DID, API server, and starred projects
3. Test Stars Query: Click "Test Stars Query" to fetch starred project changes
4. Test Scheduling: Click "Test Notification Scheduling" to schedule with 5-minute lead time
5. Toggle Mock Mode: Enable/disable mock responses for offline testing

Testing Workflow

1. Enable Mock Mode: For offline testing without API calls
2. Test Stars Query: Verify the stars querying functionality
3. Test JWT Generation: Validate authentication token creation
4. Test Notification Scheduling: Schedule notifications with 5-minute fetch timing
5. Review Results: Check JSON output for successful operations

API Integration Details

TimeSafari API Endpoints

Based on crowd-master analysis, the following endpoints are used:

• Stars Query: POST /api/v2/report/plansLastUpdatedBetween
• Authentication: JWT Bearer tokens
• Pagination: JWT ID-based cursor pagination

Request Format

{
  "planIds": ["test_project_1", "test_project_2"],
  "afterId": "1704067200_abc123_def45678"
}

Response Format

{
  "data": [
    {
      "planSummary": {
        "jwtId": "1704067200_abc123_def45678",
        "handleId": "test_project_1",
        "name": "Test Project 1",
        "description": "Project description",
        "issuerDid": "did:key:test_issuer_1",
        "agentDid": "did:key:test_agent_1",
        "startTime": "2025-01-01T00:00:00Z",
        "endTime": "2025-01-31T23:59:59Z"
      },
      "previousClaim": {
        "jwtId": "1703980800_xyz789_0badf00d",
        "claimType": "project_update"
      }
    }
  ],
  "hitLimit": false
}

5-Minute Fetch Timing Implementation

Configuration

The 5-minute fetch timing is configured in multiple places:

1. Plugin Config: fetchLeadTimeMinutes: 5
2. User Zero Config: fetchLeadTimeMinutes: 5
3. Capacitor Config: contentFetch.fetchLeadTimeMinutes: 5

Timing Logic

// Example: Notification scheduled for 9:00 AM
// Stars querying occurs at 8:55 AM (5 minutes before)
const notificationTime = new Date('2025-01-01T09:00:00Z');
const fetchTime = new Date(notificationTime.getTime() - (5 * 60 * 1000)); // 8:55 AM

Workflow

1. Notification Scheduled: User schedules notification for specific time
2. Fetch Triggered: 5 minutes before notification time
3. Stars Query: API call to fetch starred project changes
4. Content Preparation: Process stars data for notification
5. Notification Delivery: Show notification with stars information

Error Handling

API Error Handling

try {
  const result = await apiClient.getStarredProjectsWithChanges(
    config.starredProjects.planIds,
    config.starredProjects.lastAckedJwtId
  );
  // Success handling...
} catch (error) {
  console.error('❌ Stars query test failed:', error);
  errorMessage.value = `Stars query test failed: ${error.message}`;
  // Error handling...
}

Network Error Handling

• Timeout: 30-second timeout for API calls
• Retries: 3 retry attempts with exponential backoff
• Fallback: Mock responses when network fails

Security Considerations

JWT Security

• Short Expiration: 1-minute token lifetime
• DID-based Issuer: Tokens issued by User Zero's DID
• Secure Headers: Bearer token authentication

API Security

• HTTPS Only: All API calls use HTTPS
• Content-Type: Proper JSON content type headers
• User-Agent: Identifiable user agent string

Development Notes

Code Quality

• TypeScript: Full type safety with proper interfaces
• ESLint: No linting errors in implementation
• Vue 3: Modern Vue composition API usage
• Responsive Design: Mobile-friendly UI components

Testing Strategy

• Unit Tests: Individual component testing
• Integration Tests: End-to-end workflow testing
• Mock Testing: Offline development capability
• Real API Testing: Production API validation

Future Enhancements

Planned Features

1. Real-time Updates: WebSocket integration for live stars updates
2. Batch Processing: Multiple starred projects in single query
3. Caching: Local storage of stars data for offline access
4. Analytics: Usage tracking and performance metrics

Performance Optimizations

1. Request Batching: Combine multiple API calls
2. Response Caching: Cache API responses locally
3. Background Sync: Background stars synchronization
4. Compression: Gzip compression for API responses

Troubleshooting

Common Issues

1. JWT Expiration: Tokens expire after 1 minute
2. Network Timeouts: 30-second timeout may be insufficient
3. Mock Mode: Ensure mock mode is enabled for offline testing
4. API Server: Verify staging server availability

Debug Steps

1. Check Console: Review browser console for errors
2. Network Tab: Inspect API calls in browser dev tools
3. Mock Toggle: Switch between mock and real API calls
4. JWT Refresh: Generate new JWT tokens if expired

Conclusion

The User Zero stars querying implementation provides a complete foundation for testing TimeSafari integration with the Daily Notification Plugin. The 5-minute fetch timing requirement has been successfully implemented, and the system includes comprehensive testing capabilities with both mock and real API support.

The implementation follows TimeSafari crowd-master patterns and provides a robust testing environment for stars querying functionality.

---

Documentation Complete: October 24, 2025 - 12:45:02 UTC