mezon-light-sdk 1.0.2 → 1.0.3

package/README.md

@@ -1,46 +1,259 @@
-# mezon-p2p-chat-sdk
+# Mezon Light SDK
 
-SDK chat P2P cho mezon-js.
+A lightweight SDK for Mezon chat integration, providing simple APIs for authentication, real-time messaging, and direct message management.
 
-# Version SDK Example using to demo 
-` pip install p2p-chat-sdk `
-# Frontend (Client) use SDK
+## Installation
 
-## 1: Import
-
-``` 
-import { P2PClient, P2PSocket, P2PMessage } from 'p2p-chat-sdk';
+```bash
+npm install mezon-light-sdk
 ```
 
-## 2: Create P2PClient:
-```
-const p2p_client = await P2PClient.authenticate({ id_token, user_id, username, serverkey });
+## Features
+
+- 🔐 Simple authentication with ID tokens
+- 💬 Real-time messaging via WebSocket (protobuf-based)
+- 📨 Direct message (DM) and group DM support
+- 🔄 Automatic session management with token refresh
+- 📎 Attachment support for messages
+- 🎯 TypeScript-first with full type definitions
+- ⚡ Exponential backoff for socket connection reliability
+
+## Quick Start
+
+### 1. Authenticate with ID Token
+
+```typescript
+import { LightClient, AuthenticationError } from 'mezon-light-sdk';
+
+try {
+  const client = await LightClient.authenticate({
+    id_token: 'your-id-token',
+    user_id: 'user-123',
+    username: 'johndoe',
+    serverkey: 'your-server-key',     // optional, uses DEFAULT_SERVER_KEY
+    gateway_url: 'https://gw.mezon.ai' // optional, uses MEZON_GW_URL
+  });
+  
+  console.log('Authenticated as:', client.userId);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Auth failed:', error.message, error.statusCode);
+  }
+}
 ```
-## 3: Connect Socket:
+
+### 2. Restore Session from Storage
+
+After login, persist the session data and restore it later:
+
+```typescript
+import { LightClient, SessionError } from 'mezon-light-sdk';
+
+// Export session for storage
+const sessionData = client.exportSession();
+// Returns: { token, refresh_token, api_url, user_id }
+localStorage.setItem('mezon_session', JSON.stringify(sessionData));
+
+// Later: restore from storage
+try {
+  const savedData = JSON.parse(localStorage.getItem('mezon_session')!);
+  const client = LightClient.initClient(savedData);
+} catch (error) {
+  if (error instanceof SessionError) {
+    console.error('Session restore failed:', error.message);
+  }
+}
 ```
-  const p2p_socket = new P2PSocket(p2p_client.getClient(), p2p_client.getSession());
-  await p2p_socket.connect();
+
+### 3. Session Management
+
+Check and refresh the session before connecting:
+
+```typescript
+// Check if session token is expired
+if (client.isSessionExpired()) {
+  // Check if refresh token is still valid
+  if (!client.isRefreshSessionExpired()) {
+    await client.refreshSession();
+    // Update stored session data
+    localStorage.setItem('mezon_session', JSON.stringify(client.exportSession()));
+  } else {
+    // Both tokens expired - need to re-authenticate
+    console.log('Session fully expired, please login again');
+  }
+}
+
+// Access tokens and session directly if needed
+const token = client.getToken();
+const refreshToken = client.getRefreshToken();
+const session = client.getSession();
 ```
-## 4: Listen Message:
+
+### 4. Connect to Real-time Socket
+
+```typescript
+import { LightSocket, SocketError } from 'mezon-light-sdk';
+
+const socket = new LightSocket(client, client.session);
+
+await socket.connect({
+  onError: (error) => console.error('Socket error:', error),
+  onDisconnect: () => console.log('Socket disconnected'),
+  verbose: false // set to true for debug logging
+});
+
+// Check connection status
+console.log('Connected:', socket.isConnected);
 ```
