Handshake & Sync

Overview

The app syncs content with the server via a single handshake request-response cycle. The server returns a manifest indicating what needs to be added, updated, or deleted.

Endpoint

POST https://kagtryxgjwavupzlmlzv.supabase.co/functions/v1/handshake
Authorization: Bearer {user_jwt_from_supabase_session}
Content-Type: application/json

Dev mode URLs:

• Emulator: http://localhost:8080/handshake
• Device: http://{configured_ip}:8080/handshake

Sync Flow

1. Speed test — 3 tests via Cloudflare CDN (1MB each), average must be >= 1.5 Mbps. If speed test server is unreachable, sync proceeds anyway.
2. Build payload — analytics data, device ID, pending purchases. User ID is NOT in the payload — it is extracted from JWT on the server.
3. Send handshake — POST to endpoint with JWT auth
4. Receive manifest — server returns json_manifest, ai_usage, and subscription data
5. Update user profile — write ai_usage and subscription to user_profile.json
6. Analyze manifest — categorize courses into ADD, UPDATE, DELETE
7. Progressive download — download new courses with user confirmation per course
8. Batch updates — update existing courses and system JSONs
9. Safe deletion — remove courses no longer in entitlements (profile updated first)

Request Payload

{
  "analytics": {
    "current_course": "C14ENB",
    "voice": "Female",
    "background": "None",
    "induction": "Randomize",
    "deepening": "Randomize",
    "audio_usage": {
      "1": {"title": "How to Use These Sessions", "no_of_plays": 1},
      "2": {"title": "Release Social Anxiety", "no_of_plays": 3}
    }
  },
  "device_id": "unique-device-identifier-string",
  "purchases": [
    {
      "product_id": "h01enb",
      "purchase_id": "GPA.1234-5678",
      "platform": "android",
      "status": "pending_validation"
    }
  ]
}

Server Response

{
  "json_manifest": {
    "background.json": { "checksum": "a1b2c3d4...", "content": {} },
    "core_segments.json": { "checksum": "e5f6g7h8...", "content": {} },
    "FAQs.json": {},
    "shop.json": {},
    "ads.json": {},
    "C14ENB.json": {}
  },
  "ai_usage": {
    "weekly_limit_credits": 10,
    "weekly_used_credits": 2,
    "weekly_reset_date": "2025-12-30T00:00:00Z",
    "bank_limit_credits": 100,
    "bank_used_credits": 5
  },
  "subscription": {
    "subscription_id": "sub_12345",
    "subscription_type": "premium",
    "status": "active",
    "expiry_date": "2026-01-01T00:00:00Z",
    "auto_renew": true,
    "plan": "monthly-plan"
  }
}

Sync Analysis Categories

Sync Phases (SyncPhase enum)

Checksum Requirements

• JSON formatting: 4-space indentation
• Line endings: CRLF (\r\n) for Windows compatibility
• Field order: LinkedHashMap preserves server field order
• Checksum method: MD5 hash of raw file bytes

JSON Processing Order

1. background.json
2. core_segments.json
3. FAQs.json
4. shop.json
5. ads.json
6. Course JSONs (alphabetical)

System JSONs (Protected)

These cannot be deleted and are always synced: ads.json, background.json, core_segments.json, FAQs.json, shop.json

Mitigations