@omelhorsite/sdk 0.3.0 → 0.4.1

package/dist/types/resources/social/relationships.d.ts

@@ -0,0 +1,322 @@
+/** Relationships: friendships and blocks, and `oms.social.relationships`. */
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { User } from "../account";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../../types";
+/** Primary key of a relationship row. An integer, for the same reason. */
+export type RelationshipId = number;
+/** A relationship row: one friendship or one block, between two users. */
+export interface Relationship {
+    /** Integer. */
+    readonly id: RelationshipId;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly kind: RelationshipKind;
+    readonly status: RelationshipStatus;
+    /** Whoever created the row. Always the authenticated user at create time. */
+    readonly requester_id: Id;
+    readonly accepter_id: Id;
+    readonly requester: User;
+    readonly accepter: User;
+}
+/** What a relationship row means. */
+export type RelationshipKind = "friend" | "block";
+/** Where a relationship row is in its lifecycle. */
+export type RelationshipStatus = "pending" | "accepted";
+/** Filter columns of `GET /relationships`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const RELATIONSHIP_FILTER_COLUMNS: readonly ["requester_id", "accepter_id"];
+/** `extra_options` keys of `GET /relationships`. */
+export declare const RELATIONSHIP_EXTRA_OPTION_KEYS: readonly ["user_id"];
+/** `extra_options` of `GET /relationships`. `user_id` matches rows where the user is either end. */
+export interface RelationshipExtraOptions {
+    readonly user_id?: Id;
+}
+/** Filters accepted by {@link RelationshipsNamespace.list}. */
+export interface ListRelationshipsParams extends ListParams<(typeof RELATIONSHIP_FILTER_COLUMNS)[number], RelationshipExtraOptions> {
+    /**
+     * `extra_options[user_id]`: rows where this user is either end.
+     *
+     * Worth passing your own id even though it narrows nothing. The filter is
+     * what makes the server preload both ends of every row. Without it the
+     * nested {@link User} for both ends of every row is rendered out of an
+     * unprepared query - two extra `SELECT`s per relationship.
+     */
+    readonly userId?: Id;
+    /** `exact_search[requester_id]`: rows this user created. */
+    readonly requesterId?: Id;
+    /** `exact_search[accepter_id]`: rows aimed at this user. */
+    readonly accepterId?: Id;
+}
+/** Body of {@link RelationshipsNamespace.create}. */
+export interface CreateRelationshipInput {
+    /** The other user. */
+    readonly userId: Id;
+    /** `"friend"` for a request, `"block"` for a block. */
+    readonly kind: RelationshipKind;
+}
+/**
+ * Friendships and blocks, reachable as `oms.social.relationships`.
+ *
+ * ## The state machine is TWO columns, not one
+ *
+ * There is no single `status` enum with a `blocked` member, however the UIs
+ * present it. A row carries `kind` (`friend` | `block`) and `status`
+ * (`pending` | `accepted`), and only three of the four combinations exist:
+ *
+ * | kind     | status     | what it is                                     |
+ * | -------- | ---------- | ---------------------------------------------- |
+ * | `friend` | `pending`  | a friend request, awaiting the accepter         |
+ * | `friend` | `accepted` | a friendship                                    |
+ * | `block`  | `accepted` | the requester has blocked the accepter          |
+ *
+ * `block` + `pending` is unreachable: a block is forced to `accepted` at
+ * birth, which also means a block's status can never be edited afterwards
+ * (see the transition rules below). Blocking is asymmetric and direction
+ * matters - `requester_id` blocked `accepter_id`, never the reverse.
+ *
+ * ## Transitions the server will accept
+ *
+ * `PATCH` may write `status` and nothing else. Any change whose PREVIOUS value
+ * was `accepted` is aborted, so:
+ *
+ * - `pending -> accepted` is the one real transition, and it is what
+ *   {@link accept} does;
+ * - `pending -> pending` is a no-op that answers `200`, because nothing
+ *   changed and the guard only fires on a change;
+ * - `accepted -> pending` is refused, `400 "Status cannot be changed"`;
+ * - `accepted -> accepted` is a no-op `200`, same reason as above;
+ * - anything outside `pending` / `accepted` is refused by the inclusion
+ *   validation, `400 "Status is not included in the list"`.
+ *
+ * There is no un-accept, no un-block and no "decline" verb. Ending ANY
+ * relationship - rejecting a request, unfriending, unblocking - is
+ * {@link delete} on the row. That is one method for three intentions, and the
+ * server cannot tell them apart either.
+ *
+ * ## EITHER PARTY CAN ACCEPT. INCLUDING THE ONE WHO ASKED.
+ *
+ * Either end of the row may `PATCH` it, and nothing narrows that for the
+ * `pending -> accepted` transition. So the sender of a friend request can
+ * `PATCH` their own request to `accepted` and become the recipient's friend
+ * without the recipient doing anything.
+ *
+ * That is a real hole, not a subtlety of this SDK, and it is load-bearing
+ * because friendship gates real things elsewhere in the API - a `friends`
+ * playlist becomes visible, the friends listening feed starts carrying that
+ * user's playback. Do not build a UI that offers the requester an accept
+ * button, and do not treat `status: "accepted"` as proof of consent from the
+ * accepter.
+ *
+ * ## A block you receive is INVISIBLE to you
+ *
+ * A block aimed at you is hidden from listings AND from lookups by id. You
+ * can see blocks you made; you cannot see, list, count or delete a block
+ * someone made against you. Its only observable effect is that
+ * {@link DirectMessagesNamespace.send} answers `401`.
+ *
+ * ## Realtime
+ *
+ * Both interesting events reach the other party as `NotificationsChannel`
+ * pushes rather than as anything on this namespace: `friendship_request`
+ * (`{ asker_id, asker_handle }`) when a `friend`/`pending` row is created, and
+ * `friendship_accepted` (`{ accepter_id, accepter_handle }`) when it flips.
+ * Neither carries the relationship row, so a client still has to
+ * {@link list} after the nudge. `block`, `delete` and every failed transition
+ * are silent.
+ */
+export declare class RelationshipsNamespace extends Resource {
+    /**
+     * `GET /relationships` - every relationship the caller is part of, in either
+     * direction, minus the blocks aimed at them.
+     *
+     * ## `kind` AND `status` ARE NOT FILTERABLE
+     *
+     * The filter columns are `requester_id, accepter_id` plus `id, created_at,
+     * updated_at`. `kind` and `status` are absent, and an unknown filter key
+     * does not get dropped - it is `400 "Unknown search filter: kind"`. So "list
+     * my friends" is not a query the API can answer: fetch the rows and filter
+     * here. {@link friends}, {@link incomingRequests}, {@link outgoingRequests}
+     * and {@link blocked} do exactly that.
+     *
+     * This is the single most surprising thing about the endpoint.
+     *
+     * ## Paging
+     *
+     * The SDK sends an explicit `modifiers[page]` and an explicit
+     * `created_at:desc` order, for the usual reason: with no page the server
+     * silently forces `1:500`, and offset paging over an unordered query can
+     * repeat and skip rows. A client that sends neither truncates at 500 rows
+     * without saying so - a real ceiling for an account with a long history,
+     * since blocks and dead requests count towards it.
+     *
+     * Indexes carry an `ETag`, so a conditional GET can come back `304`; the SDK
+     * does not send `If-None-Match` of its own.
+     */
+    list(params?: ListRelationshipsParams, options?: RequestOptions): Promise<Paginated<Relationship>>;
+    /**
+     * Every relationship row, paged out in full and filtered in memory.
+     *
+     * The building block under {@link friends} and its siblings, exported
+     * because "fetch them all, then filter" is the only shape this endpoint
+     * supports and every client ends up writing it.
+     *
+     * `limit` caps how many rows are pulled, so a pathological account cannot
+     * turn one call into an unbounded walk. It defaults to 2000, which is four
+     * requests at the server's maximum page size.
+     */
+    all(params?: ListRelationshipsParams, limit?: number, options?: RequestOptions): Promise<Relationship[]>;
+    /**
+     * The caller's accepted friends, as {@link User} records rather than as
+     * relationship rows.
+     *
+     * `selfId` is required and is NOT fetched for you: knowing which end of the
+     * row is "the other person" needs the caller's own id, and this namespace
+     * refuses to spend a `GET /sessions/mine` on every call to find it. Take it
+     * from `oms.account.me()` once and keep it.
+     *
+     * A friend appears exactly once even though the row could be in either
+     * direction. The result is derived from the same nested `requester` /
+     * `accepter` objects the listing already carries, so this costs no extra
+     * request beyond the paging {@link all} does.
+     */
+    friends(selfId: Id, options?: RequestOptions): Promise<User[]>;
+    /**
+     * Friend requests waiting for the caller to answer: `friend` + `pending`
+     * rows where the caller is the ACCEPTER.
+     *
+     * These are the ones {@link accept} is meant for. Answer with {@link accept}
+     * or refuse with {@link delete}; there is no third verb.
+     *
+     * This walks the listing itself, as do {@link friends}, {@link blocked} and
+     * {@link outgoingRequests}, because the server cannot filter on `kind` or
+     * `status`. A screen that wants more than one of them should call
+     * {@link all} ONCE and sort the rows with {@link isFriendship},
+     * {@link isPendingRequest} and {@link isBlock} rather than paying for the
+     * same walk four times.
+     */
+    incomingRequests(selfId: Id, options?: RequestOptions): Promise<Relationship[]>;
+    /**
+     * Friend requests the caller sent and nobody has answered: `friend` +
+     * `pending` rows where the caller is the REQUESTER.
+     *
+     * {@link delete} on one of these is a cancel. {@link accept} on one of these
+     * works too, and should not - see the class docs.
+     */
+    outgoingRequests(selfId: Id, options?: RequestOptions): Promise<Relationship[]>;
+    /**
+     * Users the caller has blocked.
+     *
+     * Only blocks the caller MADE. A block made against the caller is hidden
+     * and cannot be enumerated by any means; see the class docs.
+     */
+    blocked(selfId: Id, options?: RequestOptions): Promise<User[]>;
+    /**
+     * `POST /relationships` - creates a row. `201` with the record.
+     *
+     * `requester_id` is forced to the authenticated user and `status` is not
+     * writable: a `friend` starts `pending`, a `block` is born `accepted`.
+     * Prefer {@link request} and {@link block}, which say which of the two you
+     * meant.
+     *
+     * @throws {OmsApiError} `400 "Cannot create relationship with yourself"`,
+     *   or `400 "A relationship of this kind already exists between these
+     *   users"` when a `friend` row already exists in either direction.
+     */
+    create(input: CreateRelationshipInput, options?: RequestOptions): Promise<Relationship>;
+    /**
+     * Sends a friend request: `create({ kind: "friend" })`.
+     *
+     * At most one `friend` row may exist between two users in either direction,
+     * and the uniqueness check runs UNSCOPED - it sees rows the default scope
+     * hides from you. So a second request answers `400 "A relationship of this
+     * kind already exists between these users"`, and so does requesting someone
+     * who has already requested you (accept theirs instead) and, less obviously,
+     * requesting someone who has blocked you: their block row counts as an
+     * existing relationship. That last case is the only signal the API gives that
+     * a block against you exists, and it is indistinguishable from a duplicate
+     * request.
+     *
+     * The accepter gets a `friendship_request` notification over the cable.
+     */
+    request(userId: Id, options?: RequestOptions): Promise<Relationship>;
+    /**
+     * Blocks a user: `create({ kind: "block" })`.
+     *
+     * Three things happen server-side that no other call does:
+     *
+     * 1. the row is born `accepted`, so its status is immediately frozen;
+     * 2. every existing relationship between the two of you is DELETED first -
+     *    an accepted friendship is gone, not suspended, and unblocking later
+     *    does not bring it back;
+     * 3. that deletion is skipped when a block already exists between you in
+     *    EITHER direction, which also means **blocking is not idempotent**: a
+     *    second call creates a SECOND block row rather than answering with the
+     *    first, because the uniqueness validation deliberately exempts blocks.
+     *    Check {@link blocked} before calling, and unblock all the rows you find.
+     *
+     * The effect on the other user is exactly one thing: their
+     * {@link DirectMessagesNamespace.send} to you starts answering `401`. It does
+     * not stop you messaging them, it does not hide either profile, and it does
+     * not remove either of you from the other's
+     * {@link DirectMessagesNamespace.conversedUsers}, which is built from message
+     * history rather than from relationships.
+     *
+     * The blocked user is not notified.
+     */
+    block(userId: Id, options?: RequestOptions): Promise<Relationship>;
+    /**
+     * `PATCH /relationships/:id` with `status: "accepted"` - accepts a pending
+     * friend request. `200` with the updated record.
+     *
+     * Only ever call this on a row from {@link incomingRequests}. The server will
+     * happily accept one of your OWN outgoing requests, which is a hole, not a
+     * feature; see the class docs.
+     *
+     * The requester gets a `friendship_accepted` notification.
+     *
+     * @throws {OmsApiError} `400 "Status cannot be changed"` when the row was
+     *   already `accepted` and something is trying to move it back; `401` when
+     *   the caller is neither end of the row; `404 "Resource not found"` when the
+     *   id is not visible to the caller - which includes a block made against
+     *   them.
+     */
+    accept(id: RelationshipId, options?: RequestOptions): Promise<Relationship>;
+    /**
+     * `DELETE /relationships/:id` - `204`, empty body.
+     *
+     * The one verb for every ending: rejecting an incoming request, cancelling an
+     * outgoing one, unfriending, and unblocking. Either party may call it, and
+     * the row is gone for both - there is no soft state and no history.
+     *
+     * Unblocking does NOT restore the friendship the block destroyed on its way
+     * in. That row was deleted, not archived.
+     *
+     * Nobody is notified, so the other side finds out by noticing the row is no
+     * longer in their listing.
+     *
+     * `GET /relationships/:id` does not exist. Read a single row out of
+     * {@link list} instead.
+     */
+    delete(id: RelationshipId, options?: RequestOptions): Promise<void>;
+}
+/**
+ * The user at the other end of a relationship row, given the caller's own id.
+ *
+ * A relationship is stored with a direction (`requester` asked, `accepter` was
+ * asked) that a friends list does not care about, so every client writes this
+ * function. It is here once instead.
+ *
+ * Returns `undefined` when `selfId` is neither end of the row, and when the
+ * nested user object is missing - which the API does not currently do, but is
+ * treated as possible rather than asserted away.
+ */
+export declare function counterpart(relationship: Relationship, selfId: Id): User | undefined;
+/** `kind === "friend" && status === "accepted"`. */
+export declare function isFriendship(relationship: Relationship): boolean;
+/** An unanswered friend request, in either direction. */
+export declare function isPendingRequest(relationship: Relationship): boolean;
+/**
+ * A block the CALLER made. There is no such thing as a visible block against
+ * the caller - see {@link RelationshipsNamespace}.
+ */
+export declare function isBlock(relationship: Relationship): boolean;

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

