@parall/sdk 1.53.0 → 1.55.0

package/src/constants.ts

@@ -371,6 +371,11 @@ export const ENDPOINTS = {
   ORG_MEMBERS: (orgId: string) => `${API_BASE}/orgs/${orgId}/members`,
   ORG_MEMBERS_FORMER: (orgId: string) => `${API_BASE}/orgs/${orgId}/members/former`,
   TEAMS: (orgId: string) => `${API_BASE}/orgs/${orgId}/teams`,
+  TEAM: (orgId: string, teamId: string) => `${API_BASE}/orgs/${orgId}/teams/${teamId}`,
+  TEAM_MEMBERS: (orgId: string, teamId: string) =>
+    `${API_BASE}/orgs/${orgId}/teams/${teamId}/members`,
+  TEAM_MEMBER: (orgId: string, teamId: string, userId: string) =>
+    `${API_BASE}/orgs/${orgId}/teams/${teamId}/members/${userId}`,
   ORG_MEMBERS_ONLINE: (orgId: string) => `${API_BASE}/orgs/${orgId}/members/online`,
   ORG_MEMBER: (orgId: string, userId: string) => `${API_BASE}/orgs/${orgId}/members/${userId}`,
   ORG_MEMBER_CHATS: (orgId: string, memberId: string) =>
@@ -562,6 +567,7 @@ export const ENDPOINTS = {
 
   // Tasks (org-scoped)
   TASKS: (orgId: string) => `${API_BASE}/orgs/${orgId}/tasks`,
+  TASK_SUBTASK_SUMMARY: (orgId: string) => `${API_BASE}/orgs/${orgId}/tasks/subtask-summary`,
   TASK: (orgId: string, taskId: string) => `${API_BASE}/orgs/${orgId}/tasks/${taskId}`,
   TASK_ARCHIVE: (orgId: string, taskId: string) =>
     `${API_BASE}/orgs/${orgId}/tasks/${taskId}/archive`,
@@ -585,9 +591,18 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/tasks/${taskId}/comments/${commentId}`,
   TASK_ACTIVITIES: (orgId: string, taskId: string) =>
     `${API_BASE}/orgs/${orgId}/tasks/${taskId}/activities`,
+  TASK_LABELS: (orgId: string, taskId: string) =>
+    `${API_BASE}/orgs/${orgId}/tasks/${taskId}/labels`,
+  TASK_LABEL: (orgId: string, taskId: string, labelId: string) =>
+    `${API_BASE}/orgs/${orgId}/tasks/${taskId}/labels/${labelId}`,
+
+  // Labels (org-scoped vocabulary; writes are admin-gated)
+  LABELS: (orgId: string) => `${API_BASE}/orgs/${orgId}/labels`,
+  LABEL: (orgId: string, labelId: string) => `${API_BASE}/orgs/${orgId}/labels/${labelId}`,
 
   // Projects (org-scoped)
   PROJECTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/projects`,
+  PROJECT_TASK_SUMMARY: (orgId: string) => `${API_BASE}/orgs/${orgId}/projects/task-summary`,
   PROJECT: (orgId: string, projectId: string) => `${API_BASE}/orgs/${orgId}/projects/${projectId}`,
 
   // Schedules (org-scoped, platform time trigger primitive)
@@ -653,8 +668,10 @@ export const ENDPOINTS = {
   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`,
-  // WeChat tier-B read verb (agent-only; internal research preview).
+  // WeChat tier-B read verbs (agent-only; internal research preview).
   WECHAT_CONTACTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/wechat/contacts`,
+  WECHAT_PROFILE: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/wechat/profile`,
+  WECHAT_STATUS: (orgId: string) => `${API_BASE}/orgs/${orgId}/agents/me/wechat/status`,
 
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/invitations`,
@@ -822,8 +839,11 @@ export const ENDPOINTS = {
   // Unified search (messages + tasks + wiki, org-scoped)
   SEARCH: (orgId: string) => `${API_BASE}/orgs/${orgId}/search`,
 
-  // Feature flags (org-scoped, server-evaluated)
-  FEATURE_FLAGS: (orgId: string) => `${API_BASE}/orgs/${orgId}/feature-flags`,
+  // Feature flags (server-evaluated). Org-scoped by default; omit the org for
+  // the pre-org form, which resolves "cap:" capabilities only (PostHog flags
+  // are org-scoped and absent there) for callers that have no org yet.
+  FEATURE_FLAGS: (orgId?: string) =>
+    orgId ? `${API_BASE}/orgs/${orgId}/feature-flags` : `${API_BASE}/feature-flags`,
 
   // Team templates (org-scoped, owner/admin only)
   TEMPLATES: (orgId: string) => `${API_BASE}/orgs/${orgId}/templates`,
@@ -925,17 +945,30 @@ export const ENDPOINTS = {
   ORG_CLIPS_INSTALLED: (orgId: string) => `/api/v1/orgs/${orgId}/clips/installed`,
   ORG_CLIP_UNINSTALL: (orgId: string, clipId: string) =>
     `/api/v1/orgs/${orgId}/clips/${clipId}/uninstall`,
+  ORG_CLIP_MCP_REMOVE: (orgId: string, clipId: string) =>
+    `/api/v1/orgs/${orgId}/clips/${clipId}/mcp-remove`,
   // Per-org agent exec access for one clip (default all agents; PUT human-only)
   ORG_CLIP_EXEC_ACCESS: (orgId: string, clipId: string) =>
     `/api/v1/orgs/${orgId}/clips/${clipId}/exec-access`,
-  // MCP clip server config (cap:clip-mcp; publisher-org only — cross-org gets
-  // 403 MCP_CROSS_ORG_DISABLED on the whole family, reads included)
+  // MCP clip server config (cap:clip-mcp; cross-org is limited to installed,
+  // reviewed Official OAuth Clips). The
+  // singular family addresses the org's DEFAULT connection (pre-165
+  // back-compat shim); the plural family is the multi-connection surface —
+  // one config row (credential slot) per connection, addressed by config id.
   ORG_CLIP_MCP_CONFIG: (orgId: string, clipId: string) =>
     `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-config`,
   ORG_CLIP_MCP_TOOLS_REFRESH: (orgId: string, clipId: string) =>
     `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-config/tools/refresh`,
   ORG_CLIP_MCP_OAUTH_DISCONNECT: (orgId: string, clipId: string) =>
     `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-config/oauth/disconnect`,
+  ORG_CLIP_MCP_CONFIGS: (orgId: string, clipId: string) =>
+    `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-configs`,
+  ORG_CLIP_MCP_CONFIG_BY_ID: (orgId: string, clipId: string, configId: string) =>
+    `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-configs/${configId}`,
+  ORG_CLIP_MCP_TOOLS_REFRESH_BY_ID: (orgId: string, clipId: string, configId: string) =>
+    `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-configs/${configId}/tools/refresh`,
+  ORG_CLIP_MCP_OAUTH_DISCONNECT_BY_ID: (orgId: string, clipId: string, configId: string) =>
+    `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-configs/${configId}/oauth/disconnect`,
 } as const;
 
 /**
@@ -1007,6 +1040,9 @@ export const WS_EVENTS = {
   PROJECT_CREATED: 'project.created',
   PROJECT_UPDATED: 'project.updated',
   PROJECT_DELETED: 'project.deleted',
+  LABEL_CREATED: 'label.created',
+  LABEL_UPDATED: 'label.updated',
+  LABEL_DELETED: 'label.deleted',
   AGENT_SESSION_NEW: 'agent_session.new',
   AGENT_SESSION_UPDATE: 'agent_session.update',
   AGENT_STEP_NEW: 'agent_step.new',
@@ -1017,6 +1053,7 @@ export const WS_EVENTS = {
   ORG_JOIN_REQUEST_NEW: 'org.join_request.new',
   ORG_INVITE_LINK_JOINED: 'org.invite_link.joined',
   ORG_MEMBER_REMOVED: 'org.member.removed',
+  ORG_MEMBER_PROFILE_UPDATED: 'org.member.profile.updated',
   AGENT_CONFIG_UPDATE: 'agent_config.update',
   PRESENCE_UPDATE: 'presence.update',
   WIKI_CHANGESET_CREATED: 'wiki.changeset.created',

package/src/index.ts

@@ -2,6 +2,8 @@ export * from './browser-viewer.js';
 export type { ParallClientOptions } from './client.js';
 export { ApiError, ParallClient } from './client.js';
 export * from './constants.js';
+export * from './subject.js';
+export * from './task-label-types.js';
 export * from './types.js';
 export type {
   ParallWsOptions,

package/src/project-task-client.ts

@@ -0,0 +1,249 @@
+import { ENDPOINTS } from './constants.js';
+import type {
+  CreateProjectRequest,
+  CreateTaskCommentRequest,
+  CreateTaskRelationRequest,
+  CreateTaskRequest,
+  PaginatedResponse,
+  Project,
+  ProjectTaskSummaryResponse,
+  Task,
+  TaskActivity,
+  TaskComment,
+  TaskRelation,
+  TaskRelationTargetType,
+  TaskSubtaskSummaryResponse,
+  TaskWatcher,
+  ThreadWatcher,
+  UpdateProjectRequest,
+  UpdateTaskCommentRequest,
+  UpdateTaskRequest,
+} from './types.js';
+
+/** Project and task REST methods shared by every ParallClient instance. */
+export abstract class ProjectTaskClient {
+  protected abstract request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    query?: Record<string, string | number | boolean | undefined>,
+  ): Promise<T>;
+
+  async createTask(orgId: string, data: CreateTaskRequest): Promise<Task> {
+    return this.request('POST', ENDPOINTS.TASKS(orgId), data);
+  }
+
+  async getTasks(
+    orgId: string,
+    params?: {
+      q?: string;
+      status?: string;
+      priority?: string;
+      assignee_id?: string;
+      parent_id?: string;
+      project_id?: string;
+      /** Comma-separated label IDs; matching uses any-of semantics. */
+      label_ids?: string;
+      limit?: number;
+      cursor?: string;
+      sort?: string;
+      order?: string;
+      scope?: 'active' | 'archived' | 'all';
+    },
+  ): Promise<PaginatedResponse<Task>> {
+    return this.request('GET', ENDPOINTS.TASKS(orgId), undefined, params);
+  }
+
+  async getTaskSubtaskSummary(
+    orgId: string,
+    params?: { assignee_id?: string; project_id?: string },
+  ): Promise<TaskSubtaskSummaryResponse> {
+    return this.request('GET', ENDPOINTS.TASK_SUBTASK_SUMMARY(orgId), undefined, params);
+  }
+
+  async getTask(orgId: string, taskId: string): Promise<Task> {
+    return this.request('GET', ENDPOINTS.TASK(orgId, taskId));
+  }
+
+  async updateTask(orgId: string, taskId: string, data: UpdateTaskRequest): Promise<Task> {
+    return this.request('PATCH', ENDPOINTS.TASK(orgId, taskId), data);
+  }
+
+  async deleteTask(orgId: string, taskId: string, opts?: { force?: boolean }): Promise<void> {
+    return this.request(
+      'DELETE',
+      ENDPOINTS.TASK(orgId, taskId),
+      undefined,
+      opts?.force ? { force: 'true' } : undefined,
+    );
+  }
+
+  async archiveTask(orgId: string, taskId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.TASK_ARCHIVE(orgId, taskId));
+  }
+
+  async restoreTask(orgId: string, taskId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.TASK_RESTORE(orgId, taskId));
+  }
+
+  async watchTask(orgId: string, taskId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.TASK_WATCH(orgId, taskId));
+  }
+
+  async unwatchTask(orgId: string, taskId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.TASK_WATCH(orgId, taskId));
+  }
+
+  async getTaskWatchers(orgId: string, taskId: string): Promise<TaskWatcher[]> {
+    const res = await this.request<{ data: TaskWatcher[] }>(
+      'GET',
+      ENDPOINTS.TASK_WATCHERS(orgId, taskId),
+    );
+    return res.data;
+  }
+
+  async subscribeTaskMember(orgId: string, taskId: string, userId: string): Promise<void> {
+    return this.request('PUT', ENDPOINTS.TASK_SUBSCRIBER(orgId, taskId, userId));
+  }
+
+  async unsubscribeTaskMember(orgId: string, taskId: string, userId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.TASK_SUBSCRIBER(orgId, taskId, userId));
+  }
+
+  async watchThread(threadRootId: string): Promise<void> {
+    return this.request('POST', ENDPOINTS.MESSAGE_WATCH(threadRootId));
+  }
+
+  async unwatchThread(threadRootId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.MESSAGE_WATCH(threadRootId));
+  }
+
+  async getThreadWatchers(threadRootId: string): Promise<ThreadWatcher[]> {
+    const res = await this.request<{ data: ThreadWatcher[] }>(
+      'GET',
+      ENDPOINTS.MESSAGE_WATCHERS(threadRootId),
+    );
+    return res.data;
+  }
+
+  async isWatchingThread(threadRootId: string): Promise<boolean> {
+    const res = await this.request<{ watching: boolean }>(
+      'GET',
+      ENDPOINTS.MESSAGE_WATCHING(threadRootId),
+    );
+    return res.watching;
+  }
+
+  async getSubtasks(orgId: string, taskId: string): Promise<Task[]> {
+    const res = await this.request<PaginatedResponse<Task>>(
+      'GET',
+      ENDPOINTS.TASK_SUBTASKS(orgId, taskId),
+    );
+    return res.data;
+  }
+
+  async createTaskRelation(
+    orgId: string,
+    taskId: string,
+    data: CreateTaskRelationRequest,
+  ): Promise<TaskRelation> {
+    return this.request('POST', ENDPOINTS.TASK_RELATIONS(orgId, taskId), data);
+  }
+
+  async getTaskRelations(orgId: string, taskId: string): Promise<TaskRelation[]> {
+    const res = await this.request<{ data: TaskRelation[] }>(
+      'GET',
+      ENDPOINTS.TASK_RELATIONS(orgId, taskId),
+    );
+    return res.data;
+  }
+
+  async listTaskRelationsByTarget(
+    orgId: string,
+    params: { target_type: TaskRelationTargetType; target_id: string },
+  ): Promise<TaskRelation[]> {
+    const query = new URLSearchParams({
+      target_type: params.target_type,
+      target_id: params.target_id,
+    });
+    const res = await this.request<{ data: TaskRelation[] }>(
+      'GET',
+      `${ENDPOINTS.TASK_RELATIONS_BY_TARGET(orgId)}?${query.toString()}`,
+    );
+    return res.data;
+  }
+
+  async deleteTaskRelation(orgId: string, taskId: string, relationId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.TASK_RELATION(orgId, taskId, relationId));
+  }
+
+  async getTaskComments(
+    orgId: string,
+    taskId: string,
+    params?: { limit?: number; cursor?: string; order?: string },
+  ): Promise<PaginatedResponse<TaskComment>> {
+    return this.request('GET', ENDPOINTS.TASK_COMMENTS(orgId, taskId), undefined, params);
+  }
+
+  async getTaskComment(orgId: string, taskId: string, commentId: string): Promise<TaskComment> {
+    return this.request('GET', ENDPOINTS.TASK_COMMENT(orgId, taskId, commentId));
+  }
+
+  async createTaskComment(
+    orgId: string,
+    taskId: string,
+    data: CreateTaskCommentRequest,
+  ): Promise<TaskComment> {
+    return this.request('POST', ENDPOINTS.TASK_COMMENTS(orgId, taskId), data);
+  }
+
+  async updateTaskComment(
+    orgId: string,
+    taskId: string,
+    commentId: string,
+    data: UpdateTaskCommentRequest,
+  ): Promise<TaskComment> {
+    return this.request('PATCH', ENDPOINTS.TASK_COMMENT(orgId, taskId, commentId), data);
+  }
+
+  async deleteTaskComment(orgId: string, taskId: string, commentId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.TASK_COMMENT(orgId, taskId, commentId));
+  }
+
+  async getTaskActivities(
+    orgId: string,
+    taskId: string,
+    params?: { limit?: number; cursor?: string },
+  ): Promise<PaginatedResponse<TaskActivity>> {
+    return this.request('GET', ENDPOINTS.TASK_ACTIVITIES(orgId, taskId), undefined, params);
+  }
+
+  async createProject(orgId: string, data: CreateProjectRequest): Promise<Project> {
+    return this.request('POST', ENDPOINTS.PROJECTS(orgId), data);
+  }
+
+  async getProjects(orgId: string): Promise<Project[]> {
+    const res = await this.request<{ data: Project[] }>('GET', ENDPOINTS.PROJECTS(orgId));
+    return res.data;
+  }
+
+  async getProjectTaskSummary(orgId: string): Promise<ProjectTaskSummaryResponse> {
+    return this.request('GET', ENDPOINTS.PROJECT_TASK_SUMMARY(orgId));
+  }
+
+  async getProject(orgId: string, projectId: string): Promise<Project> {
+    return this.request('GET', ENDPOINTS.PROJECT(orgId, projectId));
+  }
+
+  async updateProject(
+    orgId: string,
+    projectId: string,
+    data: UpdateProjectRequest,
+  ): Promise<Project> {
+    return this.request('PATCH', ENDPOINTS.PROJECT(orgId, projectId), data);
+  }
+
+  async deleteProject(orgId: string, projectId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.PROJECT(orgId, projectId));
+  }
+}

