//! The HTTP wire contract of filebrowser-ng in one place.
//!
//! Both the server (axum) and the web frontend (wasm `fetch`) import these
//! endpoint paths, query params and serde types, so the two sides cannot
//! drift apart. Serde only — no axum, no wasm dependencies.

use serde::{Deserialize, Serialize};

// ---------------------------------------------------------------------------
// Endpoint paths (single source of truth for the route table and the client)
// ---------------------------------------------------------------------------

pub const AUTH_LOGIN: &str = "/api/auth/login";
pub const AUTH_LOGOUT: &str = "/api/auth/logout";
pub const AUTH_ME: &str = "/api/auth/me";
pub const AUTH_SETUP: &str = "/api/auth/setup";
/// Change or set the signed-in user's password (`POST`), or remove it
/// (`DELETE`, passkey-only accounts).
pub const AUTH_PASSWORD: &str = "/api/auth/password";
/// `PUT` the signed-in user's sign-in requirement ([`AuthMode`]).
pub const AUTH_MODE: &str = "/api/auth/mode";
/// The signed-in user's passkeys: `GET {AUTH_PASSKEYS}` lists them,
/// `DELETE {AUTH_PASSKEYS}/{id}` removes one.
pub const AUTH_PASSKEYS: &str = "/api/auth/passkeys";
/// Start registering a new passkey (`POST`). Finished at
/// `{AUTH_PASSKEYS_REGISTER}{FINISH_SUFFIX}`.
pub const AUTH_PASSKEYS_REGISTER: &str = "/api/auth/passkeys/register";
/// Start a passkey sign-in (`POST`, no session needed). Finished at
/// `{AUTH_PASSKEY_LOGIN}{FINISH_SUFFIX}`.
pub const AUTH_PASSKEY_LOGIN: &str = "/api/auth/passkey/login";
/// The signed-in user's WebDAV app passwords: `GET {AUTH_APP_PASSWORDS}`
/// lists them, `POST` creates one, `DELETE {AUTH_APP_PASSWORDS}/{id}` revokes
/// one.
pub const AUTH_APP_PASSWORDS: &str = "/api/auth/app-passwords";
/// Second leg of both WebAuthn ceremonies: the browser's answer goes to the
/// begin path plus this suffix.
pub const FINISH_SUFFIX: &str = "/finish";
/// File operations: `{FILES}/{root_id}` and `{FILES}/{root_id}/{path...}`.
pub const FILES: &str = "/api/files";
/// Share management (authenticated): `{SHARES}` and `{SHARES}/{id}`.
pub const SHARES: &str = "/api/shares";
/// Public share resolve (no login): `{SHARE}/{token}`.
pub const SHARE: &str = "/api/share";
/// Suffix on `{SHARE}/{token}`: submit the password of a protected share.
pub const SHARE_UNLOCK_SUFFIX: &str = "/unlock";
/// `GET /api/search` — name and/or content search, streamed as SSE.
pub const SEARCH: &str = "/api/search";

/// WebDAV mount of the signed-in user's roots: `{DAV}` and `{DAV}/{path...}`.
pub const DAV: &str = "/dav";
/// WebDAV mount of one public share: `{DAV_SHARE}/{token}/{path...}`.
///
/// A separate top-level path, not a segment under [`DAV`]: there, the first
/// segment is a root's display name, which a reserved word could collide with.
pub const DAV_SHARE: &str = "/dav-share";

/// CalDAV and CardDAV: principals, calendars and address books.
///
/// Not under [`DAV`] for the same reason as [`DAV_SHARE`].
pub const PIM: &str = "/pim";
/// RFC 6764 discovery. Both redirect to [`PIM`].
pub const WELL_KNOWN_CALDAV: &str = "/.well-known/caldav";
pub const WELL_KNOWN_CARDDAV: &str = "/.well-known/carddav";

