gh-asleep-ai-sleeptrack-skills-sleeptrack-skills/skills/sleeptrack-foundation/SKILL.md

---
name: sleeptrack-foundation
description: This skill provides foundational knowledge about Asleep sleep tracking platform, covering core concepts, authentication, data structures, error handling, and platform-agnostic best practices. Use this skill when developers ask about Asleep fundamentals, API concepts, error codes, sleep data structures, or need to understand how the platform works before implementing platform-specific integration. This skill serves as prerequisite knowledge for sleeptrack-ios, sleeptrack-android, and sleeptrack-be skills.
---

# Sleeptrack Foundation

## Overview

This skill provides essential foundational knowledge for integrating the Asleep sleep tracking platform. It covers core concepts, authentication patterns, data structures, error handling, and platform-agnostic best practices that apply across all implementation approaches (iOS, Android, and backend API).

Use this skill when developers need to understand:
- What Asleep is and how sleep tracking works
- API authentication and key management
- Sleep session concepts and lifecycle
- Data structures (Sessions, Reports, Statistics)
- Error codes and troubleshooting
- Platform-agnostic integration patterns

## Core Concepts

### What is Asleep?

Asleep is a sleep tracking platform that analyzes sleep using audio-based monitoring through device microphones. The platform provides:

- **Real-time sleep stage analysis**: Wake, Light, Deep, REM detection
- **Comprehensive sleep metrics**: Efficiency, latency, total sleep time, wake after sleep onset
- **Snoring detection and analysis**: Snoring stages and patterns
- **Multi-platform SDKs**: Native iOS and Android SDKs plus REST API
- **Dashboard analytics**: Web-based analytics and user management

### User Management

Each application user must be registered with Asleep before tracking sleep.

**Key Points**:
- User ID is managed by the host application (not generated by Asleep)
- One user can have multiple sleep sessions
- User data persists across sessions for trend analysis
- Users can be created, retrieved, updated, and deleted via API

**Example User ID Schemes**:
```
- UUID: "550e8400-e29b-41d4-a716-446655440000"
- Email-based: "user@example.com"
- App-specific: "app_user_12345"
```

### Sleep Sessions

A session represents one complete sleep tracking period from start to stop.

**Session Lifecycle States**:
1. **IDLE**: No tracking in progress
2. **INITIALIZING**: SDK preparing resources
3. **INITIALIZED**: Ready to start tracking
4. **TRACKING_STARTED**: Active tracking in progress
5. **TRACKING_STOPPING**: Ending session and uploading data

**Session Requirements**:
- Minimum tracking duration: 5 minutes for valid session
- Microphone access required throughout tracking
- Network connectivity needed for data upload
- One active session per user at a time

**Real-time Data Access**:
- Available after sequence 10
- Check every 10 sequences thereafter
- Provides preliminary sleep stage data during tracking

### Sleep Reports

Reports contain comprehensive analysis of completed sleep sessions.

**Report Structure**:
```
Report
├── Session Metadata
│   ├── session_id
│   ├── user_id
│   ├── start_time
│   └── end_time
├── Sleep Stages Timeline
│   ├── Wake periods
│   ├── Light sleep periods
│   ├── Deep sleep periods
│   └── REM sleep periods
├── Sleep Statistics
│   ├── Total sleep time
│   ├── Time in bed
│   ├── Sleep efficiency (%)
│   ├── Sleep latency (time to fall asleep)
│   ├── Wake after sleep onset (WASO)
│   ├── Sleep stage durations
│   └── Sleep stage ratios
└── Snoring Analysis
    ├── Snoring detected (yes/no)
    ├── Snoring stages timeline
    └── Snoring statistics
```

**Key Metrics Explained**:

- **Sleep Efficiency**: (Total sleep time / Time in bed) × 100%
  - Good: > 85%
  - Fair: 75-85%
  - Poor: < 75%

- **Sleep Latency**: Time from lying down to falling asleep
  - Normal: 10-20 minutes
  - Fast: < 10 minutes (may indicate sleep deprivation)
  - Slow: > 20 minutes (may indicate insomnia)

- **WASO**: Total wake time after initial sleep onset
  - Lower is better (indicates fewer disruptions)

### Statistics

Aggregated metrics across multiple sessions for trend analysis.

**Available Statistics**:
- Average sleep duration over time range
- Average sleep efficiency
- Sleep stage distribution averages
- Trends and patterns

**Statistics API**:
```
GET /users/{user_id}/statistics/average?from={date}&to={date}
```

## Authentication

### API Key Management

All Asleep integrations require an API key for authentication.

**Obtaining an API Key**:
1. Sign up at https://dashboard.asleep.ai
2. Navigate to API key generation section
3. Create API key for the application
4. Store securely (never commit to version control)

**Using API Keys**:

