openapi: 3.1.0
info:
  title: HOACraft API
  version: 2026-11-01
  summary: Field inspections for HOA management companies.
  description: |
    Draft contract. The webhook payloads (see `webhooks`) are produced by the
    HOACraft app today, in demo mode; `examples/` holds real output, kept in sync
    with the code by `test/handoff_test.dart`. The REST paths below are the
    planned server API and are not implemented yet.

    Letters, fines, vendor billing, ACC applications and homeowner communication
    stay in the management system. HOACraft sends what was found in the field:
    violations and re-checks, common-area work orders, and ACC site reviews.
servers:
  - url: https://sandbox.api.hoacraft.com/v1
    description: Sandbox (hc_test_ keys, fictional data)
  - url: https://api.hoacraft.com/v1
    description: Production (hc_live_ keys)
security:
  - apiKey: []

tags:
  - name: Import
    description: |
      Your system pushes communities and properties so inspectors drive with
      the right map, and so every payload carries your own ids.
  - name: Violations
    description: Read violations HOACraft recorded (the pull alternative to webhooks).
  - name: Work orders
    description: |
      Maintenance issues an inspector spots in the field, usually in common areas
      or where the association maintains the item. HOACraft sends each submitted
      work order to your system; drafts stay on the phone. Vendor billing and
      payment stay with you.
  - name: ACC
    description: |
      Architectural change requests. Homeowners apply through your portal; you
      push the requests that need a site visit, the inspector reviews them on the
      drive, and HOACraft sends the review back. A site review is a
      recommendation only. The committee decision is yours to record.
  - name: Drives
    description: |
      A drive is one inspector's pass through a community. Its summary is the
      inspection record: which homes were passed, which were skipped and why,
      and what was found.
  - name: Webhooks
    description: Manage webhook endpoints and replay events.

