@parall/sdk 1.22.0 → 1.24.0

package/src/types.ts

@@ -154,29 +154,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 +250,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 +296,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;
 }
 
@@ -391,6 +415,10 @@ export interface WsTicketResponse {
   ws_url: string;
 }
 
+export interface FeatureFlagsResponse {
+  flags: Record<string, boolean | string | number>;
+}
+
 // ============================================================
 // API Request Types
 // ============================================================
@@ -479,10 +507,76 @@ export interface CreateAgentRequest {
   agent_provider?: string;
   agent_endpoint?: string;
   agent_model?: string;
+  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;
+}
+
+/**
+ * AgentProviderConfig is the WRITE shape: what a client sends on
+ * CreateAgent.provider_config or UpdateAgentProviderConfigRequest.
+ *
+ * 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_*
+ *
+ * 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 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;
+}
+
+/**
+ * PATCH /orgs/{orgId}/agents/{id}/provider-config body.
+ * Same shape as the create-time write; PATCH semantics (nil=leave,
+ * ""=clear, value=set) are handled by the server, not by the type.
+ */
+export type UpdateAgentProviderConfigRequest = AgentProviderConfig;
+
+export interface UpdateAgentRequest {
+  display_name?: string;
+  agent_provider?: string;
+  agent_endpoint?: string;
+  agent_model?: string;
+  model_management?: string;
+  agent_permissions?: string[];
+  description?: string;
 }
 
 // ---- Machine types ----
@@ -493,6 +587,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;
@@ -513,12 +614,18 @@ export interface AgentProfile {
   provider: string | null;
   endpoint: string | null;
   model: string | null;
+  model_management: string | null; // "platform" | "self" | null
   permissions: string[];
   machine_id: string | null;
   runtime_type: string;
+  description: string | null;
   run_config?: RunConfig;
   created_by: string;
   created_at: string;
+  // provider_config is deliberately NOT on this shape. It is admin-only
+  // and the server strips it from the agents list response (tag
+  // json:"-" in Go). Fetch via `ParallClient.getAgentProviderConfig`
+  // from an admin context only.
 }
 
 export interface AgentPresence {
@@ -537,11 +644,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;
@@ -550,6 +658,10 @@ export interface FileUrlResponse {
   mime_type: string;
 }
 
+export interface AvatarUploadResponse {
+  avatar_url: string;
+}
+
 // ============================================================
 // Task Types
 // ============================================================
@@ -688,14 +800,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;
@@ -708,6 +819,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;
@@ -725,8 +838,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;
 }
@@ -734,7 +845,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;
@@ -745,12 +856,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;
@@ -768,11 +880,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;
@@ -1242,12 +1356,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 {
@@ -1466,6 +1583,7 @@ export interface InboxItem {
 
 export type DispatchEventType = 'message' | 'task_assign' | 'task_comment' | 'schedule.fire';
 export type DispatchStatus = 'pending' | 'acked';
+export type DispatchDeliveryReason = 'mention' | 'watcher';
 
 export interface DispatchEvent {
   id: string;
@@ -1484,6 +1602,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;
@@ -1570,6 +1694,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
@@ -1609,6 +1738,7 @@ export interface PlatformConfigResponse {
   version: string;
   schema_version: number;
   min_plugin_version?: string;
+  mode?: string;
   config: Record<string, unknown>;
 }
 
@@ -1805,3 +1935,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;
+}