For SDK Integration (iOS/Android):
```kotlin
// Android
AsleepConfig.init(
    apiKey = "your_api_key_here",
    userId = "user_unique_id",
    ...
)
```

```swift
// iOS
AsleepConfig.init(
    apiKey: "your_api_key_here",
    userId: "user_unique_id",
    ...
)
```

For REST API Integration:
```http
GET /sessions/{session_id}
X-API-Key: your_api_key_here
```

**Security Best Practices**:
- Store API keys in environment variables or secure storage
- Never hardcode keys in source code
- Use different keys for development and production
- Rotate keys periodically
- Monitor usage in Dashboard to detect unauthorized access
- Revoke compromised keys immediately

## Error Handling

Understanding error codes is critical for robust integration.

### Error Categories

**Critical Errors** (must stop tracking):
These errors indicate conditions that prevent continued tracking and require user intervention or code fixes.

**Warning Errors** (can continue tracking):
These are transient issues that the SDK handles automatically while tracking continues.

### Error Code Reference

#### Critical Errors

**ERR_MIC_PERMISSION**
- **Cause**: App lacks microphone access permission
- **Action**: Request microphone permission from user
- **Platform Notes**:
  - Android: Check RECORD_AUDIO permission
  - iOS: Check NSMicrophoneUsageDescription and authorization status

**ERR_AUDIO**
- **Cause**: Microphone unavailable or in use by another app
- **Action**:
  - Close conflicting apps using microphone
  - Check microphone hardware functionality
  - Verify no audio conflicts in device settings

**ERR_INVALID_URL**
- **Cause**: Malformed API endpoint URL in configuration
- **Action**: Verify AsleepConfig URL format
- **Example Fix**: Ensure base URL is valid HTTPS endpoint

**ERR_COMMON_EXPIRED**
- **Cause**: API rate limit exceeded or subscription plan expired
- **Action**:
  - Check Dashboard for plan status
  - Review API usage patterns
  - Upgrade plan if needed
  - Implement rate limiting in application

**ERR_UPLOAD_FORBIDDEN**
- **Cause**: Multiple simultaneous tracking attempts with same user_id
- **Action**:
  - Ensure only one device tracks per user at a time
  - Check for orphaned sessions
  - Implement proper session cleanup

**ERR_UPLOAD_NOT_FOUND** / **ERR_CLOSE_NOT_FOUND**
- **Cause**: Attempting to interact with non-existent or already-ended session
- **Action**:
  - Verify session exists before operations
  - Handle session expiration properly
  - Implement session state management

#### Warning Errors

**ERR_AUDIO_SILENCED**
- **Cause**: Audio temporarily unavailable but tracking continues
- **Impact**: Minimal, SDK handles gracefully
- **Action**: Log for monitoring, tracking continues

**ERR_AUDIO_UNSILENCED**
- **Cause**: Audio restored after silence period
- **Impact**: Tracking resumes normally
- **Action**: Log for monitoring

**ERR_UPLOAD_FAILED**
- **Cause**: Network connectivity issue during data upload
- **Impact**: SDK will retry automatically
- **Action**:
  - Verify network connectivity
  - Check for firewall/proxy issues
  - Monitor retry success

### Error Handling Patterns

**Distinguish Error Severity**:
```kotlin
// Android example
when (errorCode) {
    in criticalErrors -> {
        // Stop tracking, notify user
        stopTracking()
        showErrorDialog(errorCode)
    }
    in warningErrors -> {
        // Log and continue
        logWarning(errorCode)
    }
}
```

**Provide User-Friendly Messages**:
```kotlin
fun getUserFriendlyMessage(errorCode: AsleepErrorCode): String {
    return when (errorCode) {
        ERR_MIC_PERMISSION -> "Please allow microphone access to track sleep"
        ERR_AUDIO -> "Another app is using the microphone. Please close it and try again"
        ERR_COMMON_EXPIRED -> "Your subscription has expired. Please renew to continue tracking"
        // ... more mappings
    }
}
```

**Implement Retry Logic**:
```kotlin
// For network-related errors
suspend fun uploadWithRetry(maxRetries: Int = 3) {
    repeat(maxRetries) { attempt ->
        try {
            upload()
            return
        } catch (e: NetworkException) {
            if (attempt == maxRetries - 1) throw e
            delay(2.0.pow(attempt) * 1000) // Exponential backoff
        }
    }
}
```

## Data Plan Considerations

Asleep operates on different data plans that affect API usage.

**Plan Limits**:
- Request rate limits
- Total sessions per month
- Data retention periods
- Feature availability

**Monitoring Usage**:
- Check Dashboard regularly
- Implement usage tracking in application
- Set up alerts for approaching limits
- Plan capacity for user growth

## Integration Workflows

### Typical Integration Flow

1. **Setup Phase**:
   - Obtain API key from Dashboard
   - Install SDK (iOS/Android) or configure REST API client
   - Configure authentication