package/src/subject.ts

@@ -0,0 +1,66 @@
+/** Shared ACL subject token helpers for clients that edit permission rosters. */
+
+export type SubjectKind = 'wildcard' | 'user' | 'team';
+
+export interface ParsedSubject {
+  kind: SubjectKind;
+  /** Empty for wildcard, user ID for user, and slug without `@` for team. */
+  value: string;
+}
+
+const TEAM_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+
+export function isValidTeamSlug(slug: string): boolean {
+  return TEAM_SLUG.test(slug);
+}
+
+export function formatTeamSubject(slug: string): string {
+  if (!isValidTeamSlug(slug)) {
+    throw new Error(`Invalid team slug: ${slug}`);
+  }
+  return `@${slug}`;
+}
+
+export function parseSubjectToken(token: string): ParsedSubject {
+  if (token === '*') {
+    return { kind: 'wildcard', value: '' };
+  }
+  if (token.startsWith('@')) {
+    const slug = token.slice(1);
+    if (!isValidTeamSlug(slug)) {
+      throw new Error(`Invalid team subject: ${token}`);
+    }
+    return { kind: 'team', value: slug };
+  }
+  if (!token) {
+    throw new Error('Subject token is empty');
+  }
+  return { kind: 'user', value: token };
+}
+
+/**
+ * Maximum distinct team references one ACL row may carry. Mirrors
+ * `subject.MaxTeamSubjectsPerWrite` on the server, which enforces it.
+ */
+export const MAX_TEAM_SUBJECTS_PER_WRITE = 200;
+
+/**
+ * Returns unique team slugs in first-seen order for batched write validation.
+ *
+ * Syntactically invalid slugs are included rather than skipped, matching the
+ * server's `subject.TeamSlugs`: a mistyped `@Finance` must reach the existence
+ * check and be reported missing, so the write fails with a legible error
+ * instead of storing a token that matches nobody.
+ */
+export function teamSlugsFromSubjects(subjects: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const slugs: string[] = [];
+  for (const token of subjects) {
+    if (!token.startsWith('@')) continue;
+    const slug = token.slice(1);
+    if (!slug || seen.has(slug)) continue;
+    seen.add(slug);
+    slugs.push(slug);
+  }
+  return slugs;
+}

