@parall/sdk 1.44.0 → 1.46.0

package/src/types.ts

@@ -1159,6 +1159,8 @@ export interface Task {
   seq_number: number | null;
   identifier: string | null;
   sort_order: number;
+  /** Planned completion date, YYYY-MM-DD (calendar date, timezone-free). */
+  due_date: string | null;
   assignee?: User;
   creator?: User;
   created_at: string;
@@ -1244,6 +1246,8 @@ export interface CreateTaskRequest {
   project_id?: string;
   source_chat_id?: string;
   sort_order?: number;
+  /** Planned completion date, YYYY-MM-DD. */
+  due_date?: string;
 }
 
 export interface UpdateTaskRequest {
@@ -1255,6 +1259,15 @@ export interface UpdateTaskRequest {
   parent_id?: string | null;
   project_id?: string | null;
   sort_order?: number;
+  /**
+   * Ordering intent resolved server-side in the update transaction:
+   * 'end' appends the task to its (possibly new) status column. Preferred
+   * over computing sort_order from client caches, which may not hold the
+   * full column. Mutually exclusive with sort_order.
+   */
+  placement?: 'end';
+  /** Planned completion date, YYYY-MM-DD; explicit null clears it. */
+  due_date?: string | null;
   /**
    * Dispatch lane binding (agent senders during a typed dispatch turn).
    * dispatch_lane + dispatch_event_id bind the update to the claimed typed
@@ -1319,6 +1332,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' | 'creator_ineligible';
+/**
+ * Why a schedule sits in its current non-active state. Cancel reasons appear
+ * only on `cancelled` rows; `attendee_unreachable` appears only on `paused`
+ * rows (stamped by the scheduler when every attendee is an agent on a
+ * terminated machine; cleared on resume — a user pause keeps null).
+ */
+export type ScheduleStatusReason = ScheduleCancelReason | 'attendee_unreachable';
 export type ScheduleRunStatus = 'delivered' | 'missed' | 'failed';
 
 export interface Schedule {
@@ -1342,7 +1362,10 @@ export interface Schedule {
   duration_seconds: number | null;
   target_ids: string[];
   status: ScheduleStatus;
-  cancel_reason: ScheduleCancelReason | null;
+  /** Optional during the rename rollout: pre-135 servers emit only `cancel_reason`. Read via `status_reason ?? cancel_reason`. */
+  status_reason?: ScheduleStatusReason | null;
+  /** @deprecated Rename-rollout alias of `status_reason`, emitted on cancelled rows only (never carries pause reasons); read `status_reason ?? cancel_reason`. */
+  cancel_reason?: ScheduleCancelReason | null;
   next_fire_at: string | null;
   last_fire_at: string | null;
   run_count: number;
@@ -1838,6 +1861,29 @@ export interface WikiAnchorStatusResponse {
   results: WikiAnchorStatus[];
 }
 
+export interface WikiAnchorResolveRequest {
+  targets: string[];
+}
+
+export type WikiAnchorResolveState = 'attached' | 'detached' | 'file_missing' | 'unknown';
+
+export interface WikiAnchorResolveRange {
+  start: number;
+  end: number;
+}
+
+export interface WikiAnchorResolveResult {
+  target_uri: string;
+  state: WikiAnchorResolveState;
+  current?: WikiAnchorResolveRange;
+  origin_quote?: string;
+}
+
+export interface WikiAnchorResolveResponse {
+  head_rev: string;
+  results: WikiAnchorResolveResult[];
+}
+
 export interface WikiRefsCheckResponse {
   wiki_id: string;
   wiki_slug: string;
@@ -2385,12 +2431,15 @@ export interface Comment {
   id: string;
   org_id: string;
   target_uri: string;
+  target_quote?: string | null;
   parent_id?: string | null;
   author_id: string;
   body: string;
   mentions?: Mention[];
   hints?: MessageHints | null;
   agent_step_id?: string | null;
+  resolved_at?: string | null;
+  resolved_by_id?: string | null;
   created_at: string;
   updated_at: string;
   author?: User;
@@ -2398,6 +2447,7 @@ export interface Comment {
 
 export interface CreateCommentRequest {
   target_uri: string;
+  target_quote?: string;
   body: string;
   parent_id?: string;
 }
@@ -2490,10 +2540,14 @@ export interface ChannelConnection {
 }
 
 export interface ChannelCredentialsInput {
-  app_id: string;
-  app_secret: string;
+  /** Feishu fields. */
+  app_id?: string;
+  app_secret?: string;
   verification_token?: string;
   encrypt_key?: string;
+  /** Slack fields (webhook-only: the signing secret is the verifier). */
+  bot_token?: string;
+  signing_secret?: string;
   team_id?: string;
 }
 
@@ -2543,10 +2597,13 @@ export interface ChannelMessage {
 }
 
 /**
- * Feishu one-click provisioning session (OAuth device flow). The client
- * renders `verification_url` as a QR code and lazily polls the status
- * endpoint every `poll_interval_seconds` — each poll may forward one
- * provider poll server-side, so respect the interval.
+ * One-click provisioning session. Provider-specific shape:
+ * - feishu (OAuth device flow): render `verification_url` as a QR code;
+ *   each status poll may forward one provider poll server-side, so respect
+ *   `poll_interval_seconds`.
+ * - slack (manifest + OAuth install): `verification_url` is the authorize
+ *   link to open; status polls are pure state reads (completion is pushed
+ *   by the OAuth callback).
  */
 export type ChannelProvisioningStatus =
   | 'pending'
@@ -2572,14 +2629,62 @@ export interface ChannelProvisioningSession {
   expires_at: string;
   created_at: string;
   updated_at: string;
-  /** QR target — present on live (pending/polling) sessions only. */
+  /**
+   * Provisioning target — present on live (pending/polling) sessions only.
+   * feishu: the QR-code content; slack: the OAuth authorize link.
+   */
   verification_url?: string;
+  /** feishu only. */
   user_code?: string;
 }
 
-export interface InitiateChannelProvisioningInput {
-  agent_id: string;
-  provider: ChannelProvider;
+/**
+ * Discriminated on `provider`: slack REQUIRES the config token (the server
+ * 400s without it), other providers have no such field — the union makes a
+ * token-less slack initiate unrepresentable at compile time.
+ */
+export type InitiateChannelProvisioningInput =
+  | {
+      agent_id: string;
+      provider: 'slack';
+      /**
+       * The short-lived app-configuration token (12h, generated at
+       * api.slack.com/apps). Transits once into apps.manifest.create and is
+       * never stored.
+       */
+      config_token: string;
+    }
+  | {
+      agent_id: string;
+      provider: Exclude<ChannelProvider, 'slack'>;
+    };
+
+/**
+ * Tier-B platform verb request (agent-only): send as the bound bot.
+ * Deliberately narrowed to 'slack' — the verb surface is per-vendor
+ * (feishu outbound is the lark-cli broker, not this endpoint), so a
+ * generic ChannelProvider here would compile call sites that always 400.
+ */
+export interface SendChannelMessageInput {
+  channel_type: 'slack';
+  /** Vendor-native conversation id from the inbound event (e.g. C…/D…). */
+  conversation_id: string;
+  /**
+   * External message id being answered (channel-domain format). REQUIRED
+   * for channel conversations (the reply lands in that message's thread);
+   * optional for DMs (always linear).
+   */
+  reply_to?: string;
+  text: string;
+}
+
+export interface SentChannelMessage {
+  channel_type: 'slack';
+  conversation_id: string;
+  /** Channel-domain external id ({channel}:{ts}) — usable as a reply_to. */
+  message_id: string;
+  thread_anchor?: string;
+  sent_at: string;
 }
 
 // ============================================================
@@ -2712,7 +2817,8 @@ export interface SteerDispatchResponse {
  */
 export type CompleteDispatchRequest =
   | CompleteDispatchLaneRequest
-  | CompleteDispatchSourceFormRequest;
+  | CompleteDispatchSourceFormRequest
+  | CompleteDispatchByIDRequest;
 
 /** Lane form: no_action sweep + lane release + re-drive. */
 export interface CompleteDispatchLaneRequest {
@@ -2726,6 +2832,7 @@ export interface CompleteDispatchLaneRequest {
    */
   turn_outcome?: 'ok' | 'error';
   sources?: never;
+  dispatch_event_id?: never;
 }
 
 /**
@@ -2740,6 +2847,25 @@ export interface CompleteDispatchSourceFormRequest {
   lane?: never;
   target_uri?: never;
   thread_root_id?: never;
+  dispatch_event_id?: never;
+}
+
+/**
+ * By-id form: terminal resolution of ONE WorkItem — the typed bridge's turn
+ * close. Exact where the source pair is ambiguous (a task PATCH enqueues
+ * sibling task_assign + task_update rows under one source tuple). `lane`
+ * doubles as the fence token: pass the claimed lane while the row is
+ * lane-owned (a stale/absent token answers 409 STALE_LANE and touches
+ * nothing); omit it to administratively close a pending row (the
+ * wrapper-less buffered-drain path). Idempotent on terminal rows.
+ */
+export interface CompleteDispatchByIDRequest {
+  dispatch_event_id: string;
+  lane?: string;
+  turn_outcome?: 'ok' | 'error';
+  sources?: never;
+  target_uri?: never;
+  thread_root_id?: never;
 }
 
 /** Lane-form result. */
@@ -3055,6 +3181,8 @@ export interface ResolvedRef {
   resolved_rev?: string;
   line_start?: number;
   line_end?: number;
+  text_start?: number;
+  text_end?: number;
   heading_path?: string[];
   symbol_name?: string;
 
@@ -3871,6 +3999,30 @@ export interface SearchResponse {
 // Edge Device Types
 // ============================================================
 
+/**
+ * Where an Edge device runs — and, consequently, who it belongs to.
+ *
+ * - `byoc`   — the user's own computer running Parall Clip. Owner-only in every
+ *              sense: only the owner connects it, manages it, or executes on it.
+ * - `hosted` — a platform-managed Cloud Profile. The browser login it holds is an
+ *              ORG-SHARED credential maintained by its creator. Members and agents
+ *              execute against it ONLY through a clip connection its maintainer
+ *              bound; there is no implicit route to a hosted device.
+ */
+export type EdgePlacement = 'byoc' | 'hosted';
+
+/**
+ * Lifecycle of a hosted Cloud Profile. Only the states the server can PROVE without
+ * the runtime fence are emitted today; the fence-aware ones (`starting` / `online` /
+ * `busy`) arrive with the controller.
+ *
+ * - `idle`     — no pod running (and none requested). Creating a profile starts nothing.
+ * - `deleting` — delete requested; the finalizer (pod drain, S3 state purge) is still
+ *                running. Deletion is async and idempotent, so this can persist for
+ *                several minutes.
+ */
+export type EdgeHostedState = 'idle' | 'deleting';
+
 export interface EdgeDevice {
   id: string;
   org_id: string;
@@ -3880,6 +4032,23 @@ export interface EdgeDevice {
   last_seen_at?: string;
   created_at: string;
   updated_at: string;
+  /** Absent on responses from a pre-D1 server; treat a missing value as 'byoc'. */
+  placement?: EdgePlacement;
+  /** Hosted devices only. */
+  hosted_state?: EdgeHostedState;
+  /**
+   * Whether THIS caller may sign into / rebind / delete this device
+   * (hosted: human maintainer ∨ human org admin; byoc: owner). Server-computed, so a
+   * client can render management affordances without reimplementing the rule and
+   * drifting from it.
+   */
+  can_manage?: boolean;
+  /**
+   * True for hosted devices: clips bound to it by its maintainer may be run by other
+   * org members and agents. Surface this before anyone signs in — the login being
+   * shared with the whole org is the product contract, not a footnote.
+   */
+  shared?: boolean;
 }
 
 export interface EdgeBrowserProfile {
@@ -3904,10 +4073,22 @@ export interface ClipConnection {
   updated_at: string;
 }
 
+/**
+ * Two INDEPENDENT onboarding journeys. The original fields mean what they always
+ * meant — "has this org set up the desktop journey?" — and hosted-backed state
+ * never counts toward them, so a Cloud Profile cannot make desktop onboarding look
+ * finished and tell the user to skip installing the app they still need. Precisely:
+ * device-backed fields are scoped to live `placement='byoc'` edges;
+ * `connection_created` additionally counts device-less MCP bindings (MCP has no
+ * device and predates hosted). The `hosted_*` fields are the second journey;
+ * neither impersonates the other.
+ */
 export interface EdgeOnboardingStatus {
   device_registered: boolean;
   device_online: boolean;
   clip_installed: boolean;
   connection_created: boolean;
   profile_created: boolean;
+  hosted_profile_created?: boolean;
+  hosted_connection_created?: boolean;
 }