@omelhorsite/sdk 0.4.0 → 0.4.1

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

@@ -1,13 +1,12 @@
 /**
  * The direct-upload driver.
  *
- * Bytes never pass through Rails. The flow the backend implements, and the one
- * this module follows exactly:
+ * Bytes never pass through the API. The flow:
  *
  * 1. `POST /fs_nodes/batch_upload_urls` with a manifest of up to 100 files
  *    (`client_id`, `name`, `size`, and optionally `relative_path`,
  *    `content_type`, `checksum`). ONE request does directory resolution, one
- *    quota reservation under a single lock, node creation and plan minting.
+ *    quota reservation, node creation and plan minting.
  * 2. Per file the server answers a {@link UploadPlan}:
  *    - `strategy: "direct"` below 32 MiB: PUT the whole body to a presigned URL
  *      with the exact headers returned, then remember `blob_signed_id`;
@@ -25,27 +24,21 @@
  *   self-contained implementation - see the note there.
  * - The presigned PUTs go to the object store, NOT to the API. They must be
  *   sent with the injected fetch but WITHOUT the `Authorization` header, or
- *   MinIO rejects the request for having two authentication schemes.
+ *   the store rejects the request for having two authentication schemes.
  *
  * A node whose bytes never landed is adopted on the next attempt rather than
  * failing, so a torn batch is simply retried with the same manifest.
  *
- * Multipart is not an optimisation. The object store sits behind Cloudflare on
- * a plan that caps a request body at roughly 100 MB, so anything larger has no
- * other way in.
+ * Multipart is not an optimisation. A single request to the object store is
+ * capped at roughly 100 MB, so anything larger has no other way in.
  *
  * ## Progress, and why it ticks per transfer rather than per byte
  *
- * The bytes go to a presigned MinIO URL. Rails is never in the data path, and
- * neither is rack-attack - so a progress bar here is a pure client-side
- * problem, and the SDK solves it as far as `fetch` allows and no further.
+ * `fetch` has no upload-progress event, and the two ways around it were both
+ * rejected for the core:
  *
- * `fetch` has no upload-progress event. The two ways out were weighed and both
- * were rejected for the core:
- *
- * - **XHR**, which is what the web frontend's axios uses today, is the only API
- *   that reports request bytes as they leave. It does not exist in a
- *   Cloudflare-Worker-class isolate, and this package must load there.
+ * - **XHR** is the only API that reports request bytes as they leave. It does
+ *   not exist in a Worker-class isolate, and this package must load there.
  * - **A counting `ReadableStream` request body** would run in an isolate, and
  *   still does not work HERE. A stream body forces chunked transfer encoding,
  *   while a presigned PUT is signed over a fixed `Content-Length` (and, on the
@@ -82,35 +75,28 @@ import type { FsNode } from "../storage";
  * import { MULTIPART_THRESHOLD } from "@omelhorsite/sdk";
  * ```
  *
- * The number was verified in all three places it is currently written down, and
- * as of this writing they agree:
- *
- * - `FsServices::NodeBatchCreator::MULTIPART_THRESHOLD = 32.megabytes`, which
- *   is the only one that decides anything. The server compares
- *   `entry[:size] >= MULTIPART_THRESHOLD` and puts `strategy` in the plan.
- * - the web frontend's `lib/upload_core.ts`, which keeps its own literal.
- * - here.
- *
- * The client-side copies exist because the CHECKSUM has to be in the manifest
- * before the server has decided anything: below the threshold the digest is
- * mandatory (it is Content-MD5-bound into the presigned signature), at or above
- * it is pointless (multipart verifies per-part ETags). So the comparison is
- * made twice, and {@link manifestEntryFor} uses `<` against exactly the
- * server's `>=`.
+ * The server decides the strategy per file with `size >= 32 MiB` and puts it
+ * in the plan. The client-side copy exists because the CHECKSUM has to be in
+ * the manifest before the server has decided anything: below the threshold
+ * the digest is mandatory (it is Content-MD5-bound into the presigned
+ * signature), at or above it is pointless (multipart verifies per-part ETags).
+ * So the comparison is made twice, and {@link manifestEntryFor} uses `<`
+ * against exactly the server's `>=`.
  *
  * Drift is expensive and silent in one direction: a client that thinks the
  * threshold is HIGHER than the server's omits the checksum on a file the server
- * still plans as direct, and the upload dies at MinIO with a signature error
- * that never mentions checksums. That is the whole reason this is exported.
+ * still plans as direct, and the upload dies at the object store with a
+ * signature error that never mentions checksums. That is the whole reason this
+ * is exported.
  */
 export declare const MULTIPART_THRESHOLD: number;
 /**
- * Part size for the multipart path. Mirrors the backend, but it is only a
+ * Part size for the multipart path. The server's default, but only a
  * fallback: the real part size is whatever `multipart/start` answered, and that
  * is the number the driver slices with.
  */
 export declare const MULTIPART_PART_SIZE: number;