/// Admin user management: `{ADMIN_USERS}` and `{ADMIN_USERS}/{id}`.
pub const ADMIN_USERS: &str = "/api/admin/users";
/// Admin view of every share on the server: `{ADMIN_SHARES}` and
/// `{ADMIN_SHARES}/{id}`. [`SHARES`] is the same data scoped to the caller.
pub const ADMIN_SHARES: &str = "/api/admin/shares";
pub const ADMIN_SETTINGS: &str = "/api/admin/settings";
/// Admin management of rooms and resources: `{ADMIN_ROOMS}` and
/// `{ADMIN_ROOMS}/{id}`.
pub const ADMIN_ROOMS: &str = "/api/admin/rooms";
/// Admin view of every public calendar and address book feed:
/// `{ADMIN_PIM_LINKS}` and `{ADMIN_PIM_LINKS}/{id}`.
pub const ADMIN_PIM_LINKS: &str = "/api/admin/pim-links";
/// The signed-in user's calendars and address books, own and lent to them
/// (`GET`). `{PIM_COLLECTIONS}/{id}{SHARES_SUFFIX}` lists (`GET`) and lends
/// (`POST`) an own one; `DELETE` on `.../{user_id}` below it ends a loan.
pub const PIM_COLLECTIONS: &str = "/api/pim/collections";
pub const SHARES_SUFFIX: &str = "/shares";
/// `{PIM_COLLECTIONS}/{id}{LINKS_SUFFIX}`: the public feeds of an own
/// collection (`GET`, `POST`); `DELETE` on `.../{link_id}` below it.
pub const LINKS_SUFFIX: &str = "/links";
/// `POST {PIM_COLLECTIONS}/{id}{IMPORT_SUFFIX}`: an `.ics` or `.vcf` body, or
/// a JSON [`PimRootFile`] naming a file in a root.
pub const IMPORT_SUFFIX: &str = "/import";
/// `{PIM_COLLECTIONS}/{id}{EXPORT_SUFFIX}`: `GET` downloads the collection as
/// one file; `POST` with a [`PimRootFile`] saves it into a root.
pub const EXPORT_SUFFIX: &str = "/export";
/// The system address book, which has no collection id: `GET` downloads it,
/// `POST` with a [`PimRootFile`] saves it into a root.
pub const PIM_SYSTEM_EXPORT: &str = "/api/pim/system/export";
/// `GET {PIM_COLLECTIONS}/{id}{OBJECTS_SUFFIX}/{name}{PHOTO_SUFFIX}`: a
/// contact's photo as a WebP thumbnail.
pub const OBJECTS_SUFFIX: &str = "/objects";
pub const PHOTO_SUFFIX: &str = "/photo";
/// Public feed of one calendar or address book: `{FEED}/{token}.ics` or
/// `.vcf`. The extension is optional.
pub const FEED: &str = "/feed";
/// Pseudo root id every signed-in admin has on the files API: the whole
/// server root, read-only (the admin folder picker browses it). Real root
/// ids are positive database ids. Not listed in `/me`.
pub const ADMIN_ROOT: i64 = -1;

// ---------------------------------------------------------------------------
// Query params
// ---------------------------------------------------------------------------

/// `?action=...` on file URLs; without it the route lists the directory.
pub const P_ACTION: &str = "action";
pub const ACTION_DOWNLOAD: &str = "download";
pub const ACTION_PREVIEW: &str = "preview";
pub const ACTION_CONTENT: &str = "content";
pub const ACTION_THUMB: &str = "thumb";
/// `POST {FILES}/...?action=mkdir` — create a folder. Explicit, because the
/// POST route also carries uploads and mutations.
pub const ACTION_MKDIR: &str = "mkdir";
/// `POST {FILES}/...?action=create-file` — create an empty file. Explicit
/// like `mkdir`, for the same reason.
pub const ACTION_CREATE_FILE: &str = "create-file";
/// `POST {FILES}/...?action=exists` with an [`ExistsReq`] body — read-only
/// pre-check for an upload: which of the given targets already exist.
pub const ACTION_EXISTS: &str = "exists";
/// `?format=...` for folder downloads (values: see `server::archive::ArchiveFormat`).
pub const P_FORMAT: &str = "format";
/// `?share=<token>` — authenticate file calls with a public share token.
pub const P_SHARE: &str = "share";
/// Search query text (`GET {SEARCH}`).
pub const P_Q: &str = "q";
/// Which index to search: `name`, `content` or `both`.
pub const P_SCOPE: &str = "scope";
/// Root id to search; omitted = the caller's first root.
pub const P_ROOT: &str = "root";
/// Folder inside the root to start a search in (relative to the root);
/// omitted or empty = the whole root.
pub const P_PATH: &str = "path";
/// `?overwrite=true|1` on mutations and uploads.
pub const P_OVERWRITE: &str = "overwrite";
/// Listing order ([`SortKey`]); omitted = by name.
pub const P_SORT: &str = "sort";
/// `?desc=true` reverses the listing order. Folders still come first.
pub const P_DESC: &str = "desc";
/// First listing entry to return, in the sorted order.
pub const P_OFFSET: &str = "offset";
/// Listing entries to return, capped at [`MAX_LIST_ENTRIES`]; omitted = the cap.
pub const P_LIMIT: &str = "limit";
/// `?dirs=true` lists only the subfolders (the folder picker).
pub const P_DIRS: &str = "dirs";
/// `?around=name` returns the page that holds this entry, instead of the
/// one at the offset. A missing name falls back to the offset.
pub const P_AROUND: &str = "around";