@@ -0,0 +1,37 @@
+/** What direct messages and group chats share: the attachment kind and the caps both message families obey. */
+import type { Timestamp } from "../../types";
+/**
+ * 25 MiB, for a direct message and a group chat message alike, checked before
+ * anything is attached.
+ *
+ * IMAGES HAVE A LOWER, WORSE-BEHAVED CEILING. See
+ * {@link MESSAGE_IMAGE_MAX_BYTES}.
+ */
+export declare const MESSAGE_ATTACHMENT_MAX_BYTES: number;
+/**
+ * Fifteen minutes from `created_at`, for a direct message and a group chat
+ * message alike, after which an edit is `401`.
+ *
+ * Measured against the SERVER's clock. {@link canEditMessage} compares against
+ * the caller's, which is close enough to grey out a button and not close
+ * enough to promise the edit will land.
+ */
+export declare const MESSAGE_EDIT_WINDOW_MS: number;
+/** How the server classified an attachment, from its `content_type`. */
+export type AttachmentKind = "image" | "audio" | "video" | "file";
+/**
+ * Whether a message is still inside its edit window, for greying out a button.
+ *
+ * Measured against the CALLER's clock, and the server measures against its own,
+ * so this is an approximation that gets less honest the further the two drift.
+ * Always handle the `401` as well; do not treat `true` here as a promise that
+ * the edit will land, and do not treat `false` as a reason to skip the call if
+ * the user insists.
+ *
+ * Takes `now` so the function stays pure and the module stays isolate-safe -
+ * no `Date.now()` at module scope, and a caller can pass a server-derived
+ * clock if it has one.
+ */
+export declare function canEditMessage(message: {
+    created_at: Timestamp;
+}, now?: number): boolean;

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

