@parall/sdk 1.20.1 → 1.21.0

package/src/client.ts

@@ -4,6 +4,7 @@ import type {
   RegisterRequest,
   RegisterResponse,
   LoginRequest,
+  ChangePasswordRequest,
   CheckEmailResponse,
   User,
   Organization,
@@ -44,11 +45,16 @@ import type {
   Project,
   CreateProjectRequest,
   UpdateProjectRequest,
+  Schedule,
+  ScheduleRun,
+  CreateScheduleInput,
+  UpdateScheduleInput,
+  ScheduleFilters,
+  ScheduleRunFilters,
   AgentSessionDB,
   AgentStep,
   CreateAgentSessionRequest,
   CreateAgentStepRequest,
-  CreateAgentTaskBackfillCommentRequest,
   UpdateAgentSessionRequest,
   OrgInvitation,
   InvitationPublicInfo,
@@ -56,12 +62,16 @@ import type {
   Wiki,
   WikiBlob,
   WikiChangeset,
+  WikiFileUploadResponse,
+  WikiFilePreviewUrlResponse,
   WikiTreeResponse,
   WikiNodeSectionArtifact,
   WikiSearchResponse,
   WikiPageIndex,
   WikiRefsResponse,
   WikiRefsCheckResponse,
+  WikiAnchorStatusRequest,
+  WikiAnchorStatusResponse,
   WikiDiff,
   WikiPathScope,
   WikiAccessStatus,
@@ -290,6 +300,68 @@ export class ParallClient {
     return res.json() as Promise<T>;
   }
 
+  /**
+   * Multipart upload variant of `request`. Same auth / refresh / error
+   * handling, but lets the caller hand us a prepared `FormData` (file +
+   * text fields) and skips the JSON content-type. Used by
+   * uploadWikiFile / uploadWikiFileToChangeset — wiki binary uploads can
+   * hit the 100 MiB cap, so a longer 5-minute timeout is used so a
+   * 50 MiB blob on a slow connection doesn't get chopped at 15 s.
+   */
+  private async multipartRequest<T>(
+    method: string,
+    path: string,
+    body: FormData,
+    retried = false,
+  ): Promise<T> {
+    if (!retried) {
+      await this.ensureFreshToken(path);
+    }
+    // Don't set Content-Type — the browser fills in the boundary.
+    const { 'Content-Type': _drop, ...headers } = this.buildHeaders();
+    void _drop;
+
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body,
+        signal: AbortSignal.timeout(5 * 60 * 1000),
+      });
+    } catch (err) {
+      if (err instanceof DOMException && err.name === 'TimeoutError') {
+        throw new ApiError(0, 'Request timed out', 'REQUEST_TIMEOUT');
+      }
+      throw err;
+    }
+
+    if (res.status === 401) {
+      const pathSuffix = path.replace(/^\/api\/v1/, '');
+      const isAuthPath = ParallClient.AUTH_PATHS.has(pathSuffix);
+      if (!retried && !isAuthPath && this.getRefreshToken) {
+        const refreshed = await this.tryRefresh();
+        if (refreshed) {
+          return this.multipartRequest<T>(method, path, body, true);
+        }
+      }
+      if (this.onTokenExpired && !isAuthPath) {
+        this.onTokenExpired();
+      }
+    }
+
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({}));
+      const errorObj = errorBody?.error && typeof errorBody.error === 'object' ? errorBody.error as { message?: string; code?: string } : undefined;
+      const errMsg = errorObj?.message ?? (typeof errorBody?.error === 'string' ? errorBody.error : undefined);
+      const errCode = errorObj?.code ?? (typeof errorBody?.code === 'string' ? errorBody.code : undefined);
+      throw new ApiError(res.status, errMsg ?? res.statusText, errCode);
+    }
+
+    if (res.status === 204) return undefined as T;
+    return res.json() as Promise<T>;
+  }
+
   // ---- Auth ----
 
   async register(req: RegisterRequest): Promise<RegisterResponse> {
@@ -308,6 +380,10 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.AUTH_LOGOUT);
   }
 
+  async changePassword(req: ChangePasswordRequest): Promise<void> {
+    return this.request('POST', ENDPOINTS.AUTH_CHANGE_PASSWORD, req);
+  }
+
   async checkEmail(email: string): Promise<CheckEmailResponse> {
     return this.request('POST', ENDPOINTS.AUTH_CHECK_EMAIL, { email });
   }