-/** Maximum files in one `batch_upload_urls` call. Mirrors the backend. */
+/** Maximum files in one `batch_upload_urls` call. Server limit. */
 export declare const MAX_BATCH = 100;
 /**
  * Files sent in one `batch_upload_urls` call by default.
@@ -120,25 +106,25 @@ export declare const MAX_BATCH = 100;
  * run leaves reserved-but-unused bytes behind.
  */
 export declare const DEFAULT_BATCH_SIZE = 50;
-/** Maximum part URLs requested in one call. Mirrors the backend. */
+/** Maximum part URLs requested in one call. Server limit. */
 export declare const MAX_PART_URLS = 100;
-/** Parts one multipart upload may have. Mirrors the backend's `MAX_PARTS`. */
+/** Parts one multipart upload may have. Server limit. */
 export declare const MAX_PARTS = 10000;
 /** Part URLs asked for in one round trip. Below {@link MAX_PART_URLS} on purpose. */
 export declare const PART_URL_WINDOW = 32;
-/** Parallel presigned PUTs in flight by default. The store is a Pi behind Cloudflare. */
+/** Parallel presigned PUTs in flight by default. Keep it modest. */
 export declare const DEFAULT_UPLOAD_CONCURRENCY = 4;
 /**
- * The `fs_upload/authed` throttle: `batch_upload_urls`, `batch_attach_blobs`
- * and every `multipart/*` call share 300 requests a minute, keyed by session.
- * {@link UploadManager} paces itself against this so a large run degrades into
- * waiting rather than into a wall of 429s.
+ * `batch_upload_urls`, `batch_attach_blobs` and every `multipart/*` call
+ * share 300 requests a minute, keyed by session. {@link UploadManager} paces
+ * itself against this so a large run degrades into waiting rather than into a
+ * wall of 429s.
  */
 export declare const FS_UPLOAD_RATE_LIMIT = 300;
 /**
- * The `fs_bulk_job/authed` throttle: `copy`, `create_directories`,
- * `empty_trash` and `move_to_trash` share TWELVE requests a minute. It is the
- * tightest limit in the API and the easiest one to trip by looping.
+ * `copy`, `create_directories`, `empty_trash` and `move_to_trash` share
+ * TWELVE requests a minute. It is the tightest limit in the API and the
+ * easiest one to trip by looping.
  */
 export declare const FS_BULK_JOB_RATE_LIMIT = 12;
 /** One entry of the manifest sent to `batch_upload_urls`. */
