{
  "openapi": "3.0.3",
  "info": {
    "title": "Panchal Driving API",
    "version": "1.0.0",
    "description": "Production API for the Panchal Driving MAUI app."
  },
  "servers": [
    {
      "url": "https://your-production-api.example.com",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-token"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Opaque session token"
      }
    },
    "schemas": {
      "AuthResponse": {
        "type": "object",
        "properties": {
          "sessionToken": { "type": "string" },
          "user": { "$ref": "#/components/schemas/User" }
        },
        "required": ["sessionToken", "user"]
      },
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "credits": { "type": "integer" },
          "settings": { "type": "string" },
          "role": { "type": "integer" },
          "reminderTimer": { "type": "integer" },
          "workingHours": { "type": "string" }
        },
        "required": ["id", "name", "credits", "settings", "role", "reminderTimer", "workingHours"]
      },
      "SyncMetadata": {
        "type": "object",
        "properties": {
          "actionId": { "type": "string" },
          "deviceId": { "type": "string" },
          "clientEditedAtUtc": { "type": "string", "format": "date-time" },
          "localId": { "type": "string" }
        },
        "required": ["actionId", "deviceId", "clientEditedAtUtc"]
      },
      "MutationResponse": {
        "type": "object",
        "properties": {
          "actionId": { "type": "string" },
          "status": { "type": "string", "enum": ["applied", "skipped"] },
          "serverId": { "type": "integer" },
          "cursor": { "type": "integer" },
          "reason": { "type": "string", "enum": ["stale_update"] }
        },
        "required": ["actionId", "status", "serverId", "cursor"]
      },
      "StudentWrite": {
        "allOf": [
          { "$ref": "#/components/schemas/SyncMetadata" },
          {
            "type": "object",
            "properties": {
              "title": { "type": "integer" },
              "firstName": { "type": "string" },
              "lastName": { "type": "string" },
              "email": { "type": "string" },
              "mobilePhone": { "type": "string" },
              "homePhone": { "type": "string" },
              "dateOfBirth": { "type": "string" },
              "archived": { "type": "boolean" },
              "pickUpAddress1": { "type": "string" },
              "pickUpAddress2": { "type": "string" },
              "pickUpTownCity": { "type": "string" },
              "pickUpCounty": { "type": "string" },
              "pickUpPostCode": { "type": "string" },
              "homeSameAsPickup": { "type": "boolean" },
              "homeAddress1": { "type": "string" },
              "homeAddress2": { "type": "string" },
              "homeTownCity": { "type": "string" },
              "homeCounty": { "type": "string" },
              "homePostCode": { "type": "string" },
              "licenceNumber": { "type": "string" },
              "deleted": { "type": "boolean" }
            },
            "required": ["firstName", "lastName"]
          }
        ]
      },
      "LessonWrite": {
        "allOf": [
          { "$ref": "#/components/schemas/SyncMetadata" },
          {
            "type": "object",
            "properties": {
              "type": { "type": "integer" },
              "start": { "type": "string", "format": "date-time" },
              "end": { "type": "string", "format": "date-time" },
              "student": { "type": "integer" },
              "reminder": { "type": "integer" },
              "deleted": { "type": "boolean" }
            },
            "required": ["type", "start", "end", "student", "reminder"]
          }
        ]
      },
      "TrackRecordWrite": {
        "allOf": [
          { "$ref": "#/components/schemas/SyncMetadata" },
          {
            "type": "object",
            "properties": {
              "rating": { "type": "integer" }
            },
            "required": ["rating"]
          }
        ]
      }
    }
  },
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/auth/login": {
      "post": {
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string" },
                  "password": { "type": "string" }
                },
                "required": ["email", "password"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Auth session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } },
          "401": { "description": "Invalid credentials" }
        }
      }
    },
    "/auth/logout": {
      "post": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Session revoked" },
          "401": { "description": "Invalid session token" }
        }
      }
    },
    "/user/me": {
      "get": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }
        }
      },
      "put": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "settings": { "type": "string" },
                  "reminderTimer": { "type": "integer" },
                  "workingHours": { "type": "string" }
                },
                "required": ["settings", "reminderTimer", "workingHours"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }
        }
      }
    },
    "/students": {
      "get": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "afterCursor", "in": "query", "description": "Delta cursor. When present, returns student changes after this cursor and ignores cursorSnapshot.", "schema": { "type": "integer" } },
          { "name": "pageSize", "in": "query", "description": "Full-sync page size. Ignored for delta pulls.", "schema": { "type": "integer" } },
          { "name": "pageAfterId", "in": "query", "description": "Full-sync pagination cursor by student ID. Ignored for delta pulls.", "schema": { "type": "integer" } },
          { "name": "cursorSnapshot", "in": "query", "description": "Full-sync snapshot cursor returned by the first full-sync page. Ignored when afterCursor is present.", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Student list" }
        }
      },
      "post": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/StudentWrite" }
            }
          }
        },
        "responses": {
          "200": { "description": "Mutation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } } }
        }
      }
    },
    "/students/{id}": {
      "put": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/StudentWrite" }
            }
          }
        },
        "responses": {
          "200": { "description": "Mutation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } } }
        }
      }
    },
    "/lessons": {
      "get": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "afterCursor", "in": "query", "description": "Delta cursor. When present, returns lesson changes after this cursor and ignores cursorSnapshot.", "schema": { "type": "integer" } },
          { "name": "pageSize", "in": "query", "description": "Full-sync page size. Ignored for delta pulls.", "schema": { "type": "integer" } },
          { "name": "pageAfterId", "in": "query", "description": "Full-sync pagination cursor by lesson ID. Ignored for delta pulls.", "schema": { "type": "integer" } },
          { "name": "cursorSnapshot", "in": "query", "description": "Full-sync snapshot cursor returned by the first full-sync page. Ignored when afterCursor is present.", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Lesson list" }
        }
      },
      "post": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LessonWrite" }
            }
          }
        },
        "responses": {
          "200": { "description": "Mutation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } } }
        }
      }
    },
    "/lessons/{id}": {
      "put": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LessonWrite" }
            }
          }
        },
        "responses": {
          "200": { "description": "Mutation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } } }
        }
      },
      "delete": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SyncMetadata" }
            }
          }
        },
        "responses": {
          "200": { "description": "Mutation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } } }
        }
      }
    },
    "/track-record": {
      "get": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "afterCursor", "in": "query", "description": "Delta cursor. When present, returns track record changes after this cursor and ignores cursorSnapshot.", "schema": { "type": "integer" } },
          { "name": "pageSize", "in": "query", "description": "Full-sync page size. Ignored for delta pulls.", "schema": { "type": "integer" } },
          { "name": "pageAfterId", "in": "query", "description": "Full-sync pagination cursor by track record ID. Ignored for delta pulls.", "schema": { "type": "integer" } },
          { "name": "cursorSnapshot", "in": "query", "description": "Full-sync snapshot cursor returned by the first full-sync page. Ignored when afterCursor is present.", "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Track record list" }
        }
      }
    },
    "/track-record/{studentId}/{skillId}": {
      "put": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "studentId", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "skillId", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TrackRecordWrite" }
            }
          }
        },
        "responses": {
          "200": { "description": "Mutation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } } }
        }
      }
    },
    "/skills": {
      "get": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "responses": { "200": { "description": "Skills list" } }
      }
    },
    "/invoices": {
      "get": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "responses": { "200": { "description": "Invoices list" } }
      }
    },
    "/students/{id}/messages": {
      "get": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "Message history" } }
      }
    },
    "/students/{id}/gdpr-send": {
      "post": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "GDPR message triggered" } }
      }
    },
    "/summary-email": {
      "post": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string" },
                  "htmlForEmail": { "type": "string" }
                },
                "required": ["email", "htmlForEmail"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Summary email sent" } }
      }
    },
    "/client-errors": {
      "post": {
        "security": [{ "ApiKeyAuth": [], "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": { "type": "string" },
                  "url": { "type": "string" },
                  "lineNumber": { "type": "integer" }
                },
                "required": ["message", "url", "lineNumber"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Client error logged" } }
      }
    }
  }
}