@parall/sdk 1.28.1 → 1.29.1

package/src/client.ts

@@ -20,7 +20,6 @@ import type {
   SendMessageRequest,
   SendDirectMessageRequest,
   DirectMessageResponse,
-  PatchMessageRequest,
   PaginatedResponse,
   Approval,
   CreateApprovalRequest,
@@ -38,6 +37,9 @@ import type {
   ResizeMachineRequest,
   MachineKey,
   MachineRuntimeAuthState,
+  AgentWorkspaceState,
+  AgentWorkspaceReportStatus,
+  DaemonAgentConfig,
   AttachedAgent,
   AttachAgentRequest,
   AttachedAgentsResponse,
@@ -48,6 +50,7 @@ import type {
   TaskRelation,
   TaskRelationTargetType,
   TaskWatcher,
+  ThreadWatcher,
   CreateTaskRelationRequest,
   TaskComment,
   CreateTaskCommentRequest,
@@ -155,6 +158,7 @@ export class ParallClient {
   private static readonly AUTH_PATHS = new Set([
     '/auth/login', '/auth/register', '/auth/refresh', '/auth/logout',
     '/auth/verify-email', '/auth/resend-code', '/auth/check-email',
+    '/auth/forgot-password', '/auth/reset-password',
   ]);
 
   /** Proactive refresh when token expires within this window (seconds). */
@@ -438,6 +442,14 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.AUTH_RESEND_CODE, { email });
   }
 
+  async forgotPassword(email: string): Promise<{ message: string }> {
+    return this.request('POST', ENDPOINTS.AUTH_FORGOT_PASSWORD, { email });
+  }
+
+  async resetPassword(token: string, newPassword: string): Promise<AuthTokens> {
+    return this.request('POST', ENDPOINTS.AUTH_RESET_PASSWORD, { token, new_password: newPassword });
+  }
+
   // ---- WebSocket ----
 
   async getWsTicket(): Promise<WsTicketResponse> {
@@ -732,10 +744,6 @@ export class ParallClient {
     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 },
@@ -753,8 +761,8 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.UPLOAD_COMPLETE(orgId), { attachment_id: attachmentId });
   }
 
-  async getFileUrl(id: string): Promise<FileUrlResponse> {
-    return this.request('GET', ENDPOINTS.FILE(id));
+  async getFileUrl(id: string, opts?: { download?: boolean }): Promise<FileUrlResponse> {
+    return this.request('GET', ENDPOINTS.FILE(id), undefined, opts?.download ? { download: true } : undefined);
   }
 
   // ---- Approvals ----
@@ -864,9 +872,8 @@ export class ParallClient {
    * List agent sessions.
    * @param params.status - Comma-separated status filter (e.g., `'open'`).
    */
-  async getAgentSessions(orgId: string, agentId: string, params?: { limit?: number; status?: string }): Promise<AgentSessionDB[]> {
-    const res = await this.request<{ data: AgentSessionDB[] }>('GET', ENDPOINTS.AGENT_SESSIONS(orgId, agentId), undefined, params);
-    return res.data;
+  async getAgentSessions(orgId: string, agentId: string, params?: { limit?: number; status?: string; cursor?: string }): Promise<PaginatedResponse<AgentSessionDB>> {
+    return this.request('GET', ENDPOINTS.AGENT_SESSIONS(orgId, agentId), undefined, params);
   }
 
   async getAgentSession(orgId: string, agentId: string, sessionId: string): Promise<AgentSessionDB> {
@@ -881,15 +888,18 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), req);
   }
 
-  async getAgentSessionSteps(orgId: string, agentId: string, sessionId: string, params?: { limit?: number }): Promise<AgentStep[]> {
-    const res = await this.request<{ data: AgentStep[] }>('GET', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), undefined, params);
-    return res.data;
+  async getAgentSessionSteps(orgId: string, agentId: string, sessionId: string, params?: { limit?: number; cursor?: string }): Promise<PaginatedResponse<AgentStep>> {
+    return this.request('GET', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), undefined, params);
   }
 
   async getAgentSessionStep(orgId: string, agentId: string, sessionId: string, stepId: string): Promise<AgentStep> {
     return this.request('GET', ENDPOINTS.AGENT_SESSION_STEP(orgId, agentId, sessionId, stepId));
   }
 
+  async getAgentStepById(orgId: string, stepId: string): Promise<AgentStep> {
+    return this.request('GET', ENDPOINTS.AGENT_STEP_BY_ID(orgId, stepId));
+  }
+
   // ---- Agent runtime auth (hosted Claude OAuth) ----
 
   async getAgentRuntimeAuth(orgId: string, agentId: string): Promise<RuntimeAuthConnectedState> {
@@ -1017,7 +1027,7 @@ export class ParallClient {
    * Create a new daemon-mode Machine. Returns the Machine row + one-shot
    * mck_ token. The UI uses this when the user clicks "Create Workspace".
    */
-  async createMachine(orgId: string, opts: { label?: string; tier?: string; compute_mode?: 'hosted' | 'local' }): Promise<{
+  async createMachine(orgId: string, opts: { label?: string; tier?: string; llm_source?: string; compute_mode?: 'hosted' | 'local' }): Promise<{
     machine: Machine;
     machine_key: string;
     key_id: string;
@@ -1044,11 +1054,49 @@ export class ParallClient {
     return this.request('DELETE', ENDPOINTS.MACHINE_DETACH_AGENT(orgId, machineId, agentId));
   }
 
+  async listAgentWorkspaceStates(orgId: string, machineId: string): Promise<AgentWorkspaceState[]> {
+    const res = await this.request<{ data: AgentWorkspaceState[] }>('GET', ENDPOINTS.MACHINE_WORKSPACE_STATES(orgId, machineId));
+    return res.data;
+  }
+
+  async patchAgentDaemonConfig(orgId: string, machineId: string, agentId: string, daemonConfig: DaemonAgentConfig): Promise<void> {
+    return this.request('PATCH', ENDPOINTS.MACHINE_AGENT_DAEMON_CONFIG(orgId, machineId, agentId), { daemon_config: daemonConfig });
+  }
+
+  async retryAgentWorkspaceSetup(orgId: string, machineId: string, agentId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.MACHINE_AGENT_WORKSPACE_SETUP(orgId, machineId, agentId));
+  }
+
+  async patchMachineLLMSource(orgId: string, machineId: string, llmSource: string): Promise<Machine> {
+    return this.request('PATCH', ENDPOINTS.MACHINE_LLM_SOURCE(orgId, machineId), { llm_source: llmSource });
+  }
+
   /** Get machine-level runtime auth state. */
   async getMachineRuntimeAuth(orgId: string, machineId: string): Promise<MachineRuntimeAuthState> {
     return this.request('GET', ENDPOINTS.MACHINE_RUNTIME_AUTH(orgId, machineId));
   }
 
+  async startMachineRuntimeAuthSession(
+    orgId: string,
+    machineId: string,
+    req: StartRuntimeAuthSessionRequest = {},
+  ): Promise<RuntimeAuthSession> {
+    return this.request('POST', ENDPOINTS.MACHINE_RUNTIME_AUTH_SESSIONS(orgId, machineId), req);
+  }
+
+  async completeMachineRuntimeAuthSession(
+    orgId: string,
+    machineId: string,
+    sessionId: string,
+    req: CompleteRuntimeAuthSessionRequest,
+  ): Promise<RuntimeAuthSession> {
+    return this.request('POST', ENDPOINTS.MACHINE_RUNTIME_AUTH_SESSION_COMPLETE(orgId, machineId, sessionId), req);
+  }
+
+  async disconnectMachineRuntimeAuth(orgId: string, machineId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.MACHINE_RUNTIME_AUTH(orgId, machineId));
+  }
+
   // ---- Machine self-control-plane (mck_-scoped) ----
   //
   // The four methods below are intended to be called from a daemon-mode
@@ -1082,6 +1130,18 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.MACHINES_ME_HEALTH);
   }
 
+  async reportAgentWorkspaceState(agentId: string, state: {
+    config_hash: string;
+    status: AgentWorkspaceReportStatus;
+    last_error?: string | null;
+    output_tail?: string | null;
+  }): Promise<void> {
+    const res = await this.request<{ status?: string }>('PUT', ENDPOINTS.MACHINES_ME_AGENT_WORKSPACE_STATE(agentId), state);
+    if (res?.status === 'ignored_stale') {
+      throw new ApiError(409, 'Workspace state report ignored as stale', 'STALE_WORKSPACE_STATE');
+    }
+  }
+
   /**
    * `POST /machines/me/agents/{agentId}/launch-credential` — mint a
    * short-lived `agk_*` for one of this Machine's attached agents. The
@@ -1287,6 +1347,24 @@ export class ParallClient {
     return res.data;
   }
 
+  async watchThread(threadRootId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.MESSAGE_WATCH(threadRootId));
+  }
+
+  async unwatchThread(threadRootId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.MESSAGE_WATCH(threadRootId));
+  }
+
+  async getThreadWatchers(threadRootId: string): Promise<ThreadWatcher[]> {
+    const res = await this.request<{ data: ThreadWatcher[] }>('GET', ENDPOINTS.MESSAGE_WATCHERS(threadRootId));
+    return res.data;
+  }
+
+  async isWatchingThread(threadRootId: string): Promise<boolean> {
+    const res = await this.request<{ watching: boolean }>('GET', ENDPOINTS.MESSAGE_WATCHING(threadRootId));
+    return res.watching;
+  }
+
   async getSubtasks(orgId: string, taskId: string): Promise<Task[]> {
     const res = await this.request<PaginatedResponse<Task>>('GET', ENDPOINTS.TASK_SUBTASKS(orgId, taskId));
     return res.data;
@@ -1745,7 +1823,7 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.BILLING(orgId));
   }
 
-  async listBillingTransactions(orgId: string, opts?: { cursor?: string; limit?: number; types?: string[]; user_id?: string; unresolved_actor?: boolean; machine_id?: string; unresolved_machine?: boolean }): Promise<{ items: CreditTransaction[]; next_cursor: string | null }> {
+  async listBillingTransactions(orgId: string, opts?: { cursor?: string; limit?: number; types?: string[]; user_id?: string; unresolved_actor?: boolean; machine_id?: string; unresolved_machine?: boolean; from?: string; to?: string }): Promise<{ items: CreditTransaction[]; next_cursor: string | null }> {
     const params = new URLSearchParams();
     if (opts?.cursor) params.set('cursor', opts.cursor);
     if (opts?.limit) params.set('limit', String(opts.limit));
@@ -1754,16 +1832,24 @@ export class ParallClient {
     if (opts?.unresolved_actor) params.set('unresolved_actor', 'true');
     if (opts?.machine_id) params.set('machine_id', opts.machine_id);
     if (opts?.unresolved_machine) params.set('unresolved_machine', 'true');
+    if (opts?.from) params.set('from', opts.from);
+    if (opts?.to) params.set('to', opts.to);
     const qs = params.toString();
     return this.request('GET', `${ENDPOINTS.BILLING_TRANSACTIONS(orgId)}${qs ? `?${qs}` : ''}`);
   }
 
-  async listBillingTransactionAgentGroups(orgId: string): Promise<{ groups: CreditTransactionAgentGroup[] }> {
-    return this.request('GET', `${ENDPOINTS.BILLING_TRANSACTIONS(orgId)}?group_by=agent`);
+  async listBillingTransactionAgentGroups(orgId: string, opts?: { from?: string; to?: string }): Promise<{ groups: CreditTransactionAgentGroup[] }> {
+    const params = new URLSearchParams({ group_by: 'agent' });
+    if (opts?.from) params.set('from', opts.from);
+    if (opts?.to) params.set('to', opts.to);
+    return this.request('GET', `${ENDPOINTS.BILLING_TRANSACTIONS(orgId)}?${params}`);
   }
 
-  async listBillingTransactionMachineGroups(orgId: string): Promise<{ groups: CreditTransactionMachineGroup[] }> {
-    return this.request('GET', `${ENDPOINTS.BILLING_TRANSACTIONS(orgId)}?group_by=machine`);
+  async listBillingTransactionMachineGroups(orgId: string, opts?: { from?: string; to?: string }): Promise<{ groups: CreditTransactionMachineGroup[] }> {
+    const params = new URLSearchParams({ group_by: 'machine' });
+    if (opts?.from) params.set('from', opts.from);
+    if (opts?.to) params.set('to', opts.to);
+    return this.request('GET', `${ENDPOINTS.BILLING_TRANSACTIONS(orgId)}?${params}`);
   }
 
   async createCheckout(orgId: string, req: CreateCheckoutRequest): Promise<CreateCheckoutResponse> {

package/src/constants.ts

@@ -93,6 +93,8 @@ export const ENDPOINTS = {
   AUTH_CHECK_EMAIL: `${API_BASE}/auth/check-email`,
   AUTH_VERIFY_EMAIL: `${API_BASE}/auth/verify-email`,
   AUTH_RESEND_CODE: `${API_BASE}/auth/resend-code`,
+  AUTH_FORGOT_PASSWORD: `${API_BASE}/auth/forgot-password`,
+  AUTH_RESET_PASSWORD: `${API_BASE}/auth/reset-password`,
 
   // Users
   USERS_ME: `${API_BASE}/users/me`,
@@ -142,8 +144,10 @@ export const ENDPOINTS = {
 
   // 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`,
+  MESSAGE_WATCH: (id: string) => `${API_BASE}/messages/${id}/watch`,
+  MESSAGE_WATCHERS: (id: string) => `${API_BASE}/messages/${id}/watchers`,
+  MESSAGE_WATCHING: (id: string) => `${API_BASE}/messages/${id}/watching`,
 
   // Upload (org-scoped)
   UPLOAD_PRESIGN: (orgId: string) => `${API_BASE}/orgs/${orgId}/upload/presign`,
@@ -183,6 +187,8 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}/steps`,
   AGENT_SESSION_STEP: (orgId: string, agentId: string, sessionId: string, stepId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}/steps/${stepId}`,
+  AGENT_STEP_BY_ID: (orgId: string, stepId: string) =>
+    `${API_BASE}/orgs/${orgId}/agent-steps/${stepId}`,
   AGENT_TASKS: (orgId: string, agentId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/tasks`,
   AGENT_RUNTIME_AUTH: (orgId: string, agentId: string) =>
@@ -230,12 +236,24 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/agents/${agentId}`,
   MACHINE_DETACH_AGENT: (orgId: string, machineId: string, agentId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/agents/${agentId}`,
+  MACHINE_WORKSPACE_STATES: (orgId: string, machineId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/workspace-states`,
+  MACHINE_AGENT_DAEMON_CONFIG: (orgId: string, machineId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/agents/${agentId}/daemon-config`,
+  MACHINE_AGENT_WORKSPACE_SETUP: (orgId: string, machineId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/agents/${agentId}/workspace/setup`,
+  MACHINE_LLM_SOURCE: (orgId: string, machineId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/llm-source`,
   MACHINE_RUNTIME_AUTH: (orgId: string, machineId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/runtime-auth`,
   MACHINE_KEYS: (orgId: string, machineId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/keys`,
   MACHINE_KEY: (orgId: string, machineId: string, keyId: string) =>
     `${API_BASE}/orgs/${orgId}/machines/${machineId}/keys/${keyId}`,
+  MACHINE_RUNTIME_AUTH_SESSIONS: (orgId: string, machineId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/runtime-auth-sessions`,
+  MACHINE_RUNTIME_AUTH_SESSION_COMPLETE: (orgId: string, machineId: string, sessionId: string) =>
+    `${API_BASE}/orgs/${orgId}/machines/${machineId}/runtime-auth-sessions/${sessionId}/complete`,
 
   // Machine self-control-plane (mck_-scoped). The bearer token implicitly
   // identifies the Machine, so there is no `:mid` URL parameter — these are
@@ -245,6 +263,8 @@ export const ENDPOINTS = {
   MACHINES_ME_HEALTH: `${API_BASE}/machines/me/health`,
   MACHINES_ME_AGENT_LAUNCH_CREDENTIAL: (agentId: string) =>
     `${API_BASE}/machines/me/agents/${agentId}/launch-credential`,
+  MACHINES_ME_AGENT_WORKSPACE_STATE: (agentId: string) =>
+    `${API_BASE}/machines/me/agents/${agentId}/workspace-state`,
   MACHINES_ME_WS_TICKET: `${API_BASE}/machines/me/ws/ticket`,
 
   // Tasks (org-scoped)
@@ -480,6 +500,7 @@ export const WS_EVENTS = {
   MACHINE_AGENT_ATTACHED: 'machine.agent.attached',
   MACHINE_AGENT_DETACHED: 'machine.agent.detached',
   MACHINE_STOP: 'machine.stop',
+  MACHINE_WORKSPACE_SETUP_REQUESTED: 'machine.workspace.setup.requested',
 } as const;
 
 // Canonical target URI builders for unified comments.

package/src/types.ts

@@ -249,6 +249,7 @@ export interface Message {
   created_at: string;
   idempotency_key: string | null;
   agent_step_id?: string | null;
+  agent_session_id?: string | null;
   hints?: MessageHints | null;
   attachments?: Attachment[];
 }
@@ -510,11 +511,6 @@ export interface DirectMessageResponse {
   message: Message;
 }
 
-export interface PatchMessageRequest {
-  version: number;
-  ops: JsonPatchOp[];
-}
-
 export interface JsonPatchOp {
   op: 'replace' | 'add';
   path: string;
@@ -544,6 +540,7 @@ export interface CreateAgentRequest {
   memory_mb?: number;
   storage_gb?: number;
   provider_config?: AgentProviderConfig;
+  daemon_config?: DaemonAgentConfig;
   /**
    * When true, marks this create as a candidate for the org's onboarding
    * agent. The server will atomically claim `org.onboarding_agent_id`;
@@ -649,6 +646,7 @@ export interface Machine {
   compute_provider: string;
   runtime_type: string;
   daemon_mode: boolean;
+  llm_source?: string;
   compute_mode: 'hosted' | 'local';
   region: string | null;
   created_by: string;
@@ -656,9 +654,53 @@ export interface Machine {
   updated_at: string;
 }
 
+export type DaemonWorkspaceMode = 'default' | 'local_path' | 'git';
+export type DaemonWorkspaceSetupRunOn = 'first_attach' | 'config_change';
+
+export interface DaemonWorkspaceGitConfig {
+  remote?: string;
+  ref?: string;
+  target_path?: string;
+}
+
+export interface DaemonWorkspaceSetup {
+  command?: string;
+  timeout_sec?: number;
+  run_on?: DaemonWorkspaceSetupRunOn;
+}
+
+export interface DaemonWorkspaceConfig {
+  mode?: DaemonWorkspaceMode;
+  path?: string;
+  git?: DaemonWorkspaceGitConfig;
+  setup?: DaemonWorkspaceSetup;
+}
+
+export interface DaemonAgentConfig {
+  /** Legacy shorthand for workspace.mode="local_path". */
+  workspace_path?: string;
+  workspace?: DaemonWorkspaceConfig;
+}
+
 /** Body for `POST /orgs/{orgId}/machines/{machineId}/agents/{agentId}`. */
 export interface AttachAgentRequest {
   workspace_path?: string;
+  daemon_config?: DaemonAgentConfig;
+}
+
+export type AgentWorkspaceStatus = 'pending' | 'preparing' | 'ready' | 'failed';
+export type AgentWorkspaceReportStatus = Exclude<AgentWorkspaceStatus, 'pending'>;
+
+export interface AgentWorkspaceState {
+  machine_id: string;
+  agent_id: string;
+  config_hash: string;
+  status: AgentWorkspaceStatus;
+  last_error?: string | null;
+  output_tail?: string | null;
+  prepared_at?: string | null;
+  created_at: string;
+  updated_at: string;
 }
 
 /** Response from `GET /orgs/{orgId}/machines/{machineId}/runtime-auth`. */
