@parall/sdk 1.56.1 → 1.56.2

package/dist/wiki-upload.js

@@ -0,0 +1,87 @@
+export function createWikiUploadFormData(params) {
+    const form = new FormData();
+    form.append('path', params.path);
+    form.append('file', params.file);
+    if (params.message)
+        form.append('message', params.message);
+    if (params.uploadId)
+        form.append('upload_id', params.uploadId);
+    if (params.conflict)
+        form.append('conflict', params.conflict);
+    if ('contentRoute' in params && params.contentRoute) {
+        form.append('content_route', params.contentRoute);
+    }
+    return form;
+}
+/** Send one multipart request. XHR is used only when a browser caller asks
+ * for upload progress; fetch remains the transport everywhere else. Auth
+ * refresh and API error decoding stay in ParallClient above this boundary. */
+export function sendMultipartRequest(options) {
+    if (options.onProgress && typeof XMLHttpRequest !== 'undefined') {
+        return multipartXHR(options, options.onProgress);
+    }
+    const timeoutSignal = AbortSignal.timeout(options.timeoutMs);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
+    return fetch(options.url, {
+        method: options.method,
+        headers: options.headers,
+        body: options.body,
+        signal,
+    });
+}
+function multipartXHR(options, onProgress) {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            options.signal?.removeEventListener('abort', abortFromSignal);
+            fn();
+        };
+        const abortFromSignal = () => xhr.abort();
+        xhr.open(options.method, options.url, true);
+        xhr.timeout = options.timeoutMs;
+        for (const [name, value] of Object.entries(options.headers)) {
+            xhr.setRequestHeader(name, value);
+        }
+        xhr.upload.onprogress = (event) => {
+            try {
+                onProgress(event.loaded, event.lengthComputable ? event.total : 0);
+            }
+            catch {
+                // Observer failures must not cancel an otherwise healthy upload.
+            }
+        };
+        xhr.onload = () => finish(() => {
+            const responseHeaders = new Headers();
+            for (const line of xhr
+                .getAllResponseHeaders()
+                .trim()
+                .split(/[\r\n]+/)) {
+                if (!line)
+                    continue;
+                const separator = line.indexOf(':');
+                if (separator > 0) {
+                    responseHeaders.append(line.slice(0, separator).trim(), line.slice(separator + 1).trim());
+                }
+            }
+            const responseBody = xhr.status === 204 || xhr.responseText === '' ? null : xhr.responseText;
+            resolve(new Response(responseBody, {
+                status: xhr.status,
+                statusText: xhr.statusText,
+                headers: responseHeaders,
+            }));
+        });
+        xhr.onerror = () => finish(() => reject(new TypeError('Network request failed')));
+        xhr.ontimeout = () => finish(() => reject(new DOMException('Request timed out', 'TimeoutError')));
+        xhr.onabort = () => finish(() => reject(new DOMException('Request aborted', 'AbortError')));
+        if (options.signal?.aborted) {
+            finish(() => reject(new DOMException('Request aborted', 'AbortError')));
+            return;
+        }
+        options.signal?.addEventListener('abort', abortFromSignal, { once: true });
+        xhr.send(options.body);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/sdk",
-  "version": "1.56.1",
+  "version": "1.56.2",
   "description": "TypeScript client SDK for Parall — REST + WebSocket client, shared types",
   "license": "MIT",
   "repository": {

package/src/client.ts

@@ -1,6 +1,14 @@
 import { type BrowserViewerRequestOptions, browserViewerRequestOptions } from './browser-viewer.js';
 import { API_BASE, ENDPOINTS, WIKI_BASE } from './constants.js';
 import { AttachmentClient } from './attachment-client.js';
+import {
+  createWikiUploadFormData,
+  sendMultipartRequest,
+  type WikiChangesetFileUploadParams,
+  type WikiFileUploadParams,
+  type WikiFileUploadResponse,
+} from './wiki-upload.js';
+import { normalizeWikiChangeset } from './wiki-changeset.js';
 import type {
   AddTeamMemberRequest,
   AgentClip,
@@ -94,6 +102,7 @@ import type {
   CreateCommentRequest,
   CreateExternalConnectionInput,
   CreateExternalTriggerInput,
+  CreatePersonalApiKeyRequest,
   CreateScheduleInput,
   CreateSetupIntentResponse,
   CreateTeamRequest,
@@ -176,6 +185,7 @@ import type {
   OutboundRefsRequest,
   OutboundRefsResponse,
   PaginatedResponse,
+  PersonalApiKey,
   PlatformConfigResponse,
   PlatformModelsResponse,
   PublishRegistryClipRequest,
@@ -262,7 +272,6 @@ import type {
   WikiCommit,
   WikiDiff,
   WikiFilePreviewUrlResponse,
-  WikiFileUploadResponse,
   WikiNodeSectionArtifact,
   WikiOperation,
   WikiOperationsResponse,
@@ -551,7 +560,7 @@ export class ParallClient extends AttachmentClient {
    * 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
+   * uploadWikiFile / uploadWikiFileToChangeset — wiki file 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.
    */
@@ -560,6 +569,11 @@ export class ParallClient extends AttachmentClient {
     path: string,
     body: FormData,
     retried = false,
+    opts?: {
+      signal?: AbortSignal;
+      onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+      timeoutMs?: number;
+    },
   ): Promise<T> {
     if (!retried) {
       await this.ensureFreshToken(path);
@@ -568,13 +582,17 @@ export class ParallClient extends AttachmentClient {
     const { 'Content-Type': _drop, ...headers } = this.buildHeaders(path);
     void _drop;
 
+    const timeoutMs = opts?.timeoutMs ?? 5 * 60 * 1000;
     let res: Response;
     try {
-      res = await fetch(`${this.baseUrlFor(path)}${path}`, {
+      res = await sendMultipartRequest({
         method,
+        url: `${this.baseUrlFor(path)}${path}`,
         headers,
         body,
-        signal: AbortSignal.timeout(5 * 60 * 1000),
+        timeoutMs,
+        signal: opts?.signal,
+        onProgress: opts?.onProgress,
       });
     } catch (err) {
       throw ParallClient.normalizeFetchError(err);
@@ -586,7 +604,7 @@ export class ParallClient extends AttachmentClient {
       if (!retried && !isAuthPath && this.getRefreshToken) {
         const refreshed = await this.tryRefresh();
         if (refreshed) {
-          return this.multipartRequest<T>(method, path, body, true);
+          return this.multipartRequest<T>(method, path, body, true, opts);
         }
       }
       if (this.onTokenExpired && !isAuthPath) {
@@ -687,6 +705,22 @@ export class ParallClient extends AttachmentClient {
     return this.request('DELETE', ENDPOINTS.USER_AVATAR);
   }
 
+  // ---- Personal API keys (org-scoped; JWT session required) ----
+
+  /** Mints an org-scoped personal API key. The plaintext is returned once and never again. */
+  async createPersonalApiKey(req: CreatePersonalApiKeyRequest): Promise<ApiKey> {
+    return this.request('POST', ENDPOINTS.PERSONAL_API_KEYS, req);
+  }
+
+  async listPersonalApiKeys(): Promise<PersonalApiKey[]> {
+    const res = await this.request<{ data: PersonalApiKey[] }>('GET', ENDPOINTS.PERSONAL_API_KEYS);
+    return res.data;
+  }
+
+  async revokePersonalApiKey(keyId: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.PERSONAL_API_KEY(keyId));
+  }
+
   async uploadAgentAvatar(
     orgId: string,
     agentId: string,
@@ -2923,39 +2957,38 @@ export class ParallClient extends AttachmentClient {
   async uploadWikiFile(
     orgId: string,
     wikiId: string,
-    params: { path: string; file: Blob; message?: string },
+    params: WikiFileUploadParams,
   ): Promise<WikiFileUploadResponse> {
     // `POST /uploads` always writes to the wiki's default branch — the
-    // backend's parseUpload silently drops any `parent_ref` field, so
+    // backend's parseUpload does not accept a `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);
+    const fd = createWikiUploadFormData(params);
+    return this.multipartRequest('POST', ENDPOINTS.WIKI_UPLOADS(orgId, wikiId), fd, false, {
+      signal: params.signal,
+      onProgress: params.onProgress,
+    });
   }
 
   /**
-   * 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.
+   * Upload a file into a changeset's feature branch (read scope +
+   * author-only). The default remains binary-only; contentRoute `auto`
+   * opts into reviewable text for the Web library upload flow. On merge the
+   * branch contents squash into the default branch.
    */
   async uploadWikiFileToChangeset(
     orgId: string,
     wikiId: string,
     changesetId: string,
-    params: { path: string; file: Blob; message?: string },
+    params: WikiChangesetFileUploadParams,
   ): Promise<WikiFileUploadResponse> {
-    const fd = new FormData();
-    fd.append('path', params.path);
-    fd.append('file', params.file);
-    if (params.message) fd.append('message', params.message);
+    const fd = createWikiUploadFormData(params);
     return this.multipartRequest(
       'POST',
       ENDPOINTS.WIKI_CHANGESET_FILES(orgId, wikiId, changesetId),
       fd,
+      false,
+      { signal: params.signal, onProgress: params.onProgress },
     );
   }
 
@@ -4405,14 +4438,6 @@ export class ParallClient extends AttachmentClient {
   }
 }
 
-function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {
-  return {
-    ...changeset,
-    changed_paths: changeset.changed_paths ?? [],
-    file_changes: changeset.file_changes ?? [],
-  };
-}
-
 export class ApiError extends Error {
   extras?: Record<string, unknown>;
   /** Retry-After delta seconds when the server supplies one. */

package/src/constants.ts

@@ -361,6 +361,8 @@ export const ENDPOINTS = {
   // Users
   USERS_ME: `${API_BASE}/users/me`,
   USER_AVATAR: `${API_BASE}/users/me/avatar`,
+  PERSONAL_API_KEYS: `${API_BASE}/users/me/api-keys`,
+  PERSONAL_API_KEY: (keyId: string) => `${API_BASE}/users/me/api-keys/${keyId}`,
   USER: (id: string) => `${API_BASE}/users/${id}`,
 
   // WebSocket ticket

package/src/index.ts

@@ -7,6 +7,12 @@ export * from './subject.js';
 export * from './task-label-types.js';
 export * from './types.js';
 export * from './wechat-types.js';
+export type {
+  WikiChangesetFileUploadParams,
+  WikiFileUploadParams,
+  WikiFileUploadResponse,
+  WikiStoredAs,
+} from './wiki-upload.js';
 export type {
   ParallWsOptions,
   WsClientEventMap,

package/src/types.ts

@@ -710,11 +710,35 @@ export interface CreateInvitationRequest {
   role?: OrgMemberRole;
 }
 
-// Response of agent API key create/regenerate. The plaintext `api_key` is
-// returned exactly once at mint time and can never be fetched again.
+// Response of API key create/regenerate (agent keys and personal keys alike).
+// The plaintext `api_key` is returned exactly once at mint time and can never
+// be fetched again. Personal keys additionally echo the org they are bound to.
 export interface ApiKey {
   id: string;
   api_key: string;
+  org_id?: string;
+}
+
+// A personal API key row as listed by GET /users/me/api-keys. Personal keys
+// are org-scoped ("org_full"): the user's permissions inside org_id only.
+// Managed Clip keys have their own surface; the key hash never leaves the
+// server.
+export interface PersonalApiKey {
+  id: string;
+  user_id: string;
+  name?: string;
+  org_id: string;
+  last_used_at?: string;
+  expires_at?: string;
+  created_at: string;
+}
+
+export interface CreatePersonalApiKeyRequest {
+  name?: string;
+  /** The org this key is bound to; the caller must be a member. */
+  org_id: string;
+  /** RFC3339; must be in the future. Omit for a non-expiring key. */
+  expires_at?: string;
 }
 
 export interface CreateAgentResponse {
@@ -2391,6 +2415,10 @@ export interface WikiChangeset {
   title: string;
   message: string | null;
   status: WikiChangesetStatus;
+  /** Present on current servers; optional keeps older mocked/client data source-compatible. */
+  head_branch?: string | null;
+  /** Present on current servers; optional keeps older mocked/client data source-compatible. */
+  base_commit?: string | null;
   merge_commit: string | null;
   file_changes: WikiFileChange[];
   changed_paths: string[];
@@ -2658,6 +2686,8 @@ export interface CreateWikiChangesetRequest {
   title: string;
   message?: string;
   file_changes: WikiFileChangeInput[];
+  /** Omit for the server default (`proposed`); pass `draft` for staged uploads. */
+  status?: 'draft' | 'proposed';
   source_chat_id?: string;
   source_message_id?: string;
   source_run_id?: string;
@@ -2667,6 +2697,8 @@ export interface UpdateWikiChangesetRequest {
   title?: string;
   message?: string;
   file_changes?: WikiFileChangeInput[];
+  /** Author-settable transitions currently include `proposed` and `closed`. */
+  status?: 'proposed' | 'closed';
   /**
    * When true, file_changes define the changeset's FULL content: the server
    * resets the feature branch to the current default-branch HEAD before
@@ -2832,17 +2864,6 @@ export interface WikiBlob {
   signed_url_expires_at?: string;
 }
 
-export type WikiStoredAs = 'git_blob' | 'lfs_pointer';
-
-/** Response from POST /uploads or POST /changesets/{csId}/files. */
-export interface WikiFileUploadResponse {
-  path: string;
-  size: number;
-  stored_as: WikiStoredAs;
-  commit_sha: string;
-  content_sha: string;
-}
-
 /** Response from POST /files/preview-url — short-lived signed URL for
  * browser `<img>`/`<video>`/`<iframe>` src. TTL is 5 minutes by default. */
 export interface WikiFilePreviewUrlResponse {
@@ -4161,6 +4182,8 @@ export interface ResolvedRef {
   type: string;
   exists: boolean;
   restricted?: boolean;
+  /** The target could not be resolved because a dependency failed temporarily. */
+  unavailable?: boolean;
 
   // User fields
   display_name?: string;

package/src/wiki-changeset.ts

@@ -0,0 +1,13 @@
+import type { WikiChangeset } from './types.js';
+
+/** Normalize fields that older wiki-service responses may omit. */
+export function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {
+  return {
+    ...changeset,
+    head_branch: changeset.head_branch ?? null,
+    base_commit: changeset.base_commit ?? null,
+    merge_commit: changeset.merge_commit ?? null,
+    changed_paths: changeset.changed_paths ?? [],
+    file_changes: changeset.file_changes ?? [],
+  };
+}

package/src/wiki-upload.ts

@@ -0,0 +1,142 @@
+interface WikiFileUploadParamsBase {
+  path: string;
+  file: Blob;
+  message?: string;
+  /** Stable per-file retry key; replays return the original successful path. */
+  uploadId?: string;
+  /** Preserve the legacy 409 by default, or atomically choose `name (N).ext`. */
+  conflict?: 'error' | 'rename';
+  signal?: AbortSignal;
+  onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+}
+
+export type WikiStoredAs = 'git_blob' | 'lfs_pointer';
+
+/** Response from POST /uploads or POST /changesets/{csId}/files. */
+export interface WikiFileUploadResponse {
+  path: string;
+  size: number;
+  stored_as: WikiStoredAs;
+  commit_sha: string;
+  content_sha: string;
+}
+
+/** Parameters for the maintain-only direct upload endpoint. */
+export type WikiFileUploadParams = WikiFileUploadParamsBase;
+
+/** Parameters for a changeset-scoped multipart upload. */
+export interface WikiChangesetFileUploadParams extends WikiFileUploadParamsBase {
+  /** `auto` accepts reviewable text as a Git blob on the changeset branch. */
+  contentRoute?: 'binary' | 'auto';
+}
+
+export function createWikiUploadFormData(
+  params: WikiFileUploadParams | WikiChangesetFileUploadParams,
+): FormData {
+  const form = new FormData();
+  form.append('path', params.path);
+  form.append('file', params.file);
+  if (params.message) form.append('message', params.message);
+  if (params.uploadId) form.append('upload_id', params.uploadId);
+  if (params.conflict) form.append('conflict', params.conflict);
+  if ('contentRoute' in params && params.contentRoute) {
+    form.append('content_route', params.contentRoute);
+  }
+  return form;
+}
+
+interface MultipartTransportOptions {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body: FormData;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+}
+
+/** Send one multipart request. XHR is used only when a browser caller asks
+ * for upload progress; fetch remains the transport everywhere else. Auth
+ * refresh and API error decoding stay in ParallClient above this boundary. */
+export function sendMultipartRequest(options: MultipartTransportOptions): Promise<Response> {
+  if (options.onProgress && typeof XMLHttpRequest !== 'undefined') {
+    return multipartXHR(options, options.onProgress);
+  }
+  const timeoutSignal = AbortSignal.timeout(options.timeoutMs);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
+  return fetch(options.url, {
+    method: options.method,
+    headers: options.headers,
+    body: options.body,
+    signal,
+  });
+}
+
+function multipartXHR(
+  options: MultipartTransportOptions,
+  onProgress: (uploadedBytes: number, totalBytes: number) => void,
+): Promise<Response> {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    let settled = false;
+
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      options.signal?.removeEventListener('abort', abortFromSignal);
+      fn();
+    };
+    const abortFromSignal = () => xhr.abort();
+
+    xhr.open(options.method, options.url, true);
+    xhr.timeout = options.timeoutMs;
+    for (const [name, value] of Object.entries(options.headers)) {
+      xhr.setRequestHeader(name, value);
+    }
+
+    xhr.upload.onprogress = (event) => {
+      try {
+        onProgress(event.loaded, event.lengthComputable ? event.total : 0);
+      } catch {
+        // Observer failures must not cancel an otherwise healthy upload.
+      }
+    };
+    xhr.onload = () =>
+      finish(() => {
+        const responseHeaders = new Headers();
+        for (const line of xhr
+          .getAllResponseHeaders()
+          .trim()
+          .split(/[\r\n]+/)) {
+          if (!line) continue;
+          const separator = line.indexOf(':');
+          if (separator > 0) {
+            responseHeaders.append(
+              line.slice(0, separator).trim(),
+              line.slice(separator + 1).trim(),
+            );
+          }
+        }
+        const responseBody =
+          xhr.status === 204 || xhr.responseText === '' ? null : xhr.responseText;
+        resolve(
+          new Response(responseBody, {
+            status: xhr.status,
+            statusText: xhr.statusText,
+            headers: responseHeaders,
+          }),
+        );
+      });
+    xhr.onerror = () => finish(() => reject(new TypeError('Network request failed')));
+    xhr.ontimeout = () =>
+      finish(() => reject(new DOMException('Request timed out', 'TimeoutError')));
+    xhr.onabort = () => finish(() => reject(new DOMException('Request aborted', 'AbortError')));
+
+    if (options.signal?.aborted) {
+      finish(() => reject(new DOMException('Request aborted', 'AbortError')));
+      return;
+    }
+    options.signal?.addEventListener('abort', abortFromSignal, { once: true });
+    xhr.send(options.body);
+  });
+}