// ---------------------------------------------------------------------------
// Wire enums
// ---------------------------------------------------------------------------

/// Access mode of a root or a share.
///
/// The serde names are also the values stored in the SQLite `mode` columns,
/// so renaming a variant would break existing databases. The round-trip test
/// below pins them.
#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Mode {
    Rw,
    Ro,
}

impl Mode {
    /// The only question callers ask: may this root be written to?
    pub fn is_writable(self) -> bool {
        matches!(self, Mode::Rw)
    }

    /// The wire/database spelling, for `<select>` values and SQL params.
    pub fn as_str(self) -> &'static str {
        match self {
            Mode::Rw => "rw",
            Mode::Ro => "ro",
        }
    }

    /// Parse the wire spelling. `None` for anything else.
    pub fn from_wire(s: &str) -> Option<Self> {
        match s {
            "rw" => Some(Mode::Rw),
            "ro" => Some(Mode::Ro),
            _ => None,
        }
    }
}

/// Which mutation [`Mutation`] asks for.
#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Op {
    Rename,
    Move,
    Copy,
}

/// What a listing is ordered by ([`P_SORT`]). Folders always sort before
/// files, so a size or date order does not scatter them through the listing.
#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq, Default)]
#[serde(rename_all = "lowercase")]
pub enum SortKey {
    #[default]
    Name,
    Size,
    Modified,
}

impl SortKey {
    pub fn as_str(self) -> &'static str {
        match self {
            SortKey::Name => "name",
            SortKey::Size => "size",
            SortKey::Modified => "modified",
        }
    }

    pub fn parse(s: &str) -> Option<Self> {
        match s {
            "name" => Some(SortKey::Name),
            "size" => Some(SortKey::Size),
            "modified" => Some(SortKey::Modified),
            _ => None,
        }
    }
}

// ---------------------------------------------------------------------------
// Request bodies (client → server)
// ---------------------------------------------------------------------------

#[derive(Serialize, Deserialize)]
pub struct Credentials {
    pub name: String,
    pub password: String,
}

/// Rename / move / copy (one body for all file mutations).
#[derive(Serialize, Deserialize)]
pub struct Mutation {
    pub op: Op,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub new_name: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub dst_root_id: Option<i64>,
    /// Destination directory, relative to `dst_root_id`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub dst: Option<String>,
    #[serde(default)]
    pub overwrite: bool,
}

/// A user folder: path relative to the server root + access mode.
#[derive(Serialize, Deserialize)]
pub struct Root {
    /// Path relative to the server root; "." means the whole root.
    pub path: String,
    #[serde(default = "default_rw")]
    pub mode: Mode,
}

fn default_rw() -> Mode {
    Mode::Rw
}

#[derive(Serialize, Deserialize)]
pub struct CreateUser {
    pub name: String,
    pub password: String,
    #[serde(default)]
    pub is_admin: bool,
    #[serde(default)]
    pub roots: Vec<Root>,
}

#[derive(Serialize, Deserialize)]
pub struct UpdateUser {
    /// Setting one is also the recovery path for a locked-out account: it
    /// deletes every passkey and puts the account back on
    /// [`AuthMode::Either`], leaving the new password as the one way in.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub password: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub is_admin: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub active: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub roots: Option<Vec<Root>>,
}

/// Server settings (GET/PUT `{ADMIN_SETTINGS}`).
#[derive(Serialize, Deserialize, Clone)]
pub struct Settings {
    pub allow_writable_shares: bool,
    /// Folders left out of every search, as paths relative to the server
    /// root. A path covers everything beneath it.
    #[serde(default)]
    pub search_excludes: Vec<String>,
}

#[derive(Serialize, Deserialize)]
pub struct CreateShare {
    pub root_id: i64,
    /// Item path relative to the root ("" or "." for the root itself).
    pub path: String,
    #[serde(default)]
    pub writable: bool,
    /// Absolute expiry as RFC 3339; absent = never.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<String>,
    /// Password the visitor must enter before the share opens; absent = none.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub password: Option<String>,
}