@@ -247,7 +233,7 @@ export interface UploadInput {
      * folder upload costs no extra round trips. A `..` segment is a 400.
      */
     readonly relativePaths?: string[];
-    /** Parallel PUTs in flight. Keep it modest: the store is a Pi behind Cloudflare. */
+    /** Parallel PUTs in flight. Keep it modest. */
     readonly concurrency?: number;
     /** Files per `batch_upload_urls` call. Clamped to {@link MAX_BATCH}. */
     readonly batchSize?: number;
@@ -338,7 +324,7 @@ export interface UploadManagerOptions {
      *
      * Two things the wrapper MUST get right, both of which the SDK's own
      * transport already does. It must not add an `Authorization` header or a
-     * cookie: the presigned signature is the credential and MinIO rejects a
+     * cookie: the presigned signature is the credential and the store rejects a
      * request carrying two authentication schemes. And it must expose `ETag` on
      * the `Response` it builds, or the multipart tier has nothing to complete
      * with - in a browser that additionally needs `ETag` in the bucket's
@@ -356,7 +342,7 @@ export interface UploadManagerOptions {
  * steps, for instance to resume a torn multipart.
  */
 export declare class UploadManager extends Resource {
-    /** Paces every control-plane call against the `fs_upload` throttle. */
+    /** Paces every control-plane call against the 300-a-minute upload limit. */
     readonly gate: StorageRateGate;
     private readonly transport;
     private readonly md5;
@@ -402,9 +388,9 @@ export declare class UploadManager extends Resource {
      * progress accounting drives `createBatch` -> {@link putDirect} /
      * {@link uploadMultipart} -> {@link attachBlobs} itself, and this is where it
      * learns the per-file strategy and the byte counts it will be reporting
-     * against. Whatever it does, it must pace itself against `fs_upload` (300
-     * requests a minute, shared by every call in this class) - {@link gate} is
-     * exposed for exactly that.
+     * against. Whatever it does, it must pace itself against the 300 requests a
+     * minute shared by every call in this class - {@link gate} is exposed for
+     * exactly that.
      *
      * @throws {OmsApiError} 400 on a structural problem, 404 when the parent is
      *   not a directory the caller may write to.
@@ -417,8 +403,8 @@ export declare class UploadManager extends Resource {
      * PUTs one whole body to a presigned URL.
      *
      * Sends the plan's headers verbatim and NO `Authorization`: this request goes
-     * to the object store, not to the API. MinIO refuses a request that carries
-     * both a presigned signature and a bearer header.
+     * to the object store, not to the API, and the store refuses a request that
+     * carries both a presigned signature and a bearer header.
      *
      * Retries a network fault or a 5xx from the store. A 4xx is never retried: an
      * expired signature or a checksum mismatch is deterministic and a retry only
@@ -450,7 +436,7 @@ export declare class UploadManager extends Resource {
      * with per-item results even when every item failed: read `attached` on each
      * one, and never infer success from the status. A caller driving the flow by
      * hand must not skip this - a node with no blob is invisible in listings and
-     * is eventually swept by `FsNodeUploadReaperJob`.
+     * is eventually swept by the server.
      */
     attachBlobs(attachments: Array<{
         fs_node_id: Id;
@@ -504,7 +490,7 @@ export declare class UploadManager extends Resource {
      * parts, PUT them in parallel, complete.
      *
      * Parts are sliced with the size the SERVER reported, never with
-     * {@link MULTIPART_PART_SIZE}, so a change on the backend does not silently
+     * {@link MULTIPART_PART_SIZE}, so a server-side change does not silently
      * corrupt an upload here.
      *
      * Phases 2 and 3 at once for a file at or above {@link MULTIPART_THRESHOLD}:
@@ -562,7 +548,7 @@ export declare class UploadManager extends Resource {
 /**
  * Base64 MD5 of a blob, in the exact form `Content-MD5` wants.
  *
- * The algorithm is not negotiable: the backend binds this digest into the
+ * The algorithm is not negotiable: the server binds this digest into the
  * presigned PUT signature as `Content-MD5`, so anything else makes the object
  * store reject the upload with a signature error that never mentions checksums.
  *

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

@@ -1,45 +1,43 @@
 /**
  * The `storage` namespace: the virtual filesystem.
  *
- * A node is a file or a directory, identified by an opaque id. Since the ltree
- * migration the id IS the address: there is no `path` column any more, and
- * navigation goes parent id -> children, with `ancestors()` for a breadcrumb.
- * Never build or parse a path string.
+ * A node is a file or a directory, identified by an opaque id. The id IS the
+ * address: a node carries no path, and navigation goes parent id -> children,
+ * with `ancestors()` for a breadcrumb. Never build or parse a path string.
  *
  * {@link StorageNamespace.resolvePath} exists for humans typing `docs/a.pdf`,
  * and it is exactly what it looks like: one request per segment, walking
- * `name` + `parent_id` down the filtered index. It memoises what it learns per
- * client instance so a CLI session does not re-walk the same prefix, but the
- * cheap call is always the one that already has an id.
+ * `name` + `parent_id` down a filtered listing. It memoises what it learns per
+ * client instance so a second walk down the same prefix is free, but the cheap
+ * call is always the one that already has an id.
  *
  * Uploads do NOT stream through this namespace. Bytes go straight to object
- * storage with a presigned URL; Rails only mints the plan and, at the end,
+ * storage with a presigned URL; the API only mints the plan and, at the end,
  * binds the blob. That whole dance lives in `storage/upload.ts` and is reached
  * through {@link StorageNamespace.upload}.
  *
- * Four throttles bound what this namespace can do, and they are far tighter
+ * Three rate limits bound what this namespace can do, and two are far tighter
  * than the API's general ceiling:
  *
- * - `fs_upload` - 300/min for the whole upload control plane. Paced by
+ * - 300 requests a minute for the whole upload control plane. Paced by
  *   {@link UploadManager}.
- * - `fs_bulk_job` - TWELVE a minute for `copy`, `createDirectories`,
- *   `emptyTrash` and `trash` together. Paced by {@link StorageNamespace.bulkGate}.
- * - the general 600/min for everything else.
- * - the direct PUTs at the object store, which rack-attack never sees at all.
+ * - TWELVE a minute for `copy`, `createDirectories`, `emptyTrash` and `trash`
+ *   together. Paced by {@link StorageNamespace.bulkGate}.
+ * - the general 600 a minute for everything else.
+ *
+ * The direct PUTs at the object store are not rate limited by the API.
  */
 /**
  * The server's null sentinel: U+0008, a literal backspace.
  *
- * `CrudActions` rewrites any filter value equal to it before the query layer
- * ever sees it - `transform_values! { |v| v == "\b" ? nil : v }`, applied to
- * every option bag, not just to `exact_search`. Through `exact_search` that is
- * exactly what is wanted: `where(parent_id: nil)`, the root nodes.
+ * The server reads any filter value equal to it as `null`, in every option
+ * bag. Through `exact_search[parent_id]` that is exactly what is wanted: the
+ * nodes with no parent, i.e. the roots.
  *
- * Through `extra_options` the same rewrite is a trap, because
- * `QueryExtraOptions::FsNodes` opens with
- * `return unless params[:parent_id].present?` and `nil` is not present, so the
- * filter is dropped without a word. {@link StorageNamespace.list} is built
- * around that difference; do not collapse the two filters back together.
+ * Through `extra_options[parent_id]` the same value is a trap: a `null` there
+ * counts as no filter at all, and the filter is dropped without a word.
+ * {@link StorageNamespace.list} is built around that difference; do not
+ * collapse the two filters back together.
  */
 import { type ApiClient, Resource } from "../http";
 import type { ListParams } from "../listing";
@@ -52,27 +50,14 @@ export type FsNodeKind = "file" | "directory";
 /**
  * A node in the virtual filesystem.
  *
- * This is the WHOLE record, and it was checked against the blueprint CHAIN
- * rather than against the table, because those two disagree.
- * `FsNodeBlueprint` declares `name`, `parent_id`, `kind`, `size`,
- * `max_size`; it extends `ApplicationBlueprint`, which contributes `id`,
- * `created_at` and `updated_at`; and its `:extended` view has an EMPTY body,
- * which in Blueprinter inherits the base fields rather than emitting nothing.
- * So `list`, `get`, `create` and `update` all answer the same eight fields.
- * Reading a view name and assuming it adds something has already produced bugs
- * in this repo - follow the `<` before deciding a field does or does not exist.
- *
- * The `fs_nodes` TABLE is wider than that, and the difference is never sent:
- * `creator_id`, `updater_id`, `destroyer_id`, `signed_url_generated`,
- * `is_vault_root` and the `id_path` ltree are all real columns that appear in
- * no view. Declaring them client-side is worse than leaving them out, because
- * every later reader then believes they arrive.
+ * This is the WHOLE record: `list`, `get`, `create` and `update` all answer
+ * the same eight fields.
  *
- * There is no `data` and no `url` field either: bytes are reached through
+ * There is no `data` and no `url` field: bytes are reached through
  * {@link StorageNamespace.download}, {@link StorageNamespace.downloadStream} or
  * {@link StorageNamespace.downloadUrl}, never off the record. And no
  * `content_type` and no `path` - the type is decided from the name at download
- * time, and the `path` column was dropped in the ltree migration.
+ * time, and a node is addressed by id.
  */
 export interface FsNode extends BaseRecord {
     readonly name: string;
@@ -101,10 +86,8 @@ export interface FsRoots {
  * A bulk operation the server runs in the background.
  *
  * `copy`, `createDirectories`, `trash` and `emptyTrash` all answer with nothing
- * but a job id: the work happens in a worker and the response says only that it
- * was enqueued. Poll it with `oms.jobs.wait(jobId)`; this namespace has no
- * access to the jobs namespace and deliberately does not grow a second polling
- * loop.
+ * but a job id: the response says only that the work was enqueued. Poll it
+ * with `oms.jobs.wait(jobId)`.
  */
 export interface FsBulkJob {
     /** Feed this to `oms.jobs.get` / `oms.jobs.wait`. */
@@ -125,7 +108,6 @@ export interface FsStream {
     /** Byte length when the server sent one. Always `undefined` for a zip. */
     readonly size: number | undefined;
 }
-/** Filters for {@link StorageNamespace.list}. */
 /** Filter columns of `GET /fs_nodes`. */
 export declare const FS_NODE_FILTER_COLUMNS: readonly ["id", "created_at", "updated_at", "name", "parent_id"];
 /** `extra_options` keys of `GET /fs_nodes`. */
@@ -157,10 +139,9 @@ export interface ListFsNodesParams extends ListParams<(typeof FS_NODE_FILTER_COL
      * Also return the parent itself, so one call gets both the folder's metadata
      * and its children. It occupies a slot on the page like any other row.
      *
-     * IGNORED when `parentId` is `null`, and that is a correction rather than a
-     * convenience: the server-side filter behind this flag cannot express "no
-     * parent" at all, and asking it to used to answer with the caller's whole
-     * tree. The roots have no folder to fold in anyway. The detail is on
+     * IGNORED when `parentId` is `null`: the server-side filter behind this flag
+     * cannot express "no parent", and asking it to answers with the caller's
+     * whole tree. The roots have no folder to fold in anyway. The detail is on
      * {@link StorageNamespace.list}.
      */
     readonly includeSelf?: boolean;
@@ -197,7 +178,7 @@ export interface FsGrant extends BaseRecord {
     readonly grantee_id: Id | null;
     /** Write access. Always `false` on a public grant - the server validates it. */
     readonly editable: boolean;
-    /** Only on the `:extended` view, i.e. from `get`, `create` and `update`. */
+    /** Only from `get`, `create` and `update`; absent in listings. */
     readonly fs_node?: FsNode;
     readonly grantor?: User;
     readonly grantee?: User | null;
@@ -232,17 +213,17 @@ export interface SharedFsNodeView {
  *
  * Creating one with a `granteeId` notifies that user. Creating one WITHOUT a
  * grantee mints a public link: the server also creates a short link in the `ss`
- * namespace whose endpoint is the grant's own id, pointing at the frontend's
- * `/storage/shared?id=<node>` page. Deleting the grant deletes that link.
+ * namespace whose endpoint is the grant's own id. Deleting the grant deletes
+ * that link.
  */
 export declare class FsGrantsNamespace extends Resource {
     /**
      * `GET /fs_grants` - the grants you hold: issued by you, or issued to you.
      *
-     * There is no server-side filter for the node. The controller allows only
-     * `id`, `created_at` and `updated_at` as search keys, and an unknown key is a
-     * 400, not a wider result - so narrowing to one node is a client-side filter
-     * over this listing. {@link StorageNamespace.shared} is the cheap way to ask
+     * There is no server-side filter for the node. The only search keys accepted
+     * are `id`, `created_at` and `updated_at`, and an unknown key is a 400, not a
+     * wider result - so narrowing to one node is a client-side filter over this
+     * listing. {@link StorageNamespace.shared} is the cheap way to ask
      * "how is THIS node shared".
      *
      * @throws {OmsAuthError} 401 when anonymous.
@@ -277,9 +258,9 @@ export declare class StorageNamespace extends Resource {
     /** Sharing grants. */
     readonly grants: FsGrantsNamespace;
     /**
-     * Paces the four bulk-job endpoints against the `fs_bulk_job` throttle, which
-     * is twelve requests a minute for all of them together. A loop that trashes
-     * files one at a time waits here rather than collecting 429s.
+     * Paces the four bulk-job endpoints against their shared limit of twelve
+     * requests a minute. A loop that trashes files one at a time waits here
+     * rather than collecting 429s.
      */
     readonly bulkGate: StorageRateGate;
     /**
@@ -318,40 +299,29 @@ export declare class StorageNamespace extends Resource {
      * TWO server-side filters address a directory and they are NOT
      * interchangeable. That asymmetry is the whole subtlety of this method:
      *
-     * - `exact_search[parent_id]` reaches `Searchable.exact_search`, which is a
-     *   bare `where(params)`. The controller has already rewritten a `\b` value
-     *   to `nil` by then, so the sentinel lands as `WHERE parent_id IS NULL` -
-     *   and since `FsNode.root_nodes` is exactly `where(parent_id: nil)`, this is
-     *   the only filter in the API that can say "the roots". The ltree
-     *   `id_path` is the source of truth for ANCESTRY, but rootness is still a
-     *   null `parent_id`.
-     * - `extra_options[parent_id]` reaches `QueryExtraOptions::FsNodes`, which
-     *   runs `where(parent_id: x).or(where(id: x))` and so folds the folder
-     *   itself back into its own listing. Convenient - and guarded by
-     *   `return unless params[:parent_id].present?`, with that same `\b` -> `nil`
-     *   rewrite happening first. Hand it the sentinel and the guard drops the
-     *   filter IN SILENCE. The request still answers 200; it just answers with
-     *   the caller's ENTIRE listable tree, page after page, instead of three
-     *   rows. It is the same failure shape as the `inside_path` incident that
-     *   `reject_unknown_filter_keys!` was written for, except this key IS known,
-     *   so nothing rejects it.
+     * - `exact_search[parent_id]` selects the children only. A `\b` value is
+     *   read as `null` and selects the nodes with no parent, so this is the only
+     *   filter in the API that can say "the roots".
+     * - `extra_options[parent_id]` selects the children AND the folder itself.
+     *   Hand it the sentinel and the filter is dropped IN SILENCE. The request
+     *   still answers 200; it just answers with the caller's ENTIRE listable
+     *   tree, page after page, instead of three rows.
      *
      * Hence `includeSelf` is honoured under a real directory and ignored at the
      * top of the tree. Not client-side taste: it is the only combination the
      * server can actually express.
      *
-     * The endpoint is conditional-GET aware and answers 304 to a matching
-     * `If-None-Match`. The SDK never sends one, and asks the runtime not to
-     * revalidate on its own, because a 304 has no body and would surface here as
-     * an error rather than as an empty page.
+     * The endpoint answers 304 to a matching `If-None-Match`. The SDK never
+     * sends one, and asks the runtime not to revalidate on its own, because a
+     * 304 has no body and would surface here as an error rather than as an
+     * empty page.
      */
     list(params?: ListFsNodesParams, options?: RequestOptions): Promise<Paginated<FsNode>>;
     /**
      * `GET /fs_nodes/:id` - one node.
      *
-     * Resolves against the broader `viewable_by` scope, so a node reached through
-     * a public share link answers here even though it never appears in
-     * {@link list}.
+     * Visibility is wider than {@link list}'s: a node reached through a public
+     * share link answers here even though it never appears in a listing.
      *
      * @throws {OmsApiError} 404 when the node does not exist or is not visible.
      */
@@ -370,11 +340,10 @@ export declare class StorageNamespace extends Resource {
      * Resolves a slash-separated path under a starting node, walking children one
      * level at a time.
      *
-     * A convenience for humans and CLIs, NOT how the API works. The `path` column
-     * was dropped in the ltree migration and nothing on the server accepts a path
-     * string, so each segment costs one filtered listing. Results are memoised
-     * per client instance, which makes a second walk down the same prefix free,
-     * but the cheap call is always the one that already has an id.
+     * A convenience for humans, NOT how the API works. Nothing on the server
+     * accepts a path string, so each segment costs one filtered listing. Results
+     * are memoised per client instance, which makes a second walk down the same
+     * prefix free, but the cheap call is always the one that already has an id.
      *
      * `.` is skipped and `..` climbs to the parent. A leading `/` means "from the
      * home root" and ignores `from`.
@@ -394,9 +363,9 @@ export declare class StorageNamespace extends Resource {
      * blobs and reads the finished nodes back.
      *
      * Files at or above `MULTIPART_THRESHOLD` (32 MiB, exported from this
-     * package) take the multipart path automatically, and that is not tuning:
-     * the object store sits behind Cloudflare with a request-body cap around
-     * 100 MB, so it is the only way a large file gets in at all.
+     * package) take the multipart path automatically, and that is not tuning: a
+     * single request to the object store is capped at roughly 100 MB, so it is
+     * the only way a large file gets in at all.
      *
      * A per-file rejection - a quota that ran out, a name that collides with a
      * directory - does not throw. It comes back in
@@ -422,7 +391,7 @@ export declare class StorageNamespace extends Resource {
      * job's result is the list of directories that were created. Existing levels
      * are reused, so re-running the same paths is a no-op that creates nothing.
      *
-     * Costs one of the twelve `fs_bulk_job` requests a minute. Pass every path in
+     * Counts against the twelve bulk-job requests a minute. Pass every path in
      * one call rather than looping.
      *
      * @throws {OmsApiError} 400 when `paths` is empty or the parent is not a
@@ -489,10 +458,10 @@ export declare class StorageNamespace extends Resource {
      * `GET /fs_nodes/:id/zip` - a directory and every file under it that the
      * caller can see, as a zip archive.
      *
-     * Streamed, and streamed for real: the server generates it with
-     * `ActionController::Live`, so there is no `Content-Length` and no way to
-     * know the size in advance. Never retried automatically either - a retry
-     * restarts the whole archive from zero.
+     * Streamed, and streamed for real: the server generates the archive as it
+     * sends it, so there is no `Content-Length` and no way to know the size in
+     * advance. Never retried automatically either - a retry restarts the whole
+     * archive from zero.
      *
      * @throws {OmsApiError} 400 when the node is not a directory, 404 when it is
      *   not visible.
@@ -501,8 +470,8 @@ export declare class StorageNamespace extends Resource {
     /**
      * `PATCH /fs_nodes/:id` with a new name.
      *
-     * The returned node is checked against what was asked for. The controller
-     * silently drops any field outside its update allowlist, so a 200 alone
+     * The returned node is checked against what was asked for. The server
+     * silently drops any field it does not accept on update, so a 200 alone
      * proves nothing about the write having happened.
      *
      * @throws {OmsApiError} 400 when the name collides with a sibling or contains
@@ -512,9 +481,7 @@ export declare class StorageNamespace extends Resource {
     /**
      * `PATCH /fs_nodes/:id` with a new parent.
      *
-     * The server refuses a move that would make a node its own ancestor; that
-     * cycle check is the fix for the 2026-07-27 copy outage and must not be
-     * second-guessed client-side.
+     * The server refuses a move that would make a node its own ancestor.
      *
      * Like {@link rename}, the answer is verified rather than assumed.
      *
@@ -533,7 +500,7 @@ export declare class StorageNamespace extends Resource {
      * filters the index does, so a copy with NO selection would resolve to the
      * caller's entire listable tree and duplicate it.
      *
-     * Costs one of the twelve `fs_bulk_job` requests a minute.
+     * Counts against the twelve bulk-job requests a minute.
      */
     copy(input: CopyFsNodesInput, options?: RequestOptions): Promise<FsBulkJob>;
     /**
@@ -546,7 +513,7 @@ export declare class StorageNamespace extends Resource {
      * Refuses an empty id list for the same reason {@link copy} does: with no
      * selection the endpoint resolves to the caller's whole listable tree.
      *
-     * Costs one of the twelve `fs_bulk_job` requests a minute, so trash the whole
+     * Counts against the twelve bulk-job requests a minute, so trash the whole
      * selection in one call.
      */
     trash(ids: Id[], options?: RequestOptions): Promise<FsBulkJob>;
@@ -605,7 +572,7 @@ export declare class StorageNamespace extends Resource {
     /**
      * Fetches an object-storage URL on the injected transport with no credential
      * of ours attached. The presigned signature in the URL IS the credential, and
-     * a bearer header alongside it is what makes MinIO reject the request.
+     * the store rejects a request that carries a bearer header alongside it.
      */
     private fetchObject;
 }

package/dist/types/resources/tools/backgroundRemoval.d.ts

@@ -1,15 +1,14 @@
 /**
  * Background removal: cuts the subject out of an image.
  *
- * `POST /background_removals` enqueues a proxy job and answers immediately with
- * a row plus a `job_id` and, for an anonymous caller, a `watch_token`. Poll
+ * `POST /background_removals` enqueues a job and answers immediately with a
+ * row plus a `job_id` and, for an anonymous caller, a `watch_token`. Poll
  * through `oms.jobs` with that handle, or use {@link BackgroundRemovalNamespace.run}.
  *
- * Backend limits: 15 MiB, and an image bomb (absurd pixel count for its byte
- * size) is rejected with a 400 before any work starts.
+ * Limits: 15 MiB, and an image bomb (absurd pixel count for its byte size) is
+ * rejected with a 400 before any work starts.
  *
- * This tool has no daily quota - it is one of the two that the `Quotas`
- * catalogue does not meter - so there is no `quota()` here to call first.
+ * This tool has no daily quota, so there is no `quota()` here to call first.
  */
 import { Resource } from "../../http";
 import type { FileInput, Id, RequestOptions } from "../../types";
@@ -18,12 +17,12 @@ import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOpti
  * A background removal run.
  *
  * Both routes that answer with one - `POST /background_removals` and
- * `GET /background_removals/:id` - render the `:extended` view, so `result_url`
- * is always PRESENT and simply `null` until the run completes.
+ * `GET /background_removals/:id` - answer the same shape, so `result_url` is
+ * always PRESENT and simply `null` until the run completes.
  *
  * `progress_percent`, inherited from {@link ToolRecord}, is never sent for this
- * tool: `BackgroundRemovalBlueprint` has no such field. Progress lives on the
- * {@link Job} row that {@link BackgroundRemovalCreated.job_id} names.
+ * tool. Progress lives on the {@link Job} row that
+ * {@link BackgroundRemovalCreated.job_id} names.
  */
 export interface BackgroundRemoval extends ToolRecord {
     /**
@@ -38,7 +37,7 @@ export interface BackgroundRemoval extends ToolRecord {
 export type BackgroundRemovalCreated = BackgroundRemoval & ToolJobHandle;
 /** Arguments for starting a run. */
 export interface CreateBackgroundRemovalInput extends ToolCaptcha {
-    /** The image. Backend cap: 15 MiB. */
+    /** The image. Cap: 15 MiB. */
     readonly file: FileInput;
 }
 /** The `backgroundRemoval` tool, reachable as `oms.tools.backgroundRemoval`. */
@@ -56,8 +55,7 @@ export declare class BackgroundRemovalNamespace extends Resource {
      *
      * NOT retried by default, unlike most of the SDK. The transport's policy
      * replays a `POST` that died with a 502, and here that would re-upload the
-     * image and start a second run on a sidecar that serialises them. Pass
-     * `retry: {}` to opt back in.
+     * image and start a second run. Pass `retry: {}` to opt back in.
      *
      * @throws {OmsApiError} 400 when the image is too large or looks like a bomb.
      * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.