2. **User Registration**:
   - Create user in Asleep system
   - Store user_id mapping in application

3. **Sleep Tracking Session**:
   - Request necessary permissions
   - Initialize SDK with user credentials
   - Start tracking session
   - Monitor session state
   - Handle real-time data (optional)
   - Stop tracking session

4. **Report Generation**:
   - Wait for report processing (automatic)
   - Fetch completed report
   - Display sleep analysis to user

5. **Statistics & Trends**:
   - Query historical sessions
   - Calculate aggregated statistics
   - Display trends over time

### Common Integration Scenarios

**Scenario 1: First-Time User Setup**
```
User downloads app
  → Request microphone permission
  → Create Asleep user (POST /users)
  → Initialize SDK with API key + user_id
  → Guide user through first tracking session
```

**Scenario 2: Returning User**
```
User opens app
  → Load user_id from local storage
  → Initialize SDK with credentials
  → Check for existing running session (reconnect if found)
  → Display previous sleep reports
```

**Scenario 3: Background Tracking**
```
User starts tracking before sleep
  → Start foreground service (Android) / background mode (iOS)
  → Maintain microphone access
  → Handle app lifecycle events
  → Continue tracking through sleep
  → Stop tracking in morning
  → Process and display report
```

## Platform Selection Guide

Choose the appropriate integration approach based on application type:

**Use iOS SDK (sleeptrack-ios)**:
- Native iOS application
- Need deep iOS integration (Siri, HealthKit, etc.)
- Require iOS-specific UI patterns
- Swift/SwiftUI development

**Use Android SDK (sleeptrack-android)**:
- Native Android application
- Need Android-specific features (foreground service, etc.)
- Require Android UI patterns
- Kotlin/Jetpack Compose development

**Use REST API (sleeptrack-be)**:
- Backend/server-side integration
- Multi-platform web application
- Data aggregation and analytics
- Webhook-based event processing
- Cross-platform mobile framework (React Native, Flutter) with custom bridge

## Resources

### Official Documentation

- **Main Documentation**: https://docs-en.asleep.ai
- **LLM-Optimized Reference**: https://docs-en.asleep.ai/llms.txt
- **Dashboard**: https://dashboard.asleep.ai

### Key Documentation Pages

- **QuickStart Guide**: https://docs-en.asleep.ai/docs/quickstart.md
- **Sleep Data Overview**: https://docs-en.asleep.ai/docs/sleep-data.md
- **System Overview**: https://docs-en.asleep.ai/docs/system-overview.md
- **API Basics**: https://docs-en.asleep.ai/docs/api-basics.md
- **Webhook Guide**: https://docs-en.asleep.ai/docs/webhook.md
- **Sleep Environment Guidelines**: https://docs-en.asleep.ai/docs/sleep-environment-guideline.md

### Platform-Specific Documentation

**Android**:
- Get Started: https://docs-en.asleep.ai/docs/android-get-started.md
- Error Codes: https://docs-en.asleep.ai/docs/android-error-codes.md
- AsleepConfig: https://docs-en.asleep.ai/docs/android-asleep-config.md
- SleepTrackingManager: https://docs-en.asleep.ai/docs/android-sleep-tracking-manager.md

**iOS**:
- Get Started: https://docs-en.asleep.ai/docs/ios-get-started.md
- Error Codes: https://docs-en.asleep.ai/docs/ios-error-codes.md
- AsleepConfig: https://docs-en.asleep.ai/docs/ios-asleep-config.md
- SleepTrackingManager: https://docs-en.asleep.ai/docs/ios-sleep-tracking-manager.md

### Reference Files

This skill includes detailed API reference documentation:

- `references/asleep_api_reference.md`: Comprehensive API endpoint reference, data structures, and integration patterns

To load this reference for detailed API information:
```
Read references/asleep_api_reference.md
```

## Best Practices Summary

### Security
- Never expose API keys in client code
- Implement secure storage for credentials
- Use HTTPS for all API communications
- Validate user permissions before operations

### Performance
- Cache reports when appropriate
- Batch API requests to respect rate limits
- Implement efficient session state management
- Monitor real-time data access patterns

### User Experience
- Provide clear permission rationales
- Show friendly error messages
- Display progress during tracking
- Handle app lifecycle gracefully

### Reliability
- Implement comprehensive error handling
- Add retry logic for transient failures
- Log errors for debugging
- Test edge cases (interruptions, low battery, etc.)

### Data Management
- Clean up old sessions appropriately
- Respect user privacy and data retention
- Implement proper user deletion flows
- Backup critical session data

## Next Steps

After understanding these foundational concepts, proceed to platform-specific skills:

- **iOS Development**: Use `sleeptrack-ios` skill
- **Android Development**: Use `sleeptrack-android` skill
- **Backend API Integration**: Use `sleeptrack-be` skill

Each platform-specific skill builds on this foundation with implementation details, code examples, and platform-specific patterns.