@parall/sdk 1.45.0 → 1.47.0

package/src/types.ts

@@ -1861,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;
@@ -2408,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;
@@ -2421,6 +2447,7 @@ export interface Comment {
 
 export interface CreateCommentRequest {
   target_uri: string;
+  target_quote?: string;
   body: string;
   parent_id?: string;
 }
@@ -2508,15 +2535,27 @@ export interface ChannelConnection {
   ingress_url?: string;
   /** Returned once at mint time (create / token regeneration). */
   ingress_token?: string;
+  /**
+   * The in-product scope-upgrade re-auth can act on this connection
+   * (slack, active, provisioned-family — its auth_config carries the
+   * OAuth client). Mirrors the upgrade endpoint's preconditions exactly.
+   * Manual-family connections upgrade via the Slack console; the UI
+   * hides the upgrade CTA when this is false/absent.
+   */
+  upgrade_eligible?: boolean;
   created_at: string;
   updated_at: string;
 }
 
 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;
 }
 
@@ -2566,10 +2605,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'
@@ -2595,14 +2637,166 @@ 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/update
+       * and is never stored.
+       */
+      config_token: string;
+      /**
+       * Scope-upgrade re-auth: converge the agent's EXISTING active
+       * connection's app on the current manifest and re-authorize it (bot
+       * token replaced in place, app id preserved) instead of creating a
+       * new app.
+       */
+      upgrade?: boolean;
+    }
+  | {
+      agent_id: string;
+      provider: Exclude<ChannelProvider, 'slack'>;
+    };
+
+/**
+ * Manifest-prefill link for the guided manual slack path: the platform
+ * mints a pending connection and returns an api.slack.com link that opens
+ * the create-app form with everything preset (events, scopes, this
+ * connection's webhook URL). The user installs the app themselves and
+ * activates the SAME connection by delivering bot token + signing secret.
+ */
+export interface SlackManifestLinkResult {
+  connection_id: string;
+  manifest_url: string;
+}
+
+/**
+ * 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:
+   * `{channel}:{ts}`, thread children `{channel}:{root}#{ts}`). REQUIRED
+   * for channel conversations (the reply lands in that message's thread).
+   * In DMs the SESSION never forks, but reply POSITION follows the
+   * question: a thread-child id lands the reply inside that thread, a
+   * bare id (or omitting the field) keeps the flattened main flow.
+   */
+  reply_to?: string;
+  text: string;
+}
+
+export interface SentChannelMessage {
+  channel_type: 'slack';
+  conversation_id: string;
+  /**
+   * Channel-domain external id — `{channel}:{ts}` for top-level posts,
+   * `{channel}:{root}#{ts}` when the reply landed inside a thread — usable
+   * directly as a future reply_to.
+   */
+  message_id: string;
+  thread_anchor?: string;
+  sent_at: string;
+}
+
+/**
+ * Tier-B read verbs (agent-only): workspace visibility as the bot sees it.
+ * Authorization is the bot's own Slack permissions (invite the bot to a
+ * channel to make its history readable) — reads have no external side
+ * effect, so the seen-conversation restriction of the send verb does not
+ * apply. Cursor pagination follows Slack's contract (empty = last page).
+ */
+export interface SlackChannelInfo {
+  id: string;
+  name: string;
+  is_private: boolean;
+  is_member: boolean;
+  num_members?: number;
+  topic?: string;
+}
+
+export interface SlackChannelsPage {
+  channels: SlackChannelInfo[];
+  next_cursor?: string;
+}
+
+export interface SlackUserInfo {
+  id: string;
+  name: string;
+  real_name?: string;
+  is_bot: boolean;
+  deleted?: boolean;
+}
+
+export interface SlackUsersPage {
+  users: SlackUserInfo[];
+  next_cursor?: string;
+}
+
+export interface SlackHistoryMessage {
+  /**
+   * Synthesized channel-domain id — `{conversation}:{ts}`, or
+   * `{conversation}:{root}#{ts}` for thread children — directly usable as
+   * the send verb's `reply_to` (no client-side root#child derivation).
+   */
+  message_id: string;
+  ts: string;
+  thread_ts?: string;
+  user?: string;
+  bot_id?: string;
+  text: string;
+}
+
+export interface SlackHistoryPage {
+  messages: SlackHistoryMessage[];
+  next_cursor?: string;
+}
+
+export interface SlackMembersPage {
+  /** Bare Slack user ids — resolve display names via the users verb. */
+  members: string[];
+  next_cursor?: string;
+}
+
+/**
+ * Slack-native pagination for the read verbs. Filters are deliberately
+ * FIXED server-side (channels: public+private, archived excluded) — the
+ * public contract is cursor/limit only; widening it is a deliberate scope
+ * decision, not a missing passthrough.
+ */
+export interface SlackReadPageQuery {
+  cursor?: string;
+  limit?: number;
+}
+
+/** Agents-pane "typing…" indicator for one assistant thread (empty status clears). */
+export interface SlackStatusInput {
+  conversation: string;
+  /** The assistant thread's root ts. */
+  thread_ts: string;
+  status?: string;
 }
 
 // ============================================================
@@ -3099,6 +3293,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;
 
@@ -3915,6 +4111,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;
@@ -3924,6 +4144,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 {
@@ -3948,10 +4185,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;
 }