-p2p_socket.setChannelMessageHandler((msg: P2PMessage) => {
-console.log('New message:', msg);
+
+### 5. Listen for Messages
+
+```typescript
+// Register a message handler (returns unsubscribe function)
+const unsubscribe = socket.onChannelMessage((message) => {
+  console.log(`Message from ${message.sender_id}: ${message.content}`);
+  console.log('Channel:', message.channel_id);
+  console.log('Timestamp:', message.create_time_seconds);
+});
+
+// Alternative: use setChannelMessageHandler (does not return unsubscribe)
+socket.setChannelMessageHandler((message) => {
+  console.log('Received:', message.content);
+});
+
+// Multiple handlers can be registered
+const unsubscribe2 = socket.onChannelMessage((message) => {
+  // Another handler for the same messages
 });
 
+// Unsubscribe when no longer needed
+unsubscribe();
+unsubscribe2();
 ```
 
-## 5: Start DM
+### 6. Create and Join Channels
 
+```typescript
+// Create a DM with a single user
+const dmChannel = await client.createDM('peer-user-id');
+await socket.joinDMChannel(dmChannel.channel_id!);
+
+// Create a group DM with multiple users
+const groupDM = await client.createGroupDM(['user-1', 'user-2', 'user-3']);
+await socket.joinGroupChannel(groupDM.channel_id!);
+
+// Leave channels
+await socket.leaveDMChannel(dmChannel.channel_id!);
+await socket.leaveGroupChannel(groupDM.channel_id!);
 ```
-const channel = await p2p_client.createDM(peerId);
-await p2p_socket.joinDMChannel(channel.channel_id);
 
+### 7. Send Messages
+
+```typescript
+// Send a DM message
+await socket.sendDM({
+  channelId: 'channel-123',
+  content: { t: 'Hello, world!' },
+  hideLink: false // optional, whether to hide link previews
+});
+
+// Send a group message
+await socket.sendGroup({
+  channelId: 'group-channel-456',
+  content: { t: 'Hello everyone!' },
+  attachments: [
+    {
+      filename: 'image.png',
+      url: 'https://cdn.mezon.ai/path/to/image.png',
+      filetype: 'image/png',
+      size: 42439,
+      width: 716,
+      height: 522
+    }
+  ],
+  hideLink: true
+});
 ```
 
-## 6: Send Message:
+### 8. Disconnect
 
+```typescript
+// Disconnect when done
+socket.disconnect();
 ```
-await p2p_socket.sendDM(channelId, { t: inputMsg });
+
+## API Reference
+
+### LightClient
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `LightClient.authenticate(config)` | Static: Authenticate with ID token |
+| `LightClient.initClient(config)` | Static: Initialize from existing tokens |
+| `client.userId` | Get current user ID |
+| `client.session` | Get underlying Session object |
+| `client.client` | Get underlying MezonApi client |
+| `client.createDM(peerId)` | Create a DM channel with one user |
+| `client.createGroupDM(userIds)` | Create a group DM with multiple users |
+| `client.refreshSession()` | Refresh the session using refresh token |
+| `client.isSessionExpired()` | Check if session token is expired |
+| `client.isRefreshSessionExpired()` | Check if refresh token is expired |
+| `client.getToken()` | Get the current auth token |
+| `client.getRefreshToken()` | Get the refresh token |
+| `client.getSession()` | Get the current session object |
+| `client.exportSession()` | Export session data for persistence |
+| `client.createSocket(verbose?, adapter?, timeout?)` | Create a raw socket instance |
+
+### LightSocket
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `new LightSocket(client, session)` | Create a new socket instance |
+| `socket.connect(options?)` | Connect to real-time server |
+| `socket.disconnect()` | Disconnect from server |
+| `socket.isConnected` | Check if socket is connected |
+| `socket.socket` | Get underlying Socket (throws if not connected) |
+| `socket.onChannelMessage(handler)` | Register message handler, returns unsubscribe fn |
+| `socket.setChannelMessageHandler(handler)` | Register message handler (alias) |
+| `socket.joinDMChannel(channelId)` | Join a DM channel |
+| `socket.joinGroupChannel(channelId)` | Join a group channel |
+| `socket.leaveDMChannel(channelId)` | Leave a DM channel |
+| `socket.leaveGroupChannel(channelId)` | Leave a group channel |
+| `socket.sendDM(payload)` | Send a DM message |
+| `socket.sendGroup(payload)` | Send a group message |
+| `socket.setErrorHandler(handler)` | Set custom error handler |
+
+### Types
+
+```typescript
+interface ClientInitConfig {
+  token: string;           // Auth token
+  refresh_token: string;   // Refresh token
+  api_url: string;         // API URL
+  user_id: string;         // User ID
+  serverkey?: string;      // Optional server key
+}
+
+interface AuthenticateConfig {
+  id_token: string;        // ID token from provider
+  user_id: string;         // User ID
+  username: string;        // Username
+  serverkey?: string;      // Optional server key
+  gateway_url?: string;    // Optional gateway URL
+}
+
+interface SendMessagePayload {
+  channelId: string;                  // Target channel
+  content: unknown;                   // Message content
+  attachments?: ApiMessageAttachment[]; // Optional attachments
+  hideLink?: boolean;                 // Hide link previews
+}
+
+interface SocketConnectOptions {
+  onError?: (error: unknown) => void;  // Error callback
+  onDisconnect?: () => void;           // Disconnect callback
+  verbose?: boolean;                    // Enable debug logging
+}
 ```
-<img width="767" height="775" alt="Screenshot 2025-12-15 132741" src="https://github.com/user-attachments/assets/3019ca86-de5f-49b7-a05a-3895c754029d" />
 
+---

package/dist/api.gen.d.ts

@@ -0,0 +1,150 @@
+/** A message sent on a channel. */
+export interface ChannelMessage {
+    id: string;
+    avatar?: string;
+    channel_id: string;
+    channel_label: string;
+    clan_id?: string;
+    code: number;
+    content: string;
+    attachments?: Array<ApiMessageAttachment>;
+    referenced_message?: string[];
+    persistent?: boolean;
+    sender_id: string;
+    update_time?: string;
+    clan_logo?: string;
+    category_name?: string;
+    username?: string;
+    clan_nick?: string;
+    clan_avatar?: string;
+    display_name?: string;
+    create_time_seconds?: number;
+    update_time_seconds?: number;
+    mode?: number;
+    message_id?: string;
+    hide_editted?: boolean;
+    is_public?: boolean;
+    topic_id?: string;
+}
+/**  */
+export interface ApiMessageAttachment {
+    filename?: string;
+    filetype?: string;
+    height?: number;
+    size?: number;
+    url?: string;
+    width?: number;
+    thumbnail?: string;
+    channel_id?: string;
+    mode?: number;
+    channel_label?: string;
+    message_id?: string;
+    sender_id?: string;
+    duration?: number;
+    create_time_seconds?: number;
+}
+/** Authenticate against the server with a refresh token. */
+export interface ApiSessionRefreshRequest {
+    is_remember?: boolean;
+    token?: string;
+    vars?: Record<string, string>;
+}
+/** A user's session used to authenticate messages. */
+export interface ApiSession {
+    created?: boolean;
+    refresh_token?: string;
+    token?: string;
+    is_remember?: boolean;
+    api_url?: string;
+    id_token?: string;
+}
+/**  */
+export interface ApiChannelDescription {
+    active?: number;
+    age_restricted?: number;
+    category_id?: string;
+    category_name?: string;
+    channel_id?: string;
+    channel_label?: string;
+    channel_private?: number;
+    clan_id?: string;
+    clan_name?: string;
+    count_mess_unread?: number;
+    create_time_seconds?: number;
+    creator_id?: string;
+    creator_name?: string;
+    e2ee?: number;
+    is_mute?: boolean;
+    last_pin_message?: string;
+    last_seen_message?: ApiChannelMessageHeader;
+    last_sent_message?: ApiChannelMessageHeader;
+    meeting_code?: string;
+    channel_avatar?: string;
+    parent_id?: string;
+    type?: number;
+    update_time_seconds?: number;
+    app_id?: string;
+    topic?: string;
+    user_ids?: Array<string>;
+    usernames?: Array<string>;
+    display_names?: Array<string>;
+    onlines?: Array<boolean>;
+    avatars?: Array<string>;
+    member_count?: number;
+}
+/**  */
+export interface ApiChannelMessageHeader {
+    attachment?: Uint8Array;
+    content?: string;
+    id?: string;
+    mention?: Uint8Array;
+    reaction?: Uint8Array;
+    reference?: Uint8Array;
+    repliers?: Array<string>;
+    sender_id?: string;
+    timestamp_seconds?: number;
+}
+/** Create a channel within clan. */
+export interface ApiCreateChannelDescRequest {
+    app_id?: string;
+    category_id?: string;
+    channel_id?: string;
+    channel_label?: string;
+    channel_private?: number;
+    clan_id?: string;
+    parent_id?: string;
+    type?: number;
+    user_ids?: Array<string>;
+}
+export interface ApiAuthenticationIdToken {
+    /** ID token from identity provider */
+    id_token: string;
+    /** User ID associated with the token. */
+    user_id: string;
+    /** Username associated with the token. */
+    username: string;
+}
+export interface AuthenticationIdTokenResponse {
+    /** Authentication token */
+    token: string;
+    /** Refresh token for session renewal */
+    refresh_token: string;
+    /** API URL for the authenticated user */
+    api_url: string;
+    /** User ID of the authenticated user */
+    user_id: string;
+}
+export declare class MezonApi {
+    readonly serverKey: string;
+    readonly timeoutMs: number;
+    basePath: string;
+    constructor(serverKey: string, timeoutMs: number, basePath: string);
+    setBasePath(basePath: string): void;
+    /** Create a new channel with the current user as the owner. */
+    authenticateIdToken(basicAuthUsername: string, basicAuthPassword: string, body: ApiAuthenticationIdToken, options?: any): Promise<AuthenticationIdTokenResponse>;
+    /** Refresh a user's session using a refresh token retrieved from a previous authentication request. */
+    sessionRefresh(basicAuthUsername: string, basicAuthPassword: string, body: ApiSessionRefreshRequest, options?: any): Promise<ApiSession>;
+    /** Create a new channel with the current user as the owner. */
+    createChannelDesc(bearerToken: string, body: ApiCreateChannelDescRequest, options?: any): Promise<ApiChannelDescription>;
+    buildFullUrl(basePath: string, fragment: string, queryParams: Map<string, any>): string;
+}

package/dist/api.gen.js

@@ -0,0 +1,149 @@
+"use strict";
+// tslint:disable
+/* Code generated by openapi-gen/main.go. DO NOT EDIT. */
+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.MezonApi = void 0;
+const utils_1 = require("./utils");
+const tsproto = __importStar(require("./proto/api"));
+const js_base64_1 = require("js-base64");
+class MezonApi {
+    constructor(serverKey, timeoutMs, basePath) {
+        this.serverKey = serverKey;
+        this.timeoutMs = timeoutMs;
+        this.basePath = basePath;
+    }
+    setBasePath(basePath) {
+        this.basePath = basePath;
+    }
+    /** Create a new channel with the current user as the owner. */
+    authenticateIdToken(basicAuthUsername, basicAuthPassword, body, options = {}) {
+        if (body === null || body === undefined) {
+            throw new Error("'body' is a required parameter but is null or undefined.");
+        }
+        const urlPath = "/v2/account/authenticate/idtoken";
+        const queryParams = new Map();
+        let bodyJson = "";
+        bodyJson = JSON.stringify(body || {});
+        const fullUrl = this.buildFullUrl(this.basePath, urlPath, queryParams);
+        const fetchOptions = (0, utils_1.buildFetchOptions)("POST", options, bodyJson);
+        if (basicAuthUsername) {
+            fetchOptions.headers["Authorization"] = "Basic " + (0, js_base64_1.encode)(basicAuthUsername + ":" + basicAuthPassword);
+        }
+        return Promise.race([
+            fetch(fullUrl, fetchOptions).then((response) => {
+                if (response.status == 204) {
+                    return response;
+                }
+                else if (response.status >= 200 && response.status < 300) {
+                    return response.json();
+                }
+                else {
+                    throw response;
+                }
+            }),
+            new Promise((_, reject) => setTimeout(reject, this.timeoutMs, "Request timed out.")),
+        ]);
+    }
+    /** Refresh a user's session using a refresh token retrieved from a previous authentication request. */
+    sessionRefresh(basicAuthUsername, basicAuthPassword, body, options = {}) {
+        if (body === null || body === undefined) {
+            throw new Error("'body' is a required parameter but is null or undefined.");
+        }
+        const urlPath = "/mezon.api.Mezon/SessionRefresh";
+        const queryParams = new Map();
+        const bodyWriter = tsproto.SessionRefreshRequest.encode(tsproto.SessionRefreshRequest.fromPartial(body));
+        const encodedBody = bodyWriter.finish();
+        const fullUrl = this.buildFullUrl(this.basePath, urlPath, queryParams);
+        const fetchOptions = (0, utils_1.buildFetchOptions)("POST", options, "");
+        fetchOptions.body = encodedBody;
+        if (basicAuthUsername) {
+            fetchOptions.headers["Authorization"] = "Basic " + (0, js_base64_1.encode)(basicAuthUsername + ":" + basicAuthPassword);
+        }
+        return Promise.race([
+            fetch(fullUrl, fetchOptions).then(async (response) => {
+                if (response.status == 204) {
+                    return {};
+                }
+                else if (response.status >= 200 && response.status < 300) {
+                    const buffer = await response.arrayBuffer();
+                    return tsproto.Session.decode(new Uint8Array(buffer));
+                }
+                else {
+                    throw response;
+                }
+            }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("Request timed out.")), this.timeoutMs)),
+        ]);
+    }
+    /** Create a new channel with the current user as the owner. */
+    createChannelDesc(bearerToken, body, options = {}) {
+        if (body === null || body === undefined) {
+            throw new Error("'body' is a required parameter but is null or undefined.");
+        }
+        const urlPath = "/mezon.api.Mezon/CreateChannelDesc";
+        const queryParams = new Map();
+        const bodyWriter = tsproto.CreateChannelDescRequest.encode(tsproto.CreateChannelDescRequest.fromPartial(body));
+        const encodedBody = bodyWriter.finish();
+        const fullUrl = this.buildFullUrl(this.basePath, urlPath, queryParams);
+        const fetchOptions = (0, utils_1.buildFetchOptions)("POST", options, "");
+        fetchOptions.body = encodedBody;
+        if (bearerToken) {
+            fetchOptions.headers["Authorization"] = "Bearer " + bearerToken;
+        }
+        return Promise.race([
+            fetch(fullUrl, fetchOptions).then(async (response) => {
+                if (response.status == 204) {
+                    return {};
+                }
+                else if (response.status >= 200 && response.status < 300) {
+                    const buffer = await response.arrayBuffer();
+                    return tsproto.ChannelDescription.decode(new Uint8Array(buffer));
+                }
+                else {
+                    throw response;
+                }
+            }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("Request timed out.")), this.timeoutMs)),
+        ]);
+    }
+    buildFullUrl(basePath, fragment, queryParams) {
+        let fullPath = basePath + fragment + "?";
+        for (let [k, v] of queryParams) {
+            if (v instanceof Array) {
+                fullPath += v.reduce((prev, curr) => {
+                    return prev + encodeURIComponent(k) + "=" + encodeURIComponent(curr) + "&";
+                }, "");
+            }
+            else {
+                if (v != null) {
+                    fullPath += encodeURIComponent(k) + "=" + encodeURIComponent(v) + "&";
+                }
+            }
+        }
+        return fullPath;
+    }
+}
+exports.MezonApi = MezonApi;