@pnds/sdk 0.1.0

package/dist/ws.js

@@ -0,0 +1,198 @@
+import { WS_EVENTS } from './constants.js';
+export class PondWs {
+    ws = null;
+    options;
+    listeners = new Map();
+    stateListeners = new Set();
+    heartbeatTimer = null;
+    reconnectTimer = null;
+    reconnectAttempts = 0;
+    lastSeq = 0;
+    _state = 'disconnected';
+    intentionalClose = false;
+    constructor(options) {
+        this.options = {
+            reconnect: true,
+            reconnectInterval: 1000,
+            maxReconnectInterval: 30000,
+            ...options,
+        };
+        this.lastSeq = options.lastSeq ?? 0;
+    }
+    get state() {
+        return this._state;
+    }
+    async connect() {
+        this.intentionalClose = false;
+        this.setState('connecting');
+        let ticket;
+        try {
+            ticket = await this.options.getTicket();
+        }
+        catch (err) {
+            console.error('Failed to get WS ticket:', err);
+            if (this.options.reconnect) {
+                this.scheduleReconnect();
+            }
+            else {
+                this.setState('disconnected');
+            }
+            return;
+        }
+        const wsUrl = ticket.ws_url || this.options.wsUrl;
+        if (!wsUrl) {
+            console.error('No WS URL available');
+            this.setState('disconnected');
+            return;
+        }
+        const params = new URLSearchParams({ ticket: ticket.ticket });
+        if (this.lastSeq > 0) {
+            params.set('last_seq', String(this.lastSeq));
+        }
+        this.ws = new WebSocket(`${wsUrl}?${params.toString()}`);
+        this.ws.onopen = () => {
+            this.reconnectAttempts = 0;
+            this.setState('connected');
+        };
+        this.ws.onmessage = (event) => {
+            try {
+                const frame = JSON.parse(event.data);
+                this.handleFrame(frame);
+            }
+            catch {
+                // ignore malformed frames
+            }
+        };
+        this.ws.onclose = () => {
+            this.stopHeartbeat();
+            if (this.intentionalClose) {
+                this.setState('disconnected');
+                return;
+            }
+            if (this.options.reconnect) {
+                this.scheduleReconnect();
+            }
+            else {
+                this.setState('disconnected');
+            }
+        };
+        this.ws.onerror = () => {
+            // onclose will fire after this
+        };
+    }
+    disconnect() {
+        this.intentionalClose = true;
+        this.stopHeartbeat();
+        this.clearReconnect();
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this.setState('disconnected');
+    }
+    // ---- Client -> Server messages ----
+    /** Tell the server which chats the user is currently viewing (no auth implications). */
+    watch(chatIds) {
+        this.send({ type: WS_EVENTS.WATCH, data: { chat_ids: chatIds } });
+    }
+    sendTyping(chatId, action, threadRootId) {
+        this.send({
+            type: WS_EVENTS.TYPING,
+            data: { chat_id: chatId, thread_root_id: threadRootId ?? null, action },
+        });
+    }
+    sendAck(messageId) {
+        this.send({ type: WS_EVENTS.ACK, data: { message_id: messageId } });
+    }
+    sendRead(chatId, lastReadId) {
+        this.send({ type: WS_EVENTS.READ, data: { chat_id: chatId, last_read_id: lastReadId } });
+    }
+    /** Send an agent heartbeat with telemetry data. */
+    sendAgentHeartbeat(sessionId, telemetry) {
+        this.send({
+            type: WS_EVENTS.AGENT_HEARTBEAT,
+            data: { session_id: sessionId, telemetry },
+        });
+    }
+    sendEvent(type, data) {
+        this.send({ type, data });
+    }
+    // ---- Event listeners ----
+    on(event, handler) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+        };
+    }
+    off(event, handler) {
+        this.listeners.get(event)?.delete(handler);
+    }
+    onStateChange(handler) {
+        this.stateListeners.add(handler);
+        return () => {
+            this.stateListeners.delete(handler);
+        };
+    }
+    // ---- Internal ----
+    send(frame) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(frame));
+        }
+    }
+    handleFrame(frame) {
+        // Track seq for reconnection
+        if (frame.seq !== undefined) {
+            this.lastSeq = frame.seq;
+        }
+        // Handle hello — start heartbeat
+        if (frame.type === WS_EVENTS.HELLO) {
+            const interval = frame.data.heartbeat_interval;
+            this.startHeartbeat(interval);
+        }
+        // Dispatch to listeners
+        const handlers = this.listeners.get(frame.type);
+        if (handlers) {
+            for (const handler of handlers) {
+                handler(frame.data, frame.seq);
+            }
+        }
+    }
+    startHeartbeat(intervalSec) {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            this.send({ type: WS_EVENTS.PING, data: { ts: Date.now() } });
+        }, intervalSec * 1000);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    scheduleReconnect() {
+        this.setState('reconnecting');
+        this.clearReconnect();
+        const delay = Math.min(this.options.reconnectInterval * Math.pow(2, this.reconnectAttempts), this.options.maxReconnectInterval);
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(() => {
+            this.connect();
+        }, delay);
+    }
+    clearReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    setState(state) {
+        this._state = state;
+        for (const listener of this.stateListeners) {
+            listener(state);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@pnds/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript client SDK for Pond — REST + WebSocket client, shared types",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RFlowAI/pond",
+    "directory": "ts/sdk"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}

package/src/client.ts

@@ -0,0 +1,435 @@
+import { ENDPOINTS } from './constants.js';
+import type {
+  AuthTokens,
+  RegisterRequest,
+  LoginRequest,
+  CheckEmailResponse,
+  User,
+  Organization,
+  OrgMember,
+  OrgMemberRole,
+  Chat,
+  ChatMember,
+  ChatMemberRole,
+  CreateChatRequest,
+  Message,
+  SendMessageRequest,
+  PatchMessageRequest,
+  PaginatedResponse,
+  Approval,
+  PresignResponse,
+  PresignUploadRequest,
+  CreateAgentRequest,
+  CreateAgentResponse,
+  AgentWithRuntime,
+  ApiKey,
+  WsTicketResponse,
+  HostedStatus,
+  WorkspaceFiles,
+  Task,
+  CreateTaskRequest,
+  UpdateTaskRequest,
+  TaskRelation,
+  CreateTaskRelationRequest,
+} from './types.js';
+
+export interface PondClientOptions {
+  baseUrl?: string;
+  token?: string;
+  onTokenExpired?: () => void;
+}
+
+export class PondClient {
+  private baseUrl: string;
+  private token: string | null;
+  private onTokenExpired?: () => void;
+
+  constructor(options: PondClientOptions = {}) {
+    this.baseUrl = options.baseUrl ?? '';
+    this.token = options.token ?? null;
+    this.onTokenExpired = options.onTokenExpired;
+  }
+
+  setToken(token: string | null) {
+    this.token = token;
+  }
+
+  getToken(): string | null {
+    return this.token;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    query?: Record<string, string | number | boolean | undefined>,
+  ): Promise<T> {
+    let url = `${this.baseUrl}${path}`;
+
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined) {
+          params.set(key, String(value));
+        }
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (res.status === 401 && this.onTokenExpired) {
+      this.onTokenExpired();
+    }
+
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({}));
+      const errorObj = errorBody?.error && typeof errorBody.error === 'object' ? errorBody.error as { message?: string; code?: string } : undefined;
+      const errMsg = errorObj?.message ?? (typeof errorBody?.error === 'string' ? errorBody.error : undefined);
+      const errCode = errorObj?.code ?? (typeof errorBody?.code === 'string' ? errorBody.code : undefined);
+      throw new ApiError(res.status, errMsg ?? res.statusText, errCode);
+    }
+
+    if (res.status === 204) return undefined as T;
+    return res.json() as Promise<T>;
+  }
+
+  // ---- Auth ----
+
+  async register(req: RegisterRequest): Promise<AuthTokens> {
+    return this.request('POST', ENDPOINTS.AUTH_REGISTER, req);
+  }
+
+  async login(req: LoginRequest): Promise<AuthTokens> {
+    return this.request('POST', ENDPOINTS.AUTH_LOGIN, req);
+  }
+
+  async refreshToken(refreshToken: string): Promise<AuthTokens> {
+    return this.request('POST', ENDPOINTS.AUTH_REFRESH, { refresh_token: refreshToken });
+  }
+
+  async logout(): Promise<void> {
+    return this.request('POST', ENDPOINTS.AUTH_LOGOUT);
+  }
+
+  async checkEmail(email: string): Promise<CheckEmailResponse> {
+    return this.request('POST', ENDPOINTS.AUTH_CHECK_EMAIL, { email });
+  }
+
+  async verifyEmail(email: string, code: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.AUTH_VERIFY_EMAIL, { email, code });
+  }
+
+  async resendCode(email: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.AUTH_RESEND_CODE, { email });
+  }
+
+  // ---- WebSocket ----
+
+  async getWsTicket(): Promise<WsTicketResponse> {
+    return this.request('POST', ENDPOINTS.WS_TICKET);
+  }
+
+  // ---- Users ----
+
+  async getMe(): Promise<User> {
+    return this.request('GET', ENDPOINTS.USERS_ME);
+  }
+
+  async updateMe(data: Partial<Pick<User, 'display_name' | 'avatar_url'>>): Promise<User> {
+    return this.request('PATCH', ENDPOINTS.USERS_ME, data);
+  }
+
+  async getUser(id: string): Promise<User> {
+    return this.request('GET', ENDPOINTS.USER(id));
+  }
+
+  async searchUsers(q: string): Promise<User[]> {
+    const res = await this.request<{ data: User[] }>('GET', ENDPOINTS.USERS_SEARCH, undefined, { q });
+    return res.data;
+  }
+
+  // ---- Organizations ----
+
+  async createOrg(data: { name: string; avatar_url?: string }): Promise<Organization> {
+    return this.request('POST', ENDPOINTS.ORGS, data);
+  }
+
+  async getOrgs(): Promise<Organization[]> {
+    const res = await this.request<{ data: Organization[] }>('GET', ENDPOINTS.ORGS);
+    return res.data;
+  }
+
+  async getOrg(orgId: string): Promise<Organization> {
+    return this.request('GET', ENDPOINTS.ORG(orgId));
+  }
+
+  async updateOrg(orgId: string, data: Partial<Pick<Organization, 'name' | 'avatar_url'>>): Promise<Organization> {
+    return this.request('PATCH', ENDPOINTS.ORG(orgId), data);
+  }
+
+  async deleteOrg(orgId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.ORG(orgId));
+  }
+
+  async getOrgMembers(orgId: string): Promise<OrgMember[]> {
+    const res = await this.request<{ data: OrgMember[] }>('GET', ENDPOINTS.ORG_MEMBERS(orgId));
+    return res.data;
+  }
+
+  async addOrgMember(orgId: string, userId: string, role?: OrgMemberRole): Promise<void> {
+    return this.request('POST', ENDPOINTS.ORG_MEMBERS(orgId), { user_id: userId, role: role ?? 'member' });
+  }
+
+  async removeOrgMember(orgId: string, userId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.ORG_MEMBER(orgId, userId));
+  }
+
+  async updateOrgMember(orgId: string, userId: string, role: OrgMemberRole): Promise<void> {
+    return this.request('PATCH', ENDPOINTS.ORG_MEMBER(orgId, userId), { role });
+  }
+
+  // ---- Chats (org-scoped) ----
+
+  async createChat(orgId: string, req: Omit<CreateChatRequest, 'org_id'>): Promise<Chat> {
+    return this.request('POST', ENDPOINTS.CHATS(orgId), req);
+  }
+
+  async getChats(orgId: string, params?: { limit?: number; cursor?: string }): Promise<PaginatedResponse<Chat>> {
+    return this.request('GET', ENDPOINTS.CHATS(orgId), undefined, params);
+  }
+
+  async getChat(orgId: string, chatId: string): Promise<Chat> {
+    return this.request('GET', ENDPOINTS.CHAT(orgId, chatId));
+  }
+
+  async updateChat(orgId: string, chatId: string, data: Partial<Pick<Chat, 'name' | 'avatar_url' | 'description'>>): Promise<Chat> {
+    return this.request('PATCH', ENDPOINTS.CHAT(orgId, chatId), data);
+  }
+
+  async deleteChat(orgId: string, chatId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.CHAT(orgId, chatId));
+  }
+
+  // ---- Chat Members ----
+
+  async getChatMembers(orgId: string, chatId: string): Promise<ChatMember[]> {
+    const res = await this.request<{ data: ChatMember[] }>('GET', ENDPOINTS.CHAT_MEMBERS(orgId, chatId));
+    return res.data;
+  }
+
+  async addChatMember(orgId: string, chatId: string, userId: string, role?: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.CHAT_MEMBERS(orgId, chatId), { user_id: userId, role });
+  }
+
+  async removeChatMember(orgId: string, chatId: string, userId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.CHAT_MEMBER(orgId, chatId, userId));
+  }
+
+  async updateChatMemberRole(orgId: string, chatId: string, userId: string, role: ChatMemberRole): Promise<void> {
+    return this.request('PATCH', ENDPOINTS.CHAT_MEMBER(orgId, chatId, userId), { role });
+  }
+
+  // ---- Messages ----
+
+  async sendMessage(orgId: string, chatId: string, req: SendMessageRequest): Promise<Message> {
+    return this.request('POST', ENDPOINTS.CHAT_MESSAGES(orgId, chatId), req);
+  }
+
+  async getMessages(
+    orgId: string,
+    chatId: string,
+    params?: {
+      before?: string;
+      after?: string;
+      limit?: number;
+      thread_root_id?: string;
+      top_level?: boolean;
+    },
+  ): Promise<PaginatedResponse<Message>> {
+    return this.request('GET', ENDPOINTS.CHAT_MESSAGES(orgId, chatId), undefined, params as Record<string, string | number | boolean | undefined>);
+  }
+
+  async getMessage(id: string): Promise<Message> {
+    return this.request('GET', ENDPOINTS.MESSAGE(id));
+  }
+
+  async editMessage(id: string, content: Message['content']): Promise<Message> {
+    return this.request('PATCH', ENDPOINTS.MESSAGE(id), { content });
+  }
+
+  async deleteMessage(id: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.MESSAGE(id));
+  }
+
+  async patchMessage(id: string, req: PatchMessageRequest): Promise<void> {
+    return this.request('POST', ENDPOINTS.MESSAGE_PATCHES(id), req);
+  }
+
+  async getMessageReplies(
+    id: string,
+    params?: { limit?: number; before?: string; after?: string },
+  ): Promise<PaginatedResponse<Message>> {
+    return this.request('GET', ENDPOINTS.MESSAGE_REPLIES(id), undefined, params);
+  }
+
+  // ---- File Upload ----
+
+  async getUploadPresignUrl(req: PresignUploadRequest): Promise<PresignResponse> {
+    return this.request('POST', ENDPOINTS.UPLOAD_PRESIGN, req);
+  }
+
+  async completeUpload(attachmentId: string): Promise<{ attachment_id: string }> {
+    return this.request('POST', ENDPOINTS.UPLOAD_COMPLETE, { attachment_id: attachmentId });
+  }
+
+  // ---- Approvals ----
+
+  async decideApproval(id: string, decision: 'approve' | 'reject'): Promise<Approval> {
+    return this.request('POST', ENDPOINTS.APPROVAL_DECIDE(id), { decision });
+  }
+
+  async getPendingApprovals(): Promise<Approval[]> {
+    return this.request('GET', ENDPOINTS.APPROVALS_PENDING);
+  }
+
+  // ---- Agents (org-scoped) ----
+
+  async createAgent(orgId: string, req: CreateAgentRequest): Promise<CreateAgentResponse> {
+    return this.request('POST', ENDPOINTS.AGENTS(orgId), req);
+  }
+
+  async getAgents(orgId: string): Promise<AgentWithRuntime[]> {
+    const res = await this.request<{ data: AgentWithRuntime[] }>('GET', ENDPOINTS.AGENTS(orgId));
+    return res.data;
+  }
+
+  async updateAgent(orgId: string, agentId: string, data: Partial<CreateAgentRequest>): Promise<User> {
+    return this.request('PATCH', ENDPOINTS.AGENT(orgId, agentId), data);
+  }
+
+  async deleteAgent(orgId: string, agentId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.AGENT(orgId, agentId));
+  }
+
+  async createAgentApiKey(orgId: string, agentId: string): Promise<ApiKey> {
+    return this.request('POST', ENDPOINTS.AGENT_API_KEYS(orgId, agentId));
+  }
+
+  async revokeAgentApiKey(orgId: string, agentId: string, key: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.AGENT_API_KEY(orgId, agentId, key));
+  }
+
+  async getAgentActivity(orgId: string, agentId: string, params?: { limit?: number }): Promise<Message[]> {
+    const res = await this.request<{ data: Message[] }>('GET', ENDPOINTS.AGENT_ACTIVITY(orgId, agentId), undefined, params);
+    return res.data;
+  }
+
+  async getAgentMonitor(orgId: string, agentId: string): Promise<unknown> {
+    const res = await this.request<{ data: unknown }>('GET', ENDPOINTS.AGENT_MONITOR(orgId, agentId));
+    return res.data;
+  }
+
+  async startAgent(orgId: string, agentId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.AGENT_START(orgId, agentId));
+  }
+
+  async stopAgent(orgId: string, agentId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.AGENT_STOP(orgId, agentId));
+  }
+
+  async getHostedStatus(orgId: string, agentId: string): Promise<HostedStatus> {
+    return this.request('GET', ENDPOINTS.AGENT_HOSTED_STATUS(orgId, agentId));
+  }
+
+  async updateWorkspace(orgId: string, agentId: string, files: WorkspaceFiles): Promise<void> {
+    return this.request('PUT', ENDPOINTS.AGENT_WORKSPACE(orgId, agentId), files);
+  }
+
+  async getAgentLogs(orgId: string, agentId: string, lines = 100): Promise<{ data: string[] }> {
+    return this.request('GET', ENDPOINTS.AGENT_LOGS(orgId, agentId), undefined, { lines });
+  }
+
+  // ---- Unread ----
+
+  async getUnreadCounts(): Promise<Record<string, number>> {
+    const res = await this.request<{ data: Record<string, number> }>('GET', ENDPOINTS.UNREAD);
+    return res.data;
+  }
+
+  async markRead(orgId: string, chatId: string, messageId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.CHAT_READ(orgId, chatId), { message_id: messageId });
+  }
+
+  // ---- Tasks (org-scoped) ----
+
+  async createTask(orgId: string, data: CreateTaskRequest): Promise<Task> {
+    return this.request('POST', ENDPOINTS.TASKS(orgId), data);
+  }
+
+  async getTasks(orgId: string, params?: {
+    status?: string;
+    priority?: string;
+    assignee_id?: string;
+    parent_id?: string;
+    limit?: number;
+    cursor?: string;
+    sort?: string;
+    order?: string;
+  }): Promise<PaginatedResponse<Task>> {
+    return this.request('GET', ENDPOINTS.TASKS(orgId), undefined, params);
+  }
+
+  async getTask(orgId: string, taskId: string): Promise<Task> {
+    return this.request('GET', ENDPOINTS.TASK(orgId, taskId));
+  }
+
+  async updateTask(orgId: string, taskId: string, data: UpdateTaskRequest): Promise<Task> {
+    return this.request('PATCH', ENDPOINTS.TASK(orgId, taskId), data);
+  }
+
+  async deleteTask(orgId: string, taskId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.TASK(orgId, taskId));
+  }
+
+  async getSubtasks(orgId: string, taskId: string): Promise<Task[]> {
+    const res = await this.request<PaginatedResponse<Task>>('GET', ENDPOINTS.TASK_SUBTASKS(orgId, taskId));
+    return res.data;
+  }
+
+  async createTaskRelation(orgId: string, taskId: string, data: CreateTaskRelationRequest): Promise<TaskRelation> {
+    return this.request('POST', ENDPOINTS.TASK_RELATIONS(orgId, taskId), data);
+  }
+
+  async getTaskRelations(orgId: string, taskId: string): Promise<TaskRelation[]> {
+    const res = await this.request<{ data: TaskRelation[] }>('GET', ENDPOINTS.TASK_RELATIONS(orgId, taskId));
+    return res.data;
+  }
+
+  async deleteTaskRelation(orgId: string, taskId: string, relationId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.TASK_RELATION(orgId, taskId, relationId));
+  }
+}
+
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+    public code?: string,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}