@pnds/sdk 0.1.0

package/src/constants.ts

@@ -0,0 +1,119 @@
+// API base path
+export const API_BASE = '/api/v1';
+
+// REST endpoints
+export const ENDPOINTS = {
+  // Auth
+  AUTH_REGISTER: `${API_BASE}/auth/register`,
+  AUTH_LOGIN: `${API_BASE}/auth/login`,
+  AUTH_REFRESH: `${API_BASE}/auth/refresh`,
+  AUTH_LOGOUT: `${API_BASE}/auth/logout`,
+  AUTH_CHECK_EMAIL: `${API_BASE}/auth/check-email`,
+  AUTH_VERIFY_EMAIL: `${API_BASE}/auth/verify-email`,
+  AUTH_RESEND_CODE: `${API_BASE}/auth/resend-code`,
+
+  // Users
+  USERS_ME: `${API_BASE}/users/me`,
+  USER: (id: string) => `${API_BASE}/users/${id}`,
+  USERS_SEARCH: `${API_BASE}/users/search`,
+
+  // WebSocket ticket
+  WS_TICKET: `${API_BASE}/ws/ticket`,
+
+  // Organizations (global)
+  ORGS: `${API_BASE}/orgs`,
+  // Org-scoped
+  ORG: (orgId: string) => `${API_BASE}/orgs/${orgId}`,
+  ORG_MEMBERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/members`,
+  ORG_MEMBER: (orgId: string, userId: string) =>
+    `${API_BASE}/orgs/${orgId}/members/${userId}`,
+
+  // Chats (org-scoped)
+  CHATS: (orgId: string) => `${API_BASE}/orgs/${orgId}/chats`,
+  CHAT: (orgId: string, chatId: string) => `${API_BASE}/orgs/${orgId}/chats/${chatId}`,
+  CHAT_MEMBERS: (orgId: string, chatId: string) =>
+    `${API_BASE}/orgs/${orgId}/chats/${chatId}/members`,
+  CHAT_MEMBER: (orgId: string, chatId: string, userId: string) =>
+    `${API_BASE}/orgs/${orgId}/chats/${chatId}/members/${userId}`,
+  CHAT_MESSAGES: (orgId: string, chatId: string) =>
+    `${API_BASE}/orgs/${orgId}/chats/${chatId}/messages`,
+
+  // Messages (global, by message ID)
+  MESSAGE: (id: string) => `${API_BASE}/messages/${id}`,
+  MESSAGE_PATCHES: (id: string) => `${API_BASE}/messages/${id}/patches`,
+  MESSAGE_REPLIES: (id: string) => `${API_BASE}/messages/${id}/replies`,
+
+  // Upload (global)
+  UPLOAD_PRESIGN: `${API_BASE}/upload/presign`,
+  UPLOAD_COMPLETE: `${API_BASE}/upload/complete`,
+
+  // Approvals (global)
+  APPROVAL_DECIDE: (id: string) => `${API_BASE}/approvals/${id}/decide`,
+  APPROVALS_PENDING: `${API_BASE}/approvals/pending`,
+
+  // Agents (org-scoped)
+  AGENTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents`,
+  AGENT: (orgId: string, agentId: string) => `${API_BASE}/orgs/${orgId}/agents/${agentId}`,
+  AGENT_API_KEYS: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys`,
+  AGENT_API_KEY: (orgId: string, agentId: string, key: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/api-keys/${key}`,
+  AGENT_ACTIVITY: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/activity`,
+  AGENT_MONITOR: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/monitor`,
+  AGENT_START: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/start`,
+  AGENT_STOP: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/stop`,
+  AGENT_HOSTED_STATUS: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/hosted-status`,
+  AGENT_WORKSPACE: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/workspace`,
+  AGENT_LOGS: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/logs`,
+
+  // Tasks (org-scoped)
+  TASKS: (orgId: string) => `${API_BASE}/orgs/${orgId}/tasks`,
+  TASK: (orgId: string, taskId: string) => `${API_BASE}/orgs/${orgId}/tasks/${taskId}`,
+  TASK_SUBTASKS: (orgId: string, taskId: string) =>
+    `${API_BASE}/orgs/${orgId}/tasks/${taskId}/subtasks`,
+  TASK_RELATIONS: (orgId: string, taskId: string) =>
+    `${API_BASE}/orgs/${orgId}/tasks/${taskId}/relations`,
+  TASK_RELATION: (orgId: string, taskId: string, relId: string) =>
+    `${API_BASE}/orgs/${orgId}/tasks/${taskId}/relations/${relId}`,
+
+  // Unread
+  UNREAD: `${API_BASE}/me/unread`,
+  CHAT_READ: (orgId: string, chatId: string) =>
+    `${API_BASE}/orgs/${orgId}/chats/${chatId}/read`,
+
+} as const;
+
+// WebSocket event types
+export const WS_EVENTS = {
+  // Client -> Server
+  PING: 'ping',
+  TYPING: 'typing',
+  ACK: 'ack',
+  READ: 'read',
+  WATCH: 'watch',
+  AGENT_HEARTBEAT: 'agent.heartbeat',
+
+  // Server -> Client
+  HELLO: 'hello',
+  PONG: 'pong',
+  WATCHING: 'watching',
+  MESSAGE_NEW: 'message.new',
+  MESSAGE_PATCH: 'message.patch',
+  MESSAGE_EDIT: 'message.edit',
+  MESSAGE_DELETE: 'message.delete',
+  TYPING_UPDATE: 'typing.update',
+  CHAT_UPDATE: 'chat.update',
+  APPROVAL_UPDATE: 'approval.update',
+  RECOVERY_OVERFLOW: 'recovery.overflow',
+  MEMBERSHIP_CHANGED: 'membership.changed',
+  TASK_CREATED: 'task.created',
+  TASK_UPDATED: 'task.updated',
+  TASK_DELETED: 'task.deleted',
+} as const;

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './constants.js';
+export { PondClient, ApiError } from './client.js';
+export type { PondClientOptions } from './client.js';
+export { PondWs } from './ws.js';
+export type { PondWsOptions, WsConnectionState, WsEventType, WsEventHandler } from './ws.js';

package/src/types.ts

@@ -0,0 +1,569 @@
+// ============================================================
+// Entity Types — mirror server data model
+// ============================================================
+
+export type UserType = 'human' | 'agent';
+export type UserStatus = 'active' | 'disabled';
+
+export interface User {
+  id: string;
+  type: UserType;
+  display_name: string;
+  avatar_url: string | null;
+  email: string | null;
+  phone: string | null;
+  agent_provider: string | null;
+  agent_endpoint: string | null;
+  agent_model: string | null;
+  agent_permissions: string[];
+  status: UserStatus;
+  email_verified: boolean;
+  last_seen_at: string | null;
+  created_at: string;
+}
+
+export type ChatType = 'direct' | 'group';
+
+export interface Chat {
+  id: string;
+  type: ChatType;
+  org_id: string;
+  name: string | null;
+  avatar_url: string | null;
+  description: string | null;
+  last_message_at: string | null;
+  last_message_preview: string | null;
+  last_message_sender: string | null;
+  creator_id: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export type ChatMemberRole = 'owner' | 'admin' | 'member';
+
+export type NotificationLevel = 'all' | 'mentions_only' | 'none';
+
+export interface ChatMember {
+  chat_id: string;
+  user_id: string;
+  role: ChatMemberRole;
+  notification_level: NotificationLevel;
+  pinned: boolean;
+  joined_at: string;
+  user?: User;
+}
+
+export type MessageType =
+  | 'text'
+  | 'image'
+  | 'file'
+  | 'tool_call'
+  | 'tool_result'
+  | 'approval_card'
+  | 'state_delta'
+  | 'system';
+
+export const MENTION_ALL_USER_ID = 'all';
+
+export interface Mention {
+  user_id: string;
+  offset: number;
+  length: number;
+}
+
+export interface LinkPreview {
+  url: string;
+  title: string;
+  image: string;
+  description: string;
+}
+
+export interface TextContent {
+  text: string;
+  format?: string;
+  mentions?: Mention[];
+  link_previews?: LinkPreview[];
+}
+
+export interface MediaContent {
+  attachment_id: string;
+  file_name: string;
+  file_size: number;
+  mime_type: string;
+  url: string;
+  thumbnail_url?: string;
+  width?: number;
+  height?: number;
+  duration?: number;
+  caption?: string;
+}
+
+export interface ToolCallContent {
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  status: string;
+  started_at: string;
+}
+
+export interface ToolResultContent {
+  tool_call_id: string;
+  tool_name: string;
+  status: string;
+  output: string;
+  duration_ms: number;
+  collapsible: boolean;
+}
+
+export interface ApprovalOption {
+  key: string;
+  label: string;
+  style: 'primary' | 'danger' | 'secondary';
+}
+
+export interface ApprovalCardContent {
+  approval_id: string;
+  title: string;
+  description: string;
+  action_type: string;
+  action_payload: Record<string, unknown>;
+  risk_level: string;
+  status: string;
+  options: ApprovalOption[];
+  expires_at: string;
+}
+
+export type AgentState = 'thinking' | 'tool_calling' | 'streaming' | 'waiting_approval' | 'completed' | 'error';
+
+export interface StateDeltaContent {
+  state: AgentState;
+  text: string;
+  progress: number;
+  collapsible: boolean;
+}
+
+export type SystemEvent =
+  | 'member_joined'
+  | 'member_left'
+  | 'member_role_changed'
+  | 'chat_renamed'
+  | 'chat_avatar_changed'
+  | 'agent_added'
+  | 'agent_removed';
+
+export interface SystemContent {
+  event: SystemEvent;
+  user_id: string;
+  user_name: string;
+}
+
+export type MessageContent =
+  | TextContent
+  | MediaContent
+  | ToolCallContent
+  | ToolResultContent
+  | ApprovalCardContent
+  | StateDeltaContent
+  | SystemContent
+  | Record<string, unknown>;
+
+export interface Message {
+  id: string;
+  chat_id: string;
+  sender_id: string;
+  sender?: User;
+  thread_root_id: string | null;
+  message_type: MessageType;
+  content: MessageContent;
+  version: number;
+  reply_count: number;
+  edited_at: string | null;
+  deleted_at: string | null;
+  created_at: string;
+  idempotency_key: string | null;
+}
+
+export interface Attachment {
+  id: string;
+  message_id: string | null;
+  uploader_id: string;
+  file_name: string;
+  file_size: number;
+  mime_type: string;
+  storage_key: string;
+  width: number | null;
+  height: number | null;
+  duration: number | null;
+  thumbnail_key: string | null;
+  created_at: string;
+}
+
+export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+
+export interface Approval {
+  id: string;
+  message_id: string;
+  chat_id: string;
+  requester_id: string;
+  status: ApprovalStatus;
+  action_type: string;
+  action_payload: Record<string, unknown>;
+  decided_by: string | null;
+  decided_at: string | null;
+  expires_at: string | null;
+  created_at: string;
+}
+
+export type OrgMemberRole = 'owner' | 'admin' | 'member';
+
+export interface Organization {
+  id: string;
+  name: string;
+  avatar_url: string | null;
+  is_personal: boolean;
+  created_at: string;
+}
+
+export interface OrgMember {
+  org_id: string;
+  user_id: string;
+  role: OrgMemberRole;
+  joined_at: string;
+  user?: User;
+}
+
+export interface ApiKey {
+  id: string;
+  key: string;
+  agent_id: string;
+  created_at: string;
+}
+
+export interface CreateAgentResponse {
+  user: User;
+  api_key: string;
+}
+
+export interface UnreadCount {
+  chat_id: string;
+  unread_count: number;
+  last_read_message_id: string;
+  last_read_at: string;
+}
+
+// ============================================================
+// API Response Types
+// ============================================================
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  has_more: boolean;
+  next_cursor?: string;
+}
+
+export interface ErrorResponse {
+  error: string;
+  code: string;
+  details?: Record<string, unknown>;
+}
+
+export interface AuthTokens {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  user: User;
+  is_new_user?: boolean;
+}
+
+export interface CheckEmailResponse {
+  exists: boolean;
+}
+
+export interface PresignResponse {
+  upload_url: string;
+  attachment_id: string;
+  expires_in: number;
+}
+
+export interface WsTicketResponse {
+  ticket: string;
+  expires_at: string;
+  ws_url: string;
+}
+
+// ============================================================
+// API Request Types
+// ============================================================
+
+export interface RegisterRequest {
+  email: string;
+  password: string;
+  display_name: string;
+}
+
+export interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+export interface CreateChatRequest {
+  type: ChatType;
+  org_id: string;
+  name?: string;
+  description?: string;
+  member_ids: string[];
+}
+
+export interface SendMessageRequest {
+  message_type: MessageType;
+  content: MessageContent;
+  thread_root_id?: string;
+  idempotency_key?: string;
+}
+
+export interface PatchMessageRequest {
+  version: number;
+  ops: JsonPatchOp[];
+}
+
+export interface JsonPatchOp {
+  op: 'replace' | 'add';
+  path: string;
+  value: unknown;
+}
+
+export interface WorkspaceFiles {
+  soul_md?: string;
+  agents_md?: string;
+  tools_md?: string;
+}
+
+export interface HostedStatus {
+  state: 'running' | 'stopped' | 'creating' | 'error';
+}
+
+export interface CreateAgentRequest {
+  display_name: string;
+  agent_provider?: string;
+  agent_endpoint?: string;
+  agent_model?: string;
+  agent_permissions?: string[];
+  machine_type?: string;
+  machine_label?: string;
+  machine_host?: string;
+  workspace?: WorkspaceFiles;
+}
+
+// ---- Agent enriched types ----
+
+export interface AgentProfile {
+  user_id: string;
+  provider: string | null;
+  endpoint: string | null;
+  model: string | null;
+  permissions: string[];
+  machine_type: string | null;
+  machine_label: string | null;
+  machine_host: string | null;
+  compute_provider: string | null;
+  compute_resource_id: string | null;
+  compute_metadata: Record<string, string> | null;
+  created_by: string;
+  created_at: string;
+}
+
+export interface AgentRun {
+  chat_id: string;
+  status: string;
+  started_at: string;
+}
+
+export interface AgentPresence {
+  online: boolean;
+  status: string; // "online" | "busy" | "error" | "offline"
+  session_id?: string;
+  run?: AgentRun;
+  telemetry?: Record<string, unknown>;
+}
+
+export interface AgentWithRuntime extends User {
+  agent_profile?: AgentProfile | null;
+  presence?: AgentPresence | null;
+}
+
+export interface PresignUploadRequest {
+  file_name: string;
+  file_size: number;
+  mime_type: string;
+}
+
+// ============================================================
+// Task Types
+// ============================================================
+
+export type TaskStatus = 'todo' | 'in_progress' | 'in_review' | 'done' | 'canceled';
+export type TaskPriority = 'high' | 'normal' | 'low';
+export type TaskRelationTargetType = 'task' | 'message' | 'chat' | 'agent_run';
+export type TaskRelationType = 'blocks' | 'related' | 'duplicate' | 'source' | 'reference' | 'discussion' | 'execution';
+
+export interface Task {
+  id: string;
+  org_id: string;
+  title: string;
+  description: string | null;
+  status: TaskStatus;
+  priority: TaskPriority;
+  assignee_id: string | null;
+  creator_id: string;
+  parent_id: string | null;
+  sort_order: number;
+  created_at: string;
+  updated_at: string;
+  started_at: string | null;
+  completed_at: string | null;
+  canceled_at: string | null;
+}
+
+export interface TaskRelation {
+  id: string;
+  task_id: string;
+  target_type: TaskRelationTargetType;
+  target_id: string;
+  relation_type: TaskRelationType;
+  created_by: string;
+  created_at: string;
+}
+
+export interface CreateTaskRequest {
+  title: string;
+  description?: string;
+  priority?: TaskPriority;
+  assignee_id?: string;
+  parent_id?: string;
+  sort_order?: number;
+}
+
+export interface UpdateTaskRequest {
+  title?: string;
+  description?: string;
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  assignee_id?: string | null;
+  sort_order?: number;
+}
+
+export interface CreateTaskRelationRequest {
+  target_type: TaskRelationTargetType;
+  target_id: string;
+  relation_type: TaskRelationType;
+}
+
+// ============================================================
+// WebSocket Event Types
+// ============================================================
+
+export interface WsFrame<T = unknown> {
+  type: string;
+  seq?: number;
+  data: T;
+}
+
+export interface HelloData {
+  conn_id: string;
+  user_id: string;
+  session_id?: string; // agent-only: server-assigned session ID
+  server_time: string;
+  heartbeat_interval: number;
+}
+
+export interface MessageNewData {
+  id: string;
+  chat_id: string;
+  sender_id: string;
+  sender?: User;
+  thread_root_id: string | null;
+  message_type: MessageType;
+  content: MessageContent;
+  version: number;
+  created_at: string;
+}
+
+export interface MessagePatchData {
+  message_id: string;
+  chat_id: string;
+  version: number;
+  ops: JsonPatchOp[];
+}
+
+export interface MessageEditData {
+  message_id: string;
+  chat_id: string;
+  content: MessageContent;
+  edited_at: string;
+}
+
+export interface MessageDeleteData {
+  message_id: string;
+  chat_id: string;
+}
+
+export interface TypingUpdateData {
+  chat_id: string;
+  thread_root_id: string | null;
+  user_id: string;
+  action: 'start' | 'stop';
+}
+
+export interface ChatUpdateData {
+  chat_id: string;
+  changes: Record<string, unknown>;
+}
+
+export interface ApprovalUpdateData {
+  approval_id: string;
+  message_id: string;
+  chat_id: string;
+  status: ApprovalStatus;
+  decided_by: string;
+  decided_at: string;
+}
+
+export interface RecoveryOverflowData {
+  message: string;
+}
+
+export interface WatchingData {
+  chat_ids: string[];
+}
+
+export interface MembershipChangedData {
+  chat_id: string;
+  user_id: string;
+  action: 'added' | 'removed';
+}
+
+// ---- Task WS Event Data ----
+
+export type TaskCreatedData = Task;
+export type TaskUpdatedData = Task;
+export interface TaskDeletedData {
+  task_id: string;
+  org_id: string;
+}
+
+export type WsEventMap = {
+  'hello': HelloData;
+  'message.new': MessageNewData;
+  'message.patch': MessagePatchData;
+  'message.edit': MessageEditData;
+  'message.delete': MessageDeleteData;
+  'typing.update': TypingUpdateData;
+  'chat.update': ChatUpdateData;
+  'approval.update': ApprovalUpdateData;
+  'recovery.overflow': RecoveryOverflowData;
+  'watching': WatchingData;
+  'pong': { ts: number };
+  'membership.changed': MembershipChangedData;
+  'task.created': TaskCreatedData;
+  'task.updated': TaskUpdatedData;
+  'task.deleted': TaskDeletedData;
+};