@@ -68,8 +68,9 @@
  * cost actually is.
  */
 import { Resource } from "../http";
+import type { ListParams } from "../listing";
 import type { User } from "./account";
-import type { BaseRecord, FileInput, Id, NativeFile, PageParams, Paginated, RequestOptions, Timestamp } from "../types";
+import type { BaseRecord, FileInput, Id, NativeFile, Paginated, RequestOptions, Timestamp } from "../types";
 /**
  * Primary key of a direct message. An INTEGER: `messages` is one of the tables
  * that kept an auto-increment key, so `id` and `quoted_message_id` are JSON
@@ -296,8 +297,17 @@ export declare class SocialNamespace extends Resource {
     readonly groupChats: GroupChatsNamespace;
     constructor(http: ConstructorParameters<typeof Resource>[0]);
 }
+/** Filter columns of `GET /messages`. */
+export declare const MESSAGE_FILTER_COLUMNS: readonly ["id", "created_at", "updated_at", "content", "sender_id", "receiver_id", "read_at"];
+/** `extra_options` keys of `GET /messages`. */
+export declare const MESSAGE_EXTRA_OPTION_KEYS: readonly ["user_id", "other_user_id"];
+/** `extra_options` of `GET /messages`. Each matches rows where the user is either end. */
+export interface MessageExtraOptions {
+    readonly user_id?: Id;
+    readonly other_user_id?: Id;
+}
 /** Filters accepted by {@link DirectMessagesNamespace.list}. */
