@parall/sdk 1.54.0 → 1.55.1

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,10 +591,31 @@ 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}`,
+  PROJECT_MEMBERS: (orgId: string, projectId: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/members`,
+  PROJECT_READERS: (orgId: string, projectId: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/readers`,
+  PROJECT_LIBRARY: (orgId: string) => `${API_BASE}/orgs/${orgId}/projects/library`,
+  PROJECT_JOIN: (orgId: string, projectId: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/join`,
+  PROJECT_JOIN_REQUESTS: (orgId: string, projectId: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/join-requests`,
+  // subject is a bare user ID or a bare team ID; both are path-segment safe.
+  PROJECT_MEMBER: (orgId: string, projectId: string, subject: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/members/${subject}`,
 
   // Schedules (org-scoped, platform time trigger primitive)
   SCHEDULES: (orgId: string) => `${API_BASE}/orgs/${orgId}/schedules`,
@@ -653,8 +680,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 +851,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`,
@@ -905,6 +937,10 @@ export const ENDPOINTS = {
   // Per-profile egress proxy (hosted Cloud Profiles; manager-only, human-only).
   ORG_EDGE_PROFILE_PROXY: (orgId: string, edgeId: string, profileName: string) =>
     `/api/v1/orgs/${orgId}/edge/${edgeId}/profiles/${encodeURIComponent(profileName)}/proxy`,
+  // Per-profile one-shot cookie seed (hosted Cloud Profiles; manager-only,
+  // human-only, idle-only). Injected at the next cold start, then consumed.
+  ORG_EDGE_PROFILE_COOKIES: (orgId: string, edgeId: string, profileName: string) =>
+    `/api/v1/orgs/${orgId}/edge/${edgeId}/profiles/${encodeURIComponent(profileName)}/cookies`,
   ORG_EDGE_EXEC: (orgId: string) => `/api/v1/orgs/${orgId}/edge/exec`,
   // Cloud Edge live viewer command (V1b) — api-server, gated on cap:edge-viewer.
   // Same request/reply shape as the v2 browser-profile viewer, on the v3 edge
@@ -925,11 +961,13 @@ 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). The
+  // 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.
@@ -998,6 +1036,7 @@ export const WS_EVENTS = {
   PONG: 'pong',
   WATCHING: 'watching',
   MESSAGE_NEW: 'message.new',
+  /** @deprecated `message.patch` is retired and never published; kept for compile compatibility. */
   MESSAGE_PATCH: 'message.patch',
   MESSAGE_EDIT: 'message.edit',
   MESSAGE_DELETE: 'message.delete',
@@ -1018,6 +1057,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',
@@ -1028,6 +1070,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,342 @@
+import { ENDPOINTS } from './constants.js';
+import type {
+  AddProjectMemberRequest,
+  Approval,
+  CreateProjectRequest,
+  CreateTaskCommentRequest,
+  CreateTaskRelationRequest,
+  CreateTaskRequest,
+  PaginatedResponse,
+  Project,
+  ProjectJoinRequest,
+  ProjectLibraryEntry,
+  ProjectMember,
+  ProjectTaskSummaryResponse,
+  Task,
+  TaskActivity,
+  TaskComment,
+  TaskRelation,
+  TaskRelationTargetType,
+  TaskSubtaskSummaryResponse,
+  TaskWatcher,
+  ThreadWatcher,
+  UpdateProjectMemberRequest,
+  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));
+  }
+
+  /** Roster with display info; readable by anyone who can read the project. */
+  async getProjectMembers(orgId: string, projectId: string): Promise<ProjectMember[]> {
+    const res = await this.request<{ data: ProjectMember[] }>(
+      'GET',
+      ENDPOINTS.PROJECT_MEMBERS(orgId, projectId),
+    );
+    return res.data;
+  }
+
+  /**
+   * User IDs who may read the project — the assignee-eligibility set. Every
+   * tier answers the roster expansion (direct, team-reached, org
+   * owners/admins); visibility only shapes admission, never reach.
+   */
+  async getProjectReaders(orgId: string, projectId: string): Promise<string[]> {
+    const res = await this.request<{ data: string[] }>(
+      'GET',
+      ENDPOINTS.PROJECT_READERS(orgId, projectId),
+    );
+    return res.data;
+  }
+
+  /** The join library: every discoverable project (public + restricted, plus
+   * private for org owners/admins) with the caller's admission state. */
+  async getProjectLibrary(orgId: string): Promise<ProjectLibraryEntry[]> {
+    const res = await this.request<{ data: ProjectLibraryEntry[] }>(
+      'GET',
+      ENDPOINTS.PROJECT_LIBRARY(orgId),
+    );
+    return res.data;
+  }
+
+  /** Public-tier self-admission: writes the caller's own member row.
+   * Other tiers answer `404 PROJECT_NOT_FOUND`; a duplicate answers
+   * `409 MEMBER_EXISTS`. */
+  async joinProject(orgId: string, projectId: string): Promise<ProjectMember> {
+    return this.request('POST', ENDPOINTS.PROJECT_JOIN(orgId, projectId));
+  }
+
+  /** Restricted-tier admission petition. A pending duplicate answers
+   * `409 REQUEST_EXISTS`; membership answers `409 MEMBER_EXISTS`. */
+  async createProjectJoinRequest(orgId: string, projectId: string): Promise<Approval> {
+    return this.request('POST', ENDPOINTS.PROJECT_JOIN_REQUESTS(orgId, projectId));
+  }
+
+  /** Pending petitions for one project — manager standing required. */
+  async listProjectJoinRequests(orgId: string, projectId: string): Promise<ProjectJoinRequest[]> {
+    const res = await this.request<{ data: ProjectJoinRequest[] }>(
+      'GET',
+      ENDPOINTS.PROJECT_JOIN_REQUESTS(orgId, projectId),
+    );
+    return res.data;
+  }
+
+  /** Withdraws the caller's own pending petition. */
+  async cancelProjectJoinRequest(orgId: string, projectId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.PROJECT_JOIN_REQUESTS(orgId, projectId));
+  }
+
+  /**
+   * Adds one subject (user ID or team ID) to the roster. Manager-only,
+   * create-only: an existing row answers `409 MEMBER_EXISTS` — change roles
+   * through updateProjectMember instead.
+   */
+  async addProjectMember(
+    orgId: string,
+    projectId: string,
+    req: AddProjectMemberRequest,
+  ): Promise<ProjectMember> {
+    return this.request('POST', ENDPOINTS.PROJECT_MEMBERS(orgId, projectId), req);
+  }
+
+  /** Sets one roster entry's role. Demoting the last manager answers `400 LAST_MANAGER`. */
+  async updateProjectMember(
+    orgId: string,
+    projectId: string,
+    subject: string,
+    req: UpdateProjectMemberRequest,
+  ): Promise<ProjectMember> {
+    return this.request('PATCH', ENDPOINTS.PROJECT_MEMBER(orgId, projectId, subject), req);
+  }
+
+  /** Removes one roster entry. Removing the last manager answers `400 LAST_MANAGER`. */
+  async removeProjectMember(orgId: string, projectId: string, subject: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.PROJECT_MEMBER(orgId, projectId, subject));
+  }
+}

package/src/subject.ts

@@ -0,0 +1,57 @@
+/** 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 the full team ID for team. */
+  value: string;
+}
+
+/**
+ * Team subjects are stored as bare team IDs (`team_...`), mirroring the
+ * server's `pkg/subject`: the ID prefix is what makes a token a team
+ * reference, so no marker syntax exists and a rename never invalidates a
+ * stored reference.
+ */
+const TEAM_ID_PREFIX = 'team_';
+
+export function isTeamSubject(token: string): boolean {
+  return token.startsWith(TEAM_ID_PREFIX);
+}
+
+export function parseSubjectToken(token: string): ParsedSubject {
+  if (token === '*') {
+    return { kind: 'wildcard', value: '' };
+  }
+  if (!token) {
+    throw new Error('Subject token is empty');
+  }
+  if (isTeamSubject(token)) {
+    return { kind: 'team', value: token };
+  }
+  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 IDs in first-seen order for batched write validation.
+ * An ID that names no team comes back from the server's existence check
+ * reported missing, so the write fails with a legible error instead of
+ * storing a token that matches nobody.
+ */
+export function teamIdsFromSubjects(subjects: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const ids: string[] = [];
+  for (const token of subjects) {
+    if (!isTeamSubject(token) || seen.has(token)) continue;
+    seen.add(token);
+    ids.push(token);
+  }
+  return ids;
+}

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;
+}