openapi: 3.1.0
info:
  title: Subject home overview
  version: 0.99.24
paths:
  /api/v1/subjects/{id}/home-overview:
    get:
      operationId: subjectHomeOverview
      summary: Current calendar week and latest finished conversation
      description: >-
        Read-only, subject-scoped metadata independent of conversation-list pagination or filters.
        Week boundaries use the subject timezone, Monday inclusive to next Monday exclusive.
        Entire duration belongs to the session start date, including midnight/week crossings.
        Legacy sessions require started_at and ended_at; DIRECT sessions require ended_at and
        a valid finalized USER or ASSISTANT utterance. Interrupted sessions with this evidence count;
        preparation failures, active sessions, future end times, and deleted sources do not count.
        DIRECT duration is created_at to ended_at, because no reliable connected_at is stored.
        Latest conversation is independent of the week and never replaced with an older recap.
        Metadata requires household conversation-read access; recap additionally requires the
        independent memory grant, current storage consent, and applicable privacy fencing.
        Legacy unclassified summaries require sensitive access. DIRECT recap is an existing
        active normal memory from that exact session, not a newly synthesized full summary.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: Home overview; no-store
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {$ref: '#/components/schemas/HomeOverview'}
        '400': {description: Invalid subject ID or unsupported query parameters}
        '401': {description: Authentication required}
        '403': {description: Subject metadata access denied}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer}
  schemas:
    HomeOverview:
      type: object
      required: [subject_id, timezone, week_start, week_end, conversation_count, total_duration_ms, daily, latest_conversation]
      properties:
        subject_id: {type: string, format: uuid}
        timezone: {type: string, example: Asia/Shanghai}
        week_start: {type: string, format: date}
        week_end: {type: string, format: date, description: Exclusive next Monday}
        conversation_count: {type: integer, minimum: 0}
        total_duration_ms: {type: integer, format: int64, minimum: 0}
        daily:
          type: array
          minItems: 7
          maxItems: 7
          items:
            type: object
            required: [date, conversation_count, duration_ms]
            properties:
              date: {type: string, format: date}
              conversation_count: {type: integer, minimum: 0}
              duration_ms: {type: integer, format: int64, minimum: 0}
        latest_conversation:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/HomeConversation'
    HomeConversation:
      type: object
      required: [id, source, status, started_at, ended_at, duration_ms, summary_state]
      properties:
        id: {type: string, format: uuid}
        source: {type: string, enum: [conversation, call_memory]}
        status: {type: string, description: Original terminal status, including FAILED for an interrupted actual conversation}
        started_at: {type: string, format: date-time}
        ended_at: {type: string, format: date-time}
        duration_ms: {type: integer, format: int64, minimum: 0}
        summary: {type: string, description: Only present when authorized and READY}
        summary_kind: {type: string, enum: [conversation_summary, memory]}
        summary_state:
          type: string
          enum: [READY, PROCESSING, INSUFFICIENT_TRANSCRIPT, NO_SUMMARY, SYNC_FAILED, UNAVAILABLE]
          description: UNAVAILABLE covers access, storage consent, or privacy restrictions without revealing hidden content.