อ้างอิงชนิดข้อมูลและข้อผิดพลาด

// สำเร็จ (HTTP 2xx)
interface ApiResponse<T> {
  statusCode: number; // เท่ากับ HTTP status เช่น 200
  data: T;
}

// ข้อผิดพลาดทั่วไป (HTTP 4xx / 5xx)
interface ApiError {
  statusCode: number;
  message: string;    // ข้อความภาษาอังกฤษที่ระบุสาเหตุ
  error?: string;     // ชื่อมาตรฐานของ HTTP status เช่น "Unauthorized" "Not Found"
}

// ข้อผิดพลาดการตรวจข้อมูลที่ส่งมา (HTTP 400)
interface ValidationError {
  statusCode: 400;
  message: "Validation failed";
  errors: {
    code: string;                 // เช่น "invalid_type" "too_small" "too_big"
    path: (string | number)[];    // ตำแหน่งของฟิลด์ที่ผิด เช่น ["players", 0, "uuid"]
    message: string;              // คำอธิบายของข้อผิดพลาดนั้น
    expected?: string;            // ชนิดที่คาดไว้ (บางกรณี)
  }[];
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "expected": "string", "code": "invalid_type", "path": ["players", 0, "uuid"], "message": "Invalid input: expected string, received undefined" }
  ]
}

/** UUID ของ Minecraft: 32 หลักฐานสิบหก ตัวพิมพ์เล็ก ไม่มีขีด (ขาออกเป็นรูปนี้เสมอ ขาเข้ารับมีขีดและตัวพิมพ์ใหญ่ได้) */
type MinecraftUuid = string;

/** เวลา ISO 8601 UTC เช่น "2026-10-06T08:30:00.000Z" */
type IsoDateTime = string;

/** ตัวระบุ Instance ที่ใช้ใน path (ฟิลด์ name ไม่ใช่ title) */
type InstanceName = string;

type ApplicationScope = "PLAYERS_READ" | "PLAYERS_WRITE"; // สิทธิ์ต่อ Instance
type AuthScope = "identify";                              // scope ของ Sign in with Minecraft
type PlayerStatus = "ACTIVE" | "PENDING" | "NOT_FOUND";

// ---- GET {Dashboard}/authorize (query string ของหน้าเว็บ)
interface AuthorizeQuery {
  client_id: string;
  redirect_uri?: string; // จำเป็นเมื่อ callbackType = REDIRECT ต้องตรงกับที่ลงทะเบียน
  scope?: string;        // ค่าเริ่มต้น "identify" คั่นด้วย ช่องว่าง , หรือ +
  state: string;         // 8..200 ตัวอักษร
}

// ---- ผลของ Redirect: query ที่เติมต่อท้าย redirect_uri
type OpenTabResult =
  | { code: string; state: string }                  // ผู้เล่นยืนยัน
  | { error: "access_denied"; state: string };       // ผู้เล่นปฏิเสธหรือยกเลิก

// ---- POST /api/v1/auth/token
interface TokenRequest {
  code: string; // 1..200 ตัวอักษร
}
type TokenResponse = ApiResponse<{
  state: string;
  scopes: AuthScope[];
  player: { uuid: MinecraftUuid; name: string };
}>;

// ---- Webhook (server เราส่งไปหาแอป)
interface AuthCompletedWebhook {
  event: "auth.completed";
  state: string;
  scopes: AuthScope[];
  player: { uuid: MinecraftUuid; name: string };
}
// headers: X-DMS-Timestamp (Unix วินาที เป็นสตริง), X-DMS-Signature ("sha256=" + hex)

// ---- GET /api/v1/instances
interface InstanceGrant {
  name: InstanceName;
  title: string;
  scopes: ApplicationScope[];
}
type ListInstancesResponse = ApiResponse<InstanceGrant[]>;

// ---- GET /api/v1/instances/{name}/players
interface InstancePlayer {
  uuid: MinecraftUuid | null;
  name: string | null;
  status: PlayerStatus;
  joinedAt: IsoDateTime;
}
type ListPlayersResponse = ApiResponse<InstancePlayer[]>;

// ---- PUT /api/v1/instances/{name}/players
interface PlayerInput {
  uuid: string;       // 1..64 ตัวอักษร ต้องอ่านเป็น UUID ได้
  username?: string;  // 0..32 ตัวอักษร คำใบ้แสดงผลเท่านั้น
}
interface PutPlayersRequest {
  players: PlayerInput[]; // 1..100
}
type PutPlayersResponse = ApiResponse<{
  added: number;
  pending: number;
  duplicates: number;
  invalid: string[];
}>;

// ---- DELETE /api/v1/instances/{name}/players  และ  /players/{uuid}
interface DeletePlayersRequest {
  players: { uuid: string }[]; // 1..100 (เฉพาะแบบมี body)
}
type DeletePlayersResponse = ApiResponse<{
  removed: number;
  notOnInstance: MinecraftUuid[];
  invalid: string[];
}>;