feat: Update spec, fix bugs, improve UI/UX, and clean up code

FitnessSync/specs/002-fitbit-garmin-sync/contracts/api-contract.yaml

@@ -0,0 +1,273 @@
+openapi: 3.0.0
+info:
+  title: Fitbit/Garmin Sync API
+  version: 1.0.0
+  description: API for synchronizing and retrieving fitness data from Garmin.
+
+paths:
+  /api/sync/activities:
+    post:
+      summary: Trigger Activity Sync
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                days_back:
+                  type: integer
+                  default: 7
+      responses:
+        '200':
+          description: Sync completed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SyncResponse'
+        '400':
+          description: Bad Request (e.g., Garmin not configured)
+        '500':
+          description: Internal Server Error
+
+  /api/sync/metrics:
+    post:
+      summary: Trigger Health Metrics Sync
+      responses:
+        '200':
+          description: Sync completed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SyncResponse'
+        '400':
+          description: Bad Request (e.g., Garmin not configured)
+        '500':
+          description: Internal Server Error
+
+  /api/activities/list:
+    get:
+      summary: List Activities
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 50
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
+      responses:
+        '200':
+          description: A list of activities
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ActivityResponse'
+
+  /api/activities/query:
+    get:
+      summary: Query Activities
+      parameters:
+        - name: activity_type
+          in: query
+          schema:
+            type: string
+        - name: start_date
+          in: query
+          schema:
+            type: string
+            format: date
+        - name: end_date
+          in: query
+          schema:
+            type: string
+            format: date
+        - name: download_status
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A list of activities
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ActivityResponse'
+
+  /api/activities/download/{activity_id}:
+    get:
+      summary: Download Activity File
+      parameters:
+        - name: activity_id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The activity file
+          content:
+            application/octet-stream: {}
+        '404':
+          description: Activity not found or file not downloaded
+
+  /api/metrics/list:
+    get:
+      summary: List Available Metrics
+      responses:
+        '200':
+          description: A list of available metric types and date ranges
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MetricsListResponse'
+
+  /api/metrics/query:
+    get:
+      summary: Query Health Metrics
+      parameters:
+        - name: metric_type
+          in: query
+          schema:
+            type: string
+        - name: start_date
+          in: query
+          schema:
+            type: string
+            format: date
+        - name: end_date
+          in: query
+          schema:
+            type: string
+            format: date
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 100
+      responses:
+        '200':
+          description: A list of health metrics
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/HealthMetricResponse'
+
+  /api/health-data/summary:
+    get:
+      summary: Get Health Data Summary
+      parameters:
+        - name: start_date
+          in: query
+          schema:
+            type: string
+            format: date
+        - name: end_date
+          in: query
+          schema:
+            type: string
+            format: date
+      responses:
+        '200':
+          description: A summary of health data
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthDataSummary'
+
+components:
+  schemas:
+    SyncResponse:
+      type: object
+      properties:
+        status:
+          type: string
+        message:
+          type: string
+        job_id:
+          type: string
+
+    ActivityResponse:
+      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_type:
+          type: string
+        download_status:
+          type: string
+        downloaded_at:
+          type: string
+          format: date-time
+
+    HealthMetricResponse:
+      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
+          nullable: true
+
+    MetricsListResponse:
+      type: object
+      properties:
+        metric_types:
+          type: array
+          items:
+            type: string
+        date_range:
+          type: object
+          properties:
+            start_date:
+              type: string
+              format: date
+            end_date:
+              type: string
+              format: date
+
+    HealthDataSummary:
+      type: object
+      properties:
+        total_steps:
+          type: integer
+        avg_heart_rate:
+          type: number
+        total_sleep_hours:
+          type: number
+        avg_calories:
+          type: number