mezon-light-sdk 1.0.2 → 1.0.3

package/dist/client.d.ts

@@ -1,26 +1,137 @@
-import { Session, Client } from 'mezon-js';
+import { Session } from "./session";
+import { ApiSession, MezonApi } from "./api.gen";
+import { ClientInitConfig, AuthenticateConfig } from "./types";
+import { ApiChannelDescription } from "./api.gen";
+import { WebSocketAdapter } from "./web_socket_adapter_pb";
+import { Socket } from "./socket.gen";
+/**
+ * Error thrown when authentication fails.
+ */
+export declare class AuthenticationError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message?: string, statusCode?: number | undefined);
+}
+/**
+ * Error thrown when session-related operations fail.
+ */
+export declare class SessionError extends Error {
+    constructor(message?: string);
+}
+/**
+ * LightClient provides a simplified interface for Mezon authentication and channel management.
+ *
+ * @example
+ * ```typescript
+ * // Initialize from existing tokens
+ * const client = LightClient.initClient({
+ *   token: 'your-token',
+ *   refresh_token: 'your-refresh-token',
+ *   api_url: 'https://api.mezon.ai',
+ *   user_id: 'user-123'
+ * });
+ *
+ * // Or authenticate with ID token
+ * const client = await LightClient.authenticate({
+ *   id_token: 'id-token-from-provider',
+ *   user_id: 'user-123',
+ *   username: 'johndoe'
+ * });
+ * ```
+ */
 export declare class LightClient {
-    private session;
-    private client;
-    user_id: string;
+    private readonly _session;
+    private readonly _client;
+    private readonly _userId;
+    /** Promise that resolves when the refresh token operation completes */
+    private refreshTokenPromise;
     private constructor();
-    static initClient({ token, refresh_token, api_url, user_id, serverkey }: {
-        token: string;
-        refresh_token: string;
-        api_url: string;
-        user_id: string;
-        serverkey: string;
-    }): LightClient;
-    static authenticate({ id_token, user_id, username, serverkey }: {
-        id_token: string;
-        user_id: string;
-        username: string;
-        serverkey: string;
-    }): Promise<LightClient>;
-    createDM(peer_id: string): Promise<import("mezon-js/dist/api.gen").ApiChannelDescription>;
-    refreshSession(): Promise<void>;
-    isSessionExpired(): Promise<boolean>;
-    isRefreshSessionExpired(): Promise<boolean>;
+    /**
+     * Gets the current user ID.
+     */
+    get userId(): string;
+    /**
+     * Gets the underlying Mezon session.
+     */
+    get session(): Session;
+    /**
+     * Gets the underlying Mezon client.
+     */
+    get client(): MezonApi;
+    /**
+     * Initializes a LightClient from existing session tokens.
+     * Use this when you have stored tokens from a previous authentication.
+     *
+     * @param config - Configuration containing tokens and connection details
+     * @returns A new LightClient instance
+     * @throws {SessionError} If required fields are missing
+     */
+    static initClient(config: ClientInitConfig): LightClient;
+    /**
+     * Authenticates a user with an ID token from an identity provider.
+     *
+     * @param config - Authentication configuration
+     * @returns A promise that resolves to a new LightClient instance
+     * @throws {AuthenticationError} If authentication fails or response is invalid
+     */
+    static authenticate(config: AuthenticateConfig): Promise<LightClient>;
+    /**
+     * Creates a direct message channel with a single user.
+     *
+     * @param peerId - The user ID to create a DM channel with
+     * @returns A promise that resolves to the created channel descriptor
+     */
+    createDM(peerId: string): Promise<ApiChannelDescription>;
+    /**
+     * Creates a group direct message channel with multiple users.
+     *
+     * @param userIds - Array of user IDs to include in the group DM
+     * @returns A promise that resolves to the created channel descriptor
+     */
+    createGroupDM(userIds: string[]): Promise<ApiChannelDescription>;
+    /**
+     * Refreshes the current session using the refresh token.
+     * Call this before the session expires to maintain connectivity.
+     *
+     * @returns A promise that resolves when the session is refreshed
+     */
+    refreshSession(): Promise<Session>;
+    /** A socket created with the client's configuration. */
+    createSocket(verbose?: boolean, adapter?: WebSocketAdapter, sendTimeoutMs?: number): Socket;
+    /**
+     * Called when a token refresh is initiated.
+     * This is a placeholder method that subclasses or instances can override
+     * to perform actions before or after the refresh logic.
+     */
+    onRefreshSession(session: ApiSession): void;
+    /**
+     * Checks if the current session token has expired.
+     *
+     * @returns True if the session is expired, false otherwise
+     */
+    isSessionExpired(): boolean;
+    /**
+     * Checks if the refresh token has expired.
+     * If this returns true, the user needs to re-authenticate.
+     *
+     * @returns True if the refresh token is expired, false otherwise
+     */
+    isRefreshSessionExpired(): boolean;
+    /**
+     * Gets the authentication token for external use.
+     */
+    getToken(): string;
+    /**
+     * Gets the refresh token for storage.
+     */
+    getRefreshToken(): string;
+    /**
+     * Gets the current session.
+     */
     getSession(): Session;
-    getClient(): Client;
+    /**
+     * Exports session data for storage and later restoration.
+     *
+     * @returns Object containing all data needed to restore the session
+     */
+    exportSession(): ClientInitConfig;
 }

