PowerfulWhitelist 1.0.1

//
//    object API_IsWhitelisted(string steamId)
//
//    steamId   target SteamID64 as a string.
//
//    Returns true if the player is allowed to connect: present in the
//    whitelist, OR holding the powerfulwhitelist.bypass permission, OR a
//    server admin while AllowAdmins is on. Returns false otherwise. Invalid
//    steamId -> false. Reads from the in-memory cache, so it is synchronous
//    and safe to call from CanUserLogin-style checks.

    if (PowerfulWhitelist?.Call("API_IsWhitelisted", steamId.ToString()) is true)
    {
        // player is allowed in
    }



//    object API_AddWhitelist(string steamId, string name)
//
//    steamId   target SteamID64 as a string.
//    name      display name stored with the record (falls back to the steamId
//              if empty).
//
//    Returns true if the entry was added, false if the steamId is invalid or
//    the player is already whitelisted. The change is written through to the
//    active backend (JSON / SQLite / MySQL). Records added via the API store
//    "API" as the author with a zero by-SteamID.

    PowerfulWhitelist?.Call("API_AddWhitelist", "76561198000000000", "Trusted Player");



//    object API_RemoveWhitelist(string steamId)
//
//    steamId   target SteamID64 as a string.
//
//    Returns true if an entry was removed, false if the steamId is invalid or
//    the player was not whitelisted. If the whitelist is enabled and the
//    player is online and no longer allowed, they are kicked.

    PowerfulWhitelist?.Call("API_RemoveWhitelist", steamId.ToString());



//    object API_IsEnabled()
//
//    Returns true if the whitelist is currently enforcing, false otherwise.
//    Enforcing means either the local "This server" switch is on, or (on a
//    database backend) the shared "In database" switch is on.

    if (PowerfulWhitelist?.Call("API_IsEnabled") is true)
    {
        // the whitelist is active
    }



//    object API_SetEnabled(bool enabled)
//
//    Turns the local "This server" switch on or off, the same as /whitelist
//    on|off. Saves the config. When it starts enforcing and KickOnEnable is
//    on, non-listed players online are kicked.
//
//    Returns true if the switch changed, false if it was already in that
//    state.

    PowerfulWhitelist?.Call("API_SetEnabled", true);



//    object API_SetDatabaseEnabled(bool enabled)
//
//    Turns the shared "In database" switch on or off. The state is stored in
//    the database, so every server on the same database picks it up (within
//    SyncInterval). Same kick behaviour as API_SetEnabled.
//
//    Returns true if the switch changed, false if it was already in that
//    state, or if the storage backend is JSON, or the database is not
//    connected.

    PowerfulWhitelist?.Call("API_SetDatabaseEnabled", true);



//    object API_GetState()
//
//    Returns a Dictionary<string, object> with the current state:
//
//        enforcing   bool    true if the whitelist is being enforced right now
//        server      bool    the local "This server" switch
//        database    bool    the shared "In database" switch (false on JSON)
//        storage     string  "Json", "Sqlite" or "MySql"
//        ready       bool    false while a database backend is not connected
//                            (everyone is let in until it is)
//        count       int     number of whitelisted players

    if (PowerfulWhitelist?.Call("API_GetState") is Dictionary<string, object> state)
    {
        Puts($"enforcing: {state["enforcing"]}, storage: {state["storage"]}, {state["count"]} entries");
    }



//    object API_GetWhitelist()
//
//    Returns a List<string[]>, one array per entry, in the form:
//
//        [ steamId, name, byName, bySteamId, createdUnixSeconds ]
//
//    All fields are strings. createdUnixSeconds is the Unix time (seconds) the
//    entry was added. bySteamId is "0" for entries added by the server/API.

    if (PowerfulWhitelist?.Call("API_GetWhitelist") is List<string[]> list)
    {
        foreach (var row in list)
            Puts($"{row[1]} ({row[0]}) added by {row[2]} / {row[3]}");
    }



// PowerfulWhitelist fires these so you can mirror changes to Discord, a web
// panel, stats, etc.

//    OnPowerfulWhitelistAdded(ulong steamId, string name, string by)
//
//        Fired when a new entry is added (manually, by command, or via
//        API_AddWhitelist). steamId is a ulong, not a string.

    private void OnPowerfulWhitelistAdded(ulong steamId, string name, string by)
    {
        Puts($"{name} ({steamId}) whitelisted by {by}");
    }

//    OnPowerfulWhitelistRemoved(ulong steamId, string by)
//
//        Fired when an entry is removed (command / UI / API_RemoveWhitelist).

    private void OnPowerfulWhitelistRemoved(ulong steamId, string by)
    {
        Puts($"{steamId} removed from the whitelist by {by}");
    }



// Storage notes:
//
//    The whitelist is kept in an in-memory cache for instant, synchronous
//    login checks, and written through to the active backend on every change:
//
//        Json    a local data file (default)
//        Sqlite  a local SQLite database file
//        MySql   a shared database for multi-server networks
//
//    With MySQL the cache is refreshed on a short interval (SyncInterval), so
//    additions/removals from other servers appear automatically. The Whitelist
//    page has two separate switches: "This server" (local) and "In database"
//    (shared); the shared state lives in the database, so flipping it on one
//    server enforces the whitelist on every server using the same database.
//
//    Switching the storage backend itself (Json / Sqlite / MySql) is done from
//    the Settings page or the config, not through the API.