@parall/sdk 1.45.0 → 1.46.0

package/src/client.ts

@@ -94,6 +94,8 @@ import type {
   ChannelProvisioningSession,
   CreateChannelConnectionInput,
   InitiateChannelProvisioningInput,
+  SendChannelMessageInput,
+  SentChannelMessage,
   UpdateChannelConnectionInput,
   ExternalIngressEvent,
   ExternalIngressEventFilters,
@@ -133,6 +135,8 @@ import type {
   WikiRefsCheckResponse,
   WikiAnchorStatusRequest,
   WikiAnchorStatusResponse,
+  WikiAnchorResolveRequest,
+  WikiAnchorResolveResponse,
   WikiDiff,
   WikiPathScope,
   WikiAccessStatus,
@@ -212,6 +216,7 @@ import type {
   BrowserViewerCommandResponse,
   GrantBrowserProfileConsentRequest,
   EdgeDevice,
+  EdgePlacement,
   EdgeBrowserProfile,
   ClipConnection,
   EdgeOnboardingStatus,
@@ -259,6 +264,7 @@ export class ParallClient {
     '/auth/check-email',
     '/auth/forgot-password',
     '/auth/reset-password',
+    '/auth/oauth/exchange',
   ]);
 
   /** Proactive refresh when token expires within this window (seconds). */
@@ -585,6 +591,15 @@ export class ParallClient {
     });
   }
 
+  /**
+   * Redeem a one-time OAuth code (from the `?code=` param the backend puts on
+   * the /auth/callback redirect) for the access/refresh tokens + user. The
+   * code is single-use and short-lived — call this once, immediately.
+   */
+  async oauthExchange(code: string): Promise<AuthTokens> {
+    return this.request('POST', ENDPOINTS.AUTH_OAUTH_EXCHANGE, { code });
+  }
+
   // ---- WebSocket ----
 
   async getWsTicket(): Promise<WsTicketResponse> {
@@ -2423,6 +2438,18 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.CHANNEL_PROVISIONING_CANCEL(orgId, sessionId));
   }
 
+  /**
+   * Tier-B platform verb (agent-only): send one message as the calling
+   * agent's bound bot identity. Credentials never leave the platform —
+   * api-server performs the vendor call in-process.
+   */
+  async sendChannelMessage(
+    orgId: string,
+    input: SendChannelMessageInput,
+  ): Promise<SentChannelMessage> {
+    return this.request('POST', ENDPOINTS.CHANNEL_SEND(orgId), input);
+  }
+
   async listChannelConversations(
     orgId: string,
     connectionId: string,
@@ -2693,6 +2720,14 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.WIKI_ANCHOR_STATUS(orgId, wikiId), body);
   }
 