-export interface ListMessagesParams extends PageParams {
+export interface ListMessagesParams extends ListParams<(typeof MESSAGE_FILTER_COLUMNS)[number], MessageExtraOptions> {
     /**
      * The other end of the conversation. Sent as
      * `extra_options[other_user_id]`, which the server expands to
@@ -621,8 +631,16 @@ export declare class DirectMessagesNamespace extends Resource {
      */
     attachmentUrl(id: MessageId): Promise<string>;
 }
+/** Filter columns of `GET /relationships`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const RELATIONSHIP_FILTER_COLUMNS: readonly ["requester_id", "accepter_id"];
+/** `extra_options` keys of `GET /relationships`. */
+export declare const RELATIONSHIP_EXTRA_OPTION_KEYS: readonly ["user_id"];
+/** `extra_options` of `GET /relationships`. `user_id` matches rows where the user is either end. */
+export interface RelationshipExtraOptions {
+    readonly user_id?: Id;
+}
 /** Filters accepted by {@link RelationshipsNamespace.list}. */
-export interface ListRelationshipsParams extends PageParams {
+export interface ListRelationshipsParams extends ListParams<(typeof RELATIONSHIP_FILTER_COLUMNS)[number], RelationshipExtraOptions> {
     /**
      * `extra_options[user_id]`: rows where this user is either end.
      *

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.
  *