@omelhorsite/sdk 0.4.5 → 0.5.0

package/README.md

@@ -163,9 +163,13 @@ const nodes = await oms.storage.upload(
 );
 ```
 
-Progress arrives per finished file or part, never per byte. A file rejected on
-its own (quota, name collision) does not throw; it is missing from the
-returned array, so compare lengths when partial success matters.
+In a browser or on React Native, progress is reported byte by byte (the bytes
+travel through `XMLHttpRequest`); elsewhere it arrives per finished file or
+part. The same goes for every other upload: pass `onUploadProgress` in the
+options of `tools.*.create`, `library.books.create` or
+`chests.entries.createWithUpload`. A file rejected on its own (quota, name
+collision) does not throw; it is missing from the returned array, so compare
+lengths when partial success matters.
 
 ## Long jobs: `create` / `get`, and `run`
 

package/dist/index.js

@@ -344,6 +344,87 @@ async function collect(first, limit = Number.POSITIVE_INFINITY) {
   return out;
 }
 
+// src/internal/xhr.ts
+function xhrAvailable() {
+  return typeof XMLHttpRequest === "function";
+}
+function xhrFetch(onUploadProgress) {
+  return (input, init) => new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest;
+    xhr.open(init?.method ?? "GET", input, true);
+    xhr.responseType = "arraybuffer";
+    xhr.withCredentials = init?.credentials === "include";
+    applyHeaders(xhr, init?.headers);
+    const signal = init?.signal ?? undefined;
+    const onAbort = () => xhr.abort();
+    if (signal) {
+      if (signal.aborted) {
+        reject(abortError());
+        return;
+      }
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    const settle = () => signal?.removeEventListener("abort", onAbort);
+    xhr.upload.onprogress = (event) => {
+      onUploadProgress({
+        phase: "upload",
+        loaded: event.loaded,
+        total: event.lengthComputable ? event.total : undefined
+      });
+    };
+    xhr.onload = () => {
+      settle();
+      if (xhr.status === 0) {
+        reject(new TypeError("Network request failed"));
+        return;
+      }
+      resolve(toResponse(xhr));
+    };
+    xhr.onerror = () => {
+      settle();
+      reject(new TypeError("Network request failed"));
+    };
+    xhr.onabort = () => {
+      settle();
+      reject(abortError());
+    };
+    xhr.send(init?.body ?? null);
+  });
+}
+function applyHeaders(xhr, headers) {
+  if (!headers)
+    return;
+  if (headers instanceof Headers) {
+    headers.forEach((value, key) => xhr.setRequestHeader(key, value));
+  } else if (Array.isArray(headers)) {
+    for (const [key, value] of headers)
+      xhr.setRequestHeader(key, value);
+  } else {
+    for (const [key, value] of Object.entries(headers))
+      xhr.setRequestHeader(key, value);
+  }
+}
+function toResponse(xhr) {
+  const headers = new Headers;
+  for (const line of xhr.getAllResponseHeaders().split(/\r?\n/)) {
+    const separator = line.indexOf(":");
+    if (separator <= 0)
+      continue;
+    headers.append(line.slice(0, separator).trim(), line.slice(separator + 1).trim());
+  }
+  const bodyless = xhr.status === 204 || xhr.status === 205 || xhr.status === 304;
+  return new Response(bodyless ? null : xhr.response, {
+    status: xhr.status,
+    statusText: xhr.statusText,
+    headers
+  });
+}
+function abortError() {
+  const error = new Error("The operation was aborted.");
+  error.name = "AbortError";
+  return error;
+}
+
 // src/http.ts
 var DEFAULT_BASE_URL = "https://backend.omelhorsite.pt";
 function transportCapabilities() {
@@ -382,6 +463,7 @@ function supportsNativeFormDataFiles() {
 class ApiClient {
   baseUrl;
   fetchImpl;
+  customFetch;
   tokens;
   sessionCookie;
   baseHeaders;
@@ -394,6 +476,7 @@ class ApiClient {
       throw new OmsNetworkError("No fetch implementation available. Pass one to the Oms constructor: new Oms({ fetch }).");
     }
     this.fetchImpl = (input, init) => injected(input, init);
+    this.customFetch = options.fetch !== undefined;
     if (options.sessionCookie && options.tokens) {
       throw new TypeError("Pass either `sessionCookie` or a token, not both: two credentials on one request means the server decides which identity wins, and the caller cannot tell which one it got.");
     }
@@ -471,6 +554,15 @@ class ApiClient {
       size: blob.size
     };
   }
+  transportFor(onUploadProgress) {
+    if (onUploadProgress && !this.customFetch && xhrAvailable())
+      return xhrFetch(onUploadProgress);
+    return this.fetchImpl;
+  }
+  async patchForm(path, fields, options = {}) {
+    const form = await buildFormData(fields);
+    return this.requestJson("PATCH", path, { ...options, body: form, isFormData: true });
+  }
   url(path, query) {
     const suffix = path.startsWith("/") ? path : `/${path}`;
     const encoded = query ? encodeQuery(query) : "";
@@ -493,7 +585,7 @@ class ApiClient {
       const deadline = createDeadline(timeoutMs, options.signal);
       let response;
       try {
-        response = await this.fetchImpl(url, await this.buildInit(method, options, deadline.signal));
+        response = await this.transportFor(options.onUploadProgress)(url, await this.buildInit(method, options, deadline.signal));
       } catch (thrown) {
         deadline.dispose();
         const failure = classifyFetchFailure(thrown, { method, url, attempts: attempt, timeoutMs, options });
@@ -9532,11 +9624,13 @@ class StorageRateGate {
 class UploadManager extends Resource {
   gate;
   transport;
+  ownTransport;
   md5;
   constructor(http, options = {}) {
     super(http);
     this.gate = new StorageRateGate(FS_UPLOAD_RATE_LIMIT);
     this.transport = options.fetch ?? objectStoreFetch(http);
+    this.ownTransport = options.fetch === undefined;
     this.md5 = options.md5 ?? md5Base64;
   }
   async upload(input, options = {}) {
@@ -9557,12 +9651,23 @@ class UploadManager extends Resource {
       };
     }));
     const total = prepared.reduce((sum, entry) => sum + entry.blob.size, 0);
-    let loaded = 0;
-    const report = (delta) => {
-      loaded += delta;
-      options.onProgress?.({ phase: "upload", loaded, total });
+    let completed = 0;
+    const inFlight = new Map;
+    const emit = () => {
+      let extra = 0;
+      inFlight.forEach((bytes) => extra += bytes);
+      options.onProgress?.({ phase: "upload", loaded: completed + extra, total });
+    };
+    const fileProgress = (clientId, size) => (progress) => {
+      inFlight.set(clientId, Math.min(progress.loaded, size));
+      emit();
     };
-    report(0);
+    const fileDone = (clientId, size) => {
+      inFlight.delete(clientId);
+      completed += size;
+      emit();
+    };
+    emit();
     const { onProgress: _runProgress, ...transfer } = options;
     const batchSize = Math.min(MAX_BATCH, Math.max(1, Math.trunc(input.batchSize ?? DEFAULT_BATCH_SIZE)));
     const concurrency = Math.max(1, Math.trunc(input.concurrency ?? DEFAULT_UPLOAD_CONCURRENCY));
@@ -9593,19 +9698,24 @@ class UploadManager extends Resource {
             if (plan.strategy === "multipart") {
               await this.uploadMultipart(plan.fs_node_id, entry.blob, {
                 ...transfer,
-                onPart: (bytes) => report(bytes),
+                onProgress: fileProgress(entry.clientId, entry.blob.size),
                 onSession: (token) => open.set(plan.fs_node_id, token)
               });
               open.delete(plan.fs_node_id);
+              fileDone(entry.clientId, entry.blob.size);
             } else {
               if (!plan.upload) {
                 throw new OmsError(`The server planned a direct upload for "${entry.filename}" but sent no presigned URL.`, "api_error");
               }
-              await this.putDirect(plan.upload, entry.blob, transfer);
+              await this.putDirect(plan.upload, entry.blob, {
+                ...transfer,
+                onProgress: fileProgress(entry.clientId, entry.blob.size)
+              });
               attachments.push({ fs_node_id: plan.fs_node_id, blob_signed_id: plan.upload.blob_signed_id });
-              report(entry.blob.size);
+              fileDone(entry.clientId, entry.blob.size);
             }
           } catch (thrown) {
+            inFlight.delete(entry.clientId);
             failed.set(entry.clientId, {
               client_id: entry.clientId,
               code: thrown instanceof OmsError ? thrown.code : "transfer_failed",
@@ -9666,8 +9776,18 @@ class UploadManager extends Resource {
     };
   }
   async putDirect(target, body, options = {}) {
-    const etag = await this.putBytes(target.url, target.headers, body, options);
-    options.onProgress?.({ phase: "upload", loaded: body.size, total: body.size });
+    const { onProgress, ...request } = options;
+    const size = body.size;
+    const etag = await this.putBytes(target.url, target.headers, body, {
+      ...request,
+      ...onProgress ? {
+        onUploadProgress: (progress) => {
+          if (progress.loaded < size)
+            onProgress({ phase: "upload", loaded: progress.loaded, total: size });
+        }
+      } : {}
+    });
+    onProgress?.({ phase: "upload", loaded: size, total: size });
     return etag;
   }
   async attachBlobs(attachments, options = {}) {
@@ -9728,7 +9848,13 @@ class UploadManager extends Resource {
     let loaded = 0;
     for (const partNumber of done.keys())
       loaded += bytesOfPart(partNumber);
-    options.onProgress?.({ phase: "upload", loaded, total: body.size });
+    const inFlight = new Map;
+    const report = () => {
+      let extra = 0;
+      inFlight.forEach((bytes) => extra += bytes);
+      options.onProgress?.({ phase: "upload", loaded: loaded + extra, total: body.size });
+    };
+    report();
     if (partCount > MAX_PARTS) {
       throw new OmsError(`storage: ${body.size} bytes needs ${partCount} parts of ${partSize}, over the server's limit of ${MAX_PARTS}.`, "invalid_request");
     }
