openapi: 3.1.0
info:
  title: CLAN Consent Adapter API
  version: 1.0.0
  description: API for Consent Events and Testimony Drafts for CLAN/ZHOS flow.
servers:
  - url: http://clan-consent-adapter:8111
security:
  - BearerAuth: []
tags:
  - name: health
  - name: consent
  - name: testimony
paths:
  /health:
    get:
      tags: [health]
      summary: Service health check
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /consent/events:
    post:
      tags: [consent]
      summary: Create consent event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConsentCreate"
      responses:
        "200":
          description: Consent event created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentCreateResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /consent/events/{event_id}:
    get:
      tags: [consent]
      summary: Get consent event by id
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Consent event
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsentEvent"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /testimony/drafts:
    post:
      tags: [testimony]
      summary: Create testimony draft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TestimonyDraftCreate"
      responses:
        "200":
          description: Testimony draft created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestimonyCreateResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /testimony/drafts/{testimony_id}:
    get:
      tags: [testimony]
      summary: Get testimony draft by id
      parameters:
        - name: testimony_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Testimony draft
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestimonyDraft"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  responses:
    BadRequest:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    VisibilityLevel:
      type: string
      enum: [public, interclan, incircle, soulsafe, sacred]
    HealthResponse:
      type: object
      required: [status, service]
      properties:
        status:
          type: string
          example: ok
        service:
          type: string
          example: clan-consent-adapter
    ErrorResponse:
      type: object
      required: [detail]
      properties:
        detail:
          oneOf:
            - type: string
            - type: object
    ConsentCreate:
      type: object
      required: [circle, subject]
      properties:
        circle:
          type: string
        subject:
          type: string
          description: decision/testimony/bridge/rights
        method:
          type: string
          default: live_presence
        signers:
          type: array
          items:
            type: string
          default: []
        caveats:
          type: string
          nullable: true
        visibility_level:
          $ref: "#/components/schemas/VisibilityLevel"
        provenance:
          type: object
          additionalProperties: true
    ConsentCreateResponse:
      type: object
      required: [consent_event_id, status, visibility_level]
      properties:
        consent_event_id:
          type: string
          format: uuid
        status:
          type: string
          example: confirmed
        visibility_level:
          $ref: "#/components/schemas/VisibilityLevel"
    ConsentEvent:
      type: object
      required:
        - id
        - circle
        - subject
        - method
        - signers
        - visibility_level
        - provenance
        - created_at
      properties:
        id:
          type: string
          format: uuid
        circle:
          type: string
        subject:
          type: string
        method:
          type: string
        signers:
          type: array
          items:
            type: string
        caveats:
          type: string
          nullable: true
        visibility_level:
          $ref: "#/components/schemas/VisibilityLevel"
        provenance:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    TestimonyDraftCreate:
      type: object
      required: [title, circle]
      properties:
        title:
          type: string
        circle:
          type: string
        visibility_level:
          $ref: "#/components/schemas/VisibilityLevel"
        content:
          type: object
          additionalProperties: true
        status:
          type: string
          enum: [draft, needs_confirmation, confirmed]
          default: draft
        provenance:
          type: object
          additionalProperties: true
        consent_event_id:
          type: string
          nullable: true
    TestimonyCreateResponse:
      type: object
      required: [testimony_id, status, visibility_level]
      properties:
        testimony_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [draft, needs_confirmation, confirmed]
        visibility_level:
          $ref: "#/components/schemas/VisibilityLevel"
    TestimonyDraft:
      type: object
      required:
        - id
        - title
        - circle
        - visibility_level
        - content
        - status
        - provenance
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        circle:
          type: string
        visibility_level:
          $ref: "#/components/schemas/VisibilityLevel"
        content:
          type: object
          additionalProperties: true
        status:
          type: string
          enum: [draft, needs_confirmation, confirmed]
        provenance:
          type: object
          additionalProperties: true
        consent_event_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time