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:

```typescript
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

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

### Stars Querying Configuration

```typescript
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

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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

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

### Response Format

```json
{
  "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

```typescript
// 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

```typescript
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