# Quickstart: Garmin Sync with Progress Tracking

This guide provides a quick overview of how to use the simplified Garmin sync functionality with progress tracking.

## 1. Initiate a Synchronization

To start a synchronization for activities, workouts, or health metrics, send a POST request to the respective endpoint. The system will only allow one sync to run at a time.

### Sync Activities

```bash
curl -X POST "http://localhost:8000/api/v1/garmin/activities" \
     -H "accept: application/json"
```

### Sync Workouts

```bash
curl -X POST "http://localhost:8000/api/v1/garmin/workouts" \
     -H "accept: application/json"
```

### Sync Health Metrics

```bash
curl -X POST "http://localhost:8000/api/v1/garmin/health" \
     -H "accept: application/json"
```

**Expected Response (Success)**:

```json
{
  "message": "Activity synchronization initiated successfully."
}
```

**Expected Response (Conflict - if another sync is in progress)**:

```json
{
  "detail": "A synchronization is already in progress. Please wait or check status."
}
```

## 2. Poll for Sync Status

To check the current status and progress of the active synchronization job, send a GET request to the status endpoint. This endpoint will always return the status of the single active sync.

```bash
curl -X GET "http://localhost:8000/api/v1/garmin/sync/status" \
     -H "accept: application/json"
```

**Expected Response (Sync in Progress)**:

```json
{
  "status": "in_progress",
  "progress": 0.5,
  "start_time": "2025-10-11T10:00:00Z",
  "end_time": null,
  "error_message": null,
  "job_type": "activities"
}
```

**Expected Response (Sync Completed)**:

```json
{
  "status": "completed",
  "progress": 1.0,
  "start_time": "2025-10-11T10:00:00Z",
  "end_time": "2025-10-11T10:15:00Z",
  "error_message": null,
  "job_type": "activities"
}
```

**Expected Response (Sync Failed)**:

```json
{
  "status": "failed",
  "progress": 0.75,
  "start_time": "2025-10-11T10:00:00Z",
  "end_time": "2025-10-11T10:10:00Z",
  "error_message": "Failed to connect to Garmin API.",
  "job_type": "activities"
}
```

**Expected Response (No Sync Active)**:

```json
{
  "status": "idle",
  "progress": 0.0,
  "start_time": "1970-01-01T00:00:00Z",
  "end_time": null,
  "error_message": null,
  "job_type": null
}
```

## 3. Handling Concurrent Sync Attempts

If you attempt to initiate a new sync while another is already in progress, the system will return a `409 Conflict` status code with an informative message. You must wait for the current sync to complete or fail before starting a new one.