@parall/sdk 1.47.0 → 1.49.0

package/src/types.ts

@@ -111,6 +111,12 @@ export interface TransferChatOwnershipRequest {
 export interface UnreadEntry {
   count: number;
   mentions: number;
+  /** Share of `count` contributed by unread thread replies (only present when
+   *  the unread fetch opted into `include_thread_replies`). Top-level timeline
+   *  unread = count - (thread_count ?? 0). */
+  thread_count?: number;
+  /** Share of `mentions` contributed by unread thread replies. */
+  thread_mentions?: number;
   since?: string;
 }
 
@@ -273,6 +279,12 @@ export interface Message {
    * absent from the stack. A reload re-derives it from the server's view.
    */
   recent_repliers?: User[];
+  /**
+   * Per-viewer count of thread replies newer than the viewer's thread read
+   * cursor, excluding the viewer's own replies (root only). Populated on
+   * top-level list responses; omitted when zero.
+   */
+  unread_reply_count?: number;
   edited_at: string | null;
   deleted_at: string | null;
   created_at: string;
@@ -281,6 +293,27 @@ export interface Message {
   agent_session_id?: string | null;
   hints?: MessageHints | null;
   attachments?: Attachment[];
+  reactions?: ReactionSummary[];
+}
+
+/**
+ * Aggregated reactions for one emoji on a message.
+ *
+ * `has_reacted` is viewer-relative in REST responses. In
+ * `message.reaction.updated` WS broadcasts it is computed for the ACTOR who
+ * triggered the toggle — subscribers must recompute their own state from
+ * `user_ids` (see docs/engineering-design/ws-protocol.md).
+ */
+export interface ReactionSummary {
+  emoji: string;
+  count: number;
+  user_ids: string[];
+  has_reacted: boolean;
+}
+
+export interface ToggleReactionResponse {
+  added: boolean;
+  reactions: ReactionSummary[];
 }
 
 export interface Attachment {
@@ -1159,6 +1192,13 @@ export interface Task {
   seq_number: number | null;
   identifier: string | null;
   sort_order: number;
+  /**
+   * Planned start date, YYYY-MM-DD (calendar date, timezone-free) — the
+   * planned schedule's left edge, independent of started_at (when work
+   * actually began). Absent on servers older than migration 145. When both
+   * dates are set, planned_start_date <= due_date.
+   */
+  planned_start_date?: string | null;
   /** Planned completion date, YYYY-MM-DD (calendar date, timezone-free). */
   due_date: string | null;
   assignee?: User;
@@ -1246,6 +1286,8 @@ export interface CreateTaskRequest {
   project_id?: string;
   source_chat_id?: string;
   sort_order?: number;
+  /** Planned start date, YYYY-MM-DD. Must be <= due_date when both are set. */
+  planned_start_date?: string;
   /** Planned completion date, YYYY-MM-DD. */
   due_date?: string;
 }
@@ -1266,6 +1308,12 @@ export interface UpdateTaskRequest {
    * full column. Mutually exclusive with sort_order.
    */
   placement?: 'end';
+  /**
+   * Planned start date, YYYY-MM-DD; explicit null clears it. The post-patch
+   * state must satisfy planned_start_date <= due_date when both are set
+   * (400 INVALID_DATE_RANGE otherwise).
+   */
+  planned_start_date?: string | null;
   /** Planned completion date, YYYY-MM-DD; explicit null clears it. */
   due_date?: string | null;
   /**
@@ -2179,6 +2227,20 @@ export interface MessageDeleteData {
   thread_root_id?: string;
 }
 
+/**
+ * Payload of the `message.reaction.updated` WS broadcast. `reactions` is the
+ * full aggregated snapshot for the message; its `has_reacted` flags are
+ * actor-relative (see {@link ReactionSummary}) — recompute from `user_ids`.
+ */
+export interface ReactionUpdatedData {
+  message_id: string;
+  chat_id: string;
+  emoji: string;
+  user_id: string;
+  added: boolean;
+  reactions: ReactionSummary[];
+}
+
 export interface TypingUpdateData {
   chat_id: string;
   thread_root_id: string | null;
@@ -2497,6 +2559,14 @@ export interface InboxItem {
   grouping_priority: number;
   /** Number of events in this group. Populated by the grouped list query. */
   group_count: number;
+  /**
+   * True when ANY row in this item's group is unread — the same group-level
+   * definition the unread-count badge uses. The representative row's own
+   * `read_at` can be set while older rows in its group are still unread, so
+   * read-state display must key off this field. Optional: absent on locally
+   * cached rows written before the field shipped (fall back to `read_at`).
+   */
+  group_unread?: boolean;
   read_at: string | null;
   archived_at: string | null;
   snoozed_until: string | null;
@@ -3065,6 +3135,13 @@ export interface ReadPositionUpdateData {
   last_read_message_id: string;
 }
 
+/** Per-thread read cursor sync across the user's devices. */
+export interface ThreadReadPositionUpdateData {
+  chat_id: string;
+  thread_root_id: string;
+  last_read_reply_id: string;
+}
+
 export interface NotificationAlertData {
   title: string;
   body: string;
@@ -3079,6 +3156,7 @@ export type WsEventMap = {
   'message.patch': MessagePatchData;
   'message.edit': MessageEditData;
   'message.delete': MessageDeleteData;
+  'message.reaction.updated': ReactionUpdatedData;
   'typing.update': TypingUpdateData;
   'chat.created': ChatCreatedData;
   'chat.update': ChatUpdateData;
@@ -3123,6 +3201,7 @@ export type WsEventMap = {
   'inbox.update': InboxUpdateData;
   'inbox.bulk_update': InboxBulkUpdateData;
   'read_position.updated': ReadPositionUpdateData;
+  'thread_read_position.updated': ThreadReadPositionUpdateData;
   'dispatch.new': DispatchNewData;
   'dispatch.received': DispatchReceivedData;
   'dispatch.resolved': DispatchResolvedData;
@@ -3327,6 +3406,37 @@ export interface BacklinksResponse {
   next_cursor?: string;
 }
 
+/**
+ * Request for POST /orgs/{orgId}/refs/outbound — two mutually exclusive
+ * forms, modeled as a union so an invalid mixed shape fails at compile time:
+ * `thread_root_id` resolves a thread's message set server-side (root + ALL
+ * non-deleted replies — the client's reply window may be partial), while
+ * `source_type` + `source_ids` lists explicit sources (max 500; v1 accepts
+ * only `message` sources).
+ */
+export type OutboundRefsRequest =
+  | { thread_root_id: string; source_type?: never; source_ids?: never }
+  | { source_type: string; source_ids: string[]; thread_root_id?: never };
+
+/** One raw ref_links row; dedupe/grouping is a client concern. */
+export interface OutboundRefItem {
+  uri: string;
+  target_type: string;
+  target_id: string;
+  target_path?: string;
+  target_frag?: string;
+  context?: string;
+  source_type: string;
+  source_id: string;
+  position: number;
+}
+
+export interface OutboundRefsResponse {
+  data: OutboundRefItem[];
+  /** Set when the server-side sanity cap dropped the tail of the row set. */
+  truncated?: boolean;
+}
+
 /**
  * One entity in a multi-hop ref-graph traversal (GET /refs/graph). `id`/`uri` are
  * the ref_links endpoint identifier: a bare prll:// entity id for most nodes
@@ -3968,6 +4078,29 @@ export interface BrowserViewerCommandResponse {
   result: Record<string, unknown> | null;
 }
 
+/**
+ * Cloud Edge live viewer (V1b, design §6). Same request/reply shape as the v2
+ * browser-profile viewer — the transport-agnostic `BrowserViewer` client drives
+ * either — but a distinct type so the edge viewer surface never depends on the
+ * v2 browser-profile viewer symbols.
+ */
+export interface EdgeViewerCommandRequest {
+  /** Correlates a viewer session. Omit on `stream.start`; the server returns one. */
+  session_id?: string;
+  command: string;
+  input?: Record<string, unknown>;
+}
+
+export interface EdgeViewerCommandResponse {
+  session_id: string;
+  /**
+   * Command-specific result. For `stream.start`:
+   * `{ offer_sdp, candidates, ice_servers, streamed_tab_id }`. May be `null` on
+   * the wire (a nil Go result map serializes as JSON null); coalesce to `{}`.
+   */
+  result: Record<string, unknown> | null;
+}
+
 export interface GrantBrowserProfileConsentRequest {
   clip_id: string;
 }
@@ -4135,6 +4268,15 @@ export type EdgePlacement = 'byoc' | 'hosted';
  */
 export type EdgeHostedState = 'idle' | 'deleting';
 
+/** Stable API error codes returned by the BYOC unregister contract. */
+export type EdgeDeviceUnregisterErrorCode =
+  | 'JWT_REQUIRED'
+  | 'HUMAN_REQUIRED'
+  | 'FORBIDDEN'
+  | 'EDGE_PLACEMENT_UNSUPPORTED'
+  | 'EDGE_ONLINE'
+  | 'EDGE_INTEGRITY_ERROR';
+
 export interface EdgeDevice {
   id: string;
   org_id: string;
@@ -4170,6 +4312,45 @@ export interface EdgeBrowserProfile {
   is_default: boolean;
   created_at: string;
   updated_at: string;
+  /**
+   * True when the profile has a fixed egress proxy configured (hosted Cloud
+   * Profiles). Presence flag only — endpoint/username/password are readable
+   * exclusively by managers via the dedicated proxy endpoint, and the password
+   * never leaves the server.
+   */
+  proxy_configured?: boolean;
+}
+
+/**
+ * Sanitized per-profile egress proxy status (hosted Cloud Profiles) — the GET
+ * response and the PUT/DELETE result. NEVER carries the password; `password_set`
+ * is the only trace of it.
+ */
+export interface EdgeProfileProxyStatus {
+  configured: boolean;
+  server?: string;
+  username?: string;
+  password_set: boolean;
+  /** Opaque compare-and-swap token for conditional PUT/DELETE. */
+  version: string;
+  /** Authoritative mutation gate; false whenever a non-released lease exists. */
+  can_mutate: boolean;
+  /** Actual lease state blocking a mutation (never inferred from device status). */
+  lease_status?: 'pending' | 'assigned' | 'active' | 'releasing' | 'repair';
+  /** Suggested delay before re-reading authoritative state. */
+  retry_after_seconds?: number;
+}
+
+/**
+ * PUT body for a profile's egress proxy: the FULL triple every time (no
+ * tri-state merge — the stored blob is encrypted, so replace always re-supplies
+ * complete credentials). Clearing is DELETE, never an empty PUT. Username and
+ * password go together or not at all.
+ */
+export interface SetEdgeProfileProxyRequest {
+  server: string;
+  username?: string;
+  password?: string;
 }
 
 export interface ClipConnection {
@@ -4185,6 +4366,102 @@ export interface ClipConnection {
   updated_at: string;
 }
 
+/**
+ * A clip in the api-server org registry (`crg_…`, table `clip_registry`) — the
+ * v3 registry that install and clip connections operate on. Distinct from
+ * {@link RegistryClipInfo}, which is the clip-service → Pinix Hub catalog proxy
+ * and carries no registry id.
+ */
+export interface ClipRegistryEntry {
+  id: string;
+  org_id: string;
+  name: string;
+  description?: string;
+  visibility: 'public' | 'private';
+  version?: string;
+  /** clip.json manifest. `type` absent/null means browser (predates the field). */
+  manifest: Record<string, unknown> | null;
+  author_id: string;
+  /** Reviewed snapshot served cross-org. Absent = never approved. */
+  approved_version_id?: string;
+  created_at: string;
+  updated_at: string;
+  /** Author-org-only computed fields (state of the latest submitted version). */
+  review_status?: string;
+  review_note?: string;
+}
+
+export interface InstallRegistryClipResponse {
+  ok: boolean;
+  clip_id: string;
+  name: string;
+}
+
+/**
+ * Execute a registry (Edge) clip command on an Edge device
+ * (`POST /orgs/{orgId}/edge/exec`).
+ *
+ * Routing is EXPLICIT — exactly one of:
+ * - `connection`: a clip connection id (`ccn_…`) or its org-local alias. The
+ *   ONLY route to a hosted (Cloud Profile) device: the connection its
+ *   maintainer bound IS the org-wide authorization. Also valid for BYOC.
+ * - `edge_id`: a BYOC desktop device the CALLER owns. Naming a hosted device
+ *   here is refused (`400 HOSTED_CONNECTION_REQUIRED`).
+ * - neither: legacy BYOC fallback — resolves only to the caller's OWN online
+ *   desktop device, never to a hosted one.
+ */
+export interface ExecEdgeClipRequest {
+  /**
+   * Clip name in the org's clip registry (or an installed marketplace clip).
+   * Exactly ONE of `clip` or `clip_id` is required — same identity contract as
+   * clip invoke: bare names keep the fail-closed collision behavior (own-org
+   * shadows installs; two installed namesakes → `409 CLIP_NAME_AMBIGUOUS`).
+   */
+  clip?: string;
+  /**
+   * Exact registry Clip id (`crg_…`). Selects the exact object without
+   * weakening execution trust (cross-org still requires public + approved +
+   * installed and runs only the approved snapshot).
+   */
+  clip_id?: string;
+  /** Command to run — resolves to `<command>.js` in the clip's files. */
+  command: string;
+  /** Command arguments, forwarded verbatim to the clip. */
+  args?: unknown;
+  /** Connection id (`ccn_…`) or alias. Required for hosted devices. */
+  connection?: string;
+  /** Owned BYOC device id. Mutually exclusive with `connection`. */
+  edge_id?: string;
+  /**
+   * Browser profile name. With `connection` it may only restate the profile
+   * that connection grants (`400 CONNECTION_PROFILE_MISMATCH` otherwise).
+   */
+  profile?: string;
+  /** Execution timeout in MILLISECONDS (default 30000, max 120000). */
+  timeout?: number;
+  /**
+   * Optional audit tag (≤128 chars). Keep the SAME id across an
+   * EDGE_ACTIVATING retry loop so the server's audit log reads the retries as
+   * one logical call. It is NOT an idempotency key — it deduplicates nothing.
+   */
+  correlation_id?: string;
+}
+
+/**
+ * A completed execution's result envelope (HTTP 200). Every non-success is
+ * thrown as a typed {@link ApiError} instead — see
+ * {@link ParallClient.execEdgeClip} for the full code table and, critically,
+ * which codes are safe to retry.
+ */
+export interface EdgeClipExecResult {
+  request_id: string;
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  error_code?: string;
+  duration_ms: number;
+}
+
 /**
  * Two INDEPENDENT onboarding journeys. The original fields mean what they always
  * meant — "has this org set up the desktop journey?" — and hosted-backed state