simple_node_characterai 1.1.1 → 1.2.0

package/README.md

@@ -7,6 +7,7 @@ Simple Node.js library for interacting with Character.AI via HTTP and WebSocket
 ## Features
 - Authenticate with a session token and initialize a WebSocket
 - Create one-on-one chats with characters
+- Create group chats with characters
 - Send messages and await final replies
 - Fetch chat turns (messages) with pagination
 - Minimal, typed API with clear data models
@@ -112,6 +113,153 @@ app.get('/messages/:chatId', async (c) => {
 export default app
 ```
 
+## Group Chat Quick Start
+
+**Warning**: Connection to room chat is cannot more than 1 connection. so you cannot mass use it.
+
+```ts
+import { 
+  authenticate,
+  createGroupChat
+  listGroupChat,
+  connectGroupChat,
+  sendGroupMessage,
+  generateTurnGroupMessage,
+  disconnectGroupChat
+} from 'simple_node_characterai';
+
+(async () => {
+  await authenticate('YOUR_SESSION_TOKEN');
+
+  // 1) List Groups
+  const listGroups = await listGroupChats();
+
+  // 2) Create Group Chat
+  const createGroupChat = await createGroupChat('My Group Chat', ['CHARACTER_ID_1', 'CHARACTER_ID_2']);
+
+  // Assuming we pick the first room or use a known ID
+  const roomId = 'ROOM_ID'; 
+
+  // 3) Connect
+  const connect = await connectGroupChat(roomId);
+
+  // 4) Send Message
+  const sendMessage = await sendGroupMessage('Hi!', roomId);
+  console.log(JSON.stringify(sendMessage, null, 4));
+
+  // 5) Generate Turn Message
+  const generateResponse = await generateTurnGroupMessage(roomId);
+  console.log(JSON.stringify(generateResponse.push, null, 4));
+
+  // 6) Disconnect
+  await disconnectGroupChat(roomId);
+})();
+```
+
+## Example with Hono Route Handler (Group Chat)
+
+```ts
+import { Hono } from 'hono'
+import { 
+  authenticate,
+  listGroupChat,
+  CreateGroupChat
+  connectGroupChat,
+  sendGroupMessage,
+  generateTurnGroupMessage,
+  disconnectGroupChat
+} from 'simple_node_characterai';
+
+const app = new Hono();
+
+(async () => {
+  await authenticate(process.env.CHARACTERAI_TOKEN!);
+})();
+
+// List all group chats
+app.get('/group', async (c) => {
+  try {
+    const list = await listGroupChat();
+    return c.json(list);
+  } catch (e) {
+    return c.json({ error: 'Failed to list groups' }, 500);
+  }
+});
+
+// Create a group chat
+// Body: {title: string, characterIds: string | string[]}
+// Store the id somewhere
+app.post('/group', async (c) => {
+  try {
+    const body = await c.req.json();
+    const title = body?.title;
+    const characterIds = body?.characterIds;
+    if (!title || !characterIds) return c.json({ error: 'title and characterIds are required' }, 400);
+    const createGroupChat = await createGroupChat(title, characterIds);
+    return c.json(createGroupChat);
+  } catch (e) {
+    return c.json({ error: 'Failed to create group chat' }, 500);
+  }
+});
+
+// Connect to a group chat room
+// Params: { roomId: string }
+app.post('/group/:roomId/connect', async (c) => {
+  try {
+    const roomId = c.req.param('roomId');
+    if (!roomId) return c.json({ error: 'roomId is required' }, 400);
+    const connect = await connectGroupChat(roomId);
+    return c.json(connect);
+  } catch (e) {
+    return c.json({ error: 'Failed to connect' }, 500);
+  }
+});
+
+// Send a message to a group chat
+// Body: { message: string }
+// After sending a message, you must generate a turn to get the response, this message function is return your message, not the character reply itself
+app.post('/group/:roomId/message', async (c) => {
+  try {
+    const roomId = c.req.param('roomId');
+    if (!roomId) return c.json({ error: 'roomId is required' }, 400);
+    const body = await c.req.json();
+    const message = body?.message;
+    if (!message) return c.json({ error: 'Message is required' }, 400);
+    const sendMessage = await sendGroupMessage(message, roomId);
+    return c.json(sendMessage);
+  } catch (e) {
+    return c.json({ error: 'Failed to send message' }, 500);
+  }
+});
+
+// Generate a turn in the group chat after sending a message
+app.post('/group/:roomId/generate', async (c) => {
+  try {
+    const roomId = c.req.param('roomId');
+    if (!roomId) return c.json({ error: 'roomId is required' }, 400);
+    const generateResponse = await generateTurnGroupMessage(roomId);
+    return c.json(generateResponse);
+  } catch (e) {
+    return c.json({ error: 'Failed to generate turn' }, 500);
+  }
+});
+
+// Disconnect a group chat room
+// Params: { roomId: string }
+app.post('/group/:roomId/disconnect', async (c) => {
+  try {
+    const roomId = c.req.param('roomId');
+    if (!roomId) return c.json({ error: 'roomId is required' }, 400);
+    const disconnect = await disconnectGroupChat(roomId);
+    return c.json(disconnect);
+  } catch (e) {
+    return c.json({ error: 'Failed to disconnect' }, 500);
+  }
+});
+
+export default app
+```
+
 ## Find Authorization Token
 <img width="795" height="550" alt="image" src="https://github.com/user-attachments/assets/fefe6262-00cb-4a1f-82da-51a4c96ef299" />
 
@@ -159,10 +307,33 @@ https://character.ai/chat/{characterId}?hist={chatId}
 - Retrieves up to 50 turns for the given chat.
 - If a `token` is provided, fetches the next page of results using `next_token`.
 
+### Group Chat
+
+#### listGroupChat(): Promise<{rooms: GroupChat[]}>
+- Lists all group chats (rooms) the user is a member of.
+
+#### createGroupChat(title: string, characters_id: string | string[]): Promise<GroupChat>
+- Creates a new group chat room with specified characters.
+
+#### connectGroupChat(roomId: string): Promise<ConnectGroupChatResponse>
+- Connects to a specific group chat room via WebSocket.
+
+#### disconnectGroupChat(roomId: string): Promise<disconnectGroupChatPayload>
+- Disconnects from a specific group chat room via WebSocket.
+
+#### sendGroupMessage(message: string, chatId: string): Promise<MessageGroupResponse>
+- Sends a message to a group chat room.
+
+#### generateTurnGroupMessage(chatId: string): Promise<MessageGroupGenerateTurnResponse>
+- Triggers the characters in the group chat to generate a turn/reply.
+
 ## Notes
 - This package is intended for personal use.
 - Avoid logging tokens, cookies, or PII; keep sensitive information in memory.
 - When building client-side applications, follow CORS restrictions; this package is designed for server-side Node usage.
 
 ## Development
-Still in development but ready to use for basic chatting usage, more feature will be added in the future.
+Still in development but ready to use for basic chatting usage, more feature will be added in the future.
+
+## Support
+If you like this package, support me with stars in github, its help me so much

package/dist/Auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAMtC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAU,cAAc,MAAM,KAAI,OAAO,CAAC,IAAI,CAoBtE,CAAA;AAoBD;;;GAGG;AACH,eAAO,MAAM,UAAU,QAAQ,OAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAMtC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAU,cAAc,MAAM,KAAI,OAAO,CAAC,IAAI,CA2BtE,CAAA;AAoBD;;;GAGG;AACH,eAAO,MAAM,UAAU,QAAQ,OAAe,CAAC"}

package/dist/Auth/index.js

@@ -26,8 +26,13 @@ const authenticate = async (sessionToken) => {
             edgeRollout: "60",
             authorization: sessionToken
         });
+        await (0, Websocket_1.connectGroup)({
+            edgeRollout: "60",
+            authorization: sessionToken
+        });
     }
     catch (error) {
+        console.log(error);
         throw Error(`Failed to initialize Character AI, Error: ${error}`);
     }
 };

package/dist/Auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/Auth/index.ts"],"names":[],"mappings":";;;AACA,4CAAuC;AACvC,gCAA8C;AAE9C,IAAI,IAAI,GAAY,EAAa,CAAC;AAElC;;;;;GAKG;AACI,MAAM,YAAY,GAAG,KAAK,EAAE,YAAoB,EAAkB,EAAE;IACvE,IAAI,CAAC;QACD,IAAI,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,YAAY,GAAG,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;QAEnH,IAAA,iBAAW,EAAC,YAAY,CAAC,CAAC;QAE1B,MAAM,GAAG,GAAG,MAAM,IAAA,aAAO,EAAC,+CAA+C,EAAE;YACvE,MAAM,EAAE,KAAK;YACb,oBAAoB,EAAE,IAAI;SAC7B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAE1D,MAAM,WAAW,EAAE,CAAC;QACpB,MAAM,IAAA,mBAAO,EAAC;YACV,WAAW,EAAE,IAAI;YACjB,aAAa,EAAE,YAAY;SAC9B,CAAC,CAAC;IACP,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACtB,MAAM,KAAK,CAAC,6CAA6C,KAAK,EAAE,CAAC,CAAC;IACtE,CAAC;AACL,CAAC,CAAA;AApBY,QAAA,YAAY,gBAoBxB;AAED;;;;GAIG;AACH,MAAM,WAAW,GAAG,KAAK,IAAoB,EAAE;IAC3C,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAA,aAAO,EAAC,sCAAsC,EAAE;YACjE,MAAM,EAAE,KAAK;YACb,oBAAoB,EAAE,IAAI;SAC7B,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACtB,MAAM,KAAK,CAAC,oDAAoD,KAAK,EAAE,CAAC,CAAC;IAC7E,CAAC;AACL,CAAC,CAAA;AAED;;;GAGG;AACI,MAAM,UAAU,GAAG,GAAa,EAAE,CAAC,IAAI,CAAC;AAAlC,QAAA,UAAU,cAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/Auth/index.ts"],"names":[],"mappings":";;;AACA,4CAAqD;AACrD,gCAA8C;AAE9C,IAAI,IAAI,GAAY,EAAa,CAAC;AAElC;;;;;GAKG;AACI,MAAM,YAAY,GAAG,KAAK,EAAE,YAAoB,EAAkB,EAAE;IACvE,IAAI,CAAC;QACD,IAAI,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,YAAY,GAAG,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;QAEnH,IAAA,iBAAW,EAAC,YAAY,CAAC,CAAC;QAE1B,MAAM,GAAG,GAAG,MAAM,IAAA,aAAO,EAAC,+CAA+C,EAAE;YACvE,MAAM,EAAE,KAAK;YACb,oBAAoB,EAAE,IAAI;SAC7B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAE1D,MAAM,WAAW,EAAE,CAAC;QAEpB,MAAM,IAAA,mBAAO,EAAC;YACV,WAAW,EAAE,IAAI;YACjB,aAAa,EAAE,YAAY;SAC9B,CAAC,CAAC;QAEH,MAAM,IAAA,wBAAY,EAAC;YACf,WAAW,EAAE,IAAI;YACjB,aAAa,EAAE,YAAY;SAC9B,CAAC,CAAC;IACP,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,MAAM,KAAK,CAAC,6CAA6C,KAAK,EAAE,CAAC,CAAC;IACtE,CAAC;AACL,CAAC,CAAA;AA3BY,QAAA,YAAY,gBA2BxB;AAED;;;;GAIG;AACH,MAAM,WAAW,GAAG,KAAK,IAAoB,EAAE;IAC3C,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAA,aAAO,EAAC,sCAAsC,EAAE;YACjE,MAAM,EAAE,KAAK;YACb,oBAAoB,EAAE,IAAI;SAC7B,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACtB,MAAM,KAAK,CAAC,oDAAoD,KAAK,EAAE,CAAC,CAAC;IAC7E,CAAC;AACL,CAAC,CAAA;AAED;;;GAGG;AACI,MAAM,UAAU,GAAG,GAAa,EAAE,CAAC,IAAI,CAAC;AAAlC,QAAA,UAAU,cAAwB"}

package/dist/Chat/index.d.ts

@@ -1,27 +1,18 @@
-import { AddTurnResponse, UpdateTurnResponse, Turn } from "../types/Chat";
+import { AddTurnResponse, UpdateTurnResponse, Turn, ConnectGroupChatResponse, disconnectGroupChatPayload, GroupChat, MessageGroupResponse, MessageGroupGenerateTurnResponse } from "../types/Chat";
 /**
  * Creates a new one-on-one chat for the given character.
  * Opens a WebSocket request and resolves when the initial turn is added.
  * @param characterId - The ID of the character to start a chat with.
- * @returns AddTurnResponse containing chat metadata and the greeting turn.
+ * @returns {Promise<AddTurnResponse>} AddTurnResponse containing chat metadata and the greeting turn.
  */
 export declare const createNewConversation: (characterId: string) => Promise<AddTurnResponse>;
-/**
- * Sends a message to an existing chat and waits for the final reply.
- * Uses the WebSocket to create and generate a turn, resolving on final candidate.
- * @param message - The user's text message to send.
- * @param characterId - The target character's ID.
- * @param chatId - The ID of the chat where the message is posted.
- * @returns UpdateTurnResponse containing the generated turn with final candidate.
- */
-export declare const sendMessage: (message: string, characterId: string, chatId: string) => Promise<UpdateTurnResponse>;
 /**
  * Retrieves up to 50 messages (turns) for a given chat.
  * If a `token` is provided, it fetches the next page of results.
  * Token can be null in the end of the chat.
  * @param chatId - The ID of the chat whose messages are to be fetched.
  * @param token - Optional pagination token for retrieving the next batch.
- * @return Parsed JSON containing up to 50 messages in turns field, and the token for pagination in meta field.
+ * @returns {Promise<{turns: Turn[], meta: {next_token: string | null}}>} Parsed JSON containing up to 50 messages in turns field, and the token for pagination in meta field.
  */
 export declare const getMessages: (chatId: string, token?: string) => Promise<{
     turns: Turn[];
@@ -29,4 +20,54 @@ export declare const getMessages: (chatId: string, token?: string) => Promise<{
         next_token: string | null;
     };
 }>;
+/**
+ * Sends a message to an existing chat and waits for the final reply.
+ * Uses the WebSocket to create and generate a turn, resolving on final candidate.
+ * @param message - The user's text message to send.
+ * @param characterId - The target character's ID.
+ * @param chatId - The ID of the chat where the message is posted.
+ * @returns {Promise<UpdateTurnResponse>} UpdateTurnResponse containing the generated turn with final candidate.
+ */
+export declare const sendMessage: (message: string, characterId: string, chatId: string) => Promise<UpdateTurnResponse>;
+/**
+ * Lists all group chats (rooms) the user is a member of.
+ * @returns {Promise<{rooms: GroupChat[]}>} Promise resolving to an object containing an array of GroupChat rooms.
+ */
+export declare const listGroupChats: () => Promise<{
+    rooms: GroupChat[];
+}>;
+/**
+ * Creates a new group chat room with specified characters.
+ * @param title - The title of the group chat room.
+ * @param characters_id - A single character ID or an array of character IDs to include in the group.
+ * @returns {Promise<GroupChat>} Promise resolving to the created GroupChat object.
+ */
+export declare const createGroupChat: (title: string, characters_id: string | string[]) => Promise<GroupChat>;
+/**
+ * Connects to a specific group chat room via WebSocket.
+ * Subscribes to the room channel to receive updates.
+ * @param roomId - The ID of the room to connect to.
+ * @returns {Promise<ConnectGroupChatResponse>} Promise resolving to the connection response.
+ */
+export declare const connectGroupChat: (roomId: string) => Promise<ConnectGroupChatResponse>;
+/**
+ * Disconnects from a specific group chat room via WebSocket.
+ * Unsubscribes from the room channel.
+ * @param roomId - The ID of the room to disconnect from.
+ * @returns {Promise<disconnectGroupChatPayload>} Promise resolving to the disconnection payload/response.
+ */
+export declare const disconnectGroupChat: (roomId: string) => Promise<disconnectGroupChatPayload>;
+/**
+ * Sends a message to a group chat room.
+ * @param message - The text content of the message.
+ * @param chatId - The ID of the group chat (room ID) to send the message to.
+ * @returns {Promise<MessageGroupResponse>} Promise resolving to the message response, including the created turn.
+ */
+export declare const sendGroupMessage: (message: string, chatId: string) => Promise<MessageGroupResponse>;
+/**
+ * Triggers the characters in the group chat to generate a turn/reply.
+ * @param chatId - The ID of the group chat (room ID).
+ * @returns {Promise<MessageGroupGenerateTurnResponse>} Promise resolving to the generated turn response.
+ */
+export declare const generateTurnGroupMessage: (chatId: string) => Promise<MessageGroupGenerateTurnResponse>;
 //# sourceMappingURL=index.d.ts.map

package/dist/Chat/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Chat/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAmD,kBAAkB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAK3H;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAU,aAAa,MAAM,KAAG,OAAO,CAAC,eAAe,CA0CxF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,SAAS,MAAM,EAAE,aAAa,MAAM,EAAE,QAAQ,MAAM,KAAG,OAAO,CAAC,kBAAkB,CAoFlH,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,QAAQ,MAAM,EAAE,QAAQ,MAAM,KAAI,OAAO,CAAC;IACxE,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,IAAI,EAAE;QACF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAC5B,CAAA;CACJ,CAcA,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Chat/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAmD,kBAAkB,EAAE,IAAI,EAA0B,wBAAwB,EAA2B,0BAA0B,EAAE,SAAS,EAAuB,oBAAoB,EAAmC,gCAAgC,EAAE,MAAM,eAAe,CAAC;AAK3V;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAU,aAAa,MAAM,KAAG,OAAO,CAAC,eAAe,CA8CxF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,QAAQ,MAAM,EAAE,QAAQ,MAAM,KAAI,OAAO,CAAC;IACxE,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,IAAI,EAAE;QACF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAC5B,CAAA;CACJ,CAcA,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,SAAS,MAAM,EAAE,aAAa,MAAM,EAAE,QAAQ,MAAM,KAAG,OAAO,CAAC,kBAAkB,CAwFlH,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAc,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAC,CAapE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAU,OAAO,MAAM,EAAE,eAAe,MAAM,GAAG,MAAM,EAAE,KAAI,OAAO,CAAC,SAAS,CAuBzG,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAU,QAAQ,MAAM,KAAI,OAAO,CAAC,wBAAwB,CAgCxF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAU,QAAQ,MAAM,KAAI,OAAO,CAAC,0BAA0B,CAgC7F,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAU,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAG,OAAO,CAAC,oBAAoB,CAgEpG,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,gCAAgC,CAkDvG,CAAC"}