openapi: "3.1.0"
info:
  title: CRM Platform API
  version: "1.0.0"
  description: |
    Multi-tenant, white-label CRM SaaS REST API.

    ## Authentication
    - **SPA (Browser)**: Sanctum stateful cookie authentication via `/sanctum/csrf-cookie`
    - **Mobile/API**: Bearer token via `Authorization: Bearer <token>`

    ## Required Headers
    | Header | Type | Description |
    |--------|------|-------------|
    | `Authorization` | string | Bearer token (mobile/API mode) |
    | `Accept` | string | Must be `application/json` |
    | `X-Request-Id` | uuid | Unique request identifier |
    | `X-Business-Id` | uuid | Current business context |
    | `X-Client-Platform` | string | `web`, `ios`, `android`, `flutter`, `react-native` |
    | `X-App-Version` | string | Client application version |

  contact:
    name: CRM Platform Support

servers:
  - url: http://localhost:8000/api/v1
    description: Local development

security:
  - bearerAuth: []
  - cookieAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "Sanctum Personal Access Token"
    cookieAuth:
      type: apiKey
      in: cookie
      name: crm_session

  schemas:
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
        meta:
          $ref: '#/components/schemas/Meta'

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'

    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          enum:
            - UNAUTHENTICATED
            - INVALID_TOKEN
            - TOKEN_EXPIRED
            - FORBIDDEN
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - DUPLICATE_RECORD
            - INVALID_STATE_TRANSITION
            - PLAN_LIMIT_REACHED
            - FEATURE_NOT_AVAILABLE
            - SUBSCRIPTION_REQUIRED
            - BUSINESS_INACTIVE
            - RATE_LIMITED
            - FILE_TOO_LARGE
            - UNSUPPORTED_FILE_TYPE
            - PAYMENT_REQUIRED
            - PAYMENT_FAILED
            - WEBHOOK_INVALID
            - EXTERNAL_PROVIDER_ERROR
            - INTERNAL_ERROR
        message:
          type: string
        fields:
          type: object
          additionalProperties:
            type: array
            items:
              type: string

    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        pagination:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        perPage:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean

    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum: [healthy, degraded]
        checks:
          type: object
          properties:
            database:
              $ref: '#/components/schemas/ServiceCheck'
            cache:
              $ref: '#/components/schemas/ServiceCheck'
            storage:
              $ref: '#/components/schemas/ServiceCheck'
        timestamp:
          type: string
          format: date-time
        version:
          type: string

    ServiceCheck:
      type: object
      properties:
        healthy:
          type: boolean
        message:
          type: string

  responses:
    Unauthenticated:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

paths:
  /health:
    get:
      summary: System Health Check
      description: Returns the health status of all platform services.
      operationId: getHealth
      tags: [System]
      security: []
      responses:
        '200':
          description: System is healthy
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/HealthStatus'
        '503':
          description: System is degraded
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/HealthStatus'

tags:
  - name: System
    description: Platform system endpoints
  - name: Authentication
    description: Login, logout, token management
  - name: Businesses
    description: Business management and settings
  - name: Leads
    description: Lead management
  - name: Contacts
    description: Contact management
  - name: Companies
    description: Company management
  - name: Deals
    description: Deal and pipeline management
  - name: Tasks
    description: Task and activity management
  - name: Invoices
    description: Invoice and payment management
  - name: Finance
    description: Financial reporting
  - name: Automations
    description: Automation workflows
  - name: Branding
    description: White-label branding and theming
  - name: Subscriptions
    description: Plans, subscriptions, and billing
  - name: Admin
    description: Super Admin operations
