{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.wikiup.app/staff-responses.schema.json",
  "title": "Wikiup staff response contracts",
  "description": "Staff-only and guest-session contracts. These fields are not available to affiliate API keys. Synthetic examples are documentation, not guest records.",
  "$defs": {
    "TimelineChange": {
      "type": "object",
      "description": "One user-visible change.",
      "properties": {
        "type": {
          "type": "string",
          "description": "Display label for the kind of change; not a fixed enum."
        },
        "description": {
          "type": "string",
          "description": "Human-readable before/after description."
        },
        "financial": {
          "type": "boolean",
          "description": "True for financial changes; these are omitted without financial visibility permission."
        }
      },
      "required": [
        "type",
        "description"
      ],
      "additionalProperties": false
    },
    "TimelineEntry": {
      "type": "object",
      "description": "Reservation audit event.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable event identifier."
        },
        "date": {
          "type": "string",
          "description": "Event timestamp; display in the property time zone."
        },
        "actor": {
          "type": "object",
          "description": "Attributed actor.",
          "properties": {
            "type": {
              "type": "string",
              "description": "Actor category.",
              "enum": [
                "guest",
                "staff",
                "system"
              ]
            },
            "name": {
              "type": "string",
              "description": "Display name at the time of the event."
            }
          },
          "required": [
            "type",
            "name"
          ],
          "additionalProperties": false
        },
        "changes": {
          "type": "array",
          "description": "Visible changes after permission redaction.",
          "items": {
            "$ref": "#/$defs/TimelineChange"
          }
        }
      },
      "required": [
        "id",
        "date",
        "actor",
        "changes"
      ],
      "additionalProperties": false
    },
    "TimelineResponse": {
      "type": "object",
      "description": "Newest reservation changes first.",
      "properties": {
        "entries": {
          "type": "array",
          "description": "Page of events; empty if no visible changes remain.",
          "items": {
            "$ref": "#/$defs/TimelineEntry"
          }
        },
        "nextCursor": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque before cursor for the next page; null at the end."
        }
      },
      "required": [
        "entries",
        "nextCursor"
      ],
      "additionalProperties": false
    },
    "ChatMessage": {
      "type": "object",
      "description": "Email message projected by the messaging service.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Provider message identifier."
        },
        "text": {
          "type": "string",
          "description": "Plain-text content, or a snippet when format=metadata."
        },
        "html": {
          "type": "string",
          "description": "Rendered-source HTML when available with format=full. Sanitize/isolate before rendering; absent for metadata."
        },
        "sender": {
          "type": "string",
          "description": "me is the property mailbox; guest is the other participant.",
          "enum": [
            "me",
            "guest"
          ]
        },
        "date": {
          "type": "string",
          "description": "Original email Date header; includes an offset and may be RFC 2822 rather than ISO 8601. Display in the property time zone."
        },
        "from": {
          "type": "string",
          "description": "From header; may contain display name and email."
        },
        "to": {
          "type": "string",
          "description": "To header."
        },
        "replyTo": {
          "type": "string",
          "description": "Reply-To header; may be empty."
        },
        "unread": {
          "type": "boolean",
          "description": "Whether the provider marks the message unread."
        },
        "subject": {
          "type": "string",
          "description": "Email subject."
        },
        "threadId": {
          "type": "string",
          "description": "Provider thread ID when included."
        },
        "isDraft": {
          "type": "boolean",
          "description": "Whether this provider record is a draft."
        },
        "draftId": {
          "type": "string",
          "description": "Draft identifier when resolved."
        }
      },
      "required": [
        "id",
        "text",
        "sender",
        "date",
        "from",
        "unread",
        "subject"
      ],
      "additionalProperties": false
    },
    "MessagesResponse": {
      "type": "object",
      "description": "Mailbox page.",
      "properties": {
        "messages": {
          "type": "array",
          "description": "Messages returned by the requested provider mode.",
          "items": {
            "$ref": "#/$defs/ChatMessage"
          }
        },
        "nextPageToken": {
          "type": "string",
          "description": "Opaque provider page token. Omitted when unavailable, including recent=true."
        }
      },
      "required": [
        "messages"
      ],
      "additionalProperties": false
    },
    "GuestMessagesResponse": {
      "type": "object",
      "description": "Reservation-scoped guest conversation.",
      "properties": {
        "propertyEmail": {
          "type": "string",
          "description": "Property mailbox address."
        },
        "guestEmail": {
          "type": "string",
          "description": "Guest participant address."
        },
        "messages": {
          "type": "array",
          "description": "Participant-filtered messages sorted oldest first.",
          "items": {
            "$ref": "#/$defs/ChatMessage"
          }
        }
      },
      "required": [
        "propertyEmail",
        "guestEmail",
        "messages"
      ],
      "additionalProperties": false
    },
    "GuestQuestion": {
      "type": "object",
      "description": "Private property knowledge review record.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Question identifier."
        },
        "propertyId": {
          "type": "string",
          "description": "Owning property identifier."
        },
        "question": {
          "type": "string",
          "description": "Question text."
        },
        "answer": {
          "type": "string",
          "description": "Proposed or reviewed answer text."
        },
        "status": {
          "type": "string",
          "description": "Review outcome.",
          "enum": [
            "pending",
            "approved",
            "rejected"
          ]
        },
        "sourceConversationId": {
          "type": "string",
          "description": "Origin conversation identifier; staff-only."
        },
        "sourceMessageId": {
          "type": "string",
          "description": "Origin message identifier; staff-only."
        },
        "createdAt": {
          "type": "string",
          "description": "Creation timestamp."
        },
        "updatedAt": {
          "type": "string",
          "description": "Last change timestamp."
        },
        "publicReviewVersion": {
          "type": [
            "string",
            "null"
          ],
          "description": "Review disclosure version accepted by staff, or null/unset before review."
        }
      },
      "required": [
        "id",
        "propertyId",
        "question",
        "answer",
        "status",
        "sourceConversationId",
        "sourceMessageId",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    },
    "QuestionsResponse": {
      "type": "object",
      "description": "Property knowledge review page.",
      "properties": {
        "questions": {
          "type": "array",
          "description": "Review records matching status filter.",
          "items": {
            "$ref": "#/$defs/GuestQuestion"
          }
        },
        "nextPage": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque Onyx page token; null at the end."
        }
      },
      "required": [
        "questions",
        "nextPage"
      ],
      "additionalProperties": false
    },
    "Reading": {
      "type": "object",
      "description": "Recorded equipment measurement.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Saved reading ID."
        },
        "propertyId": {
          "type": "string",
          "description": "Owning property ID."
        },
        "kind": {
          "type": "string",
          "description": "Equipment category.",
          "enum": [
            "boiler",
            "utility_meter",
            "pool_chemical"
          ]
        },
        "metric": {
          "type": "string",
          "description": "Measurement name, e.g. pH."
        },
        "value": {
          "type": "number",
          "description": "Measured numeric value; negative values are permitted when meaningful."
        },
        "unit": {
          "type": "string",
          "description": "Unit label, e.g. pH or psi."
        },
        "location": {
          "type": [
            "string",
            "null"
          ],
          "description": "Equipment location; null when unset."
        },
        "notes": {
          "type": [
            "string",
            "null"
          ],
          "description": "Staff notes; null when unset."
        },
        "recordedAt": {
          "type": "string",
          "description": "Measurement timestamp, not necessarily insertion time."
        },
        "recordedByUid": {
          "type": "string",
          "description": "Staff account that recorded the reading."
        }
      },
      "required": [
        "propertyId",
        "kind",
        "metric",
        "value",
        "unit",
        "recordedAt",
        "recordedByUid"
      ],
      "additionalProperties": false
    },
    "ReadingsResponse": {
      "type": "object",
      "description": "Property equipment log.",
      "properties": {
        "readings": {
          "type": "array",
          "description": "All matching readings sorted newest measurement first. No pagination token.",
          "items": {
            "$ref": "#/$defs/Reading"
          }
        }
      },
      "required": [
        "readings"
      ],
      "additionalProperties": false
    },
    "ReadingResponse": {
      "type": "object",
      "description": "Created reading.",
      "properties": {
        "reading": {
          "$ref": "#/$defs/Reading",
          "description": "Saved measurement."
        }
      },
      "required": [
        "reading"
      ],
      "additionalProperties": false
    },
    "UnpaidBalance": {
      "type": "object",
      "description": "Unpaid reservation invoice summary; requires invoice access.",
      "properties": {
        "reservationId": {
          "type": "string",
          "description": "Reservation identifier."
        },
        "confirmationNumber": {
          "type": [
            "string",
            "null"
          ],
          "description": "Guest confirmation number; null if unavailable."
        },
        "guestName": {
          "type": "string",
          "description": "Guest display name."
        },
        "guestEmail": {
          "type": [
            "string",
            "null"
          ],
          "description": "Guest email; null if unavailable."
        },
        "checkIn": {
          "type": "string",
          "description": "Reservation check-in timestamp."
        },
        "checkOut": {
          "type": "string",
          "description": "Reservation checkout timestamp."
        },
        "status": {
          "type": [
            "string",
            "null"
          ],
          "description": "Persisted reservation status; null if unset."
        },
        "roomName": {
          "type": [
            "string",
            "null"
          ],
          "description": "Room display name; null if missing."
        },
        "balanceDue": {
          "type": "number",
          "description": "Remaining amount due, in currency major units."
        },
        "totalDue": {
          "type": "number",
          "description": "Invoice total due, in currency major units."
        },
        "totalPaid": {
          "type": "number",
          "description": "Collected payment total used for the balance calculation, in currency major units."
        },
        "currency": {
          "type": "string",
          "description": "Currency code."
        },
        "lastPaymentLinkRecipientEmail": {
          "type": [
            "string",
            "null"
          ],
          "description": "Most recent payment-link recipient; null if none."
        }
      },
      "required": [
        "reservationId",
        "confirmationNumber",
        "guestName",
        "guestEmail",
        "checkIn",
        "checkOut",
        "status",
        "roomName",
        "balanceDue",
        "totalDue",
        "totalPaid",
        "currency",
        "lastPaymentLinkRecipientEmail"
      ],
      "additionalProperties": false
    },
    "UnpaidResponse": {
      "type": "object",
      "description": "Unpaid balances.",
      "properties": {
        "items": {
          "type": "array",
          "description": "Reservations with a positive balance.",
          "items": {
            "$ref": "#/$defs/UnpaidBalance"
          }
        }
      },
      "required": [
        "items"
      ],
      "additionalProperties": false
    }
  }
}