/// POST `{SHARE}/{token}/unlock` — the password for a protected share.
#[derive(Serialize, Deserialize)]
pub struct UnlockShare {
    pub password: String,
}

// ---------------------------------------------------------------------------
// Responses (server → client)
// ---------------------------------------------------------------------------

/// What a listing entry actually is, decided by the server from the file's
/// leading bytes (magic numbers via `infer`, plus a text/binary heuristic) —
/// not from its name. Drives the icon and the preview the client offers.
///
/// Deliberately coarse: this answers "which viewer opens this", not "what
/// exact format is it". Syntax highlighting still keys off the extension,
/// because `.h` is C or C++ and no amount of sniffing decides that.
#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum FileKind {
    Dir,
    Image,
    Video,
    Audio,
    Pdf,
    Archive,
    /// Anything that decodes as text: source code, markup, config, plain text.
    Text,
    /// Recognized-but-not-viewable, or undecodable bytes.
    Binary,
}

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
pub struct Entry {
    pub name: String,
    pub is_dir: bool,
    pub size: u64,
    /// RFC 3339 UTC modification time.
    pub mtime: String,
    /// Content-sniffed kind (see [`FileKind`]).
    pub kind: FileKind,
}

/// One page of a folder listing.
#[derive(Serialize, Deserialize)]
pub struct FilesResp {
    pub entries: Vec<Entry>,
    /// Entries in the whole folder, across all pages.
    pub total: usize,
    /// Position of `entries[0]` in the sorted folder. An offset past the end
    /// comes back as the start of the last page.
    pub offset: usize,
}

/// Cap on entries in one listing page.
pub const MAX_LIST_ENTRIES: usize = 10_000;

/// One streamed search result. Each is sent as one SSE event
/// (`data: <json>`), in the order found; the `done` event always ends the
/// stream.
#[derive(Serialize, Deserialize, Clone)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum SearchEvent {
    /// A file or folder whose name matched (scope `name`/`both`).
    File {
        root_id: i64,
        /// Path relative to the root, `/`-separated.
        path: String,
        size: u64,
        is_dir: bool,
        /// Sniffed the same way as a directory listing's, so the client can
        /// pick an icon and a viewer without a second guess at the name.
        kind: FileKind,
    },
    /// One matching line (scope `content`/`both`). `path` is relative to the
    /// root; `text` is the matched line, truncated to a fixed length.
    Match {
        root_id: i64,
        path: String,
        line: u64,
        text: String,
    },
    /// Stream finished. `stopped` is true when the client aborted before the
    /// search completed.
    Done {
        stopped: bool,
        /// Files examined (walked) before the stream ended.
        scanned: usize,
        /// Files skipped for content search (over the size cap).
        skipped: usize,
        elapsed_ms: u64,
    },
}

#[derive(Serialize, Deserialize, Clone, PartialEq)]
pub struct UserInfo {
    pub id: i64,
    pub name: String,
    pub is_admin: bool,
    /// Profile setting: single click opens entries (off = click selects,
    /// double click opens).
    pub single_click_open: bool,
    /// Profile setting: show image and video thumbnails in the grid.
    pub thumbnails: bool,
    /// Preferred UI language tag ("en", "de", "fr"); None = follow the
    /// browser.
    pub language: Option<String>,
    /// Profile setting: the root the UI opens on page load and on the home
    /// link. Always one of `Me::roots` (the server drops a stale id), or
    /// None for the root picker.
    pub default_root_id: Option<i64>,
    /// What this account needs to sign in.
    pub auth_mode: AuthMode,
    /// Whether a password is set at all. False means passkeys only.
    pub has_password: bool,
}

#[derive(Serialize, Deserialize, Clone)]
pub struct RootInfo {
    pub id: i64,
    pub name: String,
    pub path: String,
    pub mode: Mode,
}

/// GET `{AUTH_ME}`.
#[derive(Serialize, Deserialize, Clone)]
pub struct Me {
    /// True while no users exist yet (first-boot setup).
    pub first_boot: bool,
    /// None on first boot.
    pub user: Option<UserInfo>,
    pub roots: Vec<RootInfo>,
    pub allow_writable_shares: bool,
    /// Whether the server can make thumbnails at all (`--cache` is set).
    /// The profile setting is only offered when this is true.
    pub thumbnails_available: bool,
    /// `--public-url`, if set. The UI builds share links from it instead of
    /// the page origin.
    pub public_url: Option<String>,
}

