Class Client

Client provides an interface for you to use a vex chat server and send end to end encrypted messages to other users.

Example

import { Client } from "@vex-chat/libvex";

async function main() {
    // generate a secret key to use, save this somewhere permanent
    const privateKey = Client.generateSecretKey();

    const client = new Client(privateKey);

    // the ready event is emitted when init() is finished.
    // you must wait until this event fires to perform
    // registration or login.
    client.on("ready", async () => {
        // you must register once before you can log in
        await client.register(Client.randomUsername());
        await client.login();
    })

    // The authed event fires when login() successfully completes
    // and the server indicates you are authorized. You must wait to
    // perform any operations besides register() and login() until
    // this occurs.
    client.on("authed", async () => {
        const me = await client.users.me();

        // send a message
        await client.messages.send(me.userID, "Hello world!");
    })

    // Outgoing and incoming messages are emitted here.
    client.on("message", (message) => {
        console.log("message:", message);
    })

    // you must call init() to initialize the keyring and
    // start the client.
    client.init();
}

main();

Hierarchy

EventEmitter
- Client

Properties

channels

channels: IChannels = ...

Channel operations.

devices

devices: IDevices = ...

Device management methods.

emoji

emoji: IEmojis = ...

Emoji operations.

Example

const emoji = await client.emoji.create(imageBuffer, "party", serverID);
const list = await client.emoji.retrieveList(serverID);

files

files: IFiles = ...

File upload/download methods.

hasInit

hasInit: boolean = false

This is true if the client has ever been initialized. You can only initialize a client once.

hasLoggedIn

hasLoggedIn: boolean = false

This is true if the client has ever logged in before. You can only login a client once.

invites

invites: IInvites = ...

Invite-management methods.

me

me: IMe = ...

Helpers for information/actions related to the currently authenticated account.

messages

messages: IMessages = ...

Message operations (direct and group).

Example

await client.messages.send(userID, "Hello!");
await client.messages.group(channelID, "Hello channel!");
const dmHistory = await client.messages.retrieve(userID);

moderation

moderation: IModeration = ...

Server moderation helper methods.

permissions

permissions: IPermissions = ...

Permission-management methods for the current user.

sending

sending: Record<string, IDevice> = {}

servers

servers: IServers = ...

Server operations.

Example

const servers = await client.servers.retrieve();
const created = await client.servers.create("Team Space");

sessions

sessions: ISessions = ...

Encryption-session helpers.

users

users: IUsers = ...

User operations.

Example

const [user] = await client.users.retrieve("alice");
const familiarUsers = await client.users.familiars();

`Static`decryptKeyData

decryptKeyData: (keyData: Uint8Array, password: string) => string = XUtils.decryptKeyData

Decrypts a secret key from encrypted data produced by encryptKeyData().

Pass-through utility from @vex-chat/crypto.

Type Declaration

- (keyData: Uint8Array, password: string): string
- Decrypts a secret key from the binary format produced by encryptKeyData(). No I/O — the caller handles reading the data.
  Parameters
  - keyData: Uint8Array
    The encrypted key data as a Uint8Array.
  - password: string
    The password used to encrypt.
  Returns string
  The hex-encoded secret key.

`Static`encryptKeyData

encryptKeyData: (
    password: string,
    keyToSave: string,
    iterationOverride?: number,
) => Uint8Array = XUtils.encryptKeyData

Encrypts a secret key with a password.

Pass-through utility from @vex-chat/crypto.

Type Declaration

- (password: string, keyToSave: string, iterationOverride?: number): Uint8Array
- Encrypts a secret key with a password and saves it as a file.
  Parameters
  - password: string
    The password to derive the encryption key from.
  - keyToSave: string
    The hex-encoded secret key to encrypt.
  - OptionaliterationOverride: number
    Optional PBKDF2 iteration count (random if omitted).
  Returns Uint8Array
  The encrypted key data as a Uint8Array.

Methods

close

close(muteEvent?: boolean): Promise<void>
Manually closes the client. Emits the closed event on successful shutdown.
Parameters
- muteEvent: boolean = false
Returns Promise<void>
- Defined in Client.ts:1188

connect

connect(): Promise<void>
Connects your device to the chat. You must have a valid Bearer token. You can check whoami() to see before calling connect().

Returns Promise<void>
- Defined in Client.ts:1348

getHost

getHost(): string
Returns the current HTTP API origin with protocol.

Returns string
Example
```
console.log(client.getHost()); // "https://api.vex.wtf"
```
- Defined in Client.ts:1181

getKeys

getKeys(): IKeys
Gets the hex string representations of the public and private keys.

Returns IKeys
- Defined in Client.ts:1213

login(username: string, password: string): Promise<Error | null>
Authenticates with username/password and stores the Bearer auth token.
Parameters
- username: string
  Account username.
- password: string
  Account password.
Returns Promise<Error | null>
null on success, or the thrown error object on failure.
Example
```
const err = await client.login("alice", "correct horse battery staple");
if (err) console.error(err);
```
- Defined in Client.ts:1233

loginWithDeviceKey

loginWithDeviceKey(deviceID?: string): Promise<Error | null>
Authenticates using the device's Ed25519 signing key. No password needed — proves possession of the private key via challenge-response. Issues a short-lived (1-hour) JWT.

Used by auto-login when stored credentials have a deviceKey but no valid session.
Parameters
- OptionaldeviceID: string
Returns Promise<Error | null>
- Defined in Client.ts:1269

logout

logout(): Promise<void>
Logs out the current authenticated session from the server.

Returns Promise<void>
- Defined in Client.ts:1340

register

