@parall/sdk 1.23.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/sdk",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "TypeScript client SDK for Parall — REST + WebSocket client, shared types",
   "license": "MIT",
   "repository": {

package/src/client.ts

@@ -1,6 +1,7 @@
 import { ENDPOINTS } from './constants.js';
 import type {
   AuthTokens,
+  AvatarUploadResponse,
   RegisterRequest,
   RegisterResponse,
   LoginRequest,
@@ -22,6 +23,7 @@ import type {
   PatchMessageRequest,
   PaginatedResponse,
   Approval,
+  CreateApprovalRequest,
   PresignResponse,
   PresignUploadRequest,
   FileUrlResponse,
@@ -110,6 +112,15 @@ import type {
   UpdateAgentRequest,
   UpdateChatMemberRequest,
   UnreadEntry,
+  BillingSummary,
+  CreditTransaction,
+  CreateCheckoutRequest,
+  CreateCheckoutResponse,
+  CreateSetupIntentResponse,
+  AutoReloadSettings,
+  UpdateAutoReloadRequest,
+  ComputePricing,
+  ComputePricingResponse,
 } from './types.js';
 
 export interface ParallClientOptions {
@@ -287,11 +298,15 @@ export class ParallClient {
     }
 
     if (!res.ok) {
-      const errorBody = await res.json().catch(() => ({}));
+      const rawErrorBody = await res.json().catch(() => ({}));
+      const errorBody = rawErrorBody !== null && typeof rawErrorBody === 'object' ? rawErrorBody as Record<string, unknown> : {};
       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);
+      const apiError = new ApiError(res.status, errMsg ?? res.statusText, errCode);
+      const { error: _e, code: _c, message: _m, ...extras } = errorBody;
+      if (Object.keys(extras).length > 0) apiError.extras = extras;
+      throw apiError;
     }
 
     if (res.status === 204) return undefined as T;
@@ -355,11 +370,15 @@ export class ParallClient {
     }
 
     if (!res.ok) {
-      const errorBody = await res.json().catch(() => ({}));
+      const rawErrorBody = await res.json().catch(() => ({}));
+      const errorBody = rawErrorBody !== null && typeof rawErrorBody === 'object' ? rawErrorBody as Record<string, unknown> : {};
       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);
+      const apiError = new ApiError(res.status, errMsg ?? res.statusText, errCode);
+      const { error: _e, code: _c, message: _m, ...extras } = errorBody;
+      if (Object.keys(extras).length > 0) apiError.extras = extras;
+      throw apiError;
     }
 
     if (res.status === 204) return undefined as T;
@@ -416,6 +435,30 @@ export class ParallClient {
     return this.request('PATCH', ENDPOINTS.USERS_ME, data);
   }
 
+  async deleteAccount(): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.USERS_ME);
+  }
+
+  async uploadAvatar(file: File | Blob): Promise<AvatarUploadResponse> {
+    const fd = new FormData();
+    fd.append('file', file);
+    return this.multipartRequest('POST', ENDPOINTS.USER_AVATAR, fd);
+  }
+
+  async deleteAvatar(): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.USER_AVATAR);
+  }
+
+  async uploadAgentAvatar(orgId: string, agentId: string, file: File | Blob): Promise<AvatarUploadResponse> {
+    const fd = new FormData();
+    fd.append('file', file);
+    return this.multipartRequest('POST', ENDPOINTS.AGENT_AVATAR(orgId, agentId), fd);
+  }
+
+  async deleteAgentAvatar(orgId: string, agentId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.AGENT_AVATAR(orgId, agentId));
+  }
+
   async getUser(id: string): Promise<User> {
     return this.request('GET', ENDPOINTS.USER(id));
   }
@@ -680,15 +723,32 @@ export class ParallClient {
 
   // ---- Approvals ----
 
+  async getApproval(id: string): Promise<Approval> {
+    return this.request('GET', ENDPOINTS.APPROVAL(id));
+  }
+
+  async requestApproval(orgId: string, req: CreateApprovalRequest): Promise<Approval> {
+    return this.request('POST', ENDPOINTS.APPROVAL_REQUESTS(orgId), req);
+  }
+
   async decideApproval(id: string, decision: 'approve' | 'reject'): Promise<Approval> {
     return this.request('POST', ENDPOINTS.APPROVAL_DECIDE(id), { decision });
   }
 
+  async cancelApproval(id: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.APPROVAL_CANCEL(id));
+  }
+
   async getPendingApprovals(): Promise<Approval[]> {
     const res = await this.request<{ data: Approval[] }>('GET', ENDPOINTS.APPROVALS_PENDING);
     return res.data;
   }
 