@@ -679,15 +755,6 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), req);
   }
 
-  async createAgentTaskBackfillComment(
-    orgId: string,
-    agentId: string,
-    sessionId: string,
-    req: CreateAgentTaskBackfillCommentRequest,
-  ): Promise<Comment> {
-    return this.request('POST', ENDPOINTS.AGENT_SESSION_TASK_BACKFILL_COMMENTS(orgId, agentId, sessionId), req);
-  }
-
   async getAgentSessionSteps(orgId: string, agentId: string, sessionId: string, params?: { limit?: number }): Promise<AgentStep[]> {
     const res = await this.request<{ data: AgentStep[] }>('GET', ENDPOINTS.AGENT_SESSION_STEPS(orgId, agentId, sessionId), undefined, params);
     return res.data;
@@ -1067,6 +1134,57 @@ export class ParallClient {
     return this.request('DELETE', ENDPOINTS.PROJECT(orgId, projectId));
   }
 
+  // ---- Schedules (org-scoped) ----
+
+  async createSchedule(orgId: string, input: CreateScheduleInput): Promise<Schedule> {
+    return this.request('POST', ENDPOINTS.SCHEDULES(orgId), input);
+  }
+
+  async listSchedules(orgId: string, filters?: ScheduleFilters): Promise<PaginatedResponse<Schedule>> {
+    return this.request('GET', ENDPOINTS.SCHEDULES(orgId), undefined, filters as Record<string, string | number | undefined>);
+  }
+
+  async getSchedule(orgId: string, scheduleId: string): Promise<Schedule> {
+    return this.request('GET', ENDPOINTS.SCHEDULE(orgId, scheduleId));
+  }
+
+  async updateSchedule(orgId: string, scheduleId: string, patch: UpdateScheduleInput): Promise<Schedule> {
+    return this.request('PATCH', ENDPOINTS.SCHEDULE(orgId, scheduleId), patch);
+  }
+
+  async pauseSchedule(orgId: string, scheduleId: string): Promise<Schedule> {
+    return this.request('POST', ENDPOINTS.SCHEDULE_PAUSE(orgId, scheduleId));
+  }
+
+  async resumeSchedule(orgId: string, scheduleId: string): Promise<Schedule> {
+    return this.request('POST', ENDPOINTS.SCHEDULE_RESUME(orgId, scheduleId));
+  }
+
+  async cancelSchedule(orgId: string, scheduleId: string): Promise<Schedule> {
+    return this.request('POST', ENDPOINTS.SCHEDULE_CANCEL(orgId, scheduleId));
+  }
+
+  async deleteSchedule(orgId: string, scheduleId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.SCHEDULE(orgId, scheduleId));
+  }
+
+  async listScheduleRuns(
+    orgId: string,
+    scheduleId: string,
+    filters?: ScheduleRunFilters,
+  ): Promise<PaginatedResponse<ScheduleRun>> {
+    return this.request(
+      'GET',
+      ENDPOINTS.SCHEDULE_RUNS(orgId, scheduleId),
+      undefined,
+      filters as Record<string, string | number | undefined>,
+    );
+  }
+
+  async getScheduleRun(orgId: string, runId: string): Promise<ScheduleRun> {
+    return this.request('GET', ENDPOINTS.SCHEDULE_RUN(orgId, runId));
+  }
+
   // ---- Wikis (org-scoped) ----
 
   async createWiki(orgId: string, data: CreateWikiRequest): Promise<Wiki> {
@@ -1110,6 +1228,16 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.WIKI_REFS_CHECK(orgId, wikiId), undefined, params);
   }
 
+  // Anchor-status: batch blob-SHA compare for inline-comment outdated judging.
+  // Refs the caller cannot read are silently dropped from the response.
+  async getWikiAnchorStatus(
+    orgId: string,
+    wikiId: string,
+    body: WikiAnchorStatusRequest,
+  ): Promise<WikiAnchorStatusResponse> {
+    return this.request('POST', ENDPOINTS.WIKI_ANCHOR_STATUS(orgId, wikiId), body);
+  }
+
   async createWikiChangeset(orgId: string, wikiId: string, data: CreateWikiChangesetRequest): Promise<WikiChangeset> {
     return normalizeWikiChangeset(await this.request('POST', ENDPOINTS.WIKI_CHANGESETS(orgId, wikiId), data));
   }
