@parall/sdk 1.47.0 → 1.48.0

package/src/types.ts

@@ -2497,6 +2497,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;
@@ -4135,6 +4143,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;
@@ -4185,6 +4202,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