/// GET/POST `{SHARES}`, GET `{SHARE}/{token}`.
#[derive(Serialize, Deserialize, Clone)]
pub struct ShareInfo {
    /// Also the share's synthetic root id in file API calls.
    pub id: i64,
    pub token: String,
    /// Display name (file/folder name, or the root's name for ".").
    pub name: String,
    pub is_file: bool,
    pub writable: bool,
    /// Path relative to the server root.
    pub target: String,
    /// RFC 3339 UTC creation time.
    pub created_at: String,
    /// RFC 3339 UTC expiry; None = never.
    pub expires_at: Option<String>,
    /// The file's kind for file shares (None for folder shares, and when
    /// not sniffed — the public resolve endpoint fills it in).
    pub kind: Option<FileKind>,
    /// Whether the share asks for a password. Never the password itself.
    pub has_password: bool,
}

/// One share plus who owns it: GET `{ADMIN_SHARES}`.
///
/// Admin-only: it carries the full [`ShareInfo::token`], and a token is access.
/// Kept separate from [`ShareInfo`] because the public resolve route answers
/// with a `ShareInfo` to anonymous visitors.
#[derive(Serialize, Deserialize, Clone)]
pub struct AdminShare {
    #[serde(flatten)]
    pub share: ShareInfo,
    pub creator_id: i64,
    pub creator_name: String,
    /// Whether the creator's account can still sign in. Deactivating an account
    /// does not revoke its shares, so `false` marks a live link its owner can no
    /// longer manage.
    pub creator_active: bool,
}

/// GET/POST `{ADMIN_USERS}`, PUT `{ADMIN_USERS}/{id}`.
#[derive(Serialize, Deserialize, Clone)]
pub struct AdminUser {
    pub id: i64,
    pub name: String,
    pub is_admin: bool,
    pub active: bool,
    pub roots: Vec<RootInfo>,
}

/// Acknowledges a successful mutation. Carries nothing: the 2xx status is
/// the acknowledgement, so the body is the empty object.
#[derive(Serialize, Deserialize)]
pub struct OkResp {}

#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum PimCollectionKind {
    Calendar,
    Addressbook,
}

/// How a calendar or address book is lent. The serde names are also the
/// values stored in `pim_shares.mode`.
#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
pub enum PimShareMode {
    #[serde(rename = "ro")]
    Ro,
    /// Change members, but send no scheduling messages as the owner.
    #[serde(rename = "rw")]
    Rw,
    /// Also invite and answer as the owner, named in SENT-BY.
    #[serde(rename = "rw+schedule")]
    RwSchedule,
}

impl PimShareMode {
    pub fn as_str(self) -> &'static str {
        match self {
            PimShareMode::Ro => "ro",
            PimShareMode::Rw => "rw",
            PimShareMode::RwSchedule => "rw+schedule",
        }
    }

    pub fn from_wire(s: &str) -> Option<Self> {
        match s {
            "ro" => Some(PimShareMode::Ro),
            "rw" => Some(PimShareMode::Rw),
            "rw+schedule" => Some(PimShareMode::RwSchedule),
            _ => None,
        }
    }
}

/// One entry of `GET {PIM_COLLECTIONS}`.
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct PimCollectionInfo {
    pub id: i64,
    pub kind: PimCollectionKind,
    pub name: String,
    /// The CalDAV or CardDAV URL, as seen by the signed-in user.
    pub url: String,
    pub owner: String,
    /// `None` for an own collection, the loan's mode for a lent one.
    pub mode: Option<PimShareMode>,
}

/// `GET {PIM_COLLECTIONS}/{id}{SHARES_SUFFIX}`.
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct PimShareInfo {
    pub user_id: i64,
    pub user_name: String,
    pub mode: PimShareMode,
}

/// `POST {PIM_COLLECTIONS}/{id}{SHARES_SUFFIX}`: lend to an account, or
/// change the mode of an existing loan.
#[derive(Serialize, Deserialize)]
pub struct CreatePimShare {
    pub user: String,
    pub mode: PimShareMode,
}

/// One entry of `GET {PIM_COLLECTIONS}/{id}{LINKS_SUFFIX}`.
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct PimLinkInfo {
    pub id: i64,
    /// `{FEED}/{token}` with the extension.
    pub path: String,
    pub busy_only: bool,
    pub created_at: String,
    pub expires_at: Option<String>,
    pub has_password: bool,
}