@@ -722,7 +764,9 @@ export interface AgentWithRuntime extends User {
 export interface AttachedAgent {
   user: User | null;
   profile: AgentProfile;
-  daemon_config?: { workspace_path?: string };
+  daemon_config?: DaemonAgentConfig;
+  provider_config?: AgentProviderConfig;
+  workspace_state?: AgentWorkspaceState;
 }
 
 // ---- Machine WS event data (daemon control plane) ----
@@ -744,6 +788,16 @@ export interface MachineAgentDetachedData {
   agent_id: string;
 }
 
+export interface MachineConfigUpdatedData {
+  machine_id: string;
+  llm_source?: string;
+}
+
+export interface MachineWorkspaceSetupRequestedData {
+  machine_id: string;
+  agent_id: string;
+}
+
 export interface MachineStopData {
   machine_id: string;
   reason?: string;
@@ -826,6 +880,14 @@ export interface TaskWatcher {
   user?: User;
 }
 
+export interface ThreadWatcher {
+  thread_root_id: string;
+  chat_id: string;
+  user_id: string;
+  created_at: string;
+  user?: User;
+}
+
 /** Content shape for system messages that project issue operations into chat. */
 export interface IssueProjectionContent {
   event: 'issue_created' | 'issue_status_changed' | 'issue_assigned';
@@ -1432,6 +1494,7 @@ export interface MessageNewData {
   deleted_at?: string | null;
   idempotency_key?: string | null;
   agent_step_id?: string | null;
+  agent_session_id?: string | null;
   hints?: MessageHints | null;
   attachments?: Attachment[];
 }
@@ -1700,6 +1763,9 @@ export interface InboxItem {
   task_id: string | null;
   title: string;
   body: string;
+  grouping_priority: number;
+  /** Number of events in this group. Populated by the grouped list query. */
+  group_count: number;
   read_at: string | null;
   archived_at: string | null;
   snoozed_until: string | null;
@@ -1833,6 +1899,8 @@ export type WsEventMap = {
   'machine.hello': MachineHelloData;
   'machine.agent.attached': MachineAgentAttachedData;
   'machine.agent.detached': MachineAgentDetachedData;
+  'machine.config.updated': MachineConfigUpdatedData;
+  'machine.workspace.setup.requested': MachineWorkspaceSetupRequestedData;
   'machine.stop': MachineStopData;
 };
 

package/src/ws.ts

@@ -24,6 +24,19 @@ export interface ParallWsOptions {
   maxReconnectInterval?: number;
 }
 
+function isRetryableNetworkError(err: unknown): boolean {
+  return (
+    err instanceof Error
+    && err.name === 'ApiError'
+    && 'status' in err
+    && (err as { status?: unknown }).status === 0
+  );
+}
+
+function isBrowserRuntime(): boolean {
+  return typeof window !== 'undefined';
+}
+
 export class ParallWs {
   private ws: WebSocket | null = null;
   private options: ParallWsOptions & { reconnect: boolean; reconnectInterval: number; maxReconnectInterval: number };
@@ -63,7 +76,11 @@ export class ParallWs {
     try {
       ticket = await this.options.getTicket();
     } catch (err) {
-      console.error('Failed to get WS ticket:', err);
+      if (isBrowserRuntime() && isRetryableNetworkError(err)) {
+        console.warn('Failed to get WS ticket:', err);
+      } else {
+        console.error('Failed to get WS ticket:', err);
+      }
       if (this.options.reconnect) {
         this.scheduleReconnect();
       } else {