register(
username: string,
password: string,
): Promise<[IUser | null, Error | null]>
Registers a new account on the server.
Parameters
- username: string
  The username to register. Must be unique.
- password: string
Returns Promise<[IUser | null, Error | null]>
The error, or the user object.
Example
```
[user, err] = await client.register("MyUsername");
```
- Defined in Client.ts:1393

toString

toString(): string
Returns a compact <username><deviceID> debug label.

Returns string
- Defined in Client.ts:1446

whoami

whoami(): Promise<{ exp: number; token: string; user: IUser }>
Returns details about the currently authenticated session.

Returns Promise<{ exp: number; token: string; user: IUser }>
The authenticated user, token expiry, and active token.
Example
```
const auth = await client.whoami();
console.log(auth.user.username, new Date(auth.exp));
```
- Defined in Client.ts:1322

`Static`create

create(
    privateKey?: string,
    options?: IClientOptions,
    storage?: IStorage,
): Promise<Client>
Creates and initializes a client in one step.
Parameters
- OptionalprivateKey: string
  Optional hex secret key. When omitted, a fresh key is generated.
- Optionaloptions: IClientOptions
  Runtime options.
- Optionalstorage: IStorage
  Optional custom storage backend implementing IStorage.
Returns Promise<Client>
Example
```
const client = await Client.create(privateKey, { host: "api.vex.wtf" });
```
- Defined in Client.ts:689

`Static`generateSecretKey

generateSecretKey(): string
Generates an ed25519 secret key as a hex string.

Returns string
- A secret key to use for the client. Save it permanently somewhere safe.
- Defined in Client.ts:743

`Static`randomUsername

randomUsername(): string
Generates a random username using bip39.

Returns string
- The username.
- Defined in Client.ts:752

Events

on

on(event: "fileProgress", callback: (progress: IFileProgress) => void): this
This is emitted for file progress events.

Example:
```
  client.on("ready", () => {
      await client.register()
  });
```
Parameters
- event: "fileProgress"
- callback: (progress: IFileProgress) => void
Returns this
- Defined in Client.ts:482
on(event: "ready", callback: () => void): this
This is emitted whenever the keyring is done initializing after an init() call. You must wait to login or register until after this event.

Example:
```
  client.on("ready", () => {
      await client.register()
  });
```
Parameters
- event: "ready"
- callback: () => void
Returns this
- Defined in Client.ts:501
on(event: "decryptingMail", 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.
Parameters
- event: "decryptingMail"
- callback: () => void
Returns this
- Defined in Client.ts:512
on(event: "connected", callback: () => void): this
This is emitted when you are connected to the chat.

Example:
```
  client.on("connected", (user) => {
      // do something
  });
```
Parameters
- event: "connected"
- callback: () => void
Returns this
- Defined in Client.ts:528
on(event: "message", callback: (message: IMessage) => void): this
This is emitted for every sent and received message.

Example:
```
  client.on("message", (msg: IMessage) => {
      console.log(message);
  });
```
Parameters
- event: "message"
- callback: (message: IMessage) => void
Returns this
- Defined in Client.ts:543
on(event: "permission", callback: (permission: IPermission) => void): this
This is emitted when the user is granted a new permission.

Example:
```
  client.on("permission", (perm: IPermission) => {
      console.log(perm);
  });
```
Parameters
- event: "permission"
- callback: (permission: IPermission) => void
Returns this
- Defined in Client.ts:558
on(event: "session", callback: (session: ISession, user: IUser) => void): this
This is emitted for a new encryption session being created with a specific user.

Example:
```
  client.on("session", (session: ISession, user: IUser) => {
      console.log(session);
      console.log(user);
  });
```
Parameters
- event: "session"
- callback: (session: ISession, user: IUser) => void
Returns this
- Defined in Client.ts:575
on(event: "disconnect", callback: () => void): this
This is emitted whenever the connection is closed. You must discard the client and connect again with a fresh one.

Example:
```
  client.on("disconnect", () => {
    // do something
  });
```
Parameters
- event: "disconnect"
- callback: () => void
Returns this
- Defined in Client.ts:594
on(event: "closed", callback: () => void): this
This is emitted whenever the close() event is called and completed successfully. Note this is not fired for an unintentional disconnect, see the disconnect event.

Example:
```
  client.on("closed", () => {
      process.exit(0);
  });
```
Parameters
- event: "closed"
- callback: () => void
Returns this
- Defined in Client.ts:612

Class Client

Example

Hierarchy

Index

Properties

Methods

Events

Properties

channels

devices

emoji

Example

files

hasInit

hasLoggedIn

invites

me

messages

Example

moderation

permissions

sending

servers

Example

sessions

users

Example

StaticdecryptKeyData

Type Declaration

Parameters

Returns string

StaticencryptKeyData

Type Declaration

Parameters

Returns Uint8Array

Methods

close

Parameters

Returns Promise<void>

connect

Returns Promise<void>

getHost

Returns string

Example

getKeys

Returns IKeys

login

Parameters

Returns Promise<Error | null>

Example

loginWithDeviceKey

Parameters

Returns Promise<Error | null>

logout

Returns Promise<void>

register

Parameters

Returns Promise<[IUser | null, Error | null]>

Example

toString

Returns string

whoami

Returns Promise<{ exp: number; token: string; user: IUser }>

Example

Staticcreate

Parameters

Returns Promise<Client>

Example

StaticgenerateSecretKey

Returns string

StaticrandomUsername

Returns string

Events

on

Parameters

Returns this

Parameters

Returns this

Parameters

Returns this

`Static`decryptKeyData

`Static`encryptKeyData

`Static`create

`Static`generateSecretKey

`Static`randomUsername