/// One feed with its collection and owner: GET `{ADMIN_PIM_LINKS}`.
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct AdminPimLink {
    #[serde(flatten)]
    pub link: PimLinkInfo,
    pub collection_id: i64,
    pub collection_name: String,
    pub kind: PimCollectionKind,
    pub owner_id: i64,
    pub owner_name: String,
    /// Whether the owner can still sign in. A disabled owner's feeds stay live.
    pub owner_active: bool,
}

/// `POST {PIM_COLLECTIONS}/{id}{LINKS_SUFFIX}`.
#[derive(Serialize, Deserialize, Default)]
pub struct CreatePimLink {
    /// Calendars only: events without their details.
    #[serde(default)]
    pub busy_only: bool,
    /// Absolute expiry as RFC 3339; absent = never.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<String>,
    /// Asked for with HTTP Basic; the user name is ignored.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub password: Option<String>,
}

/// A file in one of the signed-in user's roots.
#[derive(Serialize, Deserialize)]
pub struct PimRootFile {
    pub root_id: i64,
    pub path: String,
}

/// The answer to an import.
#[derive(Serialize, Deserialize, Debug)]
pub struct PimImportResult {
    pub created: usize,
    pub updated: usize,
    /// All skipped objects, also those beyond `skipped`.
    pub skipped_total: usize,
    /// The first skipped objects.
    pub skipped: Vec<PimSkipped>,
}

#[derive(Serialize, Deserialize, Debug)]
pub struct PimSkipped {
    pub uid: Option<String>,
    /// The precondition a PUT of the object would fail, e.g.
    /// `valid-calendar-object-resource`.
    pub reason: String,
}

#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum RoomKind {
    Room,
    Resource,
}

/// A room or resource: `GET {ADMIN_ROOMS}`.
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct RoomInfo {
    pub id: i64,
    /// The URL segment. Fixed, since it is also the scheduling address.
    pub name: String,
    pub display_name: String,
    pub kind: RoomKind,
    /// The principal URL.
    pub url: String,
}

/// `POST {ADMIN_ROOMS}`.
#[derive(Serialize, Deserialize)]
pub struct CreateRoom {
    pub name: String,
    /// Defaults to `name`.
    pub display_name: Option<String>,
    pub kind: RoomKind,
}

/// `PUT {ADMIN_ROOMS}/{id}`.
#[derive(Serialize, Deserialize)]
pub struct UpdateRoom {
    pub display_name: String,
}

/// `POST ...?action=exists` body: upload targets relative to the request
/// directory (may contain subfolders, like upload part names).
#[derive(Serialize, Deserialize)]
pub struct ExistsReq {
    pub paths: Vec<String>,
}

/// One existing upload target.
#[derive(Serialize, Deserialize, Clone, PartialEq, Debug)]
pub struct Existing {
    pub path: String,
    pub is_dir: bool,
}

/// `POST ...?action=exists` response: the subset of the requested paths
/// that exist, in request order.
#[derive(Serialize, Deserialize)]
pub struct ExistsResp {
    pub existing: Vec<Existing>,
}

/// PUT `?action=content` (editor save): the file's new mtime (unix seconds).
#[derive(Serialize, Deserialize)]
pub struct SaveResp {
    pub mtime: i64,
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The serde spellings are the database values too, so they are pinned.
    #[test]
    fn mode_wire_format_is_rw_ro() {
        assert_eq!(serde_json::to_string(&Mode::Rw).unwrap(), "\"rw\"");
        assert_eq!(serde_json::to_string(&Mode::Ro).unwrap(), "\"ro\"");
        for m in [Mode::Rw, Mode::Ro] {
            let s = serde_json::to_string(&m).unwrap();
            assert_eq!(serde_json::from_str::<Mode>(&s).unwrap(), m);
            // `as_str`/`from_wire` must agree with serde.
            assert_eq!(s, format!("\"{}\"", m.as_str()));
            assert_eq!(Mode::from_wire(m.as_str()), Some(m));
        }
        assert_eq!(Mode::from_wire("both"), None);
        assert!(serde_json::from_str::<Mode>("\"both\"").is_err());
        assert!(Mode::Rw.is_writable());
        assert!(!Mode::Ro.is_writable());
    }

