@parall/sdk 1.46.0 → 1.47.0

package/src/client.ts

@@ -95,6 +95,13 @@ import type {
   CreateChannelConnectionInput,
   InitiateChannelProvisioningInput,
   SendChannelMessageInput,
+  SlackChannelsPage,
+  SlackHistoryPage,
+  SlackManifestLinkResult,
+  SlackMembersPage,
+  SlackReadPageQuery,
+  SlackStatusInput,
+  SlackUsersPage,
   SentChannelMessage,
   UpdateChannelConnectionInput,
   ExternalIngressEvent,
@@ -1754,11 +1761,17 @@ export class ParallClient {
     return this.request('PATCH', ENDPOINTS.MACHINE_SPEC(orgId, machineId), spec);
   }
 
-  /** Signal a local daemon-mode Machine to check for and apply an update. */
+  /** @deprecated Retired server-side (daemon-control-authorization §4.2):
+   *  daemons update autonomously (CDN poll + platform release signal). The
+   *  endpoint now answers 409 LOCAL_UPDATE_NOT_SUPPORTED unconditionally. */
   async requestMachineUpdate(orgId: string, machineId: string, mandatory = false): Promise<void> {
     await this.request('POST', ENDPOINTS.MACHINE_REQUEST_UPDATE(orgId, machineId), { mandatory });
   }
 
+  /** @deprecated Retired server-side (daemon-control-authorization §4.2):
+   *  remote filesystem browse of a member's machine was remote device access.
+   *  The endpoint now answers 409 LOCAL_BROWSE_NOT_SUPPORTED unconditionally;
+   *  workspace paths are typed in (or picked on the machine's own Desktop). */
   async browseMachineFilesystem(
     orgId: string,
     machineId: string,
@@ -1814,6 +1827,20 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.THREAD_UNREAD(orgId, chatId, threadRootId));
   }
 
+  /** Advance the per-thread read cursor (forward-only). The server auto-clears
+   *  thread-scoped inbox items (thread_reply + in-thread mentions) the cursor
+   *  now covers. */
+  async markThreadRead(
+    orgId: string,
+    chatId: string,
+    threadRootId: string,
+    messageId: string,
+  ): Promise<void> {
+    return this.request('POST', ENDPOINTS.THREAD_READ(orgId, chatId, threadRootId), {
+      message_id: messageId,
+    });
+  }
+
   // ---- Inbox ----
 
   async getInbox(
@@ -1854,9 +1881,15 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.INBOX_ARCHIVE_ALL(orgId));
   }
 
-  /** Mark an inbox item as read by its source (source_type + source_id) rather than inbox item ID. */
-  async ackInbox(orgId: string, source: { source_type: string; source_id: string }): Promise<void> {
-    return this.request('POST', ENDPOINTS.INBOX_ACK(orgId), source);
+  /** Mark inbox items as read by their source (source_type + source_id) or by
+   *  group_key, rather than by inbox item ID. The group_key form clears a whole
+   *  group at once (e.g. `task:{taskId}` — task_assign/task_update/task_comment
+   *  share it), used by the task detail view's auto-ack on open. */
+  async ackInbox(
+    orgId: string,
+    target: { source_type: string; source_id: string } | { group_key: string },
+  ): Promise<void> {
+    return this.request('POST', ENDPOINTS.INBOX_ACK(orgId), target);
   }
 
   async deleteInboxItem(orgId: string, id: string): Promise<void> {
@@ -2420,6 +2453,19 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.CHANNEL_PROVISIONING(orgId), input);
   }
 