@@ -1144,6 +1272,85 @@ export class ParallClient {
     return normalizeWikiChangeset(await this.request('POST', ENDPOINTS.WIKI_CHANGESET_CLOSE(orgId, wikiId, changesetId)));
   }
 
+  // ---- Wiki Binary Upload / Delete (Phase 2 of wiki-file-storage-design) ----
+
+  /**
+   * Upload a binary file directly to the wiki's default branch (maintain
+   * scope). Size ≤ 1 MiB lands as an inline Git blob; > 1 MiB lands as a
+   * Git-LFS pointer backed by S3. Text files return 422 — they must go
+   * through createWikiChangeset / updateWikiChangeset.
+   */
+  async uploadWikiFile(
+    orgId: string,
+    wikiId: string,
+    params: { path: string; file: Blob; message?: string },
+  ): Promise<WikiFileUploadResponse> {
+    // `POST /uploads` always writes to the wiki's default branch — the
+    // backend's parseUpload silently drops any `parent_ref` field, so
+    // surfacing one in this signature would mislead callers. To target
+    // a feature branch, use uploadWikiFileToChangeset.
+    const fd = new FormData();
+    fd.append('path', params.path);
+    fd.append('file', params.file);
+    if (params.message) fd.append('message', params.message);
+    return this.multipartRequest('POST', ENDPOINTS.WIKI_UPLOADS(orgId, wikiId), fd);
+  }
+
+  /**
+   * Upload a binary file into a changeset's feature branch (read scope +
+   * author-only). Used by reader flow: propose a changeset, attach
+   * binary, PATCH markdown that references it. On merge the binary
+   * squashes into the default branch.
+   */
+  async uploadWikiFileToChangeset(
+    orgId: string,
+    wikiId: string,
+    changesetId: string,
+    params: { path: string; file: Blob; message?: string },
+  ): Promise<WikiFileUploadResponse> {
+    const fd = new FormData();
+    fd.append('path', params.path);
+    fd.append('file', params.file);
+    if (params.message) fd.append('message', params.message);
+    return this.multipartRequest(
+      'POST',
+      ENDPOINTS.WIKI_CHANGESET_FILES(orgId, wikiId, changesetId),
+      fd,
+    );
+  }
+
+  /** Remove a binary file from the default branch. Text files must use a
+   * changeset delete action. The blob stays reachable via git history. */
+  async deleteWikiFile(
+    orgId: string,
+    wikiId: string,
+    params: { path: string; message?: string },
+  ): Promise<void> {
+    await this.request(
+      'DELETE',
+      ENDPOINTS.WIKI_FILES(orgId, wikiId),
+      undefined,
+      { path: params.path, message: params.message },
+    );
+  }
+
+  /**
+   * Sign a short-lived (~5-min) URL the browser can paste into a media
+   * element src. ACL is evaluated here; the returned URL is a capability
+   * token — don't leak it.
+   */
+  async getWikiFilePreviewUrl(
+    orgId: string,
+    wikiId: string,
+    params: { path: string; ref?: string },
+  ): Promise<WikiFilePreviewUrlResponse> {
+    return this.request(
+      'POST',
+      ENDPOINTS.WIKI_FILE_PREVIEW_URL(orgId, wikiId),
+      params,
+    );
+  }
+
   // ---- Wiki Path Scopes (AFCS ACL) ----
 
   async getWikiPathScopes(orgId: string, wikiId: string): Promise<WikiPathScope[]> {
@@ -1215,9 +1422,12 @@ export class ParallClient {
 
   // ---- Unified Comments ----
 
-  async getComments(orgId: string, params: {
-    target_uri: string; limit?: number; cursor?: string; order?: string;
-  }): Promise<PaginatedResponse<Comment>> {
+  async getComments(
+    orgId: string,
+    params:
+      | { target_uri: string; target_prefix?: never; limit?: number; cursor?: string; order?: string }
+      | { target_prefix: string; target_uri?: never; limit?: number; cursor?: string; order?: string },
+  ): Promise<PaginatedResponse<Comment>> {
     return this.request('GET', ENDPOINTS.COMMENTS(orgId), undefined, params);
   }
 

package/src/constants.ts

@@ -11,6 +11,7 @@ export const ENDPOINTS = {
   AUTH_LOGIN: `${API_BASE}/auth/login`,
   AUTH_REFRESH: `${API_BASE}/auth/refresh`,
   AUTH_LOGOUT: `${API_BASE}/auth/logout`,
+  AUTH_CHANGE_PASSWORD: `${API_BASE}/auth/change-password`,
   AUTH_CHECK_EMAIL: `${API_BASE}/auth/check-email`,
   AUTH_VERIFY_EMAIL: `${API_BASE}/auth/verify-email`,
   AUTH_RESEND_CODE: `${API_BASE}/auth/resend-code`,
@@ -89,8 +90,6 @@ export const ENDPOINTS = {
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}/steps`,
   AGENT_SESSION_STEP: (orgId: string, agentId: string, sessionId: string, stepId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}/steps/${stepId}`,
-  AGENT_SESSION_TASK_BACKFILL_COMMENTS: (orgId: string, agentId: string, sessionId: string) =>
-    `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}/task-backfill-comments`,
   AGENT_TASKS: (orgId: string, agentId: string) =>
     `${API_BASE}/orgs/${orgId}/agents/${agentId}/tasks`,
   AGENT_RUNTIME_AUTH: (orgId: string, agentId: string) =>
@@ -157,6 +156,15 @@ export const ENDPOINTS = {
   PROJECTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/projects`,
   PROJECT: (orgId: string, projectId: string) => `${API_BASE}/orgs/${orgId}/projects/${projectId}`,
 
+  // Schedules (org-scoped, platform time trigger primitive)
+  SCHEDULES: (orgId: string) => `${API_BASE}/orgs/${orgId}/schedules`,
+  SCHEDULE: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/schedules/${id}`,
+  SCHEDULE_PAUSE: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/schedules/${id}/pause`,
+  SCHEDULE_RESUME: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/schedules/${id}/resume`,
+  SCHEDULE_CANCEL: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/schedules/${id}/cancel`,
+  SCHEDULE_RUNS: (orgId: string, id: string) => `${API_BASE}/orgs/${orgId}/schedules/${id}/runs`,
+  SCHEDULE_RUN: (orgId: string, runId: string) => `${API_BASE}/orgs/${orgId}/schedule_runs/${runId}`,
+
   // Invitations (org-scoped, admin)
   ORG_INVITATIONS: (orgId: string) => `${API_BASE}/orgs/${orgId}/invitations`,
   ORG_INVITATION: (orgId: string, invId: string) =>
@@ -180,6 +188,7 @@ export const ENDPOINTS = {
   WIKI_PAGE_INDEX: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/page-index`,
   WIKI_REFS: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/refs`,
   WIKI_REFS_CHECK: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/refs/check`,
+  WIKI_ANCHOR_STATUS: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/anchor-status`,
   WIKI_CHANGESETS: (orgId: string, wikiId: string) => `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets`,
   WIKI_CHANGESET: (orgId: string, wikiId: string, changesetId: string) =>
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets/${changesetId}`,
@@ -189,6 +198,16 @@ export const ENDPOINTS = {
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets/${changesetId}/merge`,
   WIKI_CHANGESET_CLOSE: (orgId: string, wikiId: string, changesetId: string) =>
     `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets/${changesetId}/close`,
+  WIKI_CHANGESET_FILES: (orgId: string, wikiId: string, changesetId: string) =>
+    `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/changesets/${changesetId}/files`,
+
+  // Wiki Binary Upload / Delete (Phase 2 of wiki-file-storage-design)
+  WIKI_UPLOADS: (orgId: string, wikiId: string) =>
+    `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/uploads`,
+  WIKI_FILES: (orgId: string, wikiId: string) =>
+    `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/files`,
+  WIKI_FILE_PREVIEW_URL: (orgId: string, wikiId: string) =>
+    `${WIKI_BASE}/orgs/${orgId}/wikis/${wikiId}/files/preview-url`,
 
   // Wiki Path Scopes (AFCS ACL)
   WIKI_PATH_SCOPES: (orgId: string, wikiId: string) =>
@@ -310,11 +329,85 @@ export const WS_EVENTS = {
   INBOX_BULK_UPDATE: 'inbox.bulk_update',
   READ_POSITION_UPDATED: 'read_position.updated',
   DISPATCH_NEW: 'dispatch.new',
+  SCHEDULE_CREATED: 'schedule.created',
+  SCHEDULE_UPDATED: 'schedule.updated',
+  SCHEDULE_DELETED: 'schedule.deleted',
+  SCHEDULE_FIRED: 'schedule.fired',
 } as const;
 
 // Canonical target URI builders for unified comments.
+//
+// Heading and line anchors for wiki inline comments MUST be pinned to a full
+// commit SHA (40-hex-char). The builders do not validate — callers are
+// expected to pass the current wiki HEAD at comment-creation time.
+
+// encodeHeadingSegment mirrors Go's url.PathEscape + ':' → '%3A' exactly so
+// the Go and TS SDKs produce byte-identical target_uri values for the same
+// heading text. encodeURIComponent differs from PathEscape on a handful of
+// characters — this function normalizes back to PathEscape's character set:
+//   - unescape  & = @ $ +    (PathEscape leaves these alone, URIComponent encodes)
+//   - escape    ! * ' ( )    (URIComponent leaves these alone, PathEscape encodes)
+// ':' is already encoded as %3A by encodeURIComponent.
+function encodeHeadingSegment(seg: string): string {
+  return encodeURIComponent(seg)
+    .replace(/%26/g, '&')
+    .replace(/%3D/g, '=')
+    .replace(/%40/g, '@')
+    .replace(/%24/g, '$')
+    .replace(/%2B/g, '+')
+    .replace(/!/g, '%21')
+    .replace(/\*/g, '%2A')
+    .replace(/'/g, '%27')
+    .replace(/\(/g, '%28')
+    .replace(/\)/g, '%29');
+}
+
+// encodePathSegment mirrors Go's url.URL path encoding ("encodePath" mode) for
+// one segment (characters between '/'). Go leaves alphanumerics, -_.~, and the
+// specific sub-delims $ & + , : ; = @ alone; it percent-encodes everything else
+// — importantly including ! ' ( ) * which encodeURIComponent passes through.
+// Keeping these in sync is required so wikiPage / wikiHeading / wikiLineRange
+// produce byte-identical target_uri across Go and TS SDKs for any legal
+// filename (including ones with ', (, ), !, *, space, #, ?, %, etc.).
+function encodePathSegment(seg: string): string {
+  return encodeURIComponent(seg)
+    // Un-escape what Go's encodePath passes through
+    .replace(/%24/g, '$')
+    .replace(/%26/g, '&')
+    .replace(/%2B/g, '+')
+    .replace(/%2C/g, ',')
+    .replace(/%3A/g, ':')
+    .replace(/%3B/g, ';')
+    .replace(/%3D/g, '=')
+    .replace(/%40/g, '@')
+    // Encode what Go escapes but encodeURIComponent leaves raw
+    .replace(/!/g, '%21')
+    .replace(/'/g, '%27')
+    .replace(/\(/g, '%28')
+    .replace(/\)/g, '%29')
+    .replace(/\*/g, '%2A');
+}
+
+function encodeWikiPath(path: string): string {
+  return path
+    .replace(/^\//, '')
+    .split('/')
+    .map(encodePathSegment)
+    .join('/');
+}
+
 export const COMMENT_TARGET = {
   task: (taskId: string) => `prll://${taskId}`,
   changeset: (csId: string, wikiId: string) => `prll://${csId}?wiki=${wikiId}`,
-  wikiPage: (wikiId: string, path: string) => `prll://${wikiId}/${path.replace(/^\//, '')}`,
+  wikiPage: (wikiId: string, path: string) => `prll://${wikiId}/${encodeWikiPath(path)}`,
+  // Hierarchy encoded as "::"-joined PathEscape segments with ':' → '%3A' so a
+  // literal ':' in a heading cannot be confused with the separator.
+  wikiHeading: (wikiId: string, path: string, rev: string, headingSegments: string[]) => {
+    const encoded = headingSegments.map(encodeHeadingSegment).join('::');
+    return `prll://${wikiId}/${encodeWikiPath(path)}?rev=${rev}#h=${encoded}`;
+  },
+  wikiLineRange: (wikiId: string, path: string, rev: string, lineStart: number, lineEnd: number) => {
+    const frag = lineStart === lineEnd ? `l=${lineStart}` : `l=${lineStart}-${lineEnd}`;
+    return `prll://${wikiId}/${encodeWikiPath(path)}?rev=${rev}#${frag}`;
+  },
 } as const;