+  async resolveWikiAnchors(
+    orgId: string,
+    wikiId: string,
+    body: WikiAnchorResolveRequest,
+  ): Promise<WikiAnchorResolveResponse> {
+    return this.request('POST', ENDPOINTS.WIKI_ANCHOR_RESOLVE(orgId, wikiId), body);
+  }
+
   async createWikiChangeset(
     orgId: string,
     wikiId: string,
@@ -2964,6 +2999,7 @@ export class ParallClient {
           limit?: number;
           cursor?: string;
           order?: string;
+          resolution?: 'active' | 'resolved' | 'all';
         }
       | {
           target_prefix: string;
@@ -2971,6 +3007,7 @@ export class ParallClient {
           limit?: number;
           cursor?: string;
           order?: string;
+          resolution?: 'active' | 'resolved' | 'all';
         },
   ): Promise<PaginatedResponse<Comment>> {
     return this.request('GET', ENDPOINTS.COMMENTS(orgId), undefined, params);
@@ -2996,6 +3033,14 @@ export class ParallClient {
     return this.request('DELETE', ENDPOINTS.COMMENT(orgId, commentId));
   }
 
+  async resolveComment(orgId: string, commentId: string): Promise<Comment> {
+    return this.request('POST', ENDPOINTS.COMMENT_RESOLVE(orgId, commentId));
+  }
+
+  async reopenComment(orgId: string, commentId: string): Promise<Comment> {
+    return this.request('POST', ENDPOINTS.COMMENT_REOPEN(orgId, commentId));
+  }
+
   // ---- References ----
 
   async resolveRefs(
@@ -3338,6 +3383,35 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.ORG_EDGE_DEVICES(orgId));
   }
 
+  /**
+   * Register an Edge device. `placement` defaults to `byoc`.
+   *
+   * `placement: 'hosted'` creates a Cloud Profile: an ORG-SHARED browser that other
+   * members and agents can run clips through once you bind a clip to it. Only a human
+   * can create one (an agent gets `403 HOSTED_HUMAN_ONLY`), and only sign into it with
+   * an account you are authorized and willing to share with the whole organization.
+   * Creating one starts no pod and costs nothing.
+   */
+  async registerEdgeDevice(
+    orgId: string,
+    input: { name: string; placement?: EdgePlacement },
+  ): Promise<EdgeDevice> {
+    return this.request('POST', ENDPOINTS.ORG_EDGE(orgId), input);
+  }
+
+  /**
+   * Delete a hosted Cloud Profile. Hosted only — a BYOC device is removed by
+   * uninstalling Parall Clip on that machine (`400 EDGE_PLACEMENT_UNSUPPORTED`).
+   *
+   * Idempotent and ASYNC: returns `202` with `hosted_state: 'deleting'` on the first
+   * call and on every repeat. The device stops being usable immediately (no exec, no
+   * new bindings), but it remains listed as `deleting` until the platform has drained
+   * its pod and purged its stored browser state — which can take several minutes.
+   */
+  async deleteEdgeDevice(orgId: string, edgeId: string): Promise<EdgeDevice> {
+    return this.request('DELETE', ENDPOINTS.ORG_EDGE_DEVICE(orgId, edgeId));
+  }
+
   async getEdgeOnboarding(orgId: string): Promise<EdgeOnboardingStatus> {
     return this.request('GET', ENDPOINTS.ORG_EDGE_ONBOARDING(orgId));
   }

package/src/constants.ts

@@ -354,6 +354,7 @@ export const ENDPOINTS = {
   AUTH_RESEND_CODE: `${API_BASE}/auth/resend-code`,
   AUTH_FORGOT_PASSWORD: `${API_BASE}/auth/forgot-password`,
   AUTH_RESET_PASSWORD: `${API_BASE}/auth/reset-password`,
+  AUTH_OAUTH_EXCHANGE: `${API_BASE}/auth/oauth/exchange`,
 
   // Users
   USERS_ME: `${API_BASE}/users/me`,
@@ -631,6 +632,8 @@ export const ENDPOINTS = {
     `${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`,
 
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/invitations`,
@@ -678,6 +681,8 @@ export const ENDPOINTS = {
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/refs/check`,
   WIKI_ANCHOR_STATUS: (orgId: string, wikiId: string) =>
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/anchor-status`,
+  WIKI_ANCHOR_RESOLVE: (orgId: string, wikiId: string) =>
+    `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/anchor-resolve`,
   WIKI_CHANGESETS: (orgId: string, wikiId: string) =>
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets`,
   WIKI_CHANGESET: (orgId: string, wikiId: string, changesetId: string) =>
@@ -729,6 +734,10 @@ export const ENDPOINTS = {
   // Unified Comments (org-scoped, api-server)
   COMMENTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/comments`,
   COMMENT: (orgId: string, commentId: string) => `${API_BASE}/orgs/${orgId}/comments/${commentId}`,
+  COMMENT_RESOLVE: (orgId: string, commentId: string) =>
+    `${API_BASE}/orgs/${orgId}/comments/${commentId}:resolve`,
+  COMMENT_REOPEN: (orgId: string, commentId: string) =>
+    `${API_BASE}/orgs/${orgId}/comments/${commentId}:reopen`,
 
   // Inbox (org-scoped)
   INBOX: (orgId: string) => `${API_BASE}/orgs/${orgId}/inbox`,
@@ -849,7 +858,9 @@ export const ENDPOINTS = {
   CLIP_REGISTRY: () => `${CLIP_BASE}/registry/clips`,
 
   // Edge device endpoints
+  ORG_EDGE: (orgId: string) => `/api/v1/orgs/${orgId}/edge`,
   ORG_EDGE_DEVICES: (orgId: string) => `/api/v1/orgs/${orgId}/edge/devices`,
+  ORG_EDGE_DEVICE: (orgId: string, edgeId: string) => `/api/v1/orgs/${orgId}/edge/${edgeId}`,
   ORG_EDGE_ONBOARDING: (orgId: string) => `/api/v1/orgs/${orgId}/edge/onboarding`,
   ORG_EDGE_PROFILES: (orgId: string, edgeId: string) =>
     `/api/v1/orgs/${orgId}/edge/${edgeId}/profiles`,
@@ -1060,4 +1071,6 @@ export const COMMENT_TARGET = {
     const frag = lineStart === lineEnd ? `l=${lineStart}` : `l=${lineStart}-${lineEnd}`;
     return `prll://${wikiId}/${encodeWikiPath(path)}?rev=${rev}#${frag}`;
   },
+  wikiTextRange: (wikiId: string, path: string, rev: string, start: number, end: number) =>
+    `prll://${wikiId}/${encodeWikiPath(path)}?rev=${rev}#t=${start}-${end}`,
 } as const;

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;
 }
@@ -2513,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;
 }
 
@@ -2566,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'
@@ -2595,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;
 }
 
 // ============================================================
@@ -3099,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;
 
@@ -3915,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;
@@ -3924,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 {
@@ -3948,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;
 }