openapi: 3.0.3
info:
  title: TenantPilot Admin - Directory Groups (v1)
  version: 0.1.0
  description: |
    Admin surfaces for tenant-scoped Entra groups cache (metadata only).
    Rendering uses cached data only; sync runs read the directory via app-only auth.

paths:
  /admin/tenants/{tenantId}/directory/groups:
    get:
      summary: List cached groups
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - in: query
          name: q
          schema: { type: string }
          description: Search by display name or ID
        - in: query
          name: stale
          schema: { type: boolean }
          description: Filter to stale groups only
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EntraGroup'

  /admin/tenants/{tenantId}/directory/groups/{entraGroupId}:
    get:
      summary: Get group details
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - in: path
          name: entraGroupId
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntraGroup'

  /admin/tenants/{tenantId}/directory/groups/sync:
    post:
      summary: Start a manual groups sync
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '202':
          description: Accepted (run created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntraGroupSyncRun'

  /admin/tenants/{tenantId}/directory/groups/runs:
    get:
      summary: List group sync runs
      parameters:
        - $ref: '#/components/parameters/TenantId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EntraGroupSyncRun'

  /admin/tenants/{tenantId}/directory/groups/runs/{runId}:
    get:
      summary: Get group sync run details
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - in: path
          name: runId
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntraGroupSyncRun'

components:
  parameters:
    TenantId:
      in: path
      name: tenantId
      required: true
      schema: { type: integer }

  schemas:
    EntraGroup:
      type: object
      required: [tenant_id, entra_group_id, display_name, last_seen_at]
      properties:
        tenant_id: { type: integer }
        entra_group_id: { type: string }
        display_name: { type: string }
        group_type: { type: string }
        security_enabled: { type: boolean, nullable: true }
        mail_enabled: { type: boolean, nullable: true }
        group_types:
          type: array
          items: { type: string }
        last_seen_at: { type: string, format: date-time }

    EntraGroupSyncRun:
      type: object
      required: [tenant_id, selection_key, status, created_at]
      properties:
        id: { type: integer }
        tenant_id: { type: integer }
        initiated_by_user_id: { type: integer, nullable: true }
        selection_key: { type: string }
        status: { type: string }
        started_at: { type: string, format: date-time, nullable: true }
        finished_at: { type: string, format: date-time, nullable: true }
        observed_count: { type: integer, nullable: true }
        upserted_count: { type: integer, nullable: true }
        error_count: { type: integer, nullable: true }
        error_category: { type: string, nullable: true }
        error_summary: { type: string, nullable: true }
        created_at: { type: string, format: date-time }