package/dist/client.js

@@ -1,90 +1,267 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LightClient = void 0;
-const mezon_js_1 = require("mezon-js");
+exports.LightClient = exports.SessionError = exports.AuthenticationError = void 0;
+const session_1 = require("./session");
+const api_gen_1 = require("./api.gen");
 const constants_1 = require("./constants");
-const base64 = __importStar(require("js-base64"));
+const web_socket_adapter_pb_1 = require("./web_socket_adapter_pb");
+const socket_gen_1 = require("./socket.gen");
+/**
+ * Error thrown when authentication fails.
+ */
+class AuthenticationError extends Error {
+    constructor(message, statusCode) {
+        super(message ?? "Authentication failed.");
+        this.statusCode = statusCode;
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/**
+ * Error thrown when session-related operations fail.
+ */
+class SessionError extends Error {
+    constructor(message) {
+        super(message ?? "Session error.");
+        this.name = "SessionError";
+    }
+}
+exports.SessionError = SessionError;
+/**
+ * Parses a URL and extracts client connection parameters.
+ */
+function parseBaseUrl(apiUrl) {
+    const url = new URL(apiUrl);
+    const scheme = url.protocol === "https:" ? "https://" : "http://";
+    return `${scheme}${url.hostname}:${url.port}`;
+}
+/**
+ * LightClient provides a simplified interface for Mezon authentication and channel management.
+ *
+ * @example
+ * ```typescript
+ * // Initialize from existing tokens
+ * const client = LightClient.initClient({
+ *   token: 'your-token',
+ *   refresh_token: 'your-refresh-token',
+ *   api_url: 'https://api.mezon.ai',
+ *   user_id: 'user-123'
+ * });
+ *
+ * // Or authenticate with ID token
+ * const client = await LightClient.authenticate({
+ *   id_token: 'id-token-from-provider',
+ *   user_id: 'user-123',
+ *   username: 'johndoe'
+ * });
+ * ```
+ */
 class LightClient {
-    constructor(session, client, user_id) {
-        this.session = session;
-        this.client = client;
-        this.user_id = user_id;
+    constructor(session, client, userId) {
+        /** Promise that resolves when the refresh token operation completes */
+        this.refreshTokenPromise = null;
+        this._session = session;
+        this._client = client;
+        this._userId = userId;
+    }
+    /**
+     * Gets the current user ID.
+     */
+    get userId() {
+        return this._userId;
     }
-    static initClient({ token, refresh_token, api_url, user_id, serverkey }) {
+    /**
+     * Gets the underlying Mezon session.
+     */
+    get session() {
+        return this._session;
+    }
+    /**
+     * Gets the underlying Mezon client.
+     */
+    get client() {
+        return this._client;
+    }
+    /**
+     * Initializes a LightClient from existing session tokens.
+     * Use this when you have stored tokens from a previous authentication.
+     *
+     * @param config - Configuration containing tokens and connection details
+     * @returns A new LightClient instance
+     * @throws {SessionError} If required fields are missing
+     */
+    static initClient(config) {
+        const { token, refresh_token, api_url, user_id, serverkey } = config;
         if (!token || !refresh_token || !api_url || !user_id) {
-            throw new Error('Missing required fields to restore session from storage');
+            throw new SessionError("Missing required fields: token, refresh_token, api_url, and user_id are all required");
         }
-        const session = mezon_js_1.Session.restore(token, refresh_token, api_url, true);
-        const url = new URL(api_url);
-        const client = new mezon_js_1.Client(serverkey || 'DefaultServerKey', url.hostname, url.port || '', url.protocol === 'https:');
+        const session = session_1.Session.restore(token, refresh_token, api_url, true);
+        const client = new api_gen_1.MezonApi(serverkey || constants_1.DEFAULT_SERVER_KEY, 7000, parseBaseUrl(api_url));
         return new LightClient(session, client, user_id);
     }
-    static async authenticate({ id_token, user_id, username, serverkey }) {
-        const res = await fetch(constants_1.MEZON_GW_URL + '/v2/account/authenticate/idtoken', {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': 'Basic ' + base64.encode(serverkey || 'DefaultServerKey')
-            },
-            body: JSON.stringify({ id_token, user_id, username })
-        });
-        if (!res.ok) {
-            const errData = await res.json().catch(() => ({}));
-            throw new Error(errData.message || 'Error during authentication request');
+    /**
+     * Authenticates a user with an ID token from an identity provider.
+     *
+     * @param config - Authentication configuration
+     * @returns A promise that resolves to a new LightClient instance
+     * @throws {AuthenticationError} If authentication fails or response is invalid
+     */
+    static async authenticate(config) {
+        const { id_token, user_id, username, serverkey = constants_1.DEFAULT_SERVER_KEY, gateway_url = constants_1.MEZON_GW_URL } = config;
+        const client = new api_gen_1.MezonApi(serverkey || constants_1.DEFAULT_SERVER_KEY, 7000, parseBaseUrl(gateway_url));
+        const body = {
+            id_token,
+            user_id,
+            username,
+        };
+        const response = await client.authenticateIdToken(serverkey, "", body);
+        if (!response) {
+            throw new AuthenticationError("Authentication failed: No response from server.");
         }
-        const data = await res.json();
-        if (data && data.token && data.refresh_token && data.api_url && data.user_id) {
-            const session = mezon_js_1.Session.restore(data.token, data.refresh_token, data.api_url, true);
-            const url = new URL(data.api_url);
-            const client = new mezon_js_1.Client(serverkey || 'DefaultServerKey', url.hostname, url.port || '', url.protocol === 'https:');
-            return new LightClient(session, client, data.user_id);
-        }
-        else {
-            throw new Error('Error during authentication or missing data fields!');
+        if (!response.token || !response.refresh_token || !response.api_url || !response.user_id) {
+            throw new AuthenticationError("Invalid authentication response: missing required fields");
         }
+        const session = session_1.Session.restore(response.token, response.refresh_token, response.api_url, true);
+        client.setBasePath(parseBaseUrl(response.api_url));
+        return new LightClient(session, client, response.user_id);
     }
-    async createDM(peer_id) {
-        const req = { type: mezon_js_1.ChannelType.CHANNEL_TYPE_DM, channel_private: 1, user_ids: [peer_id] };
-        const channel = await this.client.createChannelDesc(this.session, req);
-        return channel;
+    /**
+     * Creates a direct message channel with a single user.
+     *
+     * @param peerId - The user ID to create a DM channel with
+     * @returns A promise that resolves to the created channel descriptor
+     */
+    async createDM(peerId) {
+        const request = {
+            type: constants_1.CHANNEL_TYPE_DM,
+            channel_private: 1,
+            user_ids: [peerId],
+        };
+        return this._client.createChannelDesc(this._session.token, request);
     }
+    /**
+     * Creates a group direct message channel with multiple users.
+     *
+     * @param userIds - Array of user IDs to include in the group DM
+     * @returns A promise that resolves to the created channel descriptor
+     */
+    async createGroupDM(userIds) {
+        if (userIds.length === 0) {
+            throw new Error("At least one user ID is required for a group DM");
+        }
+        const request = {
+            type: constants_1.CHANNEL_TYPE_GROUP,
+            channel_private: 1,
+            user_ids: userIds,
+        };
+        return this._client.createChannelDesc(this._session.token, request);
+    }
+    /**
+     * Refreshes the current session using the refresh token.
+     * Call this before the session expires to maintain connectivity.
+     *
+     * @returns A promise that resolves when the session is refreshed
+     */
     async refreshSession() {
-        await this.client.sessionRefresh(this.session);
+        if (!this._session) {
+            console.error("Cannot refresh a null session.");
+            return this._session;
+        }
+        if (this._session.created && this._session.expires_at - this._session.created_at < 70) {
+            console.warn("Session lifetime too short, please set '--session.token_expiry_sec' option. See the documentation for more info: https://mezon.vn/docs/mezon/getting-started/configuration/#session");
+        }
+        if (this._session.created && this._session.refresh_expires_at - this._session.created_at < 3700) {
+            console.warn("Session refresh lifetime too short, please set '--session.refresh_token_expiry_sec' option. See the documentation for more info: https://mezon.vn/docs/mezon/getting-started/configuration/#session");
+        }
+        if (this.refreshTokenPromise) {
+            return this.refreshTokenPromise;
+        }
+        this.refreshTokenPromise = new Promise(async (resolve, reject) => {
+            try {
+                const apiSession = await this.client.sessionRefresh(this._client.serverKey || constants_1.DEFAULT_SERVER_KEY, "", {
+                    token: this._session.refresh_token,
+                    vars: this._session.vars,
+                    is_remember: this._session.is_remember,
+                });
+                this._session.update(apiSession.token, apiSession.refresh_token, apiSession.is_remember || false);
+                this.onRefreshSession(apiSession);
+                resolve(this._session);
+            }
+            catch (error) {
+                console.error("Session refresh failed:", error);
+                reject(error);
+            }
+            finally {
+                this.refreshTokenPromise = null;
+            }
+        });
+        return this.refreshTokenPromise;
+    }
+    /** A socket created with the client's configuration. */
+    createSocket(verbose = false, adapter = new web_socket_adapter_pb_1.WebSocketAdapterPb(), sendTimeoutMs = socket_gen_1.DefaultSocket.DefaultSendTimeoutMs) {
+        const url = new URL(this._client.basePath);
+        const { host, port, useSSL } = {
+            host: url.hostname,
+            port: url.port || (url.protocol === "https:" ? "443" : "80"),
+            useSSL: url.protocol === "https:",
+        };
+        return new socket_gen_1.DefaultSocket(host, port, useSSL, verbose, adapter, sendTimeoutMs);
+    }
+    /**
+     * Called when a token refresh is initiated.
+     * This is a placeholder method that subclasses or instances can override
+     * to perform actions before or after the refresh logic.
+     */
+    onRefreshSession(session) {
+        console.log(`Token refresh occurred. Token: ${session.token}`);
+    }
+    /**
+     * Checks if the current session token has expired.
+     *
+     * @returns True if the session is expired, false otherwise
+     */
+    isSessionExpired() {
+        return this._session.isexpired(Date.now() / 1000);
+    }
+    /**
+     * Checks if the refresh token has expired.
+     * If this returns true, the user needs to re-authenticate.
+     *
+     * @returns True if the refresh token is expired, false otherwise
+     */
+    isRefreshSessionExpired() {
+        return this._session.isrefreshexpired(Date.now() / 1000);
     }
-    async isSessionExpired() {
-        return this.session.isexpired(Date.now() / 1000);
+    /**
+     * Gets the authentication token for external use.
+     */
+    getToken() {
+        return this._session.token;
     }
-    async isRefreshSessionExpired() {
-        return this.session.isrefreshexpired(Date.now() / 1000);
+    /**
+     * Gets the refresh token for storage.
+     */
+    getRefreshToken() {
+        return this._session.refresh_token;
     }
+    /**
+     * Gets the current session.
+     */
     getSession() {
         return this.session;
     }
-    getClient() {
-        return this.client;
+    /**
+     * Exports session data for storage and later restoration.
+     *
+     * @returns Object containing all data needed to restore the session
+     */
+    exportSession() {
+        return {
+            token: this._session.token,
+            refresh_token: this._session.refresh_token,
+            api_url: this._session.api_url || "",
+            user_id: this._userId,
+        };
     }
 }
 exports.LightClient = LightClient;

package/dist/constants.d.ts

@@ -1,4 +1,16 @@
+/** Default Mezon Gateway URL */
 export declare const MEZON_GW_URL = "https://gw.mezon.ai";
+/** Maximum number of retries when waiting for socket to be ready */
 export declare const SOCKET_READY_MAX_RETRY = 20;
+/** Initial delay in milliseconds between socket ready retries (uses exponential backoff) */
 export declare const SOCKET_READY_RETRY_DELAY = 100;
+/** Clan ID used for Direct Messages */
 export declare const CLAN_DM = "0";
+/** Channel type for Direct Messages */
+export declare const CHANNEL_TYPE_DM = 3;
+export declare const CHANNEL_TYPE_GROUP = 2;
+/** Stream mode for Direct Messages */
+export declare const STREAM_MODE_DM = 4;
+export declare const STREAM_MODE_GROUP = 3;
+/** Default server key if none is provided */
+export declare const DEFAULT_SERVER_KEY = "DefaultServerKey";

package/dist/constants.js

@@ -1,7 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLAN_DM = exports.SOCKET_READY_RETRY_DELAY = exports.SOCKET_READY_MAX_RETRY = exports.MEZON_GW_URL = void 0;
+exports.DEFAULT_SERVER_KEY = exports.STREAM_MODE_GROUP = exports.STREAM_MODE_DM = exports.CHANNEL_TYPE_GROUP = exports.CHANNEL_TYPE_DM = exports.CLAN_DM = exports.SOCKET_READY_RETRY_DELAY = exports.SOCKET_READY_MAX_RETRY = exports.MEZON_GW_URL = void 0;
+/** Default Mezon Gateway URL */
 exports.MEZON_GW_URL = 'https://gw.mezon.ai';
+/** Maximum number of retries when waiting for socket to be ready */
 exports.SOCKET_READY_MAX_RETRY = 20;
+/** Initial delay in milliseconds between socket ready retries (uses exponential backoff) */
 exports.SOCKET_READY_RETRY_DELAY = 100;
+/** Clan ID used for Direct Messages */
 exports.CLAN_DM = '0';
+/** Channel type for Direct Messages */
+exports.CHANNEL_TYPE_DM = 3;
+exports.CHANNEL_TYPE_GROUP = 2;
+/** Stream mode for Direct Messages */
+exports.STREAM_MODE_DM = 4;
+exports.STREAM_MODE_GROUP = 3;
+/** Default server key if none is provided */
+exports.DEFAULT_SERVER_KEY = 'DefaultServerKey';