guideai-app 0.4.1 → 0.4.2-1

package/API_DATA_CONTRACTS.md

@@ -0,0 +1,516 @@
+# API Data Contracts
+
+## `/initialize-session` Endpoint
+
+### BEFORE Updates (Current/Legacy)
+
+#### Request
+```typescript
+POST /initialize-session
+
+Headers:
+  Content-Type: application/json
+
+Body:
+{
+  organizationKey: string;      // Required
+  userId: "anonymous";          // Always "anonymous" (hardcoded)
+  date: string;                 // ISO date (YYYY-MM-DD)
+  time: string;                 // Time (HH:MM:SS)
+  messages: any[];              // Array (usually empty)
+  workflowKey?: string;         // Optional
+}
+```
+
+**Example:**
+```json
+{
+  "organizationKey": "demo-org-demo",
+  "userId": "anonymous",
+  "date": "2025-10-14",
+  "time": "14:30:00",
+  "messages": []
+}
+```
+
+#### Response
+```typescript
+{
+  id: string;                   // Conversation ID
+  ephemeralToken: string;       // Temporary auth token
+  prompt: string;               // AI prompt/instructions
+  workflows: Workflow[];        // Array of workflow objects
+}
+
+interface Workflow {
+  id: string;
+  name: string;
+  triggers: string[];
+  organizationKey: string;
+  prompt: string;
+  archived: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+**Example:**
+```json
+{
+  "id": "conv-123-456",
+  "ephemeralToken": "eyJhbGc...",
+  "prompt": "You are a helpful AI assistant...",
+  "workflows": [
+    {
+      "id": "workflow-1",
+      "name": "Customer Support",
+      "triggers": ["help", "support"],
+      "organizationKey": "demo-org-demo",
+      "prompt": "Help the user with...",
+      "archived": false,
+      "createdAt": "2025-01-01T00:00:00Z",
+      "updatedAt": "2025-01-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### AFTER Updates (New Implementation)
+
+#### Request
+```typescript
+POST /initialize-session
+
+Headers:
+  Content-Type: application/json
+
+Body:
+{
+  organizationKey: string;      // Required
+  userId: string;               // NEW: Email if available, or "anonymous"
+  email?: string;               // NEW: Explicit email field (undefined if not available)
+  date: string;                 // ISO date (YYYY-MM-DD)
+  time: string;                 // Time (HH:MM:SS)
+  messages: any[];              // Array (usually empty)
+  workflowKey?: string;         // Optional
+}
+```
+
+**Example 1: Authenticated User**
+```json
+{
+  "organizationKey": "demo-org-demo",
+  "userId": "csdemo@demo-org.com",
+  "email": "csdemo@demo-org.com",
+  "date": "2025-10-14",
+  "time": "14:30:00",
+  "messages": []
+}
+```
+
+**Example 2: Anonymous User**
+```json
+{
+  "organizationKey": "demo-org-demo",
+  "userId": "anonymous",
+  "email": undefined,  // Or omitted
+  "date": "2025-10-14",
+  "time": "14:30:00",
+  "messages": []
+}
+```
+
+#### Response
+```typescript
+{
+  id: string;                   // Conversation ID
+  ephemeralToken: string;       // Temporary auth token
+  prompt: string;               // AI prompt/instructions
+  workflows: Workflow[];        // Array of workflow objects
+  userMetadata?: {              // NEW: User metadata (optional)
+    visitCount: number;         // Number of visits for this user
+    loginCount?: number;        // Number of logins (optional)
+    email?: string;             // User email (if available)
+  };
+}
+```
+
+**Example 1: Authenticated User Response**
+```json
+{
+  "id": "conv-123-456",
+  "ephemeralToken": "eyJhbGc...",
+  "prompt": "You are a helpful AI assistant...",
+  "workflows": [...],
+  "userMetadata": {
+    "visitCount": 5,
+    "loginCount": 2,
+    "email": "csdemo@demo-org.com"
+  }
+}
+```
+
+**Example 2: Anonymous User Response**
+```json
+{
+  "id": "conv-123-456",
+  "ephemeralToken": "eyJhbGc...",
+  "prompt": "You are a helpful AI assistant...",
+  "workflows": [...],
+  "userMetadata": {
+    "visitCount": 0
+  }
+}
+```
+
+---
+
+## `/metadata-updates` Endpoint
+
+### Request (Already Implemented)
+
+```typescript
+POST /metadata-updates
+
+Headers:
+  Content-Type: application/json
+
+Body:
+{
+  organizationKey: string;      // Required
+  updates: MetadataUpdate[];    // Array of metadata updates
+  batchTimestamp: number;       // Timestamp when batch was created
+  updateCount: number;          // Number of updates in batch
+}
+
+interface MetadataUpdate {
+  type: 'visit' | 'login' | 'user_info' | 'session' | 'custom';
+  timestamp: number;            // Unix timestamp (milliseconds)
+  data: {
+    sessionId: string;          // Current session ID
+    email?: string;             // User email (if available) ← KEY FOR STORAGE
+    visitCount?: number;        // Current visit count
+    loginCount?: number;        // Current login count
+    firstVisit?: number;        // First visit timestamp
+    lastVisit?: number;         // Last visit timestamp
+    [key: string]: any;         // Other custom fields
+  };
+}
+```
+
+### Example Request
+
+```json
+{
+  "organizationKey": "demo-org-demo",
+  "updates": [
+    {
+      "type": "visit",
+      "timestamp": 1697295600000,
+      "data": {
+        "sessionId": "550e8400-e29b-41d4-a716-446655440000",
+        "email": "csdemo@demo-org.com",
+        "firstVisit": 1697000000000,
+        "lastVisit": 1697295600000,
+        "visitCount": 5
+      }
+    },
+    {
+      "type": "login",
+      "timestamp": 1697295650000,
+      "data": {
+        "sessionId": "550e8400-e29b-41d4-a716-446655440000",
+        "email": "csdemo@demo-org.com",
+        "loginCount": 2,
+        "lastLogin": 1697295650000
+      }
+    }
+  ],
+  "batchTimestamp": 1697295600000,
+  "updateCount": 2
+}
+```
+
+### Response
+
+```typescript
+{
+  success: boolean;             // Whether the update was successful
+  message?: string;             // Optional message
+}
+```
+
+**Example:**
+```json
+{
+  "success": true
+}
+```
+
+---
+
+## Backend Implementation Notes
+
+### Key Changes Required
+
+1. **Accept email in `/initialize-session`**
+   - Read `email` from request body
+   - Use as user identifier (along with organizationKey)
+
+2. **Return userMetadata in `/initialize-session` response**
+   - Look up user by `organizationKey + email`
+   - Return their visitCount from database
+   - If not found or anonymous, return `visitCount: 0`
+
+3. **Store visitCount from `/metadata-updates`**
+   - Extract `email` from each update's data
+   - Store visitCount in database by `organizationKey + email`
+   - Update on each request (upsert operation)
+
+### Database Schema Suggestion
+
+```sql
+-- User metadata table
+CREATE TABLE user_metadata (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_key VARCHAR(255) NOT NULL,
+  email VARCHAR(255) NOT NULL,
+  visit_count INTEGER DEFAULT 0,
+  login_count INTEGER DEFAULT 0,
+  first_visit BIGINT,  -- Unix timestamp (ms)
+  last_visit BIGINT,   -- Unix timestamp (ms)
+  last_login BIGINT,   -- Unix timestamp (ms)
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(organization_key, email)
+);
+
+-- Index for fast lookups
+CREATE INDEX idx_user_metadata_lookup ON user_metadata(organization_key, email);
+```
+
+### Backend Logic Pseudocode
+
+#### For `/initialize-session`:
+
+```python
+def initialize_session(request):
+    org_key = request.organizationKey
+    email = request.email
+    
+    # Look up user metadata
+    if email and email != 'anonymous':
+        user = db.query(
+            "SELECT * FROM user_metadata WHERE organization_key = ? AND email = ?",
+            org_key, email
+        )
+        visit_count = user.visit_count if user else 0
+        login_count = user.login_count if user else 0
+    else:
+        # Anonymous user
+        visit_count = 0
+        login_count = 0
+    
+    # Return response with userMetadata
+    return {
+        "id": generate_conversation_id(),
+        "ephemeralToken": generate_token(),
+        "prompt": get_prompt(),
+        "workflows": get_workflows(org_key),
+        "userMetadata": {
+            "visitCount": visit_count,
+            "loginCount": login_count,
+            "email": email if email != 'anonymous' else None
+        }
+    }
+```
+
+#### For `/metadata-updates`:
+
+```python
+def metadata_updates(request):
+    org_key = request.organizationKey
+    updates = request.updates
+    
+    for update in updates:
+        email = update.data.get('email')
+        
+        if email and email != 'anonymous':
+            # Update or create user metadata
+            if update.type == 'visit':
+                db.upsert(
+                    "user_metadata",
+                    organization_key=org_key,
+                    email=email,
+                    visit_count=update.data.get('visitCount'),
+                    first_visit=update.data.get('firstVisit'),
+                    last_visit=update.data.get('lastVisit')
+                )
+            
+            elif update.type == 'login':
+                db.upsert(
+                    "user_metadata",
+                    organization_key=org_key,
+                    email=email,
+                    login_count=update.data.get('loginCount'),
+                    last_login=update.data.get('lastLogin')
+                )
+    
+    return {"success": True}
+```
+
+---
+
+## Testing the Changes
+
+### Test 1: Authenticated User Flow
+
+```bash
+# Step 1: Initialize session with email
+curl -X POST https://your-api.com/initialize-session \
+  -H "Content-Type: application/json" \
+  -d '{
+    "organizationKey": "test-org",
+    "userId": "test@example.com",
+    "email": "test@example.com",
+    "date": "2025-10-14",
+    "time": "12:00:00",
+    "messages": []
+  }'
+
+# Expected response:
+# {
+#   "id": "conv-123",
+#   "ephemeralToken": "...",
+#   "prompt": "...",
+#   "workflows": [],
+#   "userMetadata": {
+#     "visitCount": 0,  // First time
+#     "email": "test@example.com"
+#   }
+# }
+
+# Step 2: Send metadata update (simulate visit)
+curl -X POST https://your-api.com/metadata-updates \
+  -H "Content-Type: application/json" \
+  -d '{
+    "organizationKey": "test-org",
+    "updates": [
+      {
+        "type": "visit",
+        "timestamp": 1697295600000,
+        "data": {
+          "sessionId": "session-123",
+          "email": "test@example.com",
+          "visitCount": 1,
+          "firstVisit": 1697295600000,
+          "lastVisit": 1697295600000
+        }
+      }
+    ],
+    "batchTimestamp": 1697295600000,
+    "updateCount": 1
+  }'
+
+# Expected response:
+# { "success": true }
+
+# Step 3: Initialize session again (should return visitCount = 1)
+curl -X POST https://your-api.com/initialize-session \
+  -H "Content-Type: application/json" \
+  -d '{
+    "organizationKey": "test-org",
+    "userId": "test@example.com",
+    "email": "test@example.com",
+    "date": "2025-10-14",
+    "time": "13:00:00",
+    "messages": []
+  }'
+
+# Expected response:
+# {
+#   "userMetadata": {
+#     "visitCount": 1  // ← Should return stored value
+#   }
+# }
+```
+
+### Test 2: Anonymous User Flow
+
+```bash
+# Initialize session without email
+curl -X POST https://your-api.com/initialize-session \
+  -H "Content-Type: application/json" \
+  -d '{
+    "organizationKey": "test-org",
+    "userId": "anonymous",
+    "date": "2025-10-14",
+    "time": "12:00:00",
+    "messages": []
+  }'
+
+# Expected response:
+# {
+#   "userMetadata": {
+#     "visitCount": 0  // Always 0 for anonymous
+#   }
+# }
+```
+
+---
+
+## Backward Compatibility
+
+### Will Old Clients Break?
+
+**NO** - The implementation is backward compatible:
+
+1. **Old FE + New BE**: Works fine
+   - Old FE sends `userId: "anonymous"`
+   - New BE returns `userMetadata` (optional field)
+   - Old FE ignores the new field
+
+2. **New FE + Old BE**: Works fine
+   - New FE sends `email` field
+   - Old BE ignores unknown fields
+   - New FE handles missing `userMetadata` gracefully
+
+3. **New FE + New BE**: Full functionality
+   - Email-based user identification
+   - Cross-browser visitCount tracking
+   - Everything works as designed
+
+---
+
+## Summary
+
+### Changed Fields in `/initialize-session`
+
+| Field | Before | After | Required |
+|-------|--------|-------|----------|
+| `userId` | Always "anonymous" | Email or "anonymous" | Yes |
+| `email` | N/A | Email string | No (undefined if not available) |
+| `userMetadata` (response) | N/A | Object with visitCount | No (optional) |
+
+### Key for Backend Team
+
+✅ **Must implement:**
+1. Read `email` from request
+2. Return `userMetadata.visitCount` in response
+3. Store visitCount from `/metadata-updates` by `organizationKey + email`
+
+✅ **Nice to have:**
+4. Store by sessionId for anonymous users (temporary tracking)
+5. Return loginCount in userMetadata
+6. Add database indexes for performance
+
+---
+
+## Questions?
+
+Contact the development team or refer to:
+- `src/utils/USER_IDENTIFICATION_NOTES.md` - Full documentation
+- `IMPLEMENTATION_SUMMARY.md` - Implementation details
+