@parall/sdk 1.35.0 → 1.36.1

package/src/client.ts

@@ -1,4 +1,4 @@
-import { ENDPOINTS } from './constants.js';
+import { ENDPOINTS, WIKI_BASE } from './constants.js';
 import type {
   AuthTokens,
   AvatarUploadResponse,
@@ -70,6 +70,19 @@ import type {
   UpdateScheduleInput,
   ScheduleFilters,
   ScheduleRunFilters,
+  ExternalConnection,
+  CreateExternalConnectionInput,
+  UpdateExternalConnectionInput,
+  ExternalConnectionFilters,
+  ExternalIngressEvent,
+  ExternalIngressEventFilters,
+  ExternalTrigger,
+  CreateExternalTriggerInput,
+  UpdateExternalTriggerInput,
+  ExternalTriggerFilters,
+  ExternalTriggerRun,
+  ExternalTriggerRunFilters,
+  ExternalTriggerSchema,
   AgentSessionDB,
   AgentStep,
   CreateAgentSessionRequest,
@@ -91,6 +104,7 @@ import type {
   WikiNodeSectionArtifact,
   WikiSearchResponse,
   WikiPageIndex,
+  SearchParams,
   SearchResponse,
   WikiRefsResponse,
   WikiRefsCheckResponse,
@@ -119,6 +133,7 @@ import type {
   DispatchExpireResult,
   ResolveRefsResponse,
   BacklinksResponse,
+  RefGraphResponse,
   BrokenRefsResponse,
   PushSubscribeRequest,
   NotifPrefs,
@@ -160,6 +175,8 @@ import type {
   RegistryClipInfo,
   MachineClip,
   BrowserProfile,
+  MachineBrowserProfile,
+  BrowserProfileListItem,
   BrowserProfileStatus,
   BrowserProfileConsent,
   CreateBrowserProfileRequest,
@@ -172,6 +189,15 @@ import type {
 
 export interface ParallClientOptions {
   baseUrl?: string;
+  /**
+   * Base URL for wiki-service endpoints (paths under `/wiki/v1`). Defaults to
+   * `baseUrl`. Wiki endpoints are served by a separate service from the rest of
+   * the API; in staging/prod one gateway fronts both (so `baseUrl` alone is
+   * correct), but local dev runs api-server (:8080) and wiki-service (:8090)
+   * separately. Set this so wiki calls reach wiki-service while everything else
+   * (chat, tasks, comments, refs) keeps using `baseUrl`.
+   */
+  wikiBaseUrl?: string;
   token?: string;
   onTokenExpired?: () => void;
   getRefreshToken?: () => string | null;
@@ -181,6 +207,7 @@ export interface ParallClientOptions {
 
 export class ParallClient {
   private baseUrl: string;
+  private wikiBaseUrl: string;
   private token: string | null;
   private onTokenExpired?: () => void;
   private getRefreshToken?: () => string | null;
@@ -242,6 +269,10 @@ export class ParallClient {
 
   constructor(options: ParallClientOptions = {}) {
     this.baseUrl = options.baseUrl ?? '';
+    // Defaults to baseUrl so existing single-origin consumers (web, desktop,
+    // hosted agents behind one gateway) are unchanged; only split api/wiki
+    // deployments (local dev) need to set it.
+    this.wikiBaseUrl = options.wikiBaseUrl ?? this.baseUrl;
     this.token = options.token ?? null;
     this.onTokenExpired = options.onTokenExpired;
     this.getRefreshToken = options.getRefreshToken;
@@ -249,6 +280,16 @@ export class ParallClient {
     this.swimlaneName = options.swimlaneName;
   }
 
+  /**
+   * Pick the origin for a request path: wiki-service base for `/wiki/v1`
+   * endpoints, api base for everything else. The path itself (from ENDPOINTS)
+   * is authoritative, so wiki vs api routing can't drift from how a caller
+   * happens to invoke the client.
+   */
+  private baseUrlFor(path: string): string {
+    return path.startsWith(WIKI_BASE) ? this.wikiBaseUrl : this.baseUrl;
+  }
+
   setToken(token: string | null) {
     this.token = token;
   }
@@ -326,7 +367,7 @@ export class ParallClient {
       await this.ensureFreshToken(path);
     }
 
-    let url = `${this.baseUrl}${path}`;
+    let url = `${this.baseUrlFor(path)}${path}`;
 
     if (query) {
       const params = new URLSearchParams();
@@ -419,7 +460,7 @@ export class ParallClient {
 
     let res: Response;
     try {
-      res = await fetch(`${this.baseUrl}${path}`, {
+      res = await fetch(`${this.baseUrlFor(path)}${path}`, {
         method,
         headers,
         body,
@@ -654,6 +695,22 @@ export class ParallClient {
     );
   }
 
+  // Auto-paginated variant of getMemberTasks: fetches ALL pending tasks
+  // (todo + in_progress) assigned to a member, including subtasks (the
+  // endpoint does not filter parent_id). Powers the CLI `tasks assigned`
+  // command so an agent answering "what's on X's plate" sees the full
+  // backlog, not just the first page.
+  async getMemberTasksAll(orgId: string, memberId: string): Promise<Task[]> {
+    const all: Task[] = [];
+    let cursor: string | undefined;
+    do {
+      const res = await this.getMemberTasks(orgId, memberId, { cursor, limit: 100 });
+      all.push(...res.data);
+      cursor = res.has_more ? res.next_cursor : undefined;
+    } while (cursor);
+    return all;
+  }
+
   // ---- Invitations ----
 
   async createInvitation(
@@ -896,6 +953,8 @@ export class ParallClient {
       limit?: number;
       thread_root_id?: string;
       top_level?: boolean;
+      /** RFC3339 or YYYY-MM-DD; filters messages created at/after this instant. Independent of before/after cursors. */
+      since?: string;
     },
   ): Promise<PaginatedResponse<Message>> {
     return this.request(
@@ -1441,9 +1500,10 @@ export class ParallClient {
     return res.data;
   }
 
-  /** `GET /machines/me/browser-profiles` — browser profiles hosted by this machine. */
-  async listMachineBrowserProfiles(): Promise<BrowserProfile[]> {
-    const res = await this.request<{ data: BrowserProfile[] }>(
+  /** `GET /machines/me/browser-profiles` — browser profiles hosted by this machine.
+   *  Returns the daemon DTO (carries proxy_password for bb-browser replay). */
+  async listMachineBrowserProfiles(): Promise<MachineBrowserProfile[]> {
+    const res = await this.request<{ data: MachineBrowserProfile[] }>(
       'GET',
       ENDPOINTS.MACHINES_ME_BROWSER_PROFILES,
     );
@@ -1747,7 +1807,7 @@ export class ParallClient {
    * Returns null when the server responds with 304 (config unchanged).
    */
   async getPlatformConfig(currentVersion?: string): Promise<PlatformConfigResponse | null> {
-    const url = `${this.baseUrl}${ENDPOINTS.PLATFORM_CONFIG}`;
+    const url = `${this.baseUrlFor(ENDPOINTS.PLATFORM_CONFIG)}${ENDPOINTS.PLATFORM_CONFIG}`;
     const extra: Record<string, string> = {};
     if (currentVersion !== undefined) {
       extra['If-None-Match'] = currentVersion;
@@ -2058,6 +2118,127 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.SCHEDULE_RUN(orgId, runId));
   }
 
+  // ---- External triggers (org-scoped) ----
+
+  async createExternalConnection(
+    orgId: string,
+    input: CreateExternalConnectionInput,
+  ): Promise<ExternalConnection> {
+    return this.request('POST', ENDPOINTS.EXTERNAL_CONNECTIONS(orgId), input);
+  }
+
+  async listExternalConnections(
+    orgId: string,
+    filters?: ExternalConnectionFilters,
+  ): Promise<PaginatedResponse<ExternalConnection>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.EXTERNAL_CONNECTIONS(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getExternalConnection(orgId: string, connectionId: string): Promise<ExternalConnection> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId));
+  }
+
+  async updateExternalConnection(
+    orgId: string,
+    connectionId: string,
+    patch: UpdateExternalConnectionInput,
+  ): Promise<ExternalConnection> {
+    return this.request('PATCH', ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId), patch);
+  }
+
+  async regenerateExternalConnectionIngressToken(
+    orgId: string,
+    connectionId: string,
+  ): Promise<ExternalConnection> {
+    return this.request(
+      'POST',
+      ENDPOINTS.EXTERNAL_CONNECTION_INGRESS_TOKEN_REGENERATE(orgId, connectionId),
+    );
+  }
+
+  async deleteExternalConnection(orgId: string, connectionId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.EXTERNAL_CONNECTION(orgId, connectionId));
+  }
+
+  async getExternalTriggerSchema(
+    orgId: string,
+    connectionId: string,
+  ): Promise<ExternalTriggerSchema> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_TRIGGER_SCHEMA(orgId, connectionId));
+  }
+
+  async listExternalIngressEvents(
+    orgId: string,
+    filters?: ExternalIngressEventFilters,
+  ): Promise<PaginatedResponse<ExternalIngressEvent>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.EXTERNAL_INGRESS_EVENTS(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getExternalIngressEvent(orgId: string, eventId: string): Promise<ExternalIngressEvent> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_INGRESS_EVENT(orgId, eventId));
+  }
+
+  async createExternalTrigger(
+    orgId: string,
+    input: CreateExternalTriggerInput,
+  ): Promise<ExternalTrigger> {
+    return this.request('POST', ENDPOINTS.EXTERNAL_TRIGGERS(orgId), input);
+  }
+
+  async listExternalTriggers(
+    orgId: string,
+    filters?: ExternalTriggerFilters,
+  ): Promise<PaginatedResponse<ExternalTrigger>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.EXTERNAL_TRIGGERS(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getExternalTrigger(orgId: string, triggerId: string): Promise<ExternalTrigger> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId));
+  }
+
+  async updateExternalTrigger(
+    orgId: string,
+    triggerId: string,
+    patch: UpdateExternalTriggerInput,
+  ): Promise<ExternalTrigger> {
+    return this.request('PATCH', ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId), patch);
+  }
+
+  async deleteExternalTrigger(orgId: string, triggerId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.EXTERNAL_TRIGGER(orgId, triggerId));
+  }
+
+  async listExternalTriggerRuns(
+    orgId: string,
+    filters?: ExternalTriggerRunFilters,
+  ): Promise<PaginatedResponse<ExternalTriggerRun>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.EXTERNAL_TRIGGER_RUNS(orgId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getExternalTriggerRun(orgId: string, runId: string): Promise<ExternalTriggerRun> {
+    return this.request('GET', ENDPOINTS.EXTERNAL_TRIGGER_RUN(orgId, runId));
+  }
+
   // ---- Wikis (org-scoped) ----
 
   async createWiki(orgId: string, data: CreateWikiRequest): Promise<Wiki> {
@@ -2081,12 +2262,43 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.WIKI_TREE(orgId, wikiId), undefined, params);
   }
 
+  /**
+   * Resolve a server-returned, host-relative media URL (a wiki `signed_url`
+   * like `/wiki/v1/signed/files?token=...`) against this client's base origin,
+   * so it can be dropped straight into a browser `<img>`/`<video>`/`<iframe>`
+   * `src`.
+   *
+   * wiki-service returns these relative on purpose — it doesn't know its own
+   * public origin. A relative `src` resolves against the *page* origin, which
+   * only works when the page and wiki-service share an origin (local dev:
+   * same-origin + Next.js `/wiki/*` proxy). In deployed envs the app
+   * (app.parall.com) and wiki-service (api.parall.com) are different origins,
+   * so `app.parall.com/wiki/v1/signed/files` hits the SPA's own `/wiki/[...]`
+   * catch-all route — an `<iframe>` then recursively renders the whole app
+   * instead of the file. Prefixing with the wiki base (the exact origin every
+   * wiki API request already uses — `baseUrlFor` resolves `/wiki/v1` paths to
+   * `wikiBaseUrl`) makes the URL absolute against the origin that actually
+   * serves the bytes. An empty base (local dev, same-origin proxy) leaves it
+   * relative, preserving the proxy path.
+   */
+  private absoluteMediaUrl(url: string): string {
+    if (/^https?:\/\//i.test(url)) return url; // already absolute — leave as-is
+    return `${this.baseUrlFor(url)}${url}`;
+  }
+
   async getWikiBlob(
     orgId: string,
     wikiId: string,
     params: { path: string; ref?: string },
   ): Promise<WikiBlob> {
-    return this.request('GET', ENDPOINTS.WIKI_BLOB(orgId, wikiId), undefined, params);
+    const blob = await this.request<WikiBlob>(
+      'GET',
+      ENDPOINTS.WIKI_BLOB(orgId, wikiId),
+      undefined,
+      params,
+    );
+    if (blob.signed_url) blob.signed_url = this.absoluteMediaUrl(blob.signed_url);
+    return blob;
   }
 
   async getWikiNodeSections(
@@ -2099,9 +2311,7 @@ export class ParallClient {
 
   async search(
     orgId: string,
-    // `types` selects entities (message/task/wiki); `wiki_type` is the distinct
-    // wiki document-type facet (frontmatter `type`) — the two never overlap.
-    params: { q: string; types?: string; chat_id?: string; limit?: number; wiki_type?: string },
+    params: SearchParams,
     opts?: { signal?: AbortSignal },
   ): Promise<SearchResponse> {
     return this.request('GET', ENDPOINTS.SEARCH(orgId), undefined, params, false, opts);
@@ -2287,7 +2497,13 @@ export class ParallClient {
     wikiId: string,
     params: { path: string; ref?: string },
   ): Promise<WikiFilePreviewUrlResponse> {
-    return this.request('POST', ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId), params);
+    const res = await this.request<WikiFilePreviewUrlResponse>(
+      'POST',
+      ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId),
+      params,
+    );
+    if (res.url) res.url = this.absoluteMediaUrl(res.url);
+    return res;
   }
 
   // ---- Wiki Path Scopes (AFCS ACL) ----
@@ -2468,6 +2684,20 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.REFS_BACKLINKS(orgId), undefined, params);
   }
 
+  /**
+   * Bounded multi-hop walk of the prll:// reference graph around `uri`. `uri`
+   * must be an entity-level prll:// URI — a refined URI (path/query/fragment) is
+   * rejected with 400 UNSUPPORTED_REFINED_URI. `depth` is clamped server-side to
+   * [1, 4]; breadth (node/edge counts) is capped server-side and surfaced via
+   * `truncated`. ACL is applied per hop (chat membership + wiki path scope).
+   */
+  async getRefsGraph(
+    orgId: string,
+    params: { uri: string; depth?: number },
+  ): Promise<RefGraphResponse> {
+    return this.request('GET', ENDPOINTS.REFS_GRAPH(orgId), undefined, params);
+  }
+
   async checkBrokenRefs(orgId: string): Promise<BrokenRefsResponse> {
     return this.request('GET', ENDPOINTS.REFS_CHECK(orgId));
   }
@@ -2665,8 +2895,11 @@ export class ParallClient {
     return resp.data;
   }
 
-  async listBrowserProfiles(orgId: string): Promise<BrowserProfile[]> {
-    const resp = await this.request<{ data: BrowserProfile[] }>(
+  /** Org-wide browser-profile discovery list. Returns the sanitized
+   *  {@link BrowserProfileListItem} shape (not the full domain model), each row
+   *  carrying a per-viewer `can_open` control hint. */
+  async listBrowserProfiles(orgId: string): Promise<BrowserProfileListItem[]> {
+    const resp = await this.request<{ data: BrowserProfileListItem[] }>(
       'GET',
       ENDPOINTS.BROWSER_PROFILES(orgId),
     );

package/src/constants.ts

@@ -566,6 +566,24 @@ export const ENDPOINTS = {
   SCHEDULE_RUN: (orgId: string, runId: string) =>
     `${API_BASE}/orgs/${orgId}/schedule_runs/${runId}`,
 
+  // External triggers (org-scoped incoming integration primitive)
+  EXTERNAL_CONNECTIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/external-connections`,
+  EXTERNAL_CONNECTION: (orgId: string, connectionId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}`,
+  EXTERNAL_CONNECTION_INGRESS_TOKEN_REGENERATE: (orgId: string, connectionId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}/ingress-token/regenerate`,
+  EXTERNAL_TRIGGER_SCHEMA: (orgId: string, connectionId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-connections/${connectionId}/trigger-schema`,
+  EXTERNAL_INGRESS_EVENTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/external-ingress-events`,
+  EXTERNAL_INGRESS_EVENT: (orgId: string, eventId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-ingress-events/${eventId}`,
+  EXTERNAL_TRIGGERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/external-triggers`,
+  EXTERNAL_TRIGGER: (orgId: string, triggerId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-triggers/${triggerId}`,
+  EXTERNAL_TRIGGER_RUNS: (orgId: string) => `${API_BASE}/orgs/${orgId}/external-trigger-runs`,
+  EXTERNAL_TRIGGER_RUN: (orgId: string, runId: string) =>
+    `${API_BASE}/orgs/${orgId}/external-trigger-runs/${runId}`,
+
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/invitations`,
   ORG_INVITATION: (orgId: string, invId: string) =>
@@ -688,6 +706,7 @@ export const ENDPOINTS = {
   // References (org-scoped)
   REFS_RESOLVE: (orgId: string) => `${API_BASE}/orgs/${orgId}/refs/resolve`,
   REFS_BACKLINKS: (orgId: string) => `${API_BASE}/orgs/${orgId}/refs/backlinks`,
+  REFS_GRAPH: (orgId: string) => `${API_BASE}/orgs/${orgId}/refs/graph`,
   REFS_CHECK: (orgId: string) => `${API_BASE}/orgs/${orgId}/refs/check`,
 
   // Platform config (agent-scoped, not org-scoped)