    #[test]
    fn pim_share_mode_wire_format() {
        for m in [PimShareMode::Ro, PimShareMode::Rw, PimShareMode::RwSchedule] {
            let s = serde_json::to_string(&m).unwrap();
            assert_eq!(s, format!("\"{}\"", m.as_str()));
            assert_eq!(serde_json::from_str::<PimShareMode>(&s).unwrap(), m);
            assert_eq!(PimShareMode::from_wire(m.as_str()), Some(m));
        }
        assert_eq!(PimShareMode::RwSchedule.as_str(), "rw+schedule");
    }

    #[test]
    fn op_wire_format() {
        assert_eq!(serde_json::to_string(&Op::Rename).unwrap(), "\"rename\"");
        assert_eq!(serde_json::to_string(&Op::Move).unwrap(), "\"move\"");
        assert_eq!(serde_json::to_string(&Op::Copy).unwrap(), "\"copy\"");
        for op in [Op::Rename, Op::Move, Op::Copy] {
            let s = serde_json::to_string(&op).unwrap();
            assert_eq!(serde_json::from_str::<Op>(&s).unwrap(), op);
        }
        assert!(serde_json::from_str::<Op>("\"explode\"").is_err());
    }

    #[test]
    fn mutation_round_trip_skips_absent_fields() {
        let m = Mutation {
            op: Op::Move,
            new_name: None,
            dst_root_id: Some(3),
            dst: Some("docs".into()),
            overwrite: true,
        };
        let s = serde_json::to_string(&m).unwrap();
        assert!(!s.contains("new_name"));
        let back: Mutation = serde_json::from_str(&s).unwrap();
        assert_eq!(back.dst_root_id, Some(3));
        assert_eq!(back.op, Op::Move);
    }

    #[test]
    fn mutation_defaults_missing_fields() {
        let m: Mutation = serde_json::from_str(r#"{"op":"rename","new_name":"a.txt"}"#).unwrap();
        assert!(!m.overwrite);
        assert_eq!(m.dst, None);
    }

    #[test]
    fn root_defaults_mode_to_rw() {
        let r: Root = serde_json::from_str(r#"{"path":"docs"}"#).unwrap();
        assert_eq!(r.mode, Mode::Rw);
    }

    #[test]
    fn me_round_trip() {
        let me = Me {
            first_boot: false,
            user: Some(UserInfo {
                id: 1,
                name: "admin".into(),
                is_admin: true,
                single_click_open: false,
                thumbnails: true,
                language: None,
                default_root_id: None,
                auth_mode: AuthMode::Either,
                has_password: true,
            }),
            roots: vec![RootInfo {
                id: 1,
                name: "root".into(),
                path: ".".into(),
                mode: Mode::Rw,
            }],
            allow_writable_shares: false,
            thumbnails_available: true,
            public_url: None,
        };
        let s = serde_json::to_string(&me).unwrap();
        let back: Me = serde_json::from_str(&s).unwrap();
        assert_eq!(back.roots.len(), 1);
    }
}

// ---------------------------------------------------------------------------
// Sign-in methods: password, passkeys, and how they combine
// ---------------------------------------------------------------------------

/// What an account needs to sign in.
///
/// Not a "2FA on/off" flag: [`AuthMode::Either`] with no password is a
/// passkey-only account, which is still two factors when the authenticator
/// does user verification (the server always asks for it).
#[derive(Serialize, Deserialize, Clone, Copy, Debug, Default, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum AuthMode {
    /// Password *or* passkey. Either one alone signs the user in.
    #[default]
    Either,
    /// Password *and* passkey. Both legs must pass, in either order.
    Both,
}

impl AuthMode {
    pub fn as_str(self) -> &'static str {
        match self {
            AuthMode::Either => "either",
            AuthMode::Both => "both",
        }
    }

    pub fn from_wire(s: &str) -> Option<Self> {
        match s {
            "either" => Some(AuthMode::Either),
            "both" => Some(AuthMode::Both),
            _ => None,
        }
    }
}

/// One registered passkey, as shown in profile settings. Never carries key
/// material.
#[derive(Serialize, Deserialize, Clone)]
pub struct PasskeyInfo {
    pub id: i64,
    /// User-chosen label ("YubiKey", "Work laptop").
    pub name: String,
    /// RFC 3339 UTC.
    pub created_at: String,
    pub last_used_at: Option<String>,
    /// Whether the browser reported this credential as discoverable, so it
    /// can sign in without the account name. `None` when the browser did not
    /// say — the `credProps` extension is optional and unsigned, so absence
    /// means "unknown", never "no".
    pub discoverable: Option<bool>,
}

