@parall/sdk 1.23.0 → 1.25.0

package/src/types.ts

@@ -62,7 +62,14 @@ export interface PushSubscribeRequest {
 export interface NotifPrefs {
   dm?: boolean;
   mention?: boolean;
+  group_message?: boolean;
   task_assign?: boolean;
+  task_comment?: boolean;
+  task_update?: boolean;
+  approval_request?: boolean;
+  schedule_fire?: boolean;
+  agent_alert?: boolean;
+  invitation?: boolean;
 }
 
 export interface NotificationPreferences {
@@ -154,29 +161,34 @@ export interface ToolResultContent {
   collapsible: boolean;
 }
 
-export interface ApprovalOption {
-  key: string;
-  label: string;
-  style: 'primary' | 'danger' | 'secondary';
-}
-
+// CardContent is the polymorphic content for 'card' message type.
+// card_type discriminates the data payload.
 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;
+  card_type: 'approval';
+  entity_id: string;
+  display: {
+    title: string;
+    description?: string;
+    requester?: { id: string; name: string };
+  };
+  interaction: {
+    action: string;
+    resource_type?: string;
+    resource_id?: string;
+    action_payload?: Record<string, unknown>;
+    actions: string[];
+    status: string;
+    decided_by?: string;
+    decided_at?: string;
+    execution_status?: ExecutionStatus | null;
+    execution_error?: string | null;
+    executed_at?: string | null;
+  };
 }
 
-// CardContent is the polymorphic content for 'card' message type.
-// card_type discriminates the data payload.
 export type CardContent =
-  | { card_type: 'approval'; data: ApprovalCardContent; approval_id?: string }
-  | { card_type: string; data: Record<string, unknown>; approval_id?: string };
+  | ApprovalCardContent
+  | { card_type: string; entity_id?: string; data?: Record<string, unknown> };
 
 export type AgentState = 'thinking' | 'tool_calling' | 'streaming' | 'waiting_approval' | 'completed' | 'error';
 
@@ -245,22 +257,40 @@ export interface Attachment {
   created_at: string;
 }
 
-export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled';
+
+export type ExecutionStatus = 'succeeded' | 'failed';
 
 export interface Approval {
   id: string;
-  message_id: string;
-  chat_id: string;
-  requester_id: string;
-  status: ApprovalStatus;
+  org_id: string;
   action_type: string;
+  resource_uri: string;
   action_payload: Record<string, unknown>;
+  title: string;
+  requester_id: string;
   decided_by: string | null;
   decided_at: string | null;
+  status: ApprovalStatus;
   expires_at: string | null;
+  execution_status?: ExecutionStatus | null;
+  execution_error?: string | null;
+  executed_at?: string | null;
+  chat_id: string;
+  message_id?: string | null;
   created_at: string;
 }
 
+export interface CreateApprovalRequest {
+  action_type: string;
+  resource_uri: string;
+  action_payload?: Record<string, unknown>;
+  chat_id: string;
+  title: string;
+  reason?: string;
+  expires_at?: string;
+}
+
 export type OrgMemberRole = 'owner' | 'admin' | 'member';
 
 export interface Organization {
@@ -273,6 +303,7 @@ export interface Organization {
   smart_routing_strategy: string | null;
   /** Agent ID for strategy='agent'. NULL when strategy is 'llm' or unset. */
   smart_routing_agent_id: string | null;
+  onboarding_agent_id: string | null;
   created_at: string;
 }
 
@@ -486,8 +517,13 @@ export interface CreateAgentRequest {
   model_management?: string; // "platform" | "self"; default by hosting type
   agent_permissions?: string[];
   runtime_type?: string; // "openclaw" | "claude-code" | "codex"; default "openclaw"
+  description?: string;
   machine_type?: string;
-  machine_label?: string;
+  machine_label?: string; // preset: "lite" | "standard" | "pro" | "custom"
+  // Required when machine_label === "custom". Validated server-side.
+  cpu_cores?: number;
+  memory_mb?: number;
+  storage_gb?: number;
   provider_config?: AgentProviderConfig;
 }
 
@@ -495,32 +531,42 @@ export interface CreateAgentRequest {
  * AgentProviderConfig is the WRITE shape: what a client sends on
  * CreateAgent.provider_config or UpdateAgentProviderConfigRequest.
  *
- * Product-default auth for hosted Codex is a ChatGPT subscription via
- * `codex login` OAuth (written to the PVC by the server-side device
- * flow). These fields exist as an admin-level escape hatch for CI,
- * Azure OpenAI, OpenAI-compatible proxies, or per-agent billing
- * isolation.
+ * Hosted agents default to "managed by Parall" — the hosting service
+ * points the runtime CLI at Parall's LLM proxy and authenticates with
+ * the agent's own API key, keeping billing and attribution server-side.
+ * These per-agent fields are the BYO override: bring your own ChatGPT/
+ * Anthropic subscription, point at Azure OpenAI, or use an OpenAI/
+ * Anthropic-compatible proxy.
+ *
+ * Each runtime consumes exactly one credential family:
+ *   - codex       → openai_*
+ *   - claude-code → anthropic_*
  *
- * Unset / empty-string fields are dropped at provisioning time (treated
- * as "no override" so a partial form doesn't mask the runtime default).
- * Sensitive fields (API key) are injected via K8s Secret-ref; endpoint
- * overrides land as plain env.
+ * The server rejects cross-family fields (e.g. anthropic_* on codex).
+ * Unset / empty-string fields are dropped at provisioning time, so a
+ * partial form doesn't mask the managed proxy path with an empty string.
+ * Sensitive fields (API key / auth token) are injected via K8s
+ * Secret-ref; endpoint overrides land as plain env.
  */
 export interface AgentProviderConfig {
   openai_api_key?: string;
   openai_base_url?: string;
+  anthropic_auth_token?: string;
+  anthropic_base_url?: string;
 }
 
 /**
  * AgentProviderConfigRead is the READ shape returned by GET / list /
- * PATCH-response paths. The server never echoes the raw API key — only
- * a presence flag — so no org admin (or log leak) can ever exfiltrate
- * a previously-configured key from the wire. The base URL is
- * non-sensitive and round-trips cleartext.
+ * PATCH-response paths. The server never echoes the raw secrets — only
+ * presence flags — so no org admin (or log leak) can ever exfiltrate
+ * a previously-configured value from the wire. Base URLs are
+ * non-sensitive and round-trip cleartext.
  */
 export interface AgentProviderConfigRead {
   openai_api_key_set: boolean;
   openai_base_url?: string;
+  anthropic_auth_token_set: boolean;
+  anthropic_base_url?: string;
 }
 
 /**
@@ -537,6 +583,7 @@ export interface UpdateAgentRequest {
   agent_model?: string;
   model_management?: string;
   agent_permissions?: string[];
+  description?: string;
 }
 
 // ---- Machine types ----
@@ -547,6 +594,13 @@ export interface Machine {
   id: string;
   org_id: string;
   label: string;
+  // Persisted spec — set at creation by agent.go from MachinePresets[label]
+  // or user-supplied custom values, and used by hosting.Service.Provision +
+  // billing.go as the authoritative source. Mirrors the server-side
+  // `model.Machine` Go struct.
+  cpu_cores: number;
+  memory_mb: number;
+  storage_gb: number;
   status: MachineStatus;
   compute_provider: string;
   runtime_type: string;
@@ -571,6 +625,7 @@ export interface AgentProfile {
   permissions: string[];
   machine_id: string | null;
   runtime_type: string;
+  description: string | null;
   run_config?: RunConfig;
   created_by: string;
   created_at: string;
@@ -596,11 +651,12 @@ export interface AgentWithRuntime extends User {
 export interface PresignUploadRequest {
   file_name: string;
   file_size: number;
-  mime_type: string;
+  mime_type?: string;
 }
 
 export interface FileUrlResponse {
   url: string;
+  is_proxy_url?: boolean;
   expires_in: number;
   width?: number;
   height?: number;
@@ -609,6 +665,10 @@ export interface FileUrlResponse {
   mime_type: string;
 }
 
+export interface AvatarUploadResponse {
+  avatar_url: string;
+}
+
 // ============================================================
 // Task Types
 // ============================================================
@@ -747,14 +807,13 @@ export interface UpdateProjectRequest {
 
 export type ScheduleSpecType = 'cron' | 'interval' | 'one_shot';
 export type ScheduleStatus = 'active' | 'paused' | 'completed' | 'cancelled';
-export type ScheduleCancelReason = 'user_cancel' | 'attached_gone' | 'target_ineligible';
+export type ScheduleCancelReason = 'user_cancel' | 'attached_gone' | 'creator_ineligible';
 export type ScheduleRunStatus = 'delivered' | 'missed' | 'failed';
 
 export interface Schedule {
   id: string;
   org_id: string;
   creator_id: string;
-  target_id: string;
   attached_to_uri: string | null;
   name: string;
   description: string;
@@ -767,6 +826,8 @@ export interface Schedule {
   end_at: string | null;
   max_runs: number | null;
   catchup_window_seconds: number;
+  duration_seconds: number | null;
+  target_ids: string[];
   status: ScheduleStatus;
   cancel_reason: ScheduleCancelReason | null;
   next_fire_at: string | null;
@@ -784,8 +845,6 @@ export interface ScheduleRun {
   status: ScheduleRunStatus;
   fired_description: string | null;
   fired_attached_uri: string | null;
-  dispatch_event_id: string | null;
-  inbox_item_id: string | null;
   error: string | null;
   created_at: string;
 }
@@ -793,7 +852,7 @@ export interface ScheduleRun {
 export interface CreateScheduleInput {
   name: string;
   description: string;
-  target_id: string;
+  target_ids: string[];
   attached_to_uri?: string;
   spec_type: ScheduleSpecType;
   cron_expr?: string;
@@ -804,12 +863,13 @@ export interface CreateScheduleInput {
   end_at?: string;
   max_runs?: number;
   catchup_window_seconds?: number;
+  duration_seconds?: number;
 }
 
 export interface UpdateScheduleInput {
   name?: string;
   description?: string;
-  target_id?: string;
+  target_ids?: string[];
   attached_to_uri?: string;
   /** Explicitly clear attached_to_uri. Server honors this over `attached_to_uri`. */
   attached_to_uri_clear?: boolean;
@@ -827,11 +887,13 @@ export interface UpdateScheduleInput {
   /** Explicitly clear max_runs. Server honors this over `max_runs`. */
   max_runs_clear?: boolean;
   catchup_window_seconds?: number;
+  duration_seconds?: number;
+  duration_seconds_clear?: boolean;
 }
 
 export interface ScheduleFilters {
   attached_to?: string;
-  target_id?: string;
+  attendee_id?: string;
   creator_id?: string;
   /** Comma-separated list of statuses (e.g. 'active,paused'). */
   status?: string;
@@ -1301,12 +1363,15 @@ export type ApprovalUpdateData = CardUpdateData;
 
 export interface CardUpdateData {
   card_type: string;
-  approval_id?: string;
+  entity_id: string;
   message_id: string;
   chat_id: string;
   status: string;
+  execution_status?: ExecutionStatus | null;
   decided_by?: string;
   decided_at?: string;
+  executed_at?: string | null;
+  execution_error?: string | null;
 }
 
 export interface RecoveryOverflowData {
@@ -1523,8 +1588,9 @@ export interface InboxItem {
 // Dispatch Types (agent event delivery)
 // ============================================================
 
-export type DispatchEventType = 'message' | 'task_assign' | 'task_comment' | 'schedule.fire';
+export type DispatchEventType = 'message' | 'task_assign' | 'task_update' | 'task_comment' | 'schedule.fire';
 export type DispatchStatus = 'pending' | 'acked';
+export type DispatchDeliveryReason = 'mention' | 'watcher';
 
 export interface DispatchEvent {
   id: string;
@@ -1543,6 +1609,12 @@ export interface DispatchEvent {
    * (@mention, DM, task assignment, active-mode fanout).
    */
   source_mode: string | null;
+  /**
+   * Recipient-resolution hint. For task_comment dispatches this distinguishes
+   * explicit @mention delivery from implicit task watcher delivery while the
+   * dispatch event itself remains a source pointer.
+   */
+  delivery_reason: DispatchDeliveryReason | null;
   status: DispatchStatus;
   acked_at: string | null;
   created_at: string;
@@ -1575,7 +1647,8 @@ export interface ReadPositionUpdateData {
 export interface NotificationAlertData {
   title: string;
   body: string;
-  category: string; // "mention" | "dm" | "task_assign"
+  category: string;
+  collapse_id?: string;
   data: Record<string, string> | null; // {org_id, chat_id, url, ...}
 }
 
@@ -1629,6 +1702,11 @@ export type WsEventMap = {
   'schedule.updated': ScheduleUpdatedData;
   'schedule.deleted': ScheduleDeletedData;
   'schedule.fired': ScheduleFiredData;
+  'billing.balance_updated': BillingBalanceUpdatedEvent;
+  'billing.low_balance': BillingLowBalanceEvent;
+  'billing.machine_stopped': BillingMachineStoppedEvent;
+  'billing.insufficient': BillingInsufficientEvent;
+  'user.updated': User;
 };
 
 // Invitation WS event data
@@ -1865,3 +1943,148 @@ export interface SetRuntimeModeRequest {
   update_mode: RuntimeUpdateMode;
   pinned_tag?: string | null;
 }
+
+// ============================================================
+// Billing & Credits
+// ============================================================
+
+export interface CreditWallet {
+  org_id: string;
+  balance: number;
+  updated_at: string;
+}
+
+export interface CreditTransaction {
+  id: string;
+  org_id: string;
+  type: 'topup' | 'auto_reload' | 'llm_deduct' | 'compute_deduct' | 'adjustment' | 'refund' | 'grant' | 'grant_expire';
+  amount: number;
+  balance_after: number;
+  grant_id: string | null;
+  description: string | null;
+  reference_type: string | null;
+  reference_id: string | null;
+  metadata: Record<string, unknown> | null;
+  created_at: string;
+}
+
+export interface BillingSummary {
+  balance: number;
+  llm_usage_this_month: number;
+  compute_usage_this_month: number;
+  total_usage_this_month: number;
+  grants?: CreditGrant[];
+}
+
+// CreditGrant is shipped to user-facing clients via BillingSummary.grants
+// (read-only — issued only by admin). `type` stays `string` so a server-side
+// custom type (an ops one-off, e.g. "incident-1234") doesn't break typed
+// clients.
+//
+// IssueGrantRequest, GrantTypePreset, and GRANT_TYPE_PRESETS are intentionally
+// NOT exported here — those are admin-only contracts (POST body for
+// /internal/admin/orgs/{id}/grants and the admin dropdown defaults).
+// The admin dashboard maintains its own mirror in `ts/admin/lib/api.ts`
+// to stay decoupled from the public SDK ecosystem and its own deploy
+// (standalone Docker, internal network only).
+export interface CreditGrant {
+  id: string;
+  org_id: string;
+  type: string;
+  name: string;
+  original_amount: number;
+  remaining: number;
+  priority: number;
+  expires_at: string | null;
+  metadata: Record<string, unknown> | null;
+  created_by: string | null;
+  created_at: string;
+}
+
+// Read model — what GET /billing/auto-reload returns.
+// `has_payment_method` is server-derived from Stripe customer state.
+export interface AutoReloadSettings {
+  enabled: boolean;
+  threshold: number;
+  reload_amount: number;
+  stripe_price: number;
+  has_payment_method: boolean;
+}
+
+// Write model — what PUT /billing/auto-reload accepts. Excludes derived /
+// read-only fields (has_payment_method) so callers can't accidentally try
+// to clobber server-side state.
+export interface UpdateAutoReloadRequest {
+  enabled: boolean;
+  threshold: number;
+  reload_amount: number;
+  stripe_price: number;
+}
+
+export interface ComputePricing {
+  id: string;
+  component: string;
+  unit: string;
+  price_per_hour: number;
+  effective_from: string;
+  created_at: string;
+}
+
+// Response shape for GET /api/v1/billing/compute-pricing — map keyed by
+// component name ("cpu" | "memory" | "storage").
+export type ComputePricingResponse = Record<string, ComputePricing>;
+
+export interface MachinePreset {
+  key: string;
+  cpu_cores: number;
+  memory_mb: number;
+  storage_gb: number;
+}
+
+export interface CreateCheckoutRequest {
+  amount_cents: number;
+}
+
+export interface CreateCheckoutResponse {
+  checkout_url: string;
+}
+
+export interface CreateSetupIntentResponse {
+  /** Stripe-hosted Checkout Session URL (mode=setup). The frontend redirects
+   * with `window.location.href = setup_url`; Stripe handles the card form
+   * and redirects back to /settings?tab=billing&setup={success|cancelled}.
+   */
+  setup_url: string;
+  /** @deprecated Always empty string. Retained so legacy clients that
+   * destructured `client_secret` from the response don't crash; new code
+   * should use `setup_url`. The redirect-style flow superseded the
+   * Payment Element flow before any consumer wired this field. */
+  client_secret?: string;
+}
+
+// ResizeMachineRequest was retired pending the server-side
+// `PATCH /machines/{id}/spec` route. Reintroduce alongside the route and
+// the matching ParallClient method when in-place resize is implemented.
+
+// Invalidation signal: server publishes only { org_id } on any wallet
+// change; clients refetch `getBilling` / `listBillingTransactions` to get
+// the latest state.
+export interface BillingBalanceUpdatedEvent {
+  org_id: string;
+}
+
+export interface BillingLowBalanceEvent {
+  org_id: string;
+  machine_id: string;
+  grace_ends: string;
+}
+
+export interface BillingMachineStoppedEvent {
+  org_id: string;
+  machine_id: string;
+  reason: string;
+}
+
+export interface BillingInsufficientEvent {
+  org_id: string;
+}