@onairos/react-native 3.7.2 → 3.7.3

package/lib/module/config/PLATFORM_APIS.md

@@ -0,0 +1,849 @@
+# Platform Connector APIs Reference
+
+Quick reference for all platform data sources, APIs, authentication, and token management.
+
+---
+
+## Sephora
+
+**Platform ID:** `mobile-sephora`  
+**Data Type:** E-commerce / Beauty
+
+### Authentication
+
+| Key | Storage | Format |
+|-----|---------|--------|
+| `seph-access-token` | localStorage | JSON: `{ data: "JWT...", expiry: "timestamp" }` |
+| `x-api-key` | Header | `nQc7BFt78yJBvfYDKtle9APd5RrX984i` |
+
+**Token Expiry:** ~150 days (expiry is Unix timestamp in seconds)
+
+### APIs
+
+| API | Endpoint | Method | Data Retrieved |
+|-----|----------|--------|----------------|
+| **Profile** | `/gapi/users/profiles/{profileId}/current/full` | GET | Name, email, VIB status, Beauty Insider points, skin/hair/makeup preferences, preferred store |
+| **Basket** | `/api/shopping-cart/basket` | GET | Cart items, subtotal, BI points, shipping info |
+| **Loves** | `/gway/v1/dotcom/users/profiles/{profileId}/lists/skus/all` | GET | Wishlist products with ratings, categories, prices, images |
+| **Purchases** | `/api/bi/profiles/{profileId}/purchases` | GET | Purchase history with products, dates, order IDs |
+
+### Profile API Params
+```
+?skipApis=targetersResult
+&includeApis=profile,basket,loves,shoppingList,segments
+```
+
+### Loves API Params
+```
+?itemsPerPage=100
+&currentPage=1
+&listShortNameLength=20
+&skipProductDetails=false
+&includeInactiveSkus=true
+&fetchAllLovesList=true
+&sortBy=recently
+&includeCategories=true
+```
+
+### Purchases API Params
+```
+?sortBy=recently
+&itemsPerPage=100
+&groupBy=none
+&excludeSamples=true
+&excludeRewards=true
+```
+
+### Data Extracted
+
+**Profile:**
+- `profileId`, `firstName`, `lastName`, `email`
+- `vibStatus` (BI, VIB, Rouge)
+- Beauty Insider: points, segment, spending, birthday gift eligibility
+- Preferences: skin concerns, hair concerns, makeup preferences
+- Preferred store info
+
+**Basket:**
+- Items with SKU ID, product ID, name, brand, price, quantity, size, image
+
+**Loves:**
+- Products with ratings, reviews, categories, stock status, sale info
+
+**Purchases:**
+- Order history with product details, dates, quantities
+
+### Token Extraction
+
+```javascript
+function getSephoraToken() {
+  var tokenKeys = ['seph-access-token', 'sephoraAccessToken', 'accessToken'];
+  
+  // Try localStorage
+  for (var i = 0; i < tokenKeys.length; i++) {
+    var token = localStorage.getItem(tokenKeys[i]);
+    if (token) {
+      try {
+        var parsed = JSON.parse(token);
+        if (parsed && parsed.data) return parsed.data;
+      } catch (e) {
+        return token; // Not JSON, use as-is
+      }
+    }
+  }
+  
+  // Try cookies
+  var cookieMatch = document.cookie.match(/seph-access-token=([^;]+)/);
+  if (cookieMatch) return cookieMatch[1];
+  
+  // Try window state
+  if (window.__PRELOADED_STATE__ && window.__PRELOADED_STATE__.user) {
+    return window.__PRELOADED_STATE__.user.accessToken;
+  }
+  
+  return null;
+}
+```
+
+### Profile ID Extraction
+
+The `profileId` is needed for most Sephora APIs. Extract from:
+
+```javascript
+function getProfileId() {
+  // Method 1: From token (JWT payload)
+  var token = getSephoraToken();
+  if (token) {
+    try {
+      var payload = JSON.parse(atob(token.split('.')[1]));
+      if (payload.sub) return payload.sub;
+    } catch (e) {}
+  }
+  
+  // Method 2: From localStorage
+  var profileId = localStorage.getItem('biAccountId') || 
+                  localStorage.getItem('profileId');
+  if (profileId) return profileId;
+  
+  // Method 3: From window state
+  if (window.__PRELOADED_STATE__ && window.__PRELOADED_STATE__.user) {
+    return window.__PRELOADED_STATE__.user.profileId;
+  }
+  
+  // Method 4: From basket API (doesn't require profileId)
+  // Call /api/shopping-cart/basket first, extract profileId from response
+  
+  return null;
+}
+```
+
+### Token Expiry Check
+
+```javascript
+function isTokenExpired() {
+  var tokenData = localStorage.getItem('seph-access-token');
+  if (!tokenData) return true;
+  
+  try {
+    var parsed = JSON.parse(tokenData);
+    var expiry = parseInt(parsed.expiry, 10);
+    var now = Math.floor(Date.now() / 1000);
+    return now >= expiry;
+  } catch (e) {
+    return true;
+  }
+}
+```
+
+---
+
+## Instagram
+
+**Platform ID:** `mobile-instagram` (data connector) / `instagram` (OAuth)  
+**Data Type:** Social
+
+### Authentication
+
+| Key | Storage | Notes |
+|-----|---------|-------|
+| `csrftoken` | Cookie | CSRF token for POST requests |
+| `sessionid` | Cookie | Session authentication |
+| `X-IG-App-ID` | Header | `936619743392459` |
+| `__bkv` | URL param | Bloks version: `cc4d2103131ee3bbc02c20a86f633b7fb7a031cbf515d12d81e0c8ae7af305dd` |
+
+**Token Expiry:** Session-based (tied to browser session cookie)
+
+### APIs
+
+| API | Endpoint | Method | Data Retrieved |
+|-----|----------|--------|----------------|
+| **Liked Media (Bloks)** | `/async/wbloks/fetch/` | POST | Liked posts via Bloks framework |
+| **Saved Posts** | `/api/v1/feed/saved/posts/` | GET | Saved posts with media, captions, owner info |
+| **Timeline (GraphQL)** | `/graphql/query` | POST | Feed timeline with media, captions, engagement |
+
+### Bloks API (Liked Media)
+
+**Endpoint:**
+```
+POST https://www.instagram.com/async/wbloks/fetch/?appid=com.instagram.privacy.activity_center.liked_media_screen&type=app&__bkv={bloksVersionId}
+```
+
+**Request Body:** `application/x-www-form-urlencoded`
+```
+params=%7B%7D
+```
+
+**Response Format:**
+```javascript
+for (;;);{"__ar":1,"rid":"...","payload":{"layout":{"bloks_payload":{"data":[
+  {"id":"440463611_0","type":"gs","data":{...}},
+  ...
+]}}}}
+```
+
+**Note:** Response has `for (;;);` prefix (anti-JSON hijacking) that must be stripped before JSON.parse()
+
+**Parsing the Bloks payload:**
+```javascript
+function parseLikedMedia(data) {
+  var likes = [];
+  if (data && data.payload && data.payload.layout && data.payload.layout.bloks_payload) {
+    var bloksData = data.payload.layout.bloks_payload.data || [];
+    bloksData.forEach(function(item, idx) {
+      // Bloks items have varying structures
+      if (item.type === 'media' || item.type === 'ig' || item.data) {
+        likes.push({
+          id: item.id || 'like_' + idx,
+          type: 'like',
+          rawData: item.data,
+          bloksType: item.type
+        });
+      }
+    });
+  }
+  return likes;
+}
+```
+
+**⚠️ Bloks Caveat:** The Bloks payload structure is complex and may vary. The `data` array contains UI component definitions, not clean media objects. You may need to recursively parse to extract actual media IDs.
+
+### Saved Posts API
+
+**Endpoint:**
+```
+GET https://www.instagram.com/api/v1/feed/saved/posts/
+```
+
+**Response Format:**
+```javascript
+{
+  "items": [
+    {
+      "media": {
+        "id": "...",
+        "pk": "...",
+        "code": "...",
+        "media_type": 1,
+        "caption": { "text": "..." },
+        "user": { "pk": "...", "username": "..." },
+        "like_count": 123,
+        "comment_count": 45,
+        "taken_at": 1706123456,
+        "image_versions2": { "candidates": [{ "url": "..." }] }
+      }
+    }
+  ],
+  "more_available": true,
+  "next_max_id": "..."
+}
+```
+
+### GraphQL API (Timeline)
+
+**Endpoint:**
+```
+POST https://www.instagram.com/graphql/query
+```
+
+**Request Body:** `application/x-www-form-urlencoded`
+```
+doc_id=8845758582119845&variables={"first":12,"after":null}
+```
+
+**Response Format:**
+```javascript
+{
+  "data": {
+    "xdt_api__v1__feed__timeline__connection": {
+      "pagination_source": null,
+      "edges": [
+        {
+          "node": {
+            "media": {
+              "id": "3820598654428293407_10139962",
+              "pk": "3820598654428293407",
+              "code": "...",
+              "media_type": 1,
+              "caption": { "text": "..." },
+              "user": { "pk": "...", "username": "..." },
+              "like_count": 123,
+              "comment_count": 45,
+              "taken_at": 1706123456,
+              "image_versions2": { "candidates": [{ "url": "..." }] }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+### Required Headers
+
+```javascript
+{
+  'Accept': '*/*',
+  'Accept-Language': 'en-US,en;q=0.9',
+  'X-CSRFToken': csrfToken,
+  'X-IG-App-ID': '936619743392459',
+  'X-Requested-With': 'XMLHttpRequest',
+  'X-ASBD-ID': '129477',
+  'Content-Type': 'application/x-www-form-urlencoded'
+}
+```
+
+### Data Extracted
+
+**Liked Media:**
+- Post IDs
+- Bloks payload data (varies by content type)
+
+**Saved Posts:**
+- `id`, `pk`, `code` (shortcode for URL)
+- `mediaType` (1=image, 2=video, 8=carousel)
+- `caption` text
+- `owner` (user info: id, username, full name)
+- `likeCount`, `commentCount`
+- `takenAt` (Unix timestamp)
+- `imageUrl` (best quality candidate)
+
+**Timeline:**
+- `id`, `pk`, `code` (shortcode for URL)
+- `mediaType` (1=image, 2=video, 8=carousel)
+- `caption` text
+- `owner` (user info: id, username, full name)
+- `likeCount`, `commentCount`
+- `takenAt` (Unix timestamp)
+- `imageUrl` (best quality candidate)
+
+### User ID Extraction
+
+Instagram requires the user's ID for some operations. Extract from page state:
+
+```javascript
+function getUserId() {
+  // Method 1: window._sharedData (older pages)
+  if (window._sharedData && window._sharedData.config) {
+    return window._sharedData.config.viewerId;
+  }
+  
+  // Method 2: window.__initialData (newer pages)
+  if (window.__initialData && window.__initialData.data && window.__initialData.data.user) {
+    return window.__initialData.data.user.id;
+  }
+  
+  // Method 3: Script tag parsing (fallback)
+  var scripts = document.querySelectorAll('script');
+  for (var i = 0; i < scripts.length; i++) {
+    var text = scripts[i].textContent || '';
+    var match = text.match(/"userId":"(\d+)"/);
+    if (match) return match[1];
+    match = text.match(/"viewerId":"(\d+)"/);
+    if (match) return match[1];
+  }
+  
+  return null;
+}
+```
+
+### Bloks Version ID
+
+The `__bkv` parameter is a hash that may change with Instagram updates.
+
+**Current value:** `cc4d2103131ee3bbc02c20a86f633b7fb7a031cbf515d12d81e0c8ae7af305dd`
+
+**To find current value:**
+1. Open Instagram DevTools → Network tab
+2. Navigate to Your Activity → Likes
+3. Look for requests to `/async/wbloks/fetch/`
+4. Copy `__bkv` value from URL
+
+### Pagination
+
+**Saved Posts:**
+```javascript
+// First request
+GET /api/v1/feed/saved/posts/
+
+// Subsequent requests (if more_available: true)
+GET /api/v1/feed/saved/posts/?max_id={next_max_id}
+```
+
+**GraphQL Timeline:**
+```javascript
+// First request
+doc_id=8845758582119845&variables={"first":12,"after":null}
+
+// Subsequent requests
+doc_id=8845758582119845&variables={"first":12,"after":"{end_cursor}"}
+```
+
+The `end_cursor` comes from `pageInfo.end_cursor` in the response.
+
+### Cookie Extraction Helper
+
+```javascript
+function getCookie(name) {
+  var match = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'));
+  return match ? match[2] : null;
+}
+
+// Usage
+var csrfToken = getCookie('csrftoken');
+var sessionId = getCookie('sessionid');
+```
+
+---
+
+## Hinge
+
+**Platform ID:** `mobile-hinge`  
+**Data Type:** Dating
+
+### Authentication
+
+| Key | Storage | Notes |
+|-----|---------|-------|
+| `auth_token` | Cookie/localStorage | TBD - need to confirm |
+| `hinge_auth_token` | Cookie | Fallback |
+
+### APIs
+
+| API | Endpoint | Data Retrieved |
+|-----|----------|----------------|
+| TBD | TBD | Matches, messages |
+
+### Data Extracted
+- Matches (profiles)
+- Messages/chat history
+
+---
+
+---
+
+## Netflix
+
+**Platform ID:** `mobile-netflix`  
+**Data Type:** Streaming / Entertainment
+
+### Authentication
+
+| Key | Storage | Format | Notes |
+|-----|---------|--------|-------|
+| `NetflixId` | Cookie | Session cookie | Main authentication |
+| `SecureNetflixId` | Cookie | Secure session cookie | HTTPS only |
+| `profilesToken` | localStorage/Cookie | JWT-like | Multi-profile auth |
+
+**Token Expiry:** Session-based (~30 days active session, refreshes on activity)
+
+> ⚠️ **DISCOVERY REQUIRED**: Use `tests/netflix-webview-test.html` to discover exact token locations and API endpoints.
+
+### APIs (To Be Discovered)
+
+| API | Expected Endpoint | Method | Data Retrieved |
+|-----|-------------------|--------|----------------|
+| **Viewing History** | `/api/viewing-history` or `/shakti/*` | GET | Watch history with timestamps |
+| **My List** | `/api/mylist` or `/lolomo/*` | GET | Saved titles queue |
+| **Continue Watching** | `/api/continueWatching` | GET | Partially watched content |
+| **Ratings** | `/api/ratings` or `/thumbs` | GET | Thumbs up/down ratings |
+| **Profile** | `/api/profiles` | GET | Profile preferences |
+
+### Known Netflix Patterns
+
+1. **Shakti API** - Netflix's internal API framework
+   - Base: `https://www.netflix.com/nq/website/memberapi/{version}/`
+   - Requires `BUILD_IDENTIFIER` from page source
+
+2. **pathEvaluator** - GraphQL-like data fetching
+   - Used for homepage/browse data
+   - May contain viewing activity
+
+3. **Multi-Profile** - Netflix supports multiple profiles per account
+   - Current profile context needed for API calls
+
+### Token Extraction (Placeholder)
+
+```javascript
+function getNetflixToken() {
+  // Method 1: Cookies
+  var netflixId = document.cookie.match(/NetflixId=([^;]+)/);
+  if (netflixId) return { token: netflixId[1], type: 'cookie' };
+  
+  // Method 2: localStorage
+  var tokenKeys = ['netflix_token', 'profilesToken', 'authToken'];
+  for (var i = 0; i < tokenKeys.length; i++) {
+    var token = localStorage.getItem(tokenKeys[i]);
+    if (token) return { token: token, type: 'localStorage' };
+  }
+  
+  // Method 3: Window state (TODO: discover Netflix state object)
+  // if (window.__NETFLIX_STATE__) return ...
+  
+  return null;
+}
+```
+
+### Data Extracted
+
+**Viewing History:**
+- `videoId` - Netflix content ID
+- `title` - Show/movie name
+- `type` - movie/series/episode
+- `seriesTitle`, `seasonNumber`, `episodeNumber` (for series)
+- `watchedAt` - Timestamp
+- `watchDuration`, `totalDuration`, `percentWatched`
+
+**My List:**
+- `videoId`, `title`, `type`
+- `addedAt` - When added to list
+- `genres`, `maturityRating`, `year`
+
+**Ratings:**
+- `videoId`, `title`
+- `rating` - thumbs_up/thumbs_down/love
+- `ratedAt` - When rated
+
+---
+
+## Spotify
+
+**Platform ID:** `mobile-spotify`  
+**Data Type:** Streaming / Music
+
+### Authentication
+
+| Key | Storage | Format | Notes |
+|-----|---------|--------|-------|
+| `sp_dc` | Cookie | Device credentials | Long-lived session cookie |
+| `sp_t` | Cookie | Spotify token | Short-lived token |
+| `accessToken` | Memory/localStorage | Bearer token | ~1 hour expiry |
+
+**Token Expiry:** Access token ~1 hour, sp_dc cookie ~1 year
+
+> ⚠️ **DISCOVERY REQUIRED**: Use `tests/spotify-webview-test.html` to discover exact token locations.
+
+### APIs (Standard Spotify Web API)
+
+| API | Endpoint | Method | Data Retrieved |
+|-----|----------|--------|----------------|
+| **Profile** | `/v1/me` | GET | User profile, subscription, country |
+| **Recently Played** | `/v1/me/player/recently-played` | GET | Last 50 played tracks |
+| **Top Tracks** | `/v1/me/top/tracks` | GET | User's most played tracks |
+| **Top Artists** | `/v1/me/top/artists` | GET | User's most played artists |
+| **Playlists** | `/v1/me/playlists` | GET | User's playlists |
+| **Saved Tracks** | `/v1/me/tracks` | GET | Liked Songs library |
+| **Saved Albums** | `/v1/me/albums` | GET | Saved albums |
+
+**API Base URL:** `https://api.spotify.com`
+
+**Alternative (Web Player Internal):**
+- `https://spclient.wg.spotify.com/` - Spotify internal client
+- `https://api-partner.spotify.com/` - Partner API
+
+### Request Headers
+
+```javascript
+{
+  'Authorization': 'Bearer ' + accessToken,
+  'Accept': 'application/json',
+  'Content-Type': 'application/json'
+}
+```
+
+### API Query Parameters
+
+**Top Items:**
+```
+?time_range=medium_term&limit=50
+```
+- `time_range`: `short_term` (4 weeks), `medium_term` (6 months), `long_term` (years)
+- `limit`: 1-50
+
+**Recently Played:**
+```
+?limit=50&before={unix_timestamp_ms}
+```
+
+**Playlists/Saved:**
+```
+?limit=50&offset=0
+```
+
+### Token Extraction (Placeholder)
+
+```javascript
+function getSpotifyToken() {
+  // Method 1: localStorage (most likely)
+  var tokenKeys = ['spotify_access_token', 'accessToken', 'sp_access_token'];
+  for (var i = 0; i < tokenKeys.length; i++) {
+    var token = localStorage.getItem(tokenKeys[i]);
+    if (token) {
+      try {
+        var parsed = JSON.parse(token);
+        return { token: parsed.accessToken || parsed.token, expiry: parsed.expiresAt };
+      } catch (e) {
+        if (token.startsWith('BQ')) return { token: token, expiry: null };
+      }
+    }
+  }
+  
+  // Method 2: Intercept from network requests
+  // The web player makes API calls with Authorization header
+  
+  // Method 3: Window state
+  // Spotify web player may store token in React state
+  
+  return null;
+}
+```
+
+### Data Extracted
+
+**Recently Played:**
+- `trackId`, `name`, `artists[]`, `album`
+- `playedAt` - ISO timestamp
+- `duration` - Track length in ms
+- `imageUrl`, `previewUrl`
+
+**Top Items:**
+- Tracks: `trackId`, `name`, `artists[]`, `popularity`
+- Artists: `artistId`, `name`, `genres[]`, `followers`
+
+**Playlists:**
+- `playlistId`, `name`, `description`
+- `isPublic`, `isCollaborative`
+- `trackCount`, `owner`
+
+**Saved Tracks/Albums:**
+- Track/Album details
+- `savedAt` - When saved
+
+### Rate Limits
+
+| Endpoint | Rate Limit | Notes |
+|----------|------------|-------|
+| Most endpoints | ~100 req/min | Per user token |
+| Search | ~30 req/min | Stricter |
+
+### Pagination
+
+```javascript
+// Response includes
+{
+  "items": [...],
+  "next": "https://api.spotify.com/v1/me/tracks?offset=50&limit=50",
+  "total": 500,
+  "limit": 50,
+  "offset": 0
+}
+
+// Use next URL or manually paginate with offset
+```
+
+---
+
+## Token Expiry Reference
+
+| Platform | Token Lifetime | Storage Location | Refresh Mechanism | How to Check Expiry |
+|----------|---------------|------------------|-------------------|---------------------|
+| **Sephora** | ~150 days | localStorage `seph-access-token` | Auto-refresh on site visit | Check `expiry` field in JSON (Unix timestamp) |
+| **Instagram** | Session-based (~24h-7d) | Cookie `sessionid` | New session on login | No direct field; 401 = expired |
+| **ChatGPT** | ~14 days | Cookie `__Secure-next-auth.session-token` | Auto-refresh on activity | JWT `exp` claim |
+| **Claude** | Session-based | Cookie/localStorage | Session refresh | Check for 401 response |
+| **Telegram** | Session-based | localStorage various keys | WebSocket reconnect | Check connection state |
+| **Hinge** | TBD | TBD | TBD | TBD |
+| **Netflix** | ~30 days session | Cookie `NetflixId` | Session cookie refresh | 401/403 response |
+| **Spotify** | ~1 hour (access token) | Memory/localStorage | Refresh token endpoint | `expires_in` field or 401 |
+
+### Token Refresh Patterns
+
+| Platform | Refresh Pattern | Implementation |
+|----------|-----------------|----------------|
+| **Sephora** | Passive (site visit) | Token auto-updates in localStorage on any page load |
+| **Instagram** | Re-authentication | User must log in again when session expires |
+| **ChatGPT** | Background refresh | Next.js session auto-refreshes; re-login if fully expired |
+| **Spotify** | Active refresh | Call `/api/token` with refresh_token (OAuth 2.0 standard) |
+| **Netflix** | Cookie refresh | Session cookies refresh on any Netflix activity |
+
+### Detecting Expired Tokens
+
+```javascript
+// Universal expiry detection
+async function checkTokenValidity(platform, token) {
+  try {
+    // Make a lightweight API call
+    var response = await fetch(getTestEndpoint(platform), {
+      headers: { 'Authorization': 'Bearer ' + token }
+    });
+    
+    if (response.status === 401 || response.status === 403) {
+      return { valid: false, reason: 'Token expired or revoked' };
+    }
+    
+    return { valid: true };
+  } catch (e) {
+    return { valid: false, reason: e.message };
+  }
+}
+
+function getTestEndpoint(platform) {
+  switch(platform) {
+    case 'spotify': return 'https://api.spotify.com/v1/me';
+    case 'instagram': return 'https://www.instagram.com/api/v1/users/web_profile_info/';
+    // Add others as needed
+  }
+}
+```
+
+### JWT Token Expiry Check
+
+```javascript
+function getJWTExpiry(token) {
+  try {
+    var payload = JSON.parse(atob(token.split('.')[1]));
+    if (payload.exp) {
+      var expiryDate = new Date(payload.exp * 1000);
+      var now = new Date();
+      return {
+        expiresAt: expiryDate.toISOString(),
+        isExpired: now > expiryDate,
+        minutesRemaining: Math.floor((expiryDate - now) / 60000)
+      };
+    }
+  } catch (e) {
+    return { error: 'Not a JWT or invalid format' };
+  }
+  return { error: 'No exp claim found' };
+}
+```
+
+---
+
+## Common Request Headers
+
+All platforms require:
+```javascript
+{
+  'Accept': 'application/json',
+  'Content-Type': 'application/json',
+  'credentials': 'include'  // for cookies
+}
+```
+
+Platform-specific headers are added per connector.
+
+---
+
+## Onairos Backend Endpoint
+
+All extracted data is sent to:
+```
+POST https://api2.onairos.uk/platform-data/store
+```
+
+With headers:
+```javascript
+{
+  'Content-Type': 'application/json',
+  'Authorization': 'Bearer <onairos_user_token>'
+}
+```
+
+Payload structure:
+```javascript
+{
+  platform: 'mobile-sephora',  // platform ID
+  dataType: 'ecommerce',       // data category
+  data: { ... },               // extracted data
+  summary: { ... },            // quick stats
+  mobileMetadata: {
+    platform: 'web',
+    source: 'bookmarklet-api',
+    extractedAt: 'ISO timestamp',
+    tokenExpiry: { ... }       // token expiry info
+  }
+}
+```
+
+---
+
+## Rate Limits & Best Practices
+
+### General Guidelines
+
+| Platform | Rate Limit | Recommendation |
+|----------|------------|----------------|
+| **Sephora** | Unknown (generous) | Max 10 requests per extraction |
+| **Instagram** | Strict (anti-bot) | Max 3-5 requests, add delays |
+| **Hinge** | TBD | TBD |
+
+### Implementation Tips
+
+1. **Parallel requests** - Use `Promise.all()` for independent API calls
+2. **Error handling** - Gracefully handle 401/403 (re-auth needed), 429 (rate limited)
+3. **Credentials** - Always include `credentials: 'include'` for cookie-based auth
+4. **CORS** - These APIs work from same-origin (bookmarklet on the site), not cross-origin
+
+### Response Parsing
+
+**Instagram Bloks (strip prefix):**
+```javascript
+function parseBloksResponse(text) {
+  if (text.startsWith('for (;;);')) {
+    text = text.substring(9);
+  }
+  return JSON.parse(text);
+}
+```
+
+**Sephora (standard JSON):**
+```javascript
+var data = await response.json();
+```
+
+### Error Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 200 | Success | Parse response |
+| 401 | Unauthorized | Token expired, prompt re-login |
+| 403 | Forbidden | Blocked/banned, try later |
+| 429 | Rate Limited | Wait and retry |
+| 500+ | Server Error | Retry with backoff |
+
+---
+
+## Quick Implementation Checklist
+
+For each platform connector:
+
+- [ ] Verify user is on correct domain
+- [ ] Show consent popup
+- [ ] Extract auth token(s)
+- [ ] Check token validity/expiry
+- [ ] Call APIs with proper headers
+- [ ] Parse responses
+- [ ] Build normalized payload
+- [ ] Send to Onairos backend
+- [ ] Show success/error message
+