/// One app password, as shown in profile settings.
///
/// WebDAV-only: it never signs in to the web UI. Never carries the secret,
/// which exists only in [`NewAppPassword`].
#[derive(Serialize, Deserialize, Clone)]
pub struct AppPasswordInfo {
    pub id: i64,
    /// User-chosen label ("Laptop mount", "phone").
    pub name: String,
    /// RFC 3339 UTC.
    pub created_at: String,
    /// Only tracked to the hour.
    pub last_used_at: Option<String>,
}

/// `POST {AUTH_APP_PASSWORDS}`.
#[derive(Serialize, Deserialize)]
pub struct CreateAppPassword {
    pub name: String,
}

/// The answer to `POST {AUTH_APP_PASSWORDS}`.
///
/// The only time `secret` is readable. The server keeps a hash of it.
#[derive(Serialize, Deserialize)]
pub struct NewAppPassword {
    #[serde(flatten)]
    pub info: AppPasswordInfo,
    pub secret: String,
}

/// `POST {AUTH_PASSWORD}` — set or change the password.
///
/// No current password to confirm: a passkey-only account has none to give.
/// The session is the gate, and the server drops the account's other
/// sessions on every change.
#[derive(Serialize, Deserialize)]
pub struct ChangePassword {
    pub new_password: String,
}

/// `PUT {AUTH_MODE}`.
#[derive(Serialize, Deserialize)]
pub struct SetAuthMode {
    pub mode: AuthMode,
}

/// A WebAuthn challenge on its way to the browser.
///
/// `options` is the raw JSON the browser's `parseCreationOptionsFromJSON` /
/// `parseRequestOptionsFromJSON` expects, carried as a string rather than a
/// nested object. Neither side has to re-parse it: the server serializes the
/// `webauthn-rs` type straight into it, and the client hands it to
/// `JSON.parse` in the browser shim.
#[derive(Serialize, Deserialize)]
pub struct PasskeyChallenge {
    /// Opaque handle for the server-side ceremony state. Echoed back on
    /// finish. Not a credential, and useless on its own.
    pub state_id: String,
    pub options: String,
}

/// `POST {AUTH_PASSKEYS_REGISTER}{FINISH_SUFFIX}`.
#[derive(Serialize, Deserialize)]
pub struct PasskeyRegisterFinish {
    pub state_id: String,
    /// Label for the new passkey.
    pub name: String,
    /// The browser's `PublicKeyCredential.toJSON()` output, verbatim.
    pub credential: String,
}

/// `POST {AUTH_PASSKEY_LOGIN}` — begin a passkey sign-in.
#[derive(Serialize, Deserialize)]
pub struct PasskeyLoginBegin {
    /// Account name, when the user typed one. Without it the server issues a
    /// discoverable challenge, which only finds passkeys the authenticator
    /// stores itself.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Ask for a conditional-mediation (autofill) challenge instead of a
    /// modal one.
    #[serde(default)]
    pub conditional: bool,
}

/// `POST {AUTH_PASSKEY_LOGIN}{FINISH_SUFFIX}`.
#[derive(Serialize, Deserialize)]
pub struct PasskeyLoginFinish {
    pub state_id: String,
    pub credential: String,
}

/// `POST {AUTH_LOGIN}` — the password leg of a sign-in.
#[derive(Serialize, Deserialize)]
pub struct LoginReq {
    /// Omitted only when `state_id` names a half-finished sign-in, which
    /// already knows who the user is.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    pub password: String,
    /// Handle from a passkey leg that still needs a password (an
    /// [`AuthMode::Both`] account signing in passkey-first).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub state_id: Option<String>,
}

/// The answer to either sign-in leg.
///
/// Exactly one of the three shapes: signed in, needs a passkey next, or needs
/// a password next. The two "needs" cases are how [`AuthMode::Both`] works,
/// and which one appears depends only on which leg the user started with.
#[derive(Serialize, Deserialize, Default)]
pub struct LoginResp {
    /// True when the session cookie is set and the user is in.
    pub ok: bool,
    /// Present when this leg passed but a passkey is still required.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub passkey_challenge: Option<PasskeyChallenge>,
    /// Present when this leg passed but the password is still required.
    /// Carries the account name, so the form can show whose password it
    /// wants, and the handle to send back with it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub password_required: Option<PasswordStep>,
}

#[derive(Serialize, Deserialize, Clone)]
pub struct PasswordStep {
    pub name: String,
    pub state_id: String,
}