sleeptrack-foundation

# 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 progres