@vex-chat/libvex 1.0.0-rc.1 → 1.0.0-rc.2

package/dist/Client.d.ts

@@ -2,30 +2,44 @@ import type { IChannel, IDevice, IEmoji, IFileResponse, IFileSQL, IInvite, IPerm
 import { AxiosError } from "axios";
 import { EventEmitter } from "events";
 import type { IStorage } from "./IStorage.js";
-interface ICensoredUser {
-    lastSeen: number;
-    userID: string;
-    username: string;
-}
 /**
  * IMessage is a chat message.
  */
 export interface IMessage {
+    /** Hex-encoded nonce used for message encryption. */
     nonce: string;
+    /** Globally unique message identifier. */
     mailID: string;
+    /** Sender device ID. */
     sender: string;
+    /** Recipient device ID. */
     recipient: string;
+    /** Plaintext message content (or empty string when decryption failed). */
     message: string;
+    /** Whether this message was received or sent by the current client. */
     direction: "incoming" | "outgoing";
+    /** Time the message was created/received. */
     timestamp: Date;
+    /** Whether payload decryption succeeded. */
     decrypted: boolean;
+    /** Channel ID for group messages; `null` for direct messages. */
     group: string | null;
+    /** `true` when this message was forwarded to another owned device. */
     forward: boolean;
+    /** User ID of the original author. */
     authorID: string;
+    /** User ID of the intended reader. */
     readerID: string;
 }
 /**
  * IPermission is a permission to a resource.
+ *
+ * Common fields:
+ * - `permissionID`: unique permission row ID
+ * - `userID`: user receiving this grant
+ * - `resourceID`: target server/channel/etc.
+ * - `resourceType`: type string for the resource
+ * - `powerLevel`: authorization level
  */
 export type { IPermission } from "@vex-chat/types";
 /**
@@ -33,154 +47,298 @@ export type { IPermission } from "@vex-chat/types";
  * encoded as hex strings.
  */
 export interface IKeys {
+    /** Public Ed25519 key as hex. */
     public: string;
+    /** Secret Ed25519 key as hex. Store securely. */
     private: string;
 }
+/**
+ * Device record associated with a user account.
+ *
+ * Common fields:
+ * - `deviceID`: unique device identifier
+ * - `owner`: owning user ID
+ * - `signKey`: signing public key
+ * - `name`: user-facing device name
+ * - `lastLogin`: last login timestamp string
+ * - `deleted`: soft-delete flag
+ */
 export type { IDevice } from "@vex-chat/types";
 /**
  * IUser is a single user on the vex platform.
+ *
+ * This is intentionally a censored user shape for client use, containing:
+ * - `userID`
+ * - `username`
+ * - `lastSeen`
  */
-export interface IUser extends ICensoredUser {
+export interface IUser {
+    /** Last-seen timestamp (unix epoch milliseconds). */
+    lastSeen: number;
+    /** User identifier. */
+    userID: string;
+    /** Public username. */
+    username: string;
 }
 /**
  * ISession is an end to end encryption session with another peer.
+ *
+ * Key fields include:
+ * - `sessionID`
+ * - `userID`
+ * - `deviceID`
+ * - `mode` (`initiator` or `receiver`)
+ * - `publicKey` and `fingerprint`
+ * - `lastUsed`
+ * - `verified`
+ *
+ * @example
+ * ```ts
+ * const session: ISession = {
+ *     sessionID: "f6e4fbd0-7222-4ba8-b799-c227faf5c8de",
+ *     userID: "f34f5e37-616f-4d3a-a437-e7c27c31cb73",
+ *     deviceID: "9b0f3f46-06ad-4bc4-8adf-4de10e13cb9c",
+ *     mode: "initiator",
+ *     SK: "7d9afde6683ecc2d1f55e34e1b95de9d4042dfd4e8cda7fdf3f0f7e02fef8f9a",
+ *     publicKey: "d58f39dc4bcfe4e8ef022f34e8b6f4f6ddc9c4acee30c0d58f126aa5db3f61b0",
+ *     fingerprint: "05294b9aa81d0fd0ca12a4b585f531d8ef1f53f8ea3d0200a0df3f9c44a7d8b1",
+ *     lastUsed: new Date(),
+ *     verified: false,
+ * };
+ * ```
  */
 export interface ISession extends ISessionSQL {
 }
 /**
  * IChannel is a chat channel on a server.
+ *
+ * Common fields:
+ * - `channelID`
+ * - `serverID`
+ * - `name`
  */
 export type { IChannel } from "@vex-chat/types";
 /**
  * IServer is a single chat server.
+ *
+ * Common fields:
+ * - `serverID`
+ * - `name`
+ * - `icon` (optional URL/data)
  */
 export type { IServer } from "@vex-chat/types";
 /**
  * Ifile is an uploaded encrypted file.
+ *
+ * Common fields:
+ * - `fileID`: file identifier
+ * - `owner`: owner device/user ID
+ * - `nonce`: file encryption nonce (hex)
+ *
+ * @example
+ * ```ts
+ * const file: IFile = {
+ *     fileID: "bb1c3fd1-4928-48ab-9d09-3ea0972fbd9d",
+ *     owner: "9b0f3f46-06ad-4bc4-8adf-4de10e13cb9c",
+ *     nonce: "aa6c8d42f3fdd032a1e9fced4be379582d26ce8f69822d64",
+ * };
+ * ```
  */
 export interface IFile extends IFileSQL {
 }
 /**
  * IFileRes is a server response to a file retrieval request.
+ *
+ * Structure:
+ * - `details`: metadata (`IFile`)
+ * - `data`: decrypted binary bytes
+ *
+ * @example
+ * ```ts
+ * const response: IFileRes = {
+ *     details: {
+ *         fileID: "bb1c3fd1-4928-48ab-9d09-3ea0972fbd9d",
+ *         owner: "9b0f3f46-06ad-4bc4-8adf-4de10e13cb9c",
+ *         nonce: "aa6c8d42f3fdd032a1e9fced4be379582d26ce8f69822d64",
+ *     },
+ *     data: Buffer.from("hello"),
+ * };
+ * ```
  */
 export interface IFileRes extends IFileResponse {
 }
 /**
  * @ignore
  */
-interface IMe {
-    user: () => ICensoredUser;
+export interface IMe {
+    /** Returns the currently authenticated user profile. */
+    user: () => IUser;
+    /** Returns metadata for the currently authenticated device. */
     device: () => IDevice;
+    /** Uploads and sets a new avatar image for the current user. */
     setAvatar: (avatar: Buffer) => Promise<void>;
 }
 /**
  * @ignore
  */
-interface IUsers {
+export interface IUsers {
+    /**
+     * Looks up a user by user ID, username, or signing key.
+     */
     retrieve: (userID: string) => Promise<[IUser | null, AxiosError | null]>;
+    /** Returns users with whom the current device has active sessions. */
     familiars: () => Promise<IUser[]>;
 }
 /**
  * @ignore
  */
-interface IMessages {
+export interface IMessages {
+    /** Sends an encrypted direct message to one user. */
     send: (userID: string, message: string) => Promise<void>;
+    /** Sends an encrypted message to all members of a channel. */
     group: (channelID: string, message: string) => Promise<void>;
+    /** Returns local direct-message history with one user. */
     retrieve: (userID: string) => Promise<IMessage[]>;
+    /** Returns local group-message history for one channel. */
     retrieveGroup: (channelID: string) => Promise<IMessage[]>;
+    /** Deletes local history for a user/channel, optionally older than a duration. */
     delete: (userOrChannelID: string, duration?: string) => Promise<void>;
+    /** Deletes all locally stored message history. */
     purge: () => Promise<void>;
 }
 /**
  * @ignore
  */
-interface IServers {
+export interface IServers {
+    /** Lists servers available to the authenticated user. */
     retrieve: () => Promise<IServer[]>;
+    /** Gets one server by ID. */
     retrieveByID: (serverID: string) => Promise<IServer | null>;
+    /** Creates a server. */
     create: (name: string) => Promise<IServer>;
+    /** Deletes a server. */
     delete: (serverID: string) => Promise<void>;
+    /** Leaves a server by removing the user's permission entry. */
     leave: (serverID: string) => Promise<void>;
 }
 /**
  * @ignore
  */
-interface IModeration {
+export interface IModeration {
+    /** Removes a user from a server by revoking their server permission(s). */
     kick: (userID: string, serverID: string) => Promise<void>;
+    /** Returns all permission entries for a server. */
     fetchPermissionList: (serverID: string) => Promise<IPermission[]>;
 }
 /**
  * @ignore
  */
-interface IPermissions {
+export interface IPermissions {
+    /** Lists permissions granted to the authenticated user. */
     retrieve: () => Promise<IPermission[]>;
+    /** Deletes one permission grant. */
     delete: (permissionID: string) => Promise<void>;
 }
 /**
  * @ignore
  */
-interface IInvites {
+export interface IInvites {
+    /** Redeems an invite and returns the created permission grant. */
     redeem: (inviteID: string) => Promise<IPermission>;
+    /** Creates an invite for a server and duration. */
     create: (serverID: string, duration: string) => Promise<IInvite>;
+    /** Lists active invites for a server. */
     retrieve: (serverID: string) => Promise<IInvite[]>;
 }
 /**
  * @ignore
  */
-interface IChannels {
+export interface IChannels {
+    /** Lists channels in a server. */
     retrieve: (serverID: string) => Promise<IChannel[]>;
+    /** Gets one channel by ID. */
     retrieveByID: (channelID: string) => Promise<IChannel | null>;
+    /** Creates a channel in a server. */
     create: (name: string, serverID: string) => Promise<IChannel>;
+    /** Deletes a channel. */
     delete: (channelID: string) => Promise<void>;
+    /** Lists users currently visible in a channel. */
     userList: (channelID: string) => Promise<IUser[]>;
 }
 /**
  * @ignore
  */
-interface ISessions {
+export interface ISessions {
+    /** Returns all locally known sessions. */
     retrieve: () => Promise<ISessionSQL[]>;
+    /** Builds a human-readable verification phrase from a session fingerprint. */
     verify: (session: ISessionSQL) => string;
+    /** Marks one session as verification-confirmed. */
     markVerified: (fingerprint: string) => Promise<void>;
 }
 /**
  * @ignore
  */
-interface IDevices {
+export interface IDevices {
+    /** Fetches one device by ID. */
     retrieve: (deviceIdentifier: string) => Promise<IDevice | null>;
+    /** Registers the current key material as a new device. */
     register: () => Promise<IDevice | null>;
+    /** Deletes one of the account's devices (except the currently active one). */
     delete: (deviceID: string) => Promise<void>;
 }
 /**
  * @ignore
  */
-interface IFiles {
+export interface IFiles {
+    /** Uploads and encrypts a file. */
     create: (file: Buffer) => Promise<[IFileSQL, string]>;
+    /** Downloads and decrypts a file using a file ID and key. */
     retrieve: (fileID: string, key: string) => Promise<IFileResponse | null>;
 }
 /**
  * @ignore
  */
-interface IEmojis {
+export interface IEmojis {
+    /** Uploads a custom emoji to a server. */
     create: (emoji: Buffer, name: string, serverID: string) => Promise<IEmoji | null>;
+    /** Lists emojis available on a server. */
     retrieveList: (serverID: string) => Promise<IEmoji[]>;
+    /** Fetches one emoji's metadata by ID. */
     retrieve: (emojiID: string) => Promise<IEmoji | null>;
 }
+/**
+ * Progress payload emitted by the `fileProgress` event.
+ */
 export interface IFileProgress {
+    /** Correlation token (file ID, nonce, or label depending on operation). */
     token: string;
+    /** Whether this progress event is for upload or download. */
     direction: "upload" | "download";
+    /** Integer percentage from `0` to `100`. */
     progress: number;
+    /** Bytes transferred so far. */
     loaded: number;
+    /** Total expected bytes when available, otherwise `0`. */
     total: number;
 }
 /**
  * IClientOptions are the options you can pass into the client.
  */
 export interface IClientOptions {
+    /** Logging level for client runtime logs. */
     logLevel?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    /** API host without protocol. Defaults to `api.vex.wtf`. */
     host?: string;
+    /** Folder path where the sqlite file is created. */
     dbFolder?: string;
+    /** Use sqlite in-memory mode (`:memory:`) instead of a file. */
     inMemoryDb?: boolean;
+    /** Logging level for storage/database logs. */
     dbLogLevel?: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly";
+    /** Use `http/ws` instead of `https/wss`. Intended for local/dev environments. */
     unsafeHttp?: boolean;
+    /** Whether local message history should be persisted by default storage. */
     saveHistory?: boolean;
 }
 export declare interface Client {
@@ -213,6 +371,14 @@ export declare interface Client {
      * @event
      */
     on(event: "ready", callback: () => void): this;
+    /**
+     * Emitted before the first inbox fetch/decrypt cycle after connect.
+     *
+     * Use this to show temporary loading UI while historical messages are
+     * decrypted from server payloads.
+     *
+     * @event
+     */
     on(event: "decryptingMail", callback: () => void): this;
     /**
      * This is emitted when you are connected to the chat.
@@ -349,12 +515,32 @@ export declare interface Client {
  *
  * main();
  * ```
- *
- * @noInheritDoc
  */
 export declare class Client extends EventEmitter {
+    /**
+     * Loads a key file from disk.
+     *
+     * Pass-through utility from `@vex-chat/crypto`.
+     */
     static loadKeyFile: (path: string, password: string) => string;
+    /**
+     * Saves a key file to disk.
+     *
+     * Pass-through utility from `@vex-chat/crypto`.
+     */
     static saveKeyFile: (path: string, password: string, keyToSave: string, iterationOverride?: number) => void;
+    /**
+     * Creates and initializes a client in one step.
+     *
+     * @param privateKey Optional hex secret key. When omitted, a fresh key is generated.
+     * @param options Runtime options.
+     * @param storage Optional custom storage backend implementing `IStorage`.
+     *
+     * @example
+     * ```ts
+     * const client = await Client.create(privateKey, { host: "api.vex.wtf" });
+     * ```
+     */
     static create: (privateKey?: string, options?: IClientOptions, storage?: IStorage) => Promise<Client>;
     /**
      * Generates an ed25519 secret key as a hex string.
@@ -371,37 +557,75 @@ export declare class Client extends EventEmitter {
     private static getMnemonic;
     private static deserializeExtra;
     /**
-     * The IUsers interface contains methods for dealing with users.
+     * User operations.
+     *
+     * @example
+     * ```ts
+     * const [user] = await client.users.retrieve("alice");
+     * const familiarUsers = await client.users.familiars();
+     * ```
      */
     users: IUsers;
+    /**
+     * Emoji operations.
+     *
+     * @example
+     * ```ts
+     * const emoji = await client.emoji.create(imageBuffer, "party", serverID);
+     * const list = await client.emoji.retrieveList(serverID);
+     * ```
+     */
     emoji: IEmojis;
+    /**
+     * Helpers for information/actions related to the currently authenticated account.
+     */
     me: IMe;
-    devices: IDevices;
     /**
-     * The IMessages interface contains methods for dealing with messages.
+     * Device management methods.
      */
+    devices: IDevices;
+    /** File upload/download methods. */
     files: IFiles;
     /**
-     * The IPermissions object contains all methods for dealing with permissions.
+     * Permission-management methods for the current user.
      */
     permissions: IPermissions;
     /**
-     * The IModeration object contains all methods for dealing with permissions.
+     * Server moderation helper methods.
      */
     moderation: IModeration;
     /**
-     * The IInvites interface contains methods for dealing with invites.
+     * Invite-management methods.
      */
     invites: IInvites;
     /**
-     * The IMessages interface contains methods for dealing with messages.
+     * Message operations (direct and group).
+     *
+     * @example
+     * ```ts
+     * await client.messages.send(userID, "Hello!");
+     * await client.messages.group(channelID, "Hello channel!");
+     * const dmHistory = await client.messages.retrieve(userID);
+     * ```
      */
     messages: IMessages;
     /**
-     * The ISessions interface contains methods for dealing with encryption sessions.
+     * Encryption-session helpers.
      */
     sessions: ISessions;
+    /**
+     * Server operations.
+     *
+     * @example
+     * ```ts
+     * const servers = await client.servers.retrieve();
+     * const created = await client.servers.create("Team Space");
+     * ```
+     */
     servers: IServers;
+    /**
+     * Channel operations.
+     */
     channels: IChannels;
     /**
      * This is true if the client has ever been initialized. You can only initialize
@@ -438,6 +662,14 @@ export declare class Client extends EventEmitter {
     private forwarded;
     private prefixes;
     private constructor();
+    /**
+     * Returns the current HTTP API origin with protocol.
+     *
+     * @example
+     * ```ts
+     * console.log(client.getHost()); // "https://api.vex.wtf"
+     * ```
+     */
     getHost(): string;
     /**
      * Manually closes the client. Emits the closed event on successful shutdown.
@@ -447,16 +679,43 @@ export declare class Client extends EventEmitter {
      * Gets the hex string representations of the public and private keys.
      */
     getKeys(): IKeys;
+    /**
+     * Authenticates with username/password and stores the auth token/cookie.
+     *
+     * @param username Account username.
+     * @param password Account password.
+     * @returns `null` on success, or the thrown error object on failure.
+     *
+     * @example
+     * ```ts
+     * const err = await client.login("alice", "correct horse battery staple");
+     * if (err) console.error(err);
+     * ```
+     */
     login(username: string, password: string): Promise<Error | null>;
     /**
      * Returns the authorization cookie details. Throws if you don't have a
      * valid authorization cookie.
      */
+    /**
+     * Returns details about the currently authenticated session.
+     *
+     * @returns The authenticated user, token expiry, and active token.
+     *
+     * @example
+     * ```ts
+     * const auth = await client.whoami();
+     * console.log(auth.user.username, new Date(auth.exp));
+     * ```
+     */
     whoami(): Promise<{
-        user: ICensoredUser;
+        user: IUser;
         exp: number;
         token: string;
     }>;
+    /**
+     * Logs out the current authenticated session from the server.
+     */
     logout(): Promise<void>;
     /**
      * Connects your device to the chat. You must have an valid authorization cookie.
@@ -471,7 +730,10 @@ export declare class Client extends EventEmitter {
      *
      * @example [user, err] = await client.register("MyUsername");
      */
-    register(username: string, password: string): Promise<[ICensoredUser | null, Error | null]>;
+    register(username: string, password: string): Promise<[IUser | null, Error | null]>;
+    /**
+     * Returns a compact `<username><deviceID>` debug label.
+     */
     toString(): string;
     private redeemInvite;
     private retrieveInvites;