@@ -9749,7 +9875,14 @@ class UploadManager extends Resource {
           throw new OmsError(`storage: the server presigned no URL for part ${partNumber}.`, "api_error");
         const from = (partNumber - 1) * partSize;
         const chunk = body.slice(from, Math.min(from + partSize, body.size));
-        const etag = await this.putBytes(url, {}, chunk, options);
+        const etag = await this.putBytes(url, {}, chunk, {
+          ...options,
+          onUploadProgress: (progress) => {
+            inFlight.set(partNumber, Math.min(progress.loaded, Math.max(0, chunk.size - 1)));
+            report();
+          }
+        });
+        inFlight.delete(partNumber);
         if (!etag) {
           throw new OmsError("storage: the object store did not expose the part ETag. In a browser this means the bucket's CORS policy is missing ETag in Access-Control-Expose-Headers.", "unsupported");
         }
@@ -9757,7 +9890,7 @@ class UploadManager extends Resource {
         done.set(partNumber, part);
         options.onPart?.(chunk.size, part);
         loaded += chunk.size;
-        options.onProgress?.({ phase: "upload", loaded, total: body.size });
+        report();
       });
     }
     return this.multipartComplete(fsNodeId, { uploadToken, parts: [...done.values()] }, options);
@@ -9765,10 +9898,11 @@ class UploadManager extends Resource {
   async putBytes(url, headers, body, options) {
     const retry = options.retry === false ? false : resolveRetry(options.retry ?? { maxAttempts: 4 });
     const maxAttempts = retry === false ? 1 : Math.max(1, retry.maxAttempts);
+    const transport = this.ownTransport && options.onUploadProgress ? this.http.transportFor(options.onUploadProgress) : this.transport;
     for (let attempt = 1;; attempt += 1) {
       let response;
       try {
-        response = await this.transport(url, {
+        response = await transport(url, {
           method: "PUT",
           headers,
           body,
@@ -10401,6 +10535,41 @@ class AdminShortLinksNamespace extends Resource {
   }
 }
 
+// src/resources/admin/users.ts
+class AdminUsersNamespace extends Resource {
+  async update(id, input, options = {}) {
+    const path = `/users/${encodeURIComponent(id)}`;
+    const body = adminUpdateBody(input);
+    if (input.picture === undefined)
+      return this.http.patch(path, body, options);
+    return this.http.patchForm(path, { ...body, picture: input.picture }, options);
+  }
+}
+function adminUpdateBody(input) {
+  const body = {};
+  const set = (key, value) => {
+    if (value !== undefined)
+      body[key] = value;
+  };
+  set("handle", input.handle);
+  set("name", input.name);
+  set("bio", input.bio);
+  set("country_code", input.countryCode);
+  set("email_is_public", input.emailIsPublic);
+  set("gender_is_public", input.genderIsPublic);
+  set("gender", input.gender);
+  set("library_public", input.libraryPublic);
+  set("library_name", input.libraryName);
+  set("library_description", input.libraryDescription);
+  set("share_listening", input.shareListening);
+  set("email", input.email);
+  set("group", input.group);
+  if (input.password)
+    set("password", input.password);
+  set("allowed_to_use_spotify", input.allowedToUseSpotify);
+  return body;
+}
+
 // src/resources/admin/vocalSeparations.ts
 var ADMIN_VOCAL_SEPARATION_FILTER_COLUMNS = Object.freeze([
   "id",
@@ -10486,6 +10655,7 @@ class AdminNamespace extends Resource {
   chests;
   notepads;
   eventAlerts;
+  users;
   constructor(http) {
     super(http);
     this.myApplications = new MyOauthApplicationsNamespace(http);
@@ -10499,6 +10669,7 @@ class AdminNamespace extends Resource {
     this.chests = new AdminChestsNamespace(http);
     this.notepads = new AdminNotepadsNamespace(http);
     this.eventAlerts = new AdminEventAlertsNamespace(http);
+    this.users = new AdminUsersNamespace(http);
   }
 }
 
@@ -10773,13 +10944,15 @@ class ChestEntriesNamespace extends Resource {
   async createWithUpload(input, options = {}) {
     const { blob, filename } = await readFileInput(input.file);
     const name = input.name ?? filename;
+    const { onReserved, ...operation } = options;
     const entry = await this.http.post("/chest_entries", {
       chest_id: input.chestId,
       kind: "file",
       name,
       size: blob.size,
       chest_token: input.chestToken
-    }, { retry: false, ...options });
+    }, { retry: false, ...operation });
+    onReserved?.(entry);
     try {
       const checksum = await md5Base64(blob);
       const { signed_url: target } = await this.http.post(`/chest_entries/${encodeURIComponent(entry.id)}/attachment_signed_url`, { checksum }, { retry: false, ...options });
@@ -14845,14 +15018,27 @@ class CaptionsNamespace extends Resource {
     for (const offset of offsets)
       if (done.has(offset))
         loaded += Math.min(partSize, total - offset);
-    onProgress?.({ phase: "upload", loaded, total });
+    const inFlight = new Map;
+    const report = () => {
+      let extra = 0;
+      inFlight.forEach((bytes) => extra += bytes);
+      onProgress?.({ phase: "upload", loaded: loaded + extra, total });
+    };
+    report();
     const concurrency = Math.max(1, Math.trunc(input.concurrency ?? CAPTION_UPLOAD_CONCURRENCY));
     await runCaptionParts(pending, concurrency, async (offset) => {
       const chunk = blob.slice(offset, Math.min(offset + partSize, total));
-      await this.uploadPart(session, offset, chunk, request);
+      await this.uploadPart(session, offset, chunk, {
+        ...request,
+        onUploadProgress: (progress) => {
+          inFlight.set(offset, Math.min(progress.loaded, Math.max(0, chunk.size - 1)));
+          report();
+        }
+      });
+      inFlight.delete(offset);
       onPart?.(offset, chunk.size);
       loaded += chunk.size;
-      onProgress?.({ phase: "upload", loaded, total });
+      report();
     });
     return this.finishUpload(session, request);
   }
@@ -15819,6 +16005,7 @@ export {
   ApiClient,
   AnalysisNamespace,
   AdminVocalSeparationsNamespace,
+  AdminUsersNamespace,
   AdminShortLinksNamespace,
   AdminQuotasNamespace,
   AdminOauthApplicationsNamespace,

package/dist/types/http.d.ts

@@ -23,7 +23,7 @@
  * polyfill after the SDK is imported, and in RN the fetch implementation is
  * swapped by libraries often enough that a cached answer goes stale.
  */
-import { type FetchLike, type FileInput, type FileOutput, type NativeFile, type QueryParams, type RequestOptions, type ResolvedRetry, type RetryOptions } from "./types";
+import { type FetchLike, type FileInput, type FileOutput, type NativeFile, type ProgressCallback, type QueryParams, type RequestOptions, type ResolvedRetry, type RetryOptions } from "./types";
 /** Production API root. Override only for a local backend or a test double. */
 export declare const DEFAULT_BASE_URL = "https://backend.omelhorsite.pt";
 /**
@@ -94,11 +94,11 @@ export declare function supportsResponseStreaming(): boolean;
  * True in a browser and in React Native (RN's networking is XHR underneath and
  * `xhr.upload.onprogress` fires there); false in a Worker-class isolate and in
  * Bun's server runtime. See {@link Progress} for the whole argument and
- * `UploadManagerOptions.fetch` for the recipe - this only reports whether that
- * recipe can be used here, so a UI can decide between a real bar and a
- * per-file tick.
+ * `RequestOptions.onUploadProgress`; this reports whether that can work here,
+ * so a UI can decide between a real bar and a per-file tick.
  *
- * The SDK never uses XHR itself. It cannot: the core has to load in an isolate.
+ * A request that asks for `onUploadProgress` travels through it when it is
+ * present; nothing else in the SDK touches it.
  */
 export declare function supportsUploadProgress(): boolean;
 /**
@@ -274,6 +274,7 @@ export declare class ApiClient {
     /** API root with no trailing slash. */
     readonly baseUrl: string;
     private readonly fetchImpl;
+    private readonly customFetch;
     private readonly tokens;
     private readonly sessionCookie;
     private readonly baseHeaders;
@@ -383,6 +384,14 @@ export declare class ApiClient {
      * downloader instead of pulling it through JavaScript.
      */
     download(path: string, options?: GetOptions): Promise<FileOutput>;
+    /**
+     * The transport a request should travel on: the client's fetch, or an
+     * `XMLHttpRequest` when upload progress was asked for and the runtime has
+     * one. A custom `fetch` is never bypassed.
+     */
+    transportFor(onUploadProgress?: ProgressCallback): FetchLike;
+    /** `PATCH` with a multipart body, parsed as JSON. */
+    patchForm<T>(path: string, fields: FormFields, options?: GetOptions): Promise<T>;
     /** Absolute URL for a path, with the query string applied. */
     url(path: string, query?: QueryParams): string;
     private requestJson;

package/dist/types/internal/xhr.d.ts

@@ -0,0 +1,6 @@
+/** A fetch-shaped XMLHttpRequest, for the one thing fetch cannot do: report upload progress. */
+import type { FetchLike, ProgressCallback } from "../types";
+/** Whether this runtime can send a request through `XMLHttpRequest`. */
+export declare function xhrAvailable(): boolean;
+/** A {@link FetchLike} over `XMLHttpRequest` that reports the bytes sent to `onUploadProgress`. */
+export declare function xhrFetch(onUploadProgress: ProgressCallback): FetchLike;

package/dist/types/resources/admin/index.d.ts

@@ -10,6 +10,7 @@ import { AdminNotepadsNamespace } from "./notepads";
 import { AdminOauthApplicationsNamespace } from "./oauthApplications";
 import { AdminQuotasNamespace } from "./quotas";
 import { AdminShortLinksNamespace } from "./shortLinks";
+import { AdminUsersNamespace } from "./users";
 import { AdminVocalSeparationsNamespace } from "./vocalSeparations";
 export * from "./authorizedApplications";
 export * from "./chests";
@@ -22,6 +23,7 @@ export * from "./oauthApplications";
 export * from "./quotas";
 export * from "./shortLinks";
 export * from "./types";
+export * from "./users";
 export * from "./vocalSeparations";
 /**
  * The `admin` namespace, reachable as `oms.admin`.
@@ -73,5 +75,7 @@ export declare class AdminNamespace extends Resource {
     readonly notepads: AdminNotepadsNamespace;
     /** The Discord alert catalogue. **Administrators only.** */
     readonly eventAlerts: AdminEventAlertsNamespace;
+    /** Any account, admin-only fields included. */
+    readonly users: AdminUsersNamespace;
     constructor(http: ConstructorParameters<typeof Resource>[0]);
 }

package/dist/types/resources/admin/users.d.ts

@@ -0,0 +1,41 @@
+/** `oms.admin.users`: editing any user's account. Administrators only. */
+import { Resource } from "../../http";
+import type { FileInput, Id, NativeFile, RequestOptions } from "../../types";
+import type { User } from "../account";
+/**
+ * Fields an administrator may change on any account. Everything is optional;
+ * omitted fields are left alone, `null` clears the nullable ones.
+ *
+ * `password` is only written when given and non-empty. `picture` makes the
+ * request multipart; the image is re-encoded server-side and capped at 1024px.
+ */
+export interface AdminUpdateUserInput {
+    readonly handle?: string;
+    readonly name?: string;
+    readonly bio?: string | null;
+    readonly countryCode?: string;
+    readonly emailIsPublic?: boolean;
+    readonly genderIsPublic?: boolean;
+    readonly gender?: string;
+    readonly libraryPublic?: boolean;
+    readonly libraryName?: string | null;
+    readonly libraryDescription?: string | null;
+    readonly shareListening?: boolean;
+    readonly email?: string;
+    /** Privilege group, e.g. `"administrator"`. */
+    readonly group?: string;
+    readonly password?: string;
+    readonly allowedToUseSpotify?: boolean;
+    readonly picture?: FileInput | NativeFile;
+}
+export declare class AdminUsersNamespace extends Resource {
+    /**
+     * `PATCH /users/:id` - edits any account, admin-only fields included.
+     *
+     * Answers the updated {@link User} as an administrator sees it.
+     *
+     * @throws {OmsAuthError} 401 for a non-administrator editing somebody else.
+     * @throws {OmsApiError} 400 with the validation messages.
+     */
+    update(id: Id, input: AdminUpdateUserInput, options?: RequestOptions): Promise<User>;
+}

package/dist/types/resources/chests.d.ts

@@ -137,7 +137,9 @@ export declare class ChestEntriesNamespace extends Resource {
      * The file is buffered whole: the MD5 the presigned signature covers has to
      * be computed over all of it.
      */
-    createWithUpload(input: CreateChestFileInput, options?: OperationOptions): Promise<ChestEntry>;
+    createWithUpload(input: CreateChestFileInput, options?: OperationOptions & {
+        readonly onReserved?: (entry: ChestEntry) => void;
+    }): Promise<ChestEntry>;
     /**
      * `GET /chest_entries/:id/data` - the entry's bytes.
      *

package/dist/types/resources/storage/upload.d.ts

@@ -345,6 +345,7 @@ export declare class UploadManager extends Resource {
     /** Paces every control-plane call against the 300-a-minute upload limit. */
     readonly gate: StorageRateGate;
     private readonly transport;
+    private readonly ownTransport;
     private readonly md5;
     constructor(http: ApiClient, options?: UploadManagerOptions);
     /**

package/dist/types/types.d.ts

@@ -231,6 +231,15 @@ export interface RequestOptions {
     readonly timeoutMs?: number;
     /** Extra request headers. Merged over the client's, under `Authorization`. */
     readonly headers?: Record<string, string>;
+    /**
+     * Called with the bytes sent so far while the request body goes up.
+     *
+     * Honoured where `XMLHttpRequest` exists (browsers, React Native) and the
+     * client was built without a custom `fetch`, which is when the request is
+     * sent through it instead. Elsewhere the request goes out as usual and this
+     * is never called.
+     */
+    readonly onUploadProgress?: ProgressCallback;
     /**
      * Per-call retry override, and the ONLY way to put a mutating request in
      * scope for a retry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omelhorsite/sdk",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",