@pmate/chat-sdk 0.1.6 → 0.1.8

package/lib/hooks/useVoiceInputController.js

@@ -7,6 +7,7 @@ import { MicEvents, MicStateManager } from "../voice/MicStateManager";
 const DEFAULT_WAVEFORM = [
     0.18, 0.28, 0.42, 0.58, 0.74, 0.9, 0.74, 0.58, 0.42, 0.28, 0.18,
 ];
+const DEFAULT_TRANSCRIBE_TIMEOUT_MS = 30_000;
 export function useVoiceInputController(config) {
     const managerRef = useRef(null);
     const stopActionRef = useRef("send");
@@ -68,10 +69,11 @@ export function useVoiceInputController(config) {
     }, []);
     async function transcribeBlob(blob) {
         try {
+            const transcribeTimeoutMs = configRef.current?.transcribeTimeoutMs ?? DEFAULT_TRANSCRIBE_TIMEOUT_MS;
             const nextTranscript = configRef.current?.asrClient
-                ? (await configRef.current.asrClient.transcribe(blob, {
+                ? (await withTimeout(configRef.current.asrClient.transcribe(blob, {
                     lang: configRef.current.lang,
-                })).text.trim()
+                }), transcribeTimeoutMs, "Voice transcription timed out. Please try again.")).text.trim()
                 : (configRef.current?.simulatedTranscript ?? "hello from transcript").trim();
             if (!nextTranscript) {
                 setStatus("error");
@@ -131,3 +133,20 @@ export function useVoiceInputController(config) {
         stopRecording,
     };
 }
+function withTimeout(promise, timeoutMs, message) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return promise;
+    }
+    return new Promise((resolve, reject) => {
+        const timeout = globalThis.setTimeout(() => {
+            reject(new Error(message));
+        }, timeoutMs);
+        promise.then((value) => {
+            globalThis.clearTimeout(timeout);
+            resolve(value);
+        }, (error) => {
+            globalThis.clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}

package/lib/index.d.ts

@@ -16,6 +16,10 @@ export * from "./hooks/useTranscriptComposer";
 export * from "./hooks/useVoiceInputController";
 export * from "./services/agentSdkASRClient";
 export * from "./services/authTokenResolver";
+export * from "./runtime/botAuth";
+export * from "./runtime/botKey";
+export * from "./runtime/chatClient";
+export * from "./runtime/thread";
 export * from "./tokens/defaultTokens";
 export * from "./tokens/chatInputThemes";
 export * from "./types/attachment";

package/lib/index.js

@@ -16,6 +16,10 @@ export * from "./hooks/useTranscriptComposer";
 export * from "./hooks/useVoiceInputController";
 export * from "./services/agentSdkASRClient";
 export * from "./services/authTokenResolver";
+export * from "./runtime/botAuth";
+export * from "./runtime/botKey";
+export * from "./runtime/chatClient";
+export * from "./runtime/thread";
 export * from "./tokens/defaultTokens";
 export * from "./tokens/chatInputThemes";
 export * from "./types/attachment";

package/lib/runtime/botAuth.d.ts

@@ -0,0 +1,32 @@
+import { type PmateBotKeyFile } from "./botKey.js";
+export type BotLoginChallenge = {
+    id: string;
+    app: string;
+    name: string;
+    accountId: string;
+    credentialId: string;
+    challenge: string;
+    issuedAt: string;
+    expiresAt: string;
+};
+export type BotLoginSession = {
+    token: string;
+    identity?: {
+        accountId?: string;
+        app?: string;
+        kind?: string;
+    };
+    session?: {
+        identity?: {
+            accountId?: string;
+            app?: string;
+            kind?: string;
+        };
+    };
+};
+export declare function loginPmateBot(input: {
+    botKey: PmateBotKeyFile;
+    authBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<BotLoginSession>;
+export declare function canonicalBotChallenge(challenge: BotLoginChallenge): string;

package/lib/runtime/botAuth.js

@@ -0,0 +1,71 @@
+import { botCredentialId } from "./botKey.js";
+const DEFAULT_AUTH_API_BASE_URL = "https://auth-api-v2.pmate.chat";
+export async function loginPmateBot(input) {
+    const fetcher = input.fetchImpl ?? fetch;
+    const baseUrl = (input.authBaseUrl ?? DEFAULT_AUTH_API_BASE_URL).replace(/\/+$/, "");
+    const credentialId = botCredentialId(input.botKey);
+    const challenge = await post(fetcher, baseUrl, "/accounts/bots/session/challenge", {
+        app: input.botKey.app,
+        name: input.botKey.name,
+        credentialId,
+    });
+    const signature = await signBotChallenge(challenge, input.botKey.privateKey);
+    return post(fetcher, baseUrl, "/accounts/bots/session", {
+        app: challenge.app,
+        name: challenge.name,
+        credentialId: challenge.credentialId,
+        challengeId: challenge.id,
+        challenge: challenge.challenge,
+        signature,
+    });
+}
+export function canonicalBotChallenge(challenge) {
+    return JSON.stringify({
+        id: challenge.id,
+        app: challenge.app,
+        name: challenge.name,
+        accountId: challenge.accountId,
+        credentialId: challenge.credentialId,
+        challenge: challenge.challenge,
+        issuedAt: challenge.issuedAt,
+        expiresAt: challenge.expiresAt,
+    });
+}
+async function post(fetcher, baseUrl, path, body) {
+    const response = await fetcher(`${baseUrl}${path}?app=${encodeURIComponent(String(body.app ?? ""))}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const json = (await response.json());
+    if (!response.ok || !json.success || !json.data) {
+        throw new Error(json.message || `Bot auth request failed: ${path}`);
+    }
+    return json.data;
+}
+async function signBotChallenge(challenge, privateKey) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("WebCrypto is required for PMate bot login");
+    }
+    const key = await subtle.importKey("pkcs8", base64UrlToBytes(privateKey), "Ed25519", false, ["sign"]);
+    const signature = await subtle.sign("Ed25519", key, new TextEncoder().encode(canonicalBotChallenge(challenge)));
+    return bytesToBase64Url(new Uint8Array(signature));
+}
+function base64UrlToBytes(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+function bytesToBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

package/lib/runtime/botKey.d.ts

@@ -0,0 +1,14 @@
+export type PmateBotKeyFile = {
+    type: "pmate-bot-key";
+    version: 1;
+    algorithm: "ed25519";
+    app: string;
+    name: string;
+    publicKey: string;
+    privateKey: string;
+    createdAt: string;
+    credentialId?: string;
+    publicKeyId?: string;
+};
+export declare function parsePmateBotKeyJson(input: string | unknown): PmateBotKeyFile;
+export declare function botCredentialId(key: PmateBotKeyFile): string;

package/lib/runtime/botKey.js

@@ -0,0 +1,25 @@
+export function parsePmateBotKeyJson(input) {
+    const value = typeof input === "string" ? JSON.parse(input) : input;
+    if (!value || typeof value !== "object") {
+        throw new Error("Invalid PMate bot key JSON");
+    }
+    const candidate = value;
+    if (candidate.type !== "pmate-bot-key") {
+        throw new Error('Invalid PMate bot key JSON: expected type "pmate-bot-key"');
+    }
+    if (candidate.version !== 1) {
+        throw new Error("Invalid PMate bot key JSON: expected version 1");
+    }
+    if (candidate.algorithm !== "ed25519") {
+        throw new Error('Invalid PMate bot key JSON: expected algorithm "ed25519"');
+    }
+    for (const key of ["app", "name", "publicKey", "privateKey", "createdAt"]) {
+        if (!candidate[key]?.trim()) {
+            throw new Error(`Invalid PMate bot key JSON: missing ${key}`);
+        }
+    }
+    return candidate;
+}
+export function botCredentialId(key) {
+    return key.credentialId || key.publicKeyId || key.publicKey;
+}

package/lib/runtime/chatClient.d.ts

@@ -0,0 +1,62 @@
+import { type BotLoginSession } from "./botAuth.js";
+import { type PmateBotKeyFile } from "./botKey.js";
+import { type ChatBody, type ChatRuntimeMessage, type RealtimeClient } from "./protocol.js";
+export type ChatClientOptions = {
+    appId: string;
+    botKey?: PmateBotKeyFile | string | unknown;
+    session?: BotLoginSession;
+    hubUrl?: string;
+    authBaseUrl?: string;
+    realtimeClient?: RealtimeClient;
+    fetchImpl?: typeof fetch;
+    ackTimeoutMs?: number;
+};
+export declare class ChatClient {
+    private readonly options;
+    private client;
+    private session;
+    private botKey;
+    private readonly pendingAcks;
+    private readonly messageHandlers;
+    constructor(options: ChatClientOptions);
+    connect(): Promise<this>;
+    close(): void;
+    watchMessages(handler: (message: ChatRuntimeMessage) => void): () => boolean;
+    requestFriend(input: {
+        to: string;
+        message?: string;
+    }): Promise<ChatRuntimeMessage>;
+    acceptFriend(input: {
+        to: string;
+        requestId?: string;
+        message?: string;
+    }): Promise<ChatRuntimeMessage>;
+    rejectFriend(input: {
+        to: string;
+        requestId?: string;
+        reason?: string;
+    }): Promise<ChatRuntimeMessage>;
+    sendDm(input: {
+        to: string;
+        text: string;
+    }): Promise<ChatRuntimeMessage>;
+    createGroup(input: {
+        groupId: string;
+        members: string[];
+        title?: string;
+    }): Promise<ChatRuntimeMessage>;
+    sendGroup(input: {
+        groupId: string;
+        text: string;
+        recipients?: string[];
+    }): Promise<ChatRuntimeMessage>;
+    sendChat(to: string, body: ChatBody, recipients?: string[]): Promise<ChatRuntimeMessage>;
+    private sendContactAction;
+    private sendAuth;
+    private sendAndWaitForAck;
+    private handleIncoming;
+    private waitUntilConnected;
+    private accountId;
+    private requireClient;
+}
+export declare function createChatClient(options: ChatClientOptions): ChatClient;

package/lib/runtime/chatClient.js

@@ -0,0 +1,209 @@
+import { loginPmateBot } from "./botAuth.js";
+import { parsePmateBotKeyJson } from "./botKey.js";
+import { ChatMsgKind, ChatMsgOp, ChatRealtimeEvents, RuntimeWebsocketClient, createRuntimeMsg, } from "./protocol.js";
+const DEFAULT_HUB_URL = "wss://hub.pmate.chat";
+const DEFAULT_ACK_TIMEOUT_MS = 5_000;
+export class ChatClient {
+    options;
+    client = null;
+    session = null;
+    botKey = null;
+    pendingAcks = new Map();
+    messageHandlers = new Set();
+    constructor(options) {
+        this.options = options;
+        if (options.botKey) {
+            this.botKey = parsePmateBotKeyJson(options.botKey);
+        }
+        this.session = options.session ?? null;
+        this.client = options.realtimeClient ?? null;
+    }
+    async connect() {
+        if (!this.session) {
+            if (!this.botKey) {
+                throw new Error("ChatClient requires either session or PMate bot key JSON");
+            }
+            this.session = await loginPmateBot({
+                botKey: this.botKey,
+                authBaseUrl: this.options.authBaseUrl,
+                fetchImpl: this.options.fetchImpl,
+            });
+        }
+        const accountId = this.accountId();
+        if (!this.client) {
+            const hubUrl = normalizeWsUrl(this.options.hubUrl ?? DEFAULT_HUB_URL, accountId);
+            this.client = new RuntimeWebsocketClient(hubUrl);
+        }
+        this.client.on(ChatRealtimeEvents.Message, (message) => {
+            this.handleIncoming(message);
+        });
+        await this.waitUntilConnected();
+        await this.sendAuth();
+        return this;
+    }
+    close() {
+        this.client?.close();
+        this.client = null;
+        for (const pending of this.pendingAcks.values()) {
+            pending.reject(new Error("ChatClient closed"));
+            clearTimeout(pending.timer);
+        }
+        this.pendingAcks.clear();
+    }
+    watchMessages(handler) {
+        this.messageHandlers.add(handler);
+        return () => this.messageHandlers.delete(handler);
+    }
+    async requestFriend(input) {
+        return this.sendContactAction(input.to, "friendRequest", {
+            message: input.message,
+        });
+    }
+    async acceptFriend(input) {
+        return this.sendContactAction(input.to, "friendAccept", {
+            requestId: input.requestId,
+            message: input.message,
+        });
+    }
+    async rejectFriend(input) {
+        return this.sendContactAction(input.to, "friendReject", {
+            requestId: input.requestId,
+            reason: input.reason,
+        });
+    }
+    async sendDm(input) {
+        return this.sendChat(input.to, {
+            kind: "message",
+            threadKind: "dm",
+            contentKind: "text",
+            content: { appId: this.options.appId, text: input.text },
+        });
+    }
+    async createGroup(input) {
+        return this.sendChat(input.groupId, {
+            kind: "group",
+            threadKind: "group",
+            action: "groupCreate",
+            payload: { appId: this.options.appId, groupId: input.groupId, members: input.members, title: input.title },
+        }, input.members);
+    }
+    async sendGroup(input) {
+        return this.sendChat(input.groupId, {
+            kind: "message",
+            threadKind: "group",
+            contentKind: "text",
+            content: { appId: this.options.appId, groupId: input.groupId, text: input.text },
+        }, input.recipients);
+    }
+    async sendChat(to, body, recipients) {
+        const msg = createRuntimeMsg(this.accountId(), to, ChatMsgOp.CHAT, body, ChatMsgKind.DM);
+        if (recipients) {
+            msg.recipients = recipients;
+        }
+        await this.sendAndWaitForAck(msg);
+        return msg;
+    }
+    async sendContactAction(to, action, payload) {
+        return this.sendChat(to, {
+            kind: "contact",
+            threadKind: "dm",
+            action,
+            payload: cleanObject({ appId: this.options.appId, ...payload }),
+        });
+    }
+    async sendAuth() {
+        const token = this.session?.token;
+        if (!token) {
+            throw new Error("Missing PMate session token");
+        }
+        const auth = createRuntimeMsg(this.accountId(), "@hub", ChatMsgOp.AUTH, {
+            token,
+            as: "user",
+        }, ChatMsgKind.DM);
+        await this.sendAndWaitForAck(auth);
+    }
+    async sendAndWaitForAck(msg) {
+        const client = this.requireClient();
+        const ack = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingAcks.delete(msg.hash);
+                reject(new Error(`Timed out waiting for ack of ${msg.hash}`));
+            }, this.options.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS);
+            this.pendingAcks.set(msg.hash, { resolve, reject, timer });
+        });
+        await client.sendMsg(msg);
+        return ack;
+    }
+    handleIncoming(message) {
+        if (message.opcode === ChatMsgOp.ACK) {
+            const ack = message.body;
+            const pending = this.pendingAcks.get(ack.ackOf);
+            if (pending) {
+                this.pendingAcks.delete(ack.ackOf);
+                clearTimeout(pending.timer);
+                if (ack.status === "ok") {
+                    pending.resolve(ack);
+                }
+                else {
+                    pending.reject(new Error(ack.message || ack.code || "Ack failed"));
+                }
+            }
+            return;
+        }
+        if (message.opcode === ChatMsgOp.CHAT) {
+            for (const handler of this.messageHandlers) {
+                handler(message);
+            }
+        }
+    }
+    waitUntilConnected() {
+        const client = this.requireClient();
+        if (client.isConnected()) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const offConnected = client.on(ChatRealtimeEvents.Connected, (connected) => {
+                if (connected) {
+                    offConnected();
+                    offError();
+                    resolve();
+                }
+            });
+            const offError = client.on(ChatRealtimeEvents.Error, (error) => {
+                offConnected();
+                offError();
+                reject(error instanceof Error ? error : new Error("WebSocket connection failed"));
+            });
+        });
+    }
+    accountId() {
+        const accountId = this.session?.session?.identity?.accountId ||
+            this.session?.identity?.accountId ||
+            this.botKey?.name;
+        if (!accountId) {
+            throw new Error("Missing account id");
+        }
+        return accountId;
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new Error("ChatClient is not connected");
+        }
+        return this.client;
+    }
+}
+export function createChatClient(options) {
+    return new ChatClient(options);
+}
+function normalizeWsUrl(baseUrl, userId) {
+    const url = new URL(baseUrl);
+    if (url.protocol === "http:")
+        url.protocol = "ws:";
+    if (url.protocol === "https:")
+        url.protocol = "wss:";
+    url.searchParams.set("userId", userId);
+    return url.toString();
+}
+function cleanObject(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined && value !== null));
+}

package/lib/runtime/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./botAuth.js";
+export * from "./botKey.js";
+export * from "./chatClient.js";
+export * from "./protocol.js";
+export * from "./thread.js";

package/lib/runtime/index.js

@@ -0,0 +1,5 @@
+export * from "./botAuth.js";
+export * from "./botKey.js";
+export * from "./chatClient.js";
+export * from "./protocol.js";
+export * from "./thread.js";

package/lib/runtime/protocol.d.ts

@@ -0,0 +1,83 @@
+export declare const ChatMsgOp: {
+    readonly CHAT: 1;
+    readonly ACK: 3;
+    readonly AUTH: 4;
+};
+export declare const ChatMsgKind: {
+    readonly DM: 1;
+    readonly GROUP: 2;
+};
+export declare const ChatRealtimeEvents: {
+    readonly Connected: "connected";
+    readonly Error: "error";
+    readonly Message: "message";
+};
+export type ChatBody = {
+    kind: "message";
+    threadKind: "dm" | "group";
+    contentKind: "text" | "image" | "emoji";
+    content: Record<string, unknown>;
+} | {
+    kind: "pending";
+    threadKind: "dm" | "group";
+    pendingId: string;
+    expire?: number;
+    content?: Record<string, unknown>;
+} | {
+    kind: "quote";
+    threadKind: "dm" | "group";
+    quotedMessageId: string;
+    content: Record<string, unknown>;
+} | {
+    kind: "contact" | "group";
+    threadKind: "dm" | "group";
+    action: string;
+    payload?: Record<string, unknown>;
+} | {
+    kind: "recall" | "edit" | "delete" | "hello";
+    threadKind: "dm" | "group";
+    [key: string]: unknown;
+};
+export type AckBody = {
+    ackOf: string;
+    status: "ok" | "error";
+    code?: string;
+    message?: string;
+    data?: unknown;
+};
+export type ChatRuntimeMessage = {
+    hash: string;
+    t: number;
+    from: string;
+    to: string;
+    body: unknown;
+    kind: number;
+    opcode: number;
+    pending?: {
+        expire: number;
+    };
+    quote?: string;
+    recipients?: string[];
+};
+export interface RealtimeClient {
+    on<T>(topic: string, handler: (value: T) => void): () => void;
+    isConnected(): boolean;
+    close(manual?: boolean): void;
+    sendMsg(msg: ChatRuntimeMessage): Promise<void>;
+    getConnectionType(): "websocket";
+}
+export declare function createRuntimeMsg(from: string, to: string, opcode: number, body: unknown, kind?: number): ChatRuntimeMessage;
+export declare class RuntimeWebsocketClient implements RealtimeClient {
+    private readonly wsUrl;
+    private ws;
+    private connected;
+    private readonly listeners;
+    constructor(wsUrl: string);
+    on<T>(topic: string, handler: (value: T) => void): () => boolean;
+    isConnected(): boolean;
+    close(): void;
+    sendMsg(msg: ChatRuntimeMessage): Promise<void>;
+    getConnectionType(): "websocket";
+    private connect;
+    private emit;
+}

package/lib/runtime/protocol.js

@@ -0,0 +1,113 @@
+import { decode, encode } from "@msgpack/msgpack";
+export const ChatMsgOp = {
+    CHAT: 1,
+    ACK: 3,
+    AUTH: 4,
+};
+export const ChatMsgKind = {
+    DM: 1,
+    GROUP: 2,
+};
+export const ChatRealtimeEvents = {
+    Connected: "connected",
+    Error: "error",
+    Message: "message",
+};
+let msgSeq = 0;
+export function createRuntimeMsg(from, to, opcode, body, kind = ChatMsgKind.DM) {
+    const seq = nextMsgSeq();
+    const msg = {
+        hash: "",
+        t: Date.now(),
+        from,
+        to,
+        body,
+        kind,
+        opcode,
+    };
+    msg.hash = hashRuntimeMsg(msg, seq);
+    return msg;
+}
+export class RuntimeWebsocketClient {
+    wsUrl;
+    ws = null;
+    connected = false;
+    listeners = new Map();
+    constructor(wsUrl) {
+        this.wsUrl = wsUrl;
+        this.connect();
+    }
+    on(topic, handler) {
+        const set = this.listeners.get(topic) ?? new Set();
+        set.add(handler);
+        this.listeners.set(topic, set);
+        return () => set.delete(handler);
+    }
+    isConnected() {
+        return this.connected;
+    }
+    close() {
+        this.ws?.close();
+        this.ws = null;
+        this.connected = false;
+    }
+    async sendMsg(msg) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error("Websocket is not connected");
+        }
+        this.ws.send(encode(msg));
+    }
+    getConnectionType() {
+        return "websocket";
+    }
+    connect() {
+        this.ws = new WebSocket(this.wsUrl);
+        this.ws.binaryType = "arraybuffer";
+        this.ws.onopen = () => {
+            this.connected = true;
+            this.emit(ChatRealtimeEvents.Connected, true);
+        };
+        this.ws.onclose = () => {
+            this.connected = false;
+            this.emit(ChatRealtimeEvents.Connected, false);
+        };
+        this.ws.onerror = (event) => {
+            this.emit(ChatRealtimeEvents.Error, event);
+        };
+        this.ws.onmessage = (event) => {
+            try {
+                this.emit(ChatRealtimeEvents.Message, decodeWireMessage(event.data));
+            }
+            catch (error) {
+                this.emit(ChatRealtimeEvents.Error, error);
+            }
+        };
+    }
+    emit(topic, value) {
+        for (const handler of this.listeners.get(topic) ?? []) {
+            handler(value);
+        }
+    }
+}
+function decodeWireMessage(data) {
+    if (typeof data === "string") {
+        return JSON.parse(data);
+    }
+    if (data instanceof ArrayBuffer) {
+        return decode(new Uint8Array(data));
+    }
+    if (data instanceof Uint8Array) {
+        return decode(data);
+    }
+    throw new Error("Unsupported websocket message payload");
+}
+function hashRuntimeMsg(msg, seq) {
+    const random = typeof crypto !== "undefined" && "randomUUID" in crypto
+        ? crypto.randomUUID()
+        : Math.random().toString(16).slice(2);
+    return `msg_${msg.t.toString(36)}_${seq.toString(36)}_${random.replace(/-/g, "")}`;
+}
+function nextMsgSeq() {
+    msgSeq = (msgSeq + 1) % Number.MAX_SAFE_INTEGER;
+    return msgSeq;
+}