+  async getApprovableActions(): Promise<string[]> {
+    const res = await this.request<{ data: string[] }>('GET', ENDPOINTS.APPROVALS_ACTIONS);
+    return res.data;
+  }
+
   // ---- Agents (org-scoped) ----
 
   async createAgent(orgId: string, req: CreateAgentRequest): Promise<CreateAgentResponse> {
@@ -945,6 +1005,10 @@ export class ParallClient {
     return this.request('PATCH', ENDPOINTS.INBOX_ITEM_READ(orgId, id));
   }
 
+  async markInboxUnread(orgId: string, id: string): Promise<void> {
+    return this.request('PATCH', ENDPOINTS.INBOX_ITEM_UNREAD(orgId, id));
+  }
+
   async archiveInboxItem(orgId: string, id: string): Promise<void> {
     return this.request('PATCH', ENDPOINTS.INBOX_ITEM_ARCHIVE(orgId, id));
   }
@@ -1012,11 +1076,15 @@ export class ParallClient {
     if (res.status === 304) return null;
 
     if (!res.ok) {
-      const errorBody = await res.json().catch(() => ({}));
+      const rawErrorBody = await res.json().catch(() => ({}));
+      const errorBody = rawErrorBody !== null && typeof rawErrorBody === 'object' ? rawErrorBody as Record<string, unknown> : {};
       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);
+      const apiError = new ApiError(res.status, errMsg ?? res.statusText, errCode);
+      const { error: _e, code: _c, message: _m, ...extras } = errorBody;
+      if (Object.keys(extras).length > 0) apiError.extras = extras;
+      throw apiError;
     }
 
     return res.json() as Promise<PlatformConfigResponse>;
@@ -1523,6 +1591,61 @@ export class ParallClient {
   async getFeatureFlags(orgId: string): Promise<FeatureFlagsResponse> {
     return this.request('GET', ENDPOINTS.FEATURE_FLAGS(orgId));
   }
+
+  // ---- Billing & Credits (org-scoped) ----
+
+  async getBilling(orgId: string): Promise<BillingSummary> {
+    return this.request('GET', ENDPOINTS.BILLING(orgId));
+  }
+
+  async listBillingTransactions(orgId: string, opts?: { cursor?: string; limit?: number; types?: 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));
+    if (opts?.types?.length) params.set('types', opts.types.join(','));
+    const qs = params.toString();
+    return this.request('GET', `${ENDPOINTS.BILLING_TRANSACTIONS(orgId)}${qs ? `?${qs}` : ''}`);
+  }
+
+  async createCheckout(orgId: string, req: CreateCheckoutRequest): Promise<CreateCheckoutResponse> {
+    return this.request('POST', ENDPOINTS.BILLING_CHECKOUT(orgId), req);
+  }
+
+  /**
+   * Creates a Stripe-hosted card-collection session (Checkout in mode=setup)
+   * and returns the redirect URL. The frontend navigates to `setup_url` and
+   * Stripe handles the card form; the resulting payment_method is recorded
+   * server-side via the `setup_intent.succeeded` webhook. Mirrors
+   * `POST /billing/setup-intent`.
+   */
+  async createSetupIntent(orgId: string): Promise<CreateSetupIntentResponse> {
+    return this.request('POST', ENDPOINTS.BILLING_SETUP_INTENT(orgId));
+  }
+
+  async getAutoReloadSettings(orgId: string): Promise<AutoReloadSettings> {
+    return this.request('GET', ENDPOINTS.BILLING_AUTO_RELOAD(orgId));
+  }
+
+  async updateAutoReloadSettings(orgId: string, req: UpdateAutoReloadRequest): Promise<AutoReloadSettings> {
+    return this.request('PUT', ENDPOINTS.BILLING_AUTO_RELOAD(orgId), req);
+  }
+
+  // NOTE: `resizeMachine` was intentionally removed before merge — the
+  // matching `PATCH /api/v1/orgs/{orgId}/machines/{machineId}/spec` route
+  // is not yet wired on the server, so exposing the method shipped a
+  // method that always 404'd. Reintroduce together with the server route
+  // when machine in-place resize lands.
+  //
+  // Similarly, the admin grant endpoints (POST/GET /internal/admin/orgs/
+  // {id}/grants) intentionally do NOT live on this public client — they
+  // are mounted on the unauthenticated `/internal/*` surface and reachable
+  // only via internal network paths. The admin dashboard maintains its
+  // own thin client (`ts/admin/lib/api.ts`) that hits these directly.
+
+  async getComputePricing(): Promise<ComputePricingResponse> {
+    const resp = await this.request<{ data: ComputePricingResponse }>('GET', ENDPOINTS.COMPUTE_PRICING());
+    return resp.data;
+  }
 }
 
 function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {
@@ -1534,6 +1657,8 @@ function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {
 }
 
 export class ApiError extends Error {
+  extras?: Record<string, unknown>;
+
   constructor(
     public status: number,
     message: string,

package/src/constants.ts

@@ -5,19 +5,24 @@ export const API_BASE = '/api/v1';
 export const WIKI_BASE = '/wiki/v1';
 
 // LLM model catalog — mirrors server/pkg/llmproxy/models.go DefaultModels.
-// SSOT is the Go side; keep this list in sync when models change.
+// SSOT is the Go side; keep this list in sync when models change. `provider`
+// is used by clients to filter runtime-specific pickers.
 export const PLATFORM_MODELS = [
-  { id: 'anthropic/claude-opus-4.6', name: 'Claude Opus 4.6' },
-  { id: 'anthropic/claude-sonnet-4.6', name: 'Claude Sonnet 4.6' },
-  { id: 'anthropic/claude-sonnet-4.5', name: 'Claude Sonnet 4.5' },
-  { id: 'openai/gpt-5.4', name: 'GPT-5.4' },
-  { id: 'openai/o4-mini', name: 'o4 Mini' },
-  { id: 'openai/gpt-4.1', name: 'GPT-4.1' },
-  { id: 'google/gemini-2.5-pro', name: 'Gemini 2.5 Pro' },
-  { id: 'google/gemini-2.5-flash', name: 'Gemini 2.5 Flash' },
-  { id: 'moonshotai/kimi-k2.5', name: 'Kimi K2.5' },
-  { id: 'z-ai/glm-5', name: 'GLM 5' },
-  { id: 'qwen/qwen3.5-plus-02-15', name: 'Qwen3.5 Plus' },
+  { id: 'anthropic/claude-opus-4.7', name: 'Claude Opus 4.7', provider: 'anthropic' },
+  { id: 'anthropic/claude-opus-4.6', name: 'Claude Opus 4.6', provider: 'anthropic' },
+  { id: 'anthropic/claude-sonnet-4.6', name: 'Claude Sonnet 4.6', provider: 'anthropic' },
+  { id: 'anthropic/claude-sonnet-4.5', name: 'Claude Sonnet 4.5', provider: 'anthropic' },
+  { id: 'openai/gpt-5-codex', name: 'GPT-5 Codex', provider: 'openai' },
+  { id: 'openai/gpt-5.4', name: 'GPT-5.4', provider: 'openai' },
+  { id: 'openai/o4-mini', name: 'o4 Mini', provider: 'openai' },
+  { id: 'openai/gpt-4.1', name: 'GPT-4.1', provider: 'openai' },
+  { id: 'google/gemini-2.5-pro', name: 'Gemini 2.5 Pro', provider: 'google' },
+  { id: 'google/gemini-2.5-flash', name: 'Gemini 2.5 Flash', provider: 'google' },
+  { id: 'moonshotai/kimi-k2.5', name: 'Kimi K2.5', provider: 'moonshotai' },
+  { id: 'z-ai/glm-5', name: 'GLM 5', provider: 'z-ai' },
+  { id: 'deepseek/deepseek-v4-pro', name: 'DeepSeek V4 Pro', provider: 'deepseek' },
+  { id: 'deepseek/deepseek-v4-flash', name: 'DeepSeek V4 Flash', provider: 'deepseek' },
+  { id: 'qwen/qwen3.5-plus-02-15', name: 'Qwen3.5 Plus', provider: 'qwen' },
 ] as const;
 
 // REST endpoints
@@ -34,6 +39,7 @@ export const ENDPOINTS = {
 
   // Users
   USERS_ME: `${API_BASE}/users/me`,
+  USER_AVATAR: `${API_BASE}/users/me/avatar`,
   USER: (id: string) => `${API_BASE}/users/${id}`,
 
   // WebSocket ticket
@@ -81,9 +87,15 @@ export const ENDPOINTS = {
   UPLOAD_COMPLETE: (orgId: string) => `${API_BASE}/orgs/${orgId}/upload/complete`,
   FILE: (id: string) => `${API_BASE}/files/${id}`,
 
+  // Approval requests (org-scoped)
+  APPROVAL_REQUESTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/approval-requests`,
+
   // Approvals (global)
+  APPROVAL: (id: string) => `${API_BASE}/approvals/${id}`,
   APPROVAL_DECIDE: (id: string) => `${API_BASE}/approvals/${id}/decide`,
+  APPROVAL_CANCEL: (id: string) => `${API_BASE}/approvals/${id}/cancel`,
   APPROVALS_PENDING: `${API_BASE}/approvals/pending`,
+  APPROVALS_ACTIONS: `${API_BASE}/approvals/actions`,
 
   // Agents (org-scoped)
   AGENTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents`,
@@ -92,6 +104,8 @@ export const ENDPOINTS = {
     `${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_AVATAR: (orgId: string, agentId: string) =>
+    `${API_BASE}/orgs/${orgId}/agents/${agentId}/avatar`,
   AGENT_ACTIVITY: (orgId: string, agentId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/activity`,
   AGENT_MONITOR: (orgId: string, agentId: string) =>
@@ -259,6 +273,7 @@ export const ENDPOINTS = {
   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_UNREAD: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/inbox/${id}/unread`,
   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`,
@@ -296,6 +311,21 @@ export const ENDPOINTS = {
   // Feature flags (org-scoped, server-evaluated)
   FEATURE_FLAGS: (orgId: string) => `${API_BASE}/orgs/${orgId}/feature-flags`,
 
+  // Billing & Credits (org-scoped)
+  BILLING: (orgId: string) => `${API_BASE}/orgs/${orgId}/billing`,
+  BILLING_TRANSACTIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/billing/transactions`,
+  BILLING_CHECKOUT: (orgId: string) => `${API_BASE}/orgs/${orgId}/billing/checkout`,
+  BILLING_AUTO_RELOAD: (orgId: string) => `${API_BASE}/orgs/${orgId}/billing/auto-reload`,
+  BILLING_SETUP_INTENT: (orgId: string) => `${API_BASE}/orgs/${orgId}/billing/setup-intent`,
+  // MACHINE_SPEC is intentionally absent until the server registers
+  // `PATCH /machines/{machineId}/spec`. Reintroduce with ParallClient.resizeMachine
+  // once the in-place resize endpoint lands.
+  COMPUTE_PRICING: () => `${API_BASE}/billing/compute-pricing`,
+
+  // ADMIN_GRANTS intentionally NOT exported here — it sits under the
+  // unauthenticated `/internal/admin/*` surface and must not bleed into the
+  // public SDK. Admin dashboard hits the URL directly from its own client.
+
 } as const;
 
 // WebSocket event types
@@ -354,6 +384,11 @@ export const WS_EVENTS = {
   SCHEDULE_UPDATED: 'schedule.updated',
   SCHEDULE_DELETED: 'schedule.deleted',
   SCHEDULE_FIRED: 'schedule.fired',
+  BILLING_BALANCE_UPDATED: 'billing.balance_updated',
+  BILLING_LOW_BALANCE: 'billing.low_balance',
+  BILLING_MACHINE_STOPPED: 'billing.machine_stopped',
+  BILLING_INSUFFICIENT: 'billing.insufficient',
+  USER_UPDATED: 'user.updated',
 } as const;
 
 // Canonical target URI builders for unified comments.