openapi: 3.0.3
info:
  title: Shoehorn Integrations API
  description: Integration management, webhooks, and sync operations.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  /integrations:
    get:
      summary: List integrations
      tags: [Integrations]
      responses:
        '200':
          description: List of configured integrations
          content:
            application/json:
              schema:
                type: object
                properties:
                  integrations:
                    type: array
                    items: { $ref: '#/components/schemas/Integration' }

    post:
      summary: Create integration
      tags: [Integrations]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateIntegrationRequest' }
      responses:
        '201':
          description: Integration created

  /integrations/configs:
    get:
      summary: List integration configurations
      description: Returns user-created integration configurations (as opposed to system integrations).
      tags: [Integrations]
      responses:
        '200':
          description: Integration configurations
          content:
            application/json:
              schema:
                type: object
                properties:
                  configs:
                    type: array
                    items: { $ref: '#/components/schemas/Integration' }

  /integrations/{id}:
    get:
      summary: Get integration details
      tags: [Integrations]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Integration details

    put:
      summary: Update integration
      tags: [Integrations]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateIntegrationRequest' }
      responses:
        '200':
          description: Integration updated

    delete:
      summary: Delete integration
      tags: [Integrations]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Integration deleted

  /integrations/{id}/sync:
    post:
      summary: Trigger manual sync
      description: Forces an immediate data pull from the integration source.
      tags: [Integrations]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Sync initiated

  /integrations/{id}/webhooks:
    get:
      summary: List webhooks for integration
      tags: [Webhooks]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Webhooks configured for this integration

    post:
      summary: Create webhook
      tags: [Webhooks]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateWebhookRequest' }
      responses:
        '201':
          description: Webhook created

  /integrations/webhooks/{webhookId}:
    put:
      summary: Update webhook
      tags: [Webhooks]
      parameters:
        - name: webhookId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateWebhookRequest' }
      responses:
        '200':
          description: Webhook updated

    delete:
      summary: Delete webhook
      tags: [Webhooks]
      parameters:
        - name: webhookId
          in: path
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Webhook deleted

  /integrations/github/webhook:
    post:
      summary: GitHub webhook receiver
      description: |
        Endpoint that receives GitHub webhook events. Verified using
        the webhook secret signature (X-Hub-Signature-256 header).
      tags: [Webhooks]
      responses:
        '200':
          description: Event processed

components:
  schemas:
    Integration:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        type: { type: string, enum: [github, gitlab, pagerduty, opsgenie, datadog, custom] }
        status: { type: string, enum: [active, inactive, error] }
        config: { type: object }
        last_sync: { type: string, format: date-time }
        created_at: { type: string, format: date-time }

    CreateIntegrationRequest:
      type: object
      required: [name, type, config]
      properties:
        name: { type: string }
        type: { type: string }
        config: { type: object }

    UpdateIntegrationRequest:
      type: object
      properties:
        name: { type: string }
        config: { type: object }
        status: { type: string }

    CreateWebhookRequest:
      type: object
      required: [url, events]
      properties:
        url: { type: string, format: uri }
        events: { type: array, items: { type: string } }
        secret: { type: string }

    UpdateWebhookRequest:
      type: object
      properties:
        url: { type: string, format: uri }
        events: { type: array, items: { type: string } }
        active: { type: boolean }
