@pnds/sdk 1.0.1 → 1.2.0

package/src/client.ts

@@ -15,6 +15,8 @@ import type {
   CreateChatRequest,
   Message,
   SendMessageRequest,
+  SendDirectMessageRequest,
+  DirectMessageResponse,
   PatchMessageRequest,
   PaginatedResponse,
   Approval,
@@ -53,6 +55,7 @@ import type {
   WikiChangeset,
   WikiTreeResponse,
   WikiBlob,
+  WikiNodeSectionArtifact,
   WikiDiff,
   CreateWikiRequest,
   CreateWikiMountRequest,
@@ -62,6 +65,8 @@ import type {
   RefreshWikiRepoTokenRequest,
   WikiMountManifestV2,
   WikiRepoToken,
+  InboxItem,
+  InboxUnreadCountResponse,
 } from './types.js';
 
 export interface PondClientOptions {
@@ -82,10 +87,13 @@ export class PondClient {
 
   /** Auth endpoints excluded from automatic 401 refresh to prevent recursion. */
   private static readonly AUTH_PATHS = new Set([
-    '/auth/login', '/auth/register', '/auth/refresh',
+    '/auth/login', '/auth/register', '/auth/refresh', '/auth/logout',
     '/auth/verify-email', '/auth/resend-code', '/auth/check-email',
   ]);
 
+  /** Proactive refresh when token expires within this window (seconds). */
+  private static readonly REFRESH_THRESHOLD_S = 5 * 60;
+
   constructor(options: PondClientOptions = {}) {
     this.baseUrl = options.baseUrl ?? '';
     this.token = options.token ?? null;
@@ -102,6 +110,38 @@ export class PondClient {
     return this.token;
   }
 
+  /** Decode the `exp` claim from a JWT without verifying the signature. */
+  private static decodeJwtExp(token: string): number | null {
+    try {
+      const parts = token.split('.');
+      if (parts.length !== 3) return null;
+      // base64url → standard base64
+      const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+      const padded = b64.padEnd(b64.length + ((4 - (b64.length % 4)) % 4), '=');
+      const payload = JSON.parse(atob(padded));
+      return typeof payload.exp === 'number' ? payload.exp : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Proactive refresh: if the current access token expires within
+   * REFRESH_THRESHOLD_S, refresh it **before** sending the request.
+   * No-op when the token is still fresh, missing, or un-parseable.
+   */
+  private async ensureFreshToken(path: string): Promise<void> {
+    if (!this.token || !this.getRefreshToken) return;
+    const pathSuffix = path.replace(/^\/api\/v1/, '');
+    if (PondClient.AUTH_PATHS.has(pathSuffix)) return;
+
+    const exp = PondClient.decodeJwtExp(this.token);
+    if (exp === null) return;
+    if (exp - Date.now() / 1000 > PondClient.REFRESH_THRESHOLD_S) return;
+
+    await this.tryRefresh();
+  }
+
   /**
    * Single-flight token refresh. Multiple concurrent 401s share one promise
    * so only one refresh request is made.
@@ -133,6 +173,11 @@ export class PondClient {
     query?: Record<string, string | number | boolean | undefined>,
     retried = false,
   ): Promise<T> {
+    // Proactive refresh: block until token is fresh (no-op if still valid)
+    if (!retried) {
+      await this.ensureFreshToken(path);
+    }
+
     let url = `${this.baseUrl}${path}`;
 
     if (query) {
@@ -194,6 +239,12 @@ export class PondClient {
     }
 
     if (res.status === 204) return undefined as T;
+    // 202 Accepted may have an empty body (e.g., async restart) or a JSON body.
+    if (res.status === 202) {
+      const text = await res.text();
+      if (!text) return undefined as T;
+      return JSON.parse(text) as T;
+    }
     return res.json() as Promise<T>;
   }
 
@@ -247,10 +298,6 @@ export class PondClient {
     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 ----
 
@@ -324,6 +371,12 @@ export class PondClient {
     return this.request('GET', ENDPOINTS.INVITATION_BY_TOKEN(token));
   }
 
+  // ---- Direct Messages (org-scoped) ----
+
+  async sendDirectMessage(orgId: string, req: SendDirectMessageRequest): Promise<DirectMessageResponse> {
+    return this.request('POST', ENDPOINTS.DM(orgId), req);
+  }
+
   // ---- Chats (org-scoped) ----
 
   async createChat(orgId: string, req: Omit<CreateChatRequest, 'org_id'>): Promise<Chat> {
@@ -504,6 +557,20 @@ export class PondClient {
     return res.data;
   }
 
+  /** Fetch all pending tasks (todo/in_progress) assigned to an agent. Pages automatically. */
+  async getAgentTasks(orgId: string, agentId: string): Promise<Task[]> {
+    const all: Task[] = [];
+    let cursor: string | undefined;
+    do {
+      const params: Record<string, string> = { limit: '100' };
+      if (cursor) params.cursor = cursor;
+      const res = await this.request<PaginatedResponse<Task>>('GET', ENDPOINTS.AGENT_TASKS(orgId, agentId), undefined, params);
+      all.push(...res.data);
+      cursor = res.has_more ? res.next_cursor : undefined;
+    } while (cursor);
+    return all;
+  }
+
   // ---- Machines (org-scoped) ----
 
   async getMachines(orgId: string): Promise<Machine[]> {
@@ -535,6 +602,14 @@ export class PondClient {
     return this.request('GET', ENDPOINTS.MACHINE_LOGS(orgId, machineId), undefined, { lines });
   }
 
+  async restartMachine(orgId: string, machineId: string): Promise<{ machine_id: string; command_id: string }> {
+    return this.request('POST', ENDPOINTS.MACHINE_RESTART(orgId, machineId));
+  }
+
+  async restartAllMachines(orgId: string): Promise<{ data: Array<{ machine_id: string; command_id?: string; status: string; error?: string }>; total: number }> {
+    return this.request('POST', ENDPOINTS.MACHINE_RESTART_ALL(orgId));
+  }
+
   async updateMachineWorkspace(orgId: string, machineId: string, files: WorkspaceFiles): Promise<void> {
     return this.request('PUT', ENDPOINTS.MACHINE_WORKSPACE(orgId, machineId), files);
   }
@@ -562,6 +637,46 @@ export class PondClient {
     return this.request('POST', ENDPOINTS.CHAT_READ(orgId, chatId), { message_id: messageId });
   }
 
+  // ---- Inbox ----
+
+  async getInbox(orgId: string, params?: {
+    type?: string; reason?: string; read?: string;
+    limit?: number; cursor?: string;
+  }): Promise<PaginatedResponse<InboxItem>> {
+    return this.request('GET', ENDPOINTS.INBOX(orgId), undefined, params as Record<string, string>);
+  }
+
+  async getInboxUnreadCount(orgId: string): Promise<InboxUnreadCountResponse> {
+    return this.request('GET', ENDPOINTS.INBOX_UNREAD_COUNT(orgId));
+  }
+
+  async markInboxRead(orgId: string, id: string): Promise<void> {
+    return this.request('PATCH', ENDPOINTS.INBOX_ITEM_READ(orgId, id));
+  }
+
+  async archiveInboxItem(orgId: string, id: string): Promise<void> {
+    return this.request('PATCH', ENDPOINTS.INBOX_ITEM_ARCHIVE(orgId, id));
+  }
+
+  // snoozeInboxItem / unsnoozeInboxItem deferred until un-snooze cron worker is implemented
+
+  async markAllInboxRead(orgId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.INBOX_MARK_ALL_READ(orgId));
+  }
+
+  async archiveAllInbox(orgId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.INBOX_ARCHIVE_ALL(orgId));
+  }
+
+  /** Mark an inbox item as read by its source (source_type + source_id) rather than inbox item ID. */
+  async ackInbox(orgId: string, source: { source_type: string; source_id: string }): Promise<void> {
+    return this.request('POST', ENDPOINTS.INBOX_ACK(orgId), source);
+  }
+
+  async deleteInboxItem(orgId: string, id: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.INBOX_ITEM(orgId, id));
+  }
+
   // ---- Platform Config ----
 
   /**
@@ -728,6 +843,10 @@ export class PondClient {
     return this.request('GET', ENDPOINTS.WIKI_BLOB(orgId, wikiId), undefined, params);
   }
 
+  async getWikiNodeSections(orgId: string, wikiId: string, params?: { ref?: string }): Promise<WikiNodeSectionArtifact> {
+    return this.request('GET', ENDPOINTS.WIKI_NODE_SECTIONS(orgId, wikiId), undefined, params);
+  }
+
   async createWikiMount(orgId: string, wikiId: string, data: CreateWikiMountRequest): Promise<WikiMount> {
     return this.request('POST', ENDPOINTS.WIKI_MOUNTS(orgId, wikiId), data);
   }
@@ -750,7 +869,12 @@ export class PondClient {
     return normalizeWikiChangeset(await this.request('GET', ENDPOINTS.WIKI_CHANGESET(orgId, wikiId, changesetId)));
   }
 
-  async updateWikiChangeset(orgId: string, wikiId: string, changesetId: string, data: UpdateWikiChangesetRequest): Promise<WikiChangeset> {
+  async updateWikiChangeset(
+    orgId: string,
+    wikiId: string,
+    changesetId: string,
+    data: UpdateWikiChangesetRequest,
+  ): Promise<WikiChangeset> {
     return normalizeWikiChangeset(await this.request('PATCH', ENDPOINTS.WIKI_CHANGESET(orgId, wikiId, changesetId), data));
   }
 

package/src/constants.ts

@@ -15,7 +15,6 @@ export const ENDPOINTS = {
   // 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`,
@@ -28,6 +27,9 @@ export const ENDPOINTS = {
   ORG_MEMBER: (orgId: string, userId: string) =>
     `${API_BASE}/orgs/${orgId}/members/${userId}`,
 
+  // Direct messages (org-scoped, atomic find-or-create + send)
+  DM: (orgId: string) => `${API_BASE}/orgs/${orgId}/dm`,
+
   // Chats (org-scoped)
   CHATS: (orgId: string) => `${API_BASE}/orgs/${orgId}/chats`,
   CHAT: (orgId: string, chatId: string) => `${API_BASE}/orgs/${orgId}/chats/${chatId}`,
@@ -71,6 +73,8 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/runs/${runId}`,
   AGENT_RUN_STEPS: (orgId: string, agentId: string, runId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/runs/${runId}/steps`,
+  AGENT_TASKS: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/tasks`,
   // Machines (org-scoped)
   MACHINES: (orgId: string) => `${API_BASE}/orgs/${orgId}/machines`,
   MACHINE: (orgId: string, machineId: string) =>
@@ -83,6 +87,10 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/status`,
   MACHINE_LOGS: (orgId: string, machineId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/logs`,
+  MACHINE_RESTART: (orgId: string, machineId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/restart`,
+  MACHINE_RESTART_ALL: (orgId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/restart-all`,
   MACHINE_WORKSPACE: (orgId: string, machineId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/workspace`,
   AGENT_WIKI_MOUNT_MANIFEST_V2: (orgId: string, agentId: string) =>
@@ -130,6 +138,7 @@ export const ENDPOINTS = {
   WIKI: (orgId: string, wikiId: string) => `${API_BASE}/orgs/${orgId}/wikis/${wikiId}`,
   WIKI_TREE: (orgId: string, wikiId: string) => `${API_BASE}/orgs/${orgId}/wikis/${wikiId}/tree`,
   WIKI_BLOB: (orgId: string, wikiId: string) => `${API_BASE}/orgs/${orgId}/wikis/${wikiId}/blob`,
+  WIKI_NODE_SECTIONS: (orgId: string, wikiId: string) => `${API_BASE}/orgs/${orgId}/wikis/${wikiId}/node-sections`,
   WIKI_MOUNTS: (orgId: string, wikiId: string) => `${API_BASE}/orgs/${orgId}/wikis/${wikiId}/mounts`,
   WIKI_CHANGESETS: (orgId: string, wikiId: string) => `${API_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets`,
   WIKI_CHANGESET: (orgId: string, wikiId: string, changesetId: string) =>
@@ -141,6 +150,17 @@ export const ENDPOINTS = {
   WIKI_CHANGESET_CLOSE: (orgId: string, wikiId: string, changesetId: string) =>
     `${API_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets/${changesetId}/close`,
 
+  // Inbox (org-scoped)
+  INBOX: (orgId: string) => `${API_BASE}/orgs/${orgId}/inbox`,
+  INBOX_UNREAD_COUNT: (orgId: string) => `${API_BASE}/orgs/${orgId}/inbox/unread-count`,
+  INBOX_ITEM_READ: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/inbox/${id}/read`,
+  INBOX_ITEM_ARCHIVE: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/inbox/${id}/archive`,
+  // Snooze/Unsnooze deferred until un-snooze cron worker is implemented
+  INBOX_MARK_ALL_READ: (orgId: string) => `${API_BASE}/orgs/${orgId}/inbox/mark-all-read`,
+  INBOX_ARCHIVE_ALL: (orgId: string) => `${API_BASE}/orgs/${orgId}/inbox/archive-all`,
+  INBOX_ITEM: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/inbox/${id}`,
+  INBOX_ACK: (orgId: string) => `${API_BASE}/orgs/${orgId}/inbox/ack`,
+
   // Unread
   UNREAD: `${API_BASE}/me/unread`,
   CHAT_READ: (orgId: string, chatId: string) =>
@@ -194,4 +214,7 @@ export const WS_EVENTS = {
   PRESENCE_UPDATE: 'presence.update',
   WIKI_CHANGESET_CREATED: 'wiki.changeset.created',
   WIKI_CHANGESET_UPDATED: 'wiki.changeset.updated',
+  NOTIFICATION_NEW: 'notification.new',
+  NOTIFICATION_UPDATE: 'notification.update',
+  NOTIFICATION_BULK_UPDATE: 'notification.bulk_update',
 } as const;

package/src/types.ts

@@ -143,18 +143,18 @@ export interface StateDeltaContent {
 
 export type SystemEvent =
   | 'chat_created'
-  | 'member_joined'
-  | 'member_left'
+  | 'member_added'
+  | 'member_removed'
   | 'member_role_changed'
   | 'chat_renamed'
-  | 'chat_avatar_changed'
-  | 'agent_added'
-  | 'agent_removed';
+  | 'chat_avatar_changed';
 
 export interface SystemContent {
   event: SystemEvent;
-  user_id: string;
-  user_name: string;
+  actor_id: string;
+  actor_name: string;
+  target_id?: string;
+  target_name?: string;
 }
 
 export type MessageContent =
@@ -183,6 +183,7 @@ export interface Message {
   created_at: string;
   idempotency_key: string | null;
   agent_run_id?: string | null;
+  hints?: MessageHints | null;
 }
 
 export interface Attachment {
@@ -352,12 +353,32 @@ export interface CreateChatRequest {
   member_ids: string[];
 }
 
+export interface MessageHints {
+  no_reply?: boolean;
+}
+
 export interface SendMessageRequest {
   message_type: MessageType;
   content: MessageContent;
   thread_root_id?: string;
   idempotency_key?: string;
   agent_run_id?: string;
+  hints?: MessageHints;
+}
+
+export interface SendDirectMessageRequest {
+  user_id: string;
+  message_type: MessageType;
+  content: MessageContent;
+  thread_root_id?: string;
+  idempotency_key?: string;
+  agent_run_id?: string;
+  hints?: MessageHints;
+}
+
+export interface DirectMessageResponse {
+  chat: Chat;
+  message: Message;
 }
 
 export interface PatchMessageRequest {
@@ -673,6 +694,33 @@ export interface WikiBlob {
   content: string;
 }
 
+export interface WikiNodeSection {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  node_id: string;
+  path: string;
+  title: string;
+  heading_path?: string[];
+  section_path: string;
+  level: number;
+  start_line: number;
+  end_line: number;
+  content: string;
+}
+
+export interface WikiNodeSectionArtifact {
+  version: number;
+  generated_at: string;
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  ref: string;
+  manifest_digest: string;
+  file_count: number;
+  nodes: WikiNodeSection[];
+}
+
 export interface WikiDiffFile {
   path: string;
   additions: number;
@@ -766,21 +814,7 @@ export interface CreateWikiChangesetRequest {
   status?: WikiChangesetStatus;
 }
 
-export interface UpdateWikiChangesetRequest {
-  base_ref?: string;
-  base_commit?: string;
-  head_branch?: string;
-  head_commit?: string;
-  title: string;
-  summary?: string;
-  source_chat_id?: string;
-  source_message_id?: string;
-  source_run_id?: string;
-  changed_paths?: string[];
-  diff_files?: WikiDiffFile[];
-  patch?: string;
-  status?: WikiChangesetStatus;
-}
+export interface UpdateWikiChangesetRequest extends CreateWikiChangesetRequest {}
 
 export interface MintWikiRepoTokenRequest {
   wiki_id: string;
@@ -826,6 +860,7 @@ export interface MessageNewData {
   deleted_at?: string | null;
   idempotency_key?: string | null;
   agent_run_id?: string | null;
+  hints?: MessageHints | null;
 }
 
 export interface MessagePatchData {
@@ -928,6 +963,8 @@ export interface UpdateTaskCommentRequest {
 
 export type TaskCreatedData = Task;
 export type TaskUpdatedData = Task;
+/** Sent to user:{agentID} channel when a task is assigned to an agent. Data is the full Task. */
+export type TaskAssignedData = Task;
 export interface TaskDeletedData {
   task_id: string;
   org_id: string;
@@ -1011,6 +1048,61 @@ export interface AgentStepNewData extends AgentStep {
 export type WikiChangesetCreatedData = WikiChangeset & { org_id: string };
 export type WikiChangesetUpdatedData = WikiChangeset & { org_id: string };
 
+// ============================================================
+// Inbox Types
+// ============================================================
+
+export type InboxItemType =
+  | 'mention' | 'task_assign' | 'task_update'
+  | 'task_comment' | 'approval_request'
+  | 'agent_alert' | 'invitation'
+  | 'agent_dm';
+
+export type InboxItemReason =
+  | 'assigned' | 'mentioned' | 'authored'
+  | 'subscribed' | 'approval_requested'
+  | 'dm_received';
+
+export interface InboxItem {
+  id: string;
+  org_id: string;
+  recipient_id: string;
+  actor_id: string | null;
+  type: InboxItemType;
+  reason: InboxItemReason;
+  entity_type: string;
+  entity_id: string;
+  group_key: string;
+  source_type: string;
+  source_id: string;
+  chat_id: string | null;
+  task_id: string | null;
+  title: string;
+  body: string;
+  read_at: string | null;
+  archived_at: string | null;
+  snoozed_until: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export type NotificationNewData = InboxItem;
+
+export interface NotificationUpdateData {
+  id: string;
+  read_at?: string | null;
+  archived_at?: string | null;
+  snoozed_until?: string | null;
+}
+
+export interface NotificationBulkUpdateData {
+  action: 'mark_all_read' | 'archive_all';
+}
+
+export interface InboxUnreadCountResponse {
+  count: number;
+}
+
 export type WsEventMap = {
   'hello': HelloData;
   'message.new': MessageNewData;
@@ -1029,6 +1121,7 @@ export type WsEventMap = {
   'task.created': TaskCreatedData;
   'task.updated': TaskUpdatedData;
   'task.deleted': TaskDeletedData;
+  'task.assigned': TaskAssignedData;
   'task.comment.created': TaskCommentCreatedData;
   'task.comment.updated': TaskCommentUpdatedData;
   'task.comment.deleted': TaskCommentDeletedData;
@@ -1045,6 +1138,9 @@ export type WsEventMap = {
   'presence.update': PresenceUpdateData;
   'wiki.changeset.created': WikiChangesetCreatedData;
   'wiki.changeset.updated': WikiChangesetUpdatedData;
+  'notification.new': NotificationNewData;
+  'notification.update': NotificationUpdateData;
+  'notification.bulk_update': NotificationBulkUpdateData;
 };
 
 // Invitation WS event data