paths:
  /communities/{communityId}:
    put:
      tags: [Import]
      summary: Create or update a community
      parameters: [{ $ref: '#/components/parameters/communityId' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommunityInput' }
      responses:
        '200': { description: Updated, content: { application/json: { schema: { $ref: '#/components/schemas/Community' } } } }
        '201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/Community' } } } }
        '422': { $ref: '#/components/responses/Invalid' }

  /communities/{communityId}/properties:
    put:
      tags: [Import]
      summary: Bulk upsert properties (up to 1,000 per call)
      description: Rows are matched on `external_id`. Properties not in the call are left alone.
      parameters: [{ $ref: '#/components/parameters/communityId' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [properties]
              properties:
                properties:
                  type: array
                  maxItems: 1000
                  items: { $ref: '#/components/schemas/PropertyInput' }
      responses:
        '200': { $ref: '#/components/responses/BulkResult' }
        '422': { $ref: '#/components/responses/Invalid' }

  /communities/{communityId}/open-violations:
    put:
      tags: [Violations, Import]
      summary: Replace the set of violations your system considers open
      description: |
        Drives the "re-check due" list on the inspector's phone. Violations that
        HOACraft created and you omit here are marked resolved with resolution
        `closed_in_management_system` (no webhook is sent for that change).
      parameters: [{ $ref: '#/components/parameters/communityId' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [violations]
              properties:
                violations:
                  type: array
                  items: { $ref: '#/components/schemas/OpenViolationInput' }
      responses:
        '200': { $ref: '#/components/responses/BulkResult' }
        '422': { $ref: '#/components/responses/Invalid' }

  /violations:
    get:
      tags: [Violations]
      summary: List violations
      parameters:
        - { name: community_id, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [open, resolved] } }
        - name: updated_since
          in: query
          description: Only violations created, re-checked or resolved after this time.
          schema: { type: string, format: date-time }
        - { $ref: '#/components/parameters/cursor' }
        - { $ref: '#/components/parameters/limit' }
      responses:
        '200':
          description: A page of violations, oldest change first.
          content:
            application/json:
              schema:
                type: object
                required: [data, next_cursor]
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Violation' } }
                  next_cursor: { type: [string, 'null'] }

  /violations/{violationId}:
    get:
      tags: [Violations]
      summary: Get a violation
      parameters: [{ $ref: '#/components/parameters/violationId' }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Violation' } } } }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [Violations]
      summary: Update from your system (after a letter, or when you close it)
      parameters: [{ $ref: '#/components/parameters/violationId' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_id: { type: string, description: Your violation/case id. }
                stage: { type: string, description: 'Stage you are at, e.g. "First violation notice".' }
                cure_by: { type: string, format: date-time, description: Next re-check date. }
                status: { type: string, enum: [open, resolved] }
                resolution: { type: string, description: 'e.g. "Fine paid, closed".' }
      responses:
        '200': { description: Updated, content: { application/json: { schema: { $ref: '#/components/schemas/Violation' } } } }
        '404': { $ref: '#/components/responses/NotFound' }

  /work-orders:
    get:
      tags: [Work orders]
      summary: List work orders
      parameters:
        - { name: community_id, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { $ref: '#/components/schemas/WorkOrder/properties/status' } }
        - { name: updated_since, in: query, schema: { type: string, format: date-time } }
        - { $ref: '#/components/parameters/cursor' }
        - { $ref: '#/components/parameters/limit' }
      responses:
        '200':
          description: A page of work orders, oldest change first.
          content:
            application/json:
              schema:
                type: object
                required: [data, next_cursor]
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/WorkOrder' } }
                  next_cursor: { type: [string, 'null'] }

  /work-orders/{workOrderId}:
    get:
      tags: [Work orders]
      summary: Get a work order
      parameters: [{ $ref: '#/components/parameters/workOrderId' }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/WorkOrder' } } } }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [Work orders]
      summary: Update from your system (vendor assigned, work done, cancelled)
      description: |
        Use this when the vendor workflow runs in your system, so the inspector
        sees the current status and can check the work on the next drive. Status
        changes follow the same rules as the app: open → assigned → in_progress →
        completed, with cancel and reopen.
      parameters: [{ $ref: '#/components/parameters/workOrderId' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_id: { type: string, description: Your work order id. }
                status: { type: string, enum: [open, assigned, inProgress, completed, cancelled] }
                vendor_external_id: { type: [string, 'null'], description: Your vendor id. Imported vendors only. }
                due_date: { type: [string, 'null'], format: date-time }
                completion_notes: { type: string, description: Required when status is completed. }
      responses:
        '200': { description: Updated, content: { application/json: { schema: { $ref: '#/components/schemas/WorkOrder' } } } }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { description: The status change is not allowed from the current status., content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }

  /communities/{communityId}/acc-requests:
    put:
      tags: [ACC, Import]
      summary: Push ACC requests that need a site visit
      description: |
        Rows are matched on `external_id`. Each new request appears on the
        inspector's open-items drive until it has a site review. Requests you
        omit are left alone; close them with a decision instead.
      parameters: [{ $ref: '#/components/parameters/communityId' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [acc_requests]
              properties:
                acc_requests:
                  type: array
                  maxItems: 1000
                  items: { $ref: '#/components/schemas/AccRequestInput' }
      responses:
        '200': { $ref: '#/components/responses/BulkResult' }
        '422': { $ref: '#/components/responses/Invalid' }

  /acc-requests:
    get:
      tags: [ACC]
      summary: List ACC requests
      parameters:
        - { name: community_id, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { $ref: '#/components/schemas/AccRequest/properties/status' } }
        - { name: updated_since, in: query, schema: { type: string, format: date-time } }
        - { $ref: '#/components/parameters/cursor' }
        - { $ref: '#/components/parameters/limit' }
      responses:
        '200':
          description: A page of ACC requests, oldest change first.
          content:
            application/json:
              schema:
                type: object
                required: [data, next_cursor]
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/AccRequest' } }
                  next_cursor: { type: [string, 'null'] }

  /acc-requests/{accRequestId}:
    get:
      tags: [ACC]
      summary: Get an ACC request with its site reviews
      parameters: [{ $ref: '#/components/parameters/accRequestId' }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/AccRequest' } } } }
        '404': { $ref: '#/components/responses/NotFound' }

  /acc-requests/{accRequestId}/decision:
    post:
      tags: [ACC]
      summary: Record the committee decision
      description: |
        Closes the request in HOACraft and takes it off the drive. A decision
        can be recorded once. HOACraft never approves or denies on its own.
      parameters: [{ $ref: '#/components/parameters/accRequestId' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision, decided_at]
              properties:
                decision: { $ref: '#/components/schemas/AccDecision/properties/decision' }
                decided_at: { type: string, format: date-time }
                conditions: { type: string }
      responses:
        '200': { description: Recorded, content: { application/json: { schema: { $ref: '#/components/schemas/AccRequest' } } } }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { description: A decision is already recorded., content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }

  /drives:
    get:
      tags: [Drives]
      summary: List completed drives
      parameters:
        - { name: community_id, in: query, schema: { type: string } }
        - { name: since, in: query, schema: { type: string, format: date-time } }
        - { $ref: '#/components/parameters/cursor' }
        - { $ref: '#/components/parameters/limit' }
      responses:
        '200':
          description: A page of drives.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Drive' } }
                  next_cursor: { type: [string, 'null'] }

  /webhook-endpoints:
    get:
      tags: [Webhooks]
      summary: List endpoints
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/WebhookEndpoint' } }
    post:
      tags: [Webhooks]
      summary: Register an endpoint
      description: The signing secret is returned once, in this response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url: { type: string, format: uri, pattern: '^https://' }
                events:
                  type: array
                  description: Omit for all event types.
                  items: { $ref: '#/components/schemas/EventType' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/WebhookEndpoint' }
                  - type: object
                    properties:
                      secret: { type: string, example: whsec_… }

  /webhook-endpoints/{endpointId}/rotate-secret:
    post:
      tags: [Webhooks]
      summary: Rotate the signing secret
      description: The old secret keeps working for 24 hours so you can deploy the new one.
      parameters: [{ $ref: '#/components/parameters/endpointId' }]
      responses:
        '200':
          description: New secret
          content:
            application/json:
              schema: { type: object, properties: { secret: { type: string } } }

  /webhook-endpoints/{endpointId}/test:
    post:
      tags: [Webhooks]
      summary: Send a webhook.test event
      parameters: [{ $ref: '#/components/parameters/endpointId' }]
      responses:
        '202': { description: Queued }

  /events:
    get:
      tags: [Webhooks]
      summary: List or replay recent events (30 days)
      parameters:
        - { name: type, in: query, schema: { $ref: '#/components/schemas/EventType' } }
        - { name: since, in: query, schema: { type: string, format: date-time } }
        - name: delivery_status
          in: query
          schema: { type: string, enum: [delivered, failed, pending] }
        - { $ref: '#/components/parameters/cursor' }
      responses:
        '200':
          description: Events, same envelopes as the webhook bodies.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Event' } }
                  next_cursor: { type: [string, 'null'] }

webhooks:
  violation.created:
    post:
      summary: A violation was approved in the field
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/Event' }
                - type: object
                  properties:
                    type: { const: violation.created }
                    data:
                      type: object
                      required: [violation]
                      properties:
                        violation: { $ref: '#/components/schemas/Violation' }
      responses:
        '2XX': { description: Received. Anything else is retried. }
  violation.still_open:
    post:
      summary: A re-check after the cure date found the violation unfixed
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecheckEvent' }
      responses:
        '2XX': { description: Received. }
  violation.resolved:
    post:
      summary: A re-check found the violation fixed
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecheckEvent' }
      responses:
        '2XX': { description: Received. }
  work_order.created:
    post:
      summary: A work order was submitted in the field
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/Event' }
                - type: object
                  properties:
                    type: { const: work_order.created }
                    data:
                      type: object
                      required: [work_order]
                      properties:
                        work_order: { $ref: '#/components/schemas/WorkOrder' }
      responses:
        '2XX': { description: Received. }
  work_order.updated:
    post:
      summary: A work order changed status or vendor
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/Event' }
                - type: object
                  properties:
                    type: { const: work_order.updated }
                    data:
                      type: object
                      required: [work_order]
                      properties:
                        work_order: { $ref: '#/components/schemas/WorkOrder' }
                        previous_status: { $ref: '#/components/schemas/WorkOrder/properties/status' }
      responses:
        '2XX': { description: Received. }
  work_order.completed:
    post:
      summary: A work order was marked completed
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/Event' }
                - type: object
                  properties:
                    type: { const: work_order.completed }
                    data:
                      type: object
                      required: [work_order]
                      properties:
                        work_order: { $ref: '#/components/schemas/WorkOrder' }
      responses:
        '2XX': { description: Received. }
  acc_request.site_reviewed:
    post:
      summary: An inspector recorded an ACC site review (a recommendation, not a decision)
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/Event' }
                - type: object
                  properties:
                    type: { const: acc_request.site_reviewed }
                    data:
                      type: object
                      required: [acc_request, site_review]
                      properties:
                        acc_request: { $ref: '#/components/schemas/AccRequest' }
                        site_review: { $ref: '#/components/schemas/SiteReview' }
      responses:
        '2XX': { description: Received. }
  acc_request.decided:
    post:
      summary: A manager recorded the committee decision in HOACraft
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/Event' }
                - type: object
                  properties:
                    type: { const: acc_request.decided }
                    data:
                      type: object
                      required: [acc_request]
                      properties:
                        acc_request: { $ref: '#/components/schemas/AccRequest' }
      responses:
        '2XX': { description: Received. }
  drive.completed:
    post:
      summary: An inspector ended a drive
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/Event' }
                - type: object
                  properties:
                    type: { const: drive.completed }
                    data:
                      type: object
                      required: [drive]
                      properties:
                        drive: { $ref: '#/components/schemas/Drive' }
      responses:
        '2XX': { description: Received. }
  webhook.test:
    post:
      summary: Connectivity check
      parameters: [{ $ref: '#/components/parameters/signature' }]
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/Event' }
                - type: object
                  properties:
                    data: { type: object, properties: { message: { type: string } } }
      responses:
        '2XX': { description: Received. }

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: hc_test_… (sandbox) or hc_live_… (production) key.

  parameters:
    communityId: { name: communityId, in: path, required: true, schema: { type: string } }
    violationId: { name: violationId, in: path, required: true, schema: { type: string } }
    workOrderId: { name: workOrderId, in: path, required: true, schema: { type: string } }
    accRequestId: { name: accRequestId, in: path, required: true, schema: { type: string } }
    endpointId: { name: endpointId, in: path, required: true, schema: { type: string } }
    cursor: { name: cursor, in: query, schema: { type: string } }
    limit: { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 100 } }
    signature:
      name: HOACraft-Signature
      in: header
      required: true
      description: 't=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">'
      schema: { type: string }

  responses:
    Invalid:
      description: Validation failed
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Not found
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    BulkResult:
      description: Per-row outcome
      content:
        application/json:
          schema:
            type: object
            properties:
              created: { type: integer }
              updated: { type: integer }
              errors:
                type: array
                items:
                  type: object
                  properties:
                    index: { type: integer }
                    external_id: { type: string }
                    message: { type: string }

  schemas:
    EventType:
      type: string
      enum:
        - violation.created
        - violation.still_open
        - violation.resolved
        - work_order.created
        - work_order.updated
        - work_order.completed
        - acc_request.site_reviewed
        - acc_request.decided
        - drive.completed
        - webhook.test

    Event:
      type: object
      required: [id, type, api_version, created_at, community, data]
      properties:
        id: { type: string, description: Unique per event. Retries reuse it; dedupe on it. }
        type: { $ref: '#/components/schemas/EventType' }
        api_version: { type: string, example: '2026-11-01' }
        created_at: { type: string, format: date-time }
        community:
          type: object
          required: [id, name]
          properties:
            id: { type: string }
            name: { type: string }
        data: { type: object }

    RecheckEvent:
      allOf:
        - { $ref: '#/components/schemas/Event' }
        - type: object
          properties:
            data:
              type: object
              required: [violation, recheck]
              properties:
                violation: { $ref: '#/components/schemas/Violation' }
                recheck: { $ref: '#/components/schemas/Recheck' }

    Person:
      type: object
      required: [id, name]
      properties:
        id: { type: string }
        name: { type: string }

    Location:
      type: object
      required: [kind, id, address]
      properties:
        kind: { type: string, enum: [property, common_area] }
        id: { type: string, description: HOACraft id. }
        external_id: { type: string, description: Your id, present once properties are imported via the API. }
        lot_number: { type: string, description: Properties only. }
        address: { type: string, description: Street address, or the common area's name. }
        geo:
          type: object
          properties:
            lat: { type: number }
            lng: { type: number }

    Photo:
      type: object
      required: [id, url, taken_at]
      properties:
        id: { type: string }
        url: { type: string, format: uri, description: Signed link, valid for 7 days. Fetch and store it if you need it longer. }
        taken_at: { type: string, format: date-time }
        demo: { type: boolean, description: True for bundled sample photos (demo and sandbox only). }

    Recheck:
      type: object
      required: [at, by, result]
      properties:
        at: { type: string, format: date-time }
        by: { $ref: '#/components/schemas/Person' }
        result: { type: string, enum: [fixed, still_open] }
        note: { type: string }
        photos: { type: array, items: { $ref: '#/components/schemas/Photo' } }

    Violation:
      type: object
      required: [id, status, location, issue_type, title, observed_at, rechecks]
      properties:
        id: { type: string }
        status: { type: string, enum: [open, resolved] }
        location: { $ref: '#/components/schemas/Location' }
        issue_type:
          type: string
          enum: [landscaping, trash, exteriorMaintenance, fence, parking, unapprovedChange, signage, commonAreaDamage, other]
        title: { type: string }
        description: { type: string }
        level: { type: [integer, 'null'], description: '1 = first offence of this issue type at this location.' }
        suggested_stage: { type: [string, 'null'], description: Advisory, from the community's notice ladder. Your system owns the real stage. }
        cure_by: { type: [string, 'null'], format: date-time, description: Next re-check date. }
        rules: { type: array, items: { $ref: '#/components/schemas/Rule' } }
        photos: { type: array, items: { $ref: '#/components/schemas/Photo' } }
        observed_at: { type: string, format: date-time }
        observed_by: { $ref: '#/components/schemas/Person' }
        approved_at: { type: [string, 'null'], format: date-time }
        approved_by: { oneOf: [{ $ref: '#/components/schemas/Person' }, { type: 'null' }] }
        session_id: { type: [string, 'null'], description: The drive it was found on. }
        ai_assisted: { type: boolean, description: An AI suggestion was reviewed and approved by a person. }
        ai_confidence: { type: [number, 'null'] }
        rechecks: { type: array, items: { $ref: '#/components/schemas/Recheck' } }
        resolved_at: { type: [string, 'null'], format: date-time }
        resolution: { type: [string, 'null'] }

    Rule:
      type: object
      properties:
        id: { type: string }
        document: { type: string, example: CC&Rs }
        section: { type: string, example: '7.1' }
        title: { type: string }

    WorkOrder:
      type: object
      required: [id, number, status, location, title, category, priority, created_at, created_by]
      properties:
        id: { type: string }
        number: { type: integer, description: Per-community number shown to staff, e.g. 101. }
        status: { type: string, enum: [open, assigned, inProgress, completed, cancelled] }
        location: { $ref: '#/components/schemas/Location' }
        title: { type: string }
        category:
          type: string
          enum: [landscaping, irrigation, lighting, poolAmenity, fencingGates, signage, drainage, pavement, general]
        priority: { type: string, enum: [low, normal, high, urgent] }
        description: { type: string }
        vendor:
          oneOf:
            - type: object
              properties:
                id: { type: string }
                name: { type: string }
            - { type: 'null' }
        due_date: { type: [string, 'null'], format: date-time }
        follow_up_date: { type: [string, 'null'], format: date-time, description: When the inspector plans to check it again. }
        photos: { type: array, items: { $ref: '#/components/schemas/Photo' } }
        created_at: { type: string, format: date-time }
        created_by: { $ref: '#/components/schemas/Person' }
        ai_assisted: { type: boolean, description: The description was drafted with AI and reviewed by the creator. }
        completed_at: { type: [string, 'null'], format: date-time }
        completion_notes: { type: [string, 'null'] }

    SiteReview:
      type: object
      required: [id, at, by, outcome]
      properties:
        id: { type: string }
        at: { type: string, format: date-time }
        by: { $ref: '#/components/schemas/Person' }
        outcome:
          type: string
          enum: [reviewed, moreInfoNeeded, recommendApproval, recommendDenial]
          description: The inspector's recommendation. Advisory only.
        observations: { type: string }
        measurements: { type: string }
        rules: { type: array, items: { $ref: '#/components/schemas/Rule' }, description: Rules the reviewer checked against. }
        photos: { type: array, items: { $ref: '#/components/schemas/Photo' } }
        session_id: { type: [string, 'null'], description: The drive it was done on. }

    AccDecision:
      type: object
      required: [decision, decided_at]
      properties:
        decision: { type: string, enum: [approved, approvedWithConditions, denied] }
        decided_at: { type: string, format: date-time }
        recorded_by: { $ref: '#/components/schemas/Person' }
        conditions: { type: string }

    AccRequest:
      type: object
      required: [id, number, status, location, request_type, title, site_reviews]
      properties:
        id: { type: string }
        number: { type: integer }
        status:
          type: string
          enum: [submitted, siteReviewPending, siteReviewed, infoRequested, approved, approvedWithConditions, denied]
        location: { $ref: '#/components/schemas/Location' }
        request_type: { type: string, enum: [fence, exteriorPaint, shed, landscaping, solar, patio, roof] }
        title: { type: string }
        description: { type: string }
        applicant_name: { type: string }
        requested_at: { type: string, format: date-time }
        documents:
          type: array
          description: Names of the files attached to the application. The files stay in your system.
          items:
            type: object
            properties:
              name: { type: string }
              kind: { type: string, enum: [plan, colorSample, survey, quote, photo] }
        site_reviews: { type: array, items: { $ref: '#/components/schemas/SiteReview' } }
        decision: { oneOf: [{ $ref: '#/components/schemas/AccDecision' }, { type: 'null' }] }

    AccRequestInput:
      type: object
      required: [external_id, property_external_id, request_type, title]
      properties:
        external_id: { type: string, description: Your application id. }
        property_external_id: { type: string }
        request_type: { $ref: '#/components/schemas/AccRequest/properties/request_type' }
        title: { type: string }
        description: { type: string, description: What the homeowner wants to change. Shown to the inspector. }
        applicant_name: { type: string }
        requested_at: { type: string, format: date-time }
        review_by: { type: string, format: date-time, description: Deadline from the community's ACC window. }
        documents:
          type: array
          items:
            type: object
            required: [name, kind]
            properties:
              name: { type: string }
              kind: { $ref: '#/components/schemas/AccRequest/properties/documents/items/properties/kind' }
              url: { type: string, format: uri, description: Optional link the inspector can open. }

    Drive:
      type: object
      required: [id, started_at, inspector, stops]
      properties:
        id: { type: string }
        title: { type: string }
        started_at: { type: string, format: date-time }
        ended_at: { type: [string, 'null'], format: date-time }
        inspector: { $ref: '#/components/schemas/Person' }
        stops:
          type: object
          properties:
            total: { type: integer }
            completed: { type: integer }
            skipped:
              type: array
              items:
                type: object
                properties:
                  address: { type: string }
                  reason: { type: string }
        violations_created: { type: array, items: { type: string } }
        rechecks:
          type: array
          items:
            type: object
            properties:
              violation_id: { type: string }
              result: { type: string, enum: [fixed, still_open] }

    CommunityInput:
      type: object
      required: [name]
      properties:
        name: { type: string }
        city: { type: string }
        state: { type: string }
        cure_days: { type: integer, description: Default days to cure before re-check. }
        notice_stages: { type: array, items: { type: string }, example: [Courtesy notice, First violation notice, Final notice before fine] }

    Community:
      allOf:
        - { $ref: '#/components/schemas/CommunityInput' }
        - type: object
          properties:
            id: { type: string }

    PropertyInput:
      type: object
      required: [external_id, address]
      properties:
        external_id: { type: string, description: Your account or unit id. }
        lot_number: { type: string }
        address: { type: string }
        occupied: { type: boolean }
        owner_name: { type: string, description: Shown to inspectors on the phone. Optional. }
        lat: { type: number }
        lng: { type: number }

    OpenViolationInput:
      type: object
      required: [external_id, property_external_id, issue_type, title]
      properties:
        external_id: { type: string }
        hoacraft_id: { type: string, description: Set when the violation came from HOACraft. }
        property_external_id: { type: string }
        issue_type: { $ref: '#/components/schemas/Violation/properties/issue_type' }
        title: { type: string }
        stage: { type: string }
        level: { type: integer }
        cure_by: { type: string, format: date-time }
        last_notice_at: { type: string, format: date-time }

    WebhookEndpoint:
      type: object
      properties:
        id: { type: string }
        url: { type: string, format: uri }
        events: { type: array, items: { $ref: '#/components/schemas/EventType' } }
        enabled: { type: boolean }
        created_at: { type: string, format: date-time }

    Error:
      type: object
      required: [code, message]
      properties:
        code: { type: string }
        message: { type: string }
        details: { type: object }