+  /**
+   * Mint a pending slack connection + api.slack.com manifest-prefill link
+   * (guided manual path). Activate the returned connection_id with
+   * deliverChannelCredentials once the user brings back the bot token +
+   * signing secret.
+   */
+  async createSlackManifestLink(
+    orgId: string,
+    input: { agent_id: string },
+  ): Promise<SlackManifestLinkResult> {
+    return this.request('POST', ENDPOINTS.CHANNEL_SLACK_MANIFEST_LINK(orgId), input);
+  }
+
   /**
    * Lazy status poll — server-side this may forward one provider poll, so
    * call it at the session's `poll_interval_seconds` cadence, not faster.
@@ -2450,6 +2496,55 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.CHANNEL_SEND(orgId), input);
   }
 
+  private slackReadQuery(base: string, query?: SlackReadPageQuery, extra?: Record<string, string>) {
+    const params = new URLSearchParams();
+    if (query?.cursor) params.set('cursor', query.cursor);
+    if (query?.limit) params.set('limit', String(query.limit));
+    for (const [k, v] of Object.entries(extra ?? {})) params.set(k, v);
+    const qs = params.toString();
+    return qs ? `${base}?${qs}` : base;
+  }
+
+  /**
+   * Tier-B read verbs (agent-only): workspace visibility as the bot sees
+   * it. Same live gate as the send verb; authorization beyond it is the
+   * bot's own Slack permissions.
+   */
+  async listSlackChannels(orgId: string, query?: SlackReadPageQuery): Promise<SlackChannelsPage> {
+    return this.request('GET', this.slackReadQuery(ENDPOINTS.SLACK_CHANNELS(orgId), query));
+  }
+
+  async listSlackUsers(orgId: string, query?: SlackReadPageQuery): Promise<SlackUsersPage> {
+    return this.request('GET', this.slackReadQuery(ENDPOINTS.SLACK_USERS(orgId), query));
+  }
+
+  async slackHistory(
+    orgId: string,
+    conversationId: string,
+    query?: SlackReadPageQuery,
+  ): Promise<SlackHistoryPage> {
+    return this.request(
+      'GET',
+      this.slackReadQuery(ENDPOINTS.SLACK_HISTORY(orgId), query, { conversation: conversationId }),
+    );
+  }
+
+  async slackMembers(
+    orgId: string,
+    conversationId: string,
+    query?: SlackReadPageQuery,
+  ): Promise<SlackMembersPage> {
+    return this.request(
+      'GET',
+      this.slackReadQuery(ENDPOINTS.SLACK_MEMBERS(orgId), query, { conversation: conversationId }),
+    );
+  }
+
+  /** Set/clear the Agents-pane "typing…" indicator (best-effort cosmetic). */
+  async setSlackStatus(orgId: string, input: SlackStatusInput): Promise<void> {
+    await this.request('POST', ENDPOINTS.SLACK_STATUS(orgId), input);
+  }
+
   async listChannelConversations(
     orgId: string,
     connectionId: string,

package/src/constants.ts

@@ -628,12 +628,20 @@ export const ENDPOINTS = {
   CHANNEL_MESSAGE: (orgId: string, messageId: string) =>
     `${API_BASE}/orgs/${orgId}/channel-messages/${messageId}`,
   CHANNEL_PROVISIONING: (orgId: string) => `${API_BASE}/orgs/${orgId}/channel-provisioning`,
+  CHANNEL_SLACK_MANIFEST_LINK: (orgId: string) =>
+    `${API_BASE}/orgs/${orgId}/channel-provisioning/slack/manifest-link`,
   CHANNEL_PROVISIONING_SESSION: (orgId: string, sessionId: string) =>
     `${API_BASE}/orgs/${orgId}/channel-provisioning/${sessionId}`,
   CHANNEL_PROVISIONING_CANCEL: (orgId: string, sessionId: string) =>
     `${API_BASE}/orgs/${orgId}/channel-provisioning/${sessionId}/cancel`,
   // Tier-B platform verb (agent-only): send one message as the bound bot.
   CHANNEL_SEND: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/channel-send`,
+  // Tier-B read verbs (agent-only): workspace visibility as the bot sees it.
+  SLACK_CHANNELS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/channels`,
+  SLACK_USERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/users`,
+  SLACK_HISTORY: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/history`,
+  SLACK_MEMBERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/members`,
+  SLACK_STATUS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/slack/status`,
 
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/invitations`,
@@ -774,6 +782,8 @@ export const ENDPOINTS = {
   CHAT_READ: (orgId: string, chatId: string) => `${API_BASE}/orgs/${orgId}/chats/${chatId}/read`,
   THREAD_UNREAD: (orgId: string, chatId: string, threadRootId: string) =>
     `${API_BASE}/orgs/${orgId}/chats/${chatId}/threads/${threadRootId}/unread`,
+  THREAD_READ: (orgId: string, chatId: string, threadRootId: string) =>
+    `${API_BASE}/orgs/${orgId}/chats/${chatId}/threads/${threadRootId}/read`,
 
   // References (org-scoped)
   REFS_RESOLVE: (orgId: string) => `${API_BASE}/orgs/${orgId}/refs/resolve`,

package/src/types.ts

@@ -2535,6 +2535,14 @@ 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;
 }
@@ -2649,16 +2657,35 @@ export type InitiateChannelProvisioningInput =
       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.
+       * 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
@@ -2670,9 +2697,12 @@ export interface SendChannelMessageInput {
   /** 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).
+   * 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;
@@ -2681,12 +2711,94 @@ export interface SendChannelMessageInput {
 export interface SentChannelMessage {
   channel_type: 'slack';
   conversation_id: string;
-  /** Channel-domain external id ({channel}:{ts}) — usable as a reply_to. */
+  /**
+   * 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;
+}
+
 // ============================================================
 // Dispatch Types (agent event delivery)
 // ============================================================