Initial commit

2025-11-29 17:58:23 +08:00
commit 9faa5d88f3
22 changed files with 9600 additions and 0 deletions
--- a/skills/sleeptrack-be/SKILL.md
+++ b/skills/sleeptrack-be/SKILL.md
@@ -0,0 +1,519 @@
+---
+name: sleeptrack-be
+description: This skill provides comprehensive backend REST API integration for Asleep sleep tracking platform. Use this skill when building server-side applications, API proxies for mobile apps, webhook event handlers, cross-platform backends (React Native, Flutter), analytics dashboards, or multi-tenant sleep tracking systems. Covers authentication, user management, session retrieval, statistics, webhook integration, and production-ready patterns with code examples in Python, Node.js, and curl.
+---
+
+# Sleeptrack Backend API Integration
+
+## Overview
+
+This skill provides comprehensive guidance for integrating the Asleep REST API into backend applications. It covers server-side user management, session data retrieval, statistics aggregation, webhook event handling, and production-ready patterns for building robust sleep tracking backends.
+
+**Use this skill when:**
+- Building backend/server-side sleep tracking integrations
+- Creating API proxies for mobile applications
+- Implementing webhook handlers for real-time sleep data
+- Developing cross-platform backends (React Native, Flutter)
+- Building analytics dashboards and reporting systems
+- Creating multi-tenant sleep tracking applications
+- Integrating sleep data with other health platforms
+
+## Quick Start
+
+### 1. Get Your API Key
+
+1. Sign up at https://dashboard.asleep.ai
+2. Generate an API key for your application
+3. Store securely in environment variables (never commit to version control)
+
+### 2. Basic Authentication
+
+All API requests require the `x-api-key` header:
+
+**curl:**
+```bash
+curl -X GET "https://api.asleep.ai/ai/v1/users/USER_ID" \
+  -H "x-api-key: YOUR_API_KEY"
+```
+
+**Python:**
+```python
+import requests
+
+headers = {"x-api-key": "YOUR_API_KEY"}
+response = requests.get(
+    "https://api.asleep.ai/ai/v1/users/USER_ID",
+    headers=headers
+)
+```
+
+**Node.js:**
+```javascript
+const axios = require('axios');
+
+const response = await axios.get(
+  'https://api.asleep.ai/ai/v1/users/USER_ID',
+  {
+    headers: { 'x-api-key': 'YOUR_API_KEY' }
+  }
+);
+```
+
+## API Client Structure
+
+Build a reusable API client to handle authentication, error handling, and common operations.
+
+**Key Components:**
+- Base URL configuration (`https://api.asleep.ai`)
+- API key authentication in headers
+- Error handling for common HTTP status codes (401, 403, 404)
+- Request methods for all API endpoints
+- Session management with persistent connections
+
+**For complete implementations:**
+- Python: See `references/python_client_implementation.md`
+- Node.js: See `references/nodejs_client_implementation.md`
+- REST API details: See `references/rest_api_reference.md`
+
+**Basic Client Structure:**
+```python
+class AsleepClient:
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+        self.base_url = "https://api.asleep.ai"
+        self.session = requests.Session()
+        self.session.headers.update({"x-api-key": api_key})
+
+    def _request(self, method: str, path: str, **kwargs):
+        # Handle authentication and errors
+        # See python_client_implementation.md for full code
+        pass
+```
+
+## User Management
+
+### Creating Users
+
+Create users before tracking sleep. User IDs are managed by your application.
+
+```python
+# Create user with metadata
+user_id = client.create_user(metadata={
+    "birth_year": 1990,
+    "gender": "male",
+    "height": 175.5,  # cm
+    "weight": 70.0    # kg
+})
+```
+
+**Available Metadata Fields:**
+- `birth_year` (Integer): Birth year
+- `birth_month` (Integer): 1-12
+- `birth_day` (Integer): 1-31
+- `gender` (String): `male`, `female`, `non_binary`, `other`, `prefer_not_to_say`
+- `height` (Float): Height in cm (0-300)
+- `weight` (Float): Weight in kg (0-1000)
+
+### Retrieving User Information
+
+```python
+user_data = client.get_user(user_id)
+# Returns: user_id, to_be_deleted status, last_session_info, metadata
+```
+
+**Response includes:**
+- User ID and deletion status
+- Last session information (if available)
+- User metadata (demographic information)
+
+### Deleting Users
+
+Permanently removes user and all associated data (sessions, reports).
+
+```python
+client.delete_user(user_id)
+```
+
+**For detailed examples and response structures:**
+- See `references/rest_api_reference.md` (User Management section)
+- See `references/python_client_implementation.md` or `references/nodejs_client_implementation.md`
+
+## Session Management
+
+### Retrieving Session Details
+
+Get comprehensive sleep analysis for a specific session.
+
+```python
+session = client.get_session(
+    session_id="session123",
+    user_id="user123",
+    timezone="America/New_York"
+)
+
+# Access key metrics
+print(f"Sleep efficiency: {session['stat']['sleep_efficiency']:.1f}%")
+print(f"Total sleep time: {session['stat']['sleep_time']}")
+print(f"Sleep stages: {session['session']['sleep_stages']}")
+```
+
+**Sleep Stage Values:**
+- `-1`: Unknown/No data
+- `0`: Wake
+- `1`: Light sleep
+- `2`: Deep sleep
+- `3`: REM sleep
+
+**Key Metrics:**
+- `sleep_efficiency`: (Total sleep time / Time in bed) × 100%
+- `sleep_latency`: Time to fall asleep (seconds)
+- `waso_count`: Wake after sleep onset episodes
+- `time_in_bed`: Total time in bed (seconds)
+- `time_in_sleep`: Actual sleep time (seconds)
+- `time_in_light/deep/rem`: Stage durations (seconds)
+
+### Listing Sessions
+
+Retrieve multiple sessions with date filtering and pagination.
+
+```python
+sessions = client.list_sessions(
+    user_id="user123",
+    date_gte="2024-01-01",
+    date_lte="2024-01-31",
+    limit=50,
+    order_by="DESC"
+)
+```
+
+**Pagination Example:**
+```python
+all_sessions = []
+offset = 0
+limit = 100
+
+while True:
+    result = client.list_sessions(
+        user_id="user123",
+        offset=offset,
+        limit=limit
+    )
+    sessions = result['sleep_session_list']
+    all_sessions.extend(sessions)
+
+    if len(sessions) < limit:
+        break
+    offset += limit
+```
+
+### Deleting Sessions
+
+```python
+client.delete_session(session_id="session123", user_id="user123")
+```
+
+**For detailed session data structures and examples:**
+- See `references/rest_api_reference.md` (Session Management section)
+- See client implementation references for language-specific examples
+
+## Statistics and Analytics
+
+### Average Statistics
+
+Get aggregated sleep metrics over a time period (max 100 days).
+
+```python
+stats = client.get_average_stats(
+    user_id="user123",
+    start_date="2024-01-01",
+    end_date="2024-01-31",
+    timezone="UTC"
+)
+
+avg = stats['average_stats']
+print(f"Average sleep time: {avg['sleep_time']}")
+print(f"Average efficiency: {avg['sleep_efficiency']:.1f}%")
+print(f"Light sleep ratio: {avg['light_ratio']:.1%}")
+print(f"Number of sessions: {len(stats['slept_sessions'])}")
+```
+
+**Returned Metrics:**
+- Average sleep time, bedtime, wake time
+- Average sleep efficiency
+- Sleep stage ratios (light, deep, REM)
+- List of sessions included in calculation
+
+**For trend analysis and advanced analytics:**
+- See `references/python_client_implementation.md` (Analytics section)
+- See `references/rest_api_reference.md` (Statistics section)
+
+## Webhook Integration
+
+Webhooks enable real-time notifications for sleep session events.
+
+### Webhook Event Types
+
+1. **INFERENCE_COMPLETE**: Incremental sleep data during tracking (every 5-40 minutes)
+2. **SESSION_COMPLETE**: Final comprehensive sleep analysis when session ends
+
+### Setting Up Webhook Endpoint
+
+**Basic Structure:**
+```python
+@app.route('/asleep-webhook', methods=['POST'])
+def asleep_webhook():
+    # 1. Verify authentication (x-api-key header)
+    # 2. Parse event data
+    # 3. Handle event type (INFERENCE_COMPLETE or SESSION_COMPLETE)
+    # 4. Process and store data
+    # 5. Return 200 response
+    pass
+```
+
+**Key Implementation Points:**
+- Verify `x-api-key` header matches your API key
+- Validate `x-user-id` header
+- Handle both INFERENCE_COMPLETE and SESSION_COMPLETE events
+- Implement idempotency (check if event already processed)
+- Process asynchronously for better performance
+- Return 200 status immediately
+
+**For complete webhook implementations:**
+- Python (Flask): See `references/webhook_implementation_guide.md`
+- Node.js (Express): See `references/webhook_implementation_guide.md`
+- Webhook payloads: See `references/webhook_reference.md`
+
+### Webhook Best Practices
+
+**Idempotency:**
+Check if webhook event was already processed to avoid duplicates.
+
+**Asynchronous Processing:**
+Queue webhook events for background processing and respond immediately.
+
+**Error Handling:**
+Return 200 even if processing fails internally to prevent retries.
+
+**For detailed patterns:**
+- See `references/webhook_implementation_guide.md`
+- See `references/production_patterns.md` (Background Jobs section)
+
+## Common Backend Patterns
+
+### 1. API Proxy for Mobile Apps
+
+Create a backend proxy to:
+- Hide API keys from mobile clients
+- Add custom authentication
+- Implement business logic
+- Track usage and analytics
+
+**Key endpoints:**
+- POST `/api/users` - Create Asleep user for authenticated app user
+- GET `/api/sessions/{id}` - Proxy session retrieval with auth
+- GET `/api/sessions` - List sessions with filtering
+- GET `/api/statistics` - Get aggregated statistics
+
+**For complete implementation:**
+- See `references/python_client_implementation.md` (API Proxy section)
+
+### 2. Analytics Dashboard Backend
+
+Aggregate and analyze sleep data across multiple users:
+- Calculate comprehensive sleep scores
+- Generate weekly/monthly reports
+- Analyze cohort sleep patterns
+- Provide personalized insights
+
+**Key features:**
+- Sleep score calculation (efficiency + consistency + duration)
+- Trend analysis over time
+- Multi-user aggregation
+- Report generation
+
+**For complete implementation:**
+- See `references/python_client_implementation.md` (Analytics section)
+
+### 3. Multi-Tenant Application
+
+Manage sleep tracking for multiple organizations or teams:
+- Organization-level user management
+- Aggregated organization statistics
+- Role-based access control
+- Per-organization settings
+
+**For complete implementation:**
+- See `references/python_client_implementation.md` (Multi-Tenant section)
+
+## Error Handling
+
+### Common Error Codes
+
+- **401 Unauthorized**: Invalid API key
+- **403 Forbidden**: Rate limit exceeded or insufficient permissions
+- **404 Not Found**: Resource does not exist
+- **422 Unprocessable Entity**: Invalid request parameters
+
+### Retry Logic with Exponential Backoff
+
+```python
+def retry_with_exponential_backoff(func, max_retries=3, base_delay=1.0):
+    for attempt in range(max_retries):
+        try:
+            return func()
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 403 and "rate limit" in str(e):
+                if attempt < max_retries - 1:
+                    delay = min(base_delay * (2 ** attempt), 60.0)
+                    time.sleep(delay)
+                    continue
+            raise
+```
+
+### Custom Exception Classes
+
+```python
+class AsleepAPIError(Exception):
+    """Base exception for Asleep API errors"""
+    pass
+
+class RateLimitError(AsleepAPIError):
+    """Rate limit exceeded"""
+    pass
+
+class ResourceNotFoundError(AsleepAPIError):
+    """Resource not found"""
+    pass
+```
+
+**For comprehensive error handling:**
+- See `references/python_client_implementation.md` or `references/nodejs_client_implementation.md`
+- See `references/production_patterns.md` (Error Recovery section)
+
+## Testing
+
+### Local Webhook Testing
+
+Use ngrok to expose local server for webhook testing:
+
+```bash
+# Start local server
+python app.py  # or npm start
+
+# Expose with ngrok
+ngrok http 5000
+
+# Use ngrok URL in webhook configuration
+# Example: https://abc123.ngrok.io/asleep-webhook
+```
+
+### Mock API Responses
+
+```python
+@patch('requests.Session.request')
+def test_create_user(mock_request):
+    mock_response = Mock()
+    mock_response.json.return_value = {
+        "result": {"user_id": "test_user_123"}
+    }
+    mock_request.return_value = mock_response
+
+    user_id = client.create_user()
+    assert user_id == "test_user_123"
+```
+
+**For complete testing examples:**
+- See `references/python_client_implementation.md` (Testing section)
+
+## Production Best Practices
+
+### Security
+
+1. **API Key Management:**
+   - Store in environment variables or secret management system
+   - Never commit to version control
+   - Rotate keys periodically
+   - Use different keys for dev/staging/production
+
+2. **Webhook Security:**
+   - Verify `x-api-key` header
+   - Use HTTPS endpoints only
+   - Implement rate limiting
+   - Log all webhook attempts
+
+3. **User Data Privacy:**
+   - Encrypt sensitive data at rest
+   - Implement proper access controls
+   - Handle data deletion requests
+   - Comply with GDPR/CCPA
+
+### Performance
+
+1. **Caching:** Cache immutable session data
+2. **Rate Limiting:** Protect your backend from overload
+3. **Connection Pooling:** Reuse HTTP connections
+4. **Batch Processing:** Process multiple requests in parallel
+
+### Monitoring
+
+1. **Logging:** Structured logging for all API requests
+2. **Metrics:** Track request duration, error rates, throughput
+3. **Health Checks:** Implement `/health`, `/ready`, `/live` endpoints
+4. **Alerting:** Alert on error rate spikes or API failures
+
+### Deployment
+
+1. **Configuration:** Environment-based settings with validation
+2. **Health Checks:** Support Kubernetes liveness/readiness probes
+3. **Graceful Shutdown:** Handle termination signals properly
+4. **Error Recovery:** Circuit breaker pattern for API failures
+
+**For comprehensive production patterns:**
+- Caching strategies: See `references/production_patterns.md`
+- Rate limiting: See `references/production_patterns.md`
+- Monitoring: See `references/production_patterns.md`
+- Deployment: See `references/production_patterns.md`
+
+## Resources
+
+### Reference Documentation
+
+This skill includes comprehensive reference files:
+
+- `references/python_client_implementation.md`: Complete Python client with all methods, analytics classes, and examples
+- `references/nodejs_client_implementation.md`: Complete Node.js client with Express integration
+- `references/webhook_implementation_guide.md`: Full webhook handlers in Python and Node.js with best practices
+- `references/rest_api_reference.md`: Complete REST API endpoint documentation with request/response examples
+- `references/webhook_reference.md`: Webhook integration guide with payload structures
+- `references/production_patterns.md`: Caching, rate limiting, monitoring, deployment, and performance optimization
+
+To access detailed information:
+```
+Read references/python_client_implementation.md
+Read references/nodejs_client_implementation.md
+Read references/webhook_implementation_guide.md
+Read references/rest_api_reference.md
+Read references/webhook_reference.md
+Read references/production_patterns.md
+```
+
+### Official Documentation
+
+- **Main Documentation**: https://docs-en.asleep.ai
+- **API Basics**: https://docs-en.asleep.ai/docs/api-basics.md
+- **Webhook Guide**: https://docs-en.asleep.ai/docs/webhook.md
+- **Dashboard**: https://dashboard.asleep.ai
+- **LLM-Optimized Reference**: https://docs-en.asleep.ai/llms.txt
+
+### Related Skills
+
+- **sleeptrack-foundation**: Core concepts, authentication, data structures, and platform-agnostic patterns
+- **sleeptrack-ios**: iOS SDK integration for native iOS applications
+- **sleeptrack-android**: Android SDK integration for native Android applications
+
+### Support
+
+For technical support and API issues:
+- Check Dashboard for API usage and status
+- Review error logs and response codes
+- Contact support through Asleep Dashboard