openapi: 3.0.0
info:
  title: Fitbit-Garmin Sync API
  description: API for synchronizing health and fitness data between Fitbit and Garmin Connect platforms
  version: 1.0.0
servers:
  - url: http://localhost:8000
    description: Development server

paths:
  /api/status:
    get:
      summary: Get current sync status
      description: Provides JSON data for the status dashboard including sync counts and recent logs
      responses:
        '200':
          description: Current sync status
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_weight_records:
                    type: integer
                    description: Total number of weight records
                  synced_weight_records:
                    type: integer
                    description: Number of synced weight records
                  unsynced_weight_records:
                    type: integer
                    description: Number of unsynced weight records
                  total_activities:
                    type: integer
                    description: Total number of activities
                  downloaded_activities:
                    type: integer
                    description: Number of downloaded activities
                  recent_logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/SyncLog'

  /api/logs:
    get:
      summary: Get sync logs
      description: Provides JSON data for the sync logs table
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          description: Number of log entries to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Offset for pagination
      responses:
        '200':
          description: Array of sync log entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SyncLog'

  /api/sync/weight:
    post:
      summary: Trigger weight sync
      description: Starts the process of syncing weight data from Fitbit to Garmin
      responses:
        '200':
          description: Weight sync initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "started"
                  message:
                    type: string
                    example: "Weight sync process started"
                  job_id:
                    type: string
                    example: "weight-sync-12345"

  /api/sync/activities:
    post:
      summary: Trigger activity sync
      description: Starts the process of archiving activities from Garmin to local storage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                days_back:
                  type: integer
                  description: Number of days to look back for activities
                  example: 30
      responses:
        '200':
          description: Activity sync initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "started"
                  message:
                    type: string
                    example: "Activity sync process started"
                  job_id:
                    type: string
                    example: "activity-sync-12345"

  /api/setup/garmin:
    post:
      summary: Save Garmin credentials
      description: Saves Garmin credentials from the setup form
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Garmin Connect username
                password:
                  type: string
                  description: Garmin Connect password
      responses:
        '200':
          description: Garmin credentials saved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  message:
                    type: string
                    example: "Garmin credentials saved"

  /api/setup/fitbit:
    post:
      summary: Save Fitbit credentials
      description: Saves Fitbit credentials and returns the auth URL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: Fitbit API client ID
                client_secret:
                  type: string
                  description: Fitbit API client secret
      responses:
        '200':
          description: Fitbit credentials saved and auth URL returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  auth_url:
                    type: string
                    example: "https://www.fitbit.com/oauth2/authorize?..."
                  message:
                    type: string
                    example: "Fitbit credentials saved, please visit auth_url to authorize"

  /api/setup/fitbit/callback:
    post:
      summary: Complete Fitbit OAuth flow
      description: Completes the Fitbit OAuth flow with the callback URL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callback_url:
                  type: string
                  description: Full callback URL from the browser after authorizing the Fitbit app
      responses:
        '200':
          description: Fitbit OAuth flow completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  message:
                    type: string
                    example: "Fitbit OAuth flow completed successfully"

  /api/metrics/list:
    get:
      summary: List available metric types
      description: Returns a list of available metric types and date ranges
      responses:
        '200':
          description: List of available metric types
          content:
            application/json:
              schema:
                type: object
                properties:
                  metric_types:
                    type: array
                    items:
                      type: string
                    example: ["steps", "heart_rate", "sleep", "calories"]
                  date_range:
                    type: object
                    properties:
                      start_date:
                        type: string
                        format: date
                      end_date:
                        type: string
                        format: date

  /api/metrics/query:
    get:
      summary: Query health metrics
      description: Allows filtering and retrieval of specific metrics by date range, type, or other criteria
      parameters:
        - name: metric_type
          in: query
          schema:
            type: string
          description: Type of metric to retrieve
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          description: Start date for the query
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          description: End date for the query
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          description: Number of records to return
      responses:
        '200':
          description: Array of health metrics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HealthMetric'

  /api/activities/list:
    get:
      summary: List available activities
      description: Returns metadata for all downloaded/available activities
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
          description: Number of activities to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Offset for pagination
      responses:
        '200':
          description: Array of activity metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Activity'

  /api/activities/query:
    get:
      summary: Query activities
      description: Allows advanced filtering of activities by type, date, duration, etc.
      parameters:
        - name: activity_type
          in: query
          schema:
            type: string
          description: Type of activity to filter
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          description: Start date for the query
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          description: End date for the query
        - name: download_status
          in: query
          schema:
            type: string
            enum: [pending, downloaded, failed]
          description: Download status to filter
      responses:
        '200':
          description: Array of activities matching the filter
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Activity'

  /api/health-data/summary:
    get:
      summary: Get health data summary
      description: Provides aggregated health statistics
      parameters:
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          description: Start date for the summary
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          description: End date for the summary
      responses:
        '200':
          description: Aggregated health statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_steps:
                    type: integer
                  avg_heart_rate:
                    type: number
                    format: float
                  total_sleep_hours:
                    type: number
                    format: float
                  avg_calories:
                    type: number
                    format: float

components:
  schemas:
    SyncLog:
      type: object
      properties:
        id:
          type: integer
        operation:
          type: string
          enum: [weight_sync, activity_archive, metrics_download]
        status:
          type: string
          enum: [started, in_progress, completed, failed]
        message:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        records_processed:
          type: integer
        records_failed:
          type: integer

    HealthMetric:
      type: object
      properties:
        id:
          type: integer
        metric_type:
          type: string
        metric_value:
          type: number
        unit:
          type: string
        timestamp:
          type: string
          format: date-time
        date:
          type: string
          format: date
        source:
          type: string
        detailed_data:
          type: object

    Activity:
      type: object
      properties:
        id:
          type: integer
        garmin_activity_id:
          type: string
        activity_name:
          type: string
        activity_type:
          type: string
        start_time:
          type: string
          format: date-time
        duration:
          type: integer
        file_path:
          type: string
        file_type:
          type: string
        download_status:
          type: string
          enum: [pending, downloaded, failed]
        downloaded_at:
          type: string
          format: date-time