package/src/task-label-client.ts

@@ -0,0 +1,37 @@
+import { ENDPOINTS } from './constants.js';
+import { ProjectTaskClient } from './project-task-client.js';
+import type {
+  AddTaskLabelsRequest,
+  CreateLabelRequest,
+  Label,
+  UpdateLabelRequest,
+} from './task-label-types.js';
+import type { Task } from './types.js';
+
+/** Organization label vocabulary and incremental Task attachment methods. */
+export abstract class TaskLabelClient extends ProjectTaskClient {
+  async getLabels(orgId: string): Promise<Label[]> {
+    const response = await this.request<{ data: Label[] }>('GET', ENDPOINTS.LABELS(orgId));
+    return response.data;
+  }
+
+  async createLabel(orgId: string, data: CreateLabelRequest): Promise<Label> {
+    return this.request('POST', ENDPOINTS.LABELS(orgId), data);
+  }
+
+  async updateLabel(orgId: string, labelId: string, data: UpdateLabelRequest): Promise<Label> {
+    return this.request('PATCH', ENDPOINTS.LABEL(orgId, labelId), data);
+  }
+
+  async deleteLabel(orgId: string, labelId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.LABEL(orgId, labelId));
+  }
+
+  async addTaskLabels(orgId: string, taskId: string, data: AddTaskLabelsRequest): Promise<Task> {
+    return this.request('POST', ENDPOINTS.TASK_LABELS(orgId, taskId), data);
+  }
+
+  async removeTaskLabel(orgId: string, taskId: string, labelId: string): Promise<Task> {
+    return this.request('DELETE', ENDPOINTS.TASK_LABEL(orgId, taskId, labelId));
+  }
+}

package/src/task-label-types.ts

@@ -0,0 +1,51 @@
+export type LabelColor =
+  | 'default'
+  | 'red'
+  | 'green'
+  | 'yellow'
+  | 'blue'
+  | 'lilac'
+  | 'orange'
+  | 'magenta'
+  | 'sand'
+  | 'fuchsia'
+  | 'cerulean'
+  | 'teal'
+  | 'lime';
+
+export interface Label {
+  id: string;
+  org_id: string;
+  name: string;
+  color: LabelColor;
+  /** Optional agent-readable guidance for when this label applies. */
+  description?: string | null;
+  created_by: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateLabelRequest {
+  name: string;
+  color?: LabelColor;
+  description?: string;
+}
+
+export interface UpdateLabelRequest {
+  name?: string;
+  color?: LabelColor;
+  /** Explicit null clears the description. */
+  description?: string | null;
+}
+
+export interface AddTaskLabelsRequest {
+  label_ids: string[];
+}
+
+export type LabelCreatedData = Label;
+export type LabelUpdatedData = Label;
+
+export interface LabelDeletedData {
+  label_id: string;
+  org_id: string;
+}