@omelhorsite/sdk 0.2.0 → 0.3.0

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

@@ -33,11 +33,76 @@
  * 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.
+ *
+ * ## 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. 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.
+ * - **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
+ *   direct tier, over a `Content-MD5` covering the whole body), so the store
+ *   answers a signature error. It also needs `duplex: "half"` and HTTP/2, which
+ *   Safari and Firefox do not have. And it would count bytes handed to the
+ *   runtime rather than bytes the store acknowledged - the lie that makes a bar
+ *   sit at 100% for a minute.
+ *
+ * So: every `onProgress` in this module reports a COMPLETED transfer. On the
+ * multipart tier that is one tick per part, which the server sizes at 32 MiB,
+ * so a 1 GB file moves the bar 32 times. On the direct tier it is one tick for
+ * the whole file, which is at most 32 MiB by construction.
+ *
+ * A host that wants true byte-level granularity does not have to give up the
+ * driver: {@link UploadManagerOptions.fetch} takes the transport used for the
+ * presigned PUTs, so a browser can hand in an XHR-backed {@link FetchLike} and
+ * keep everything else. See the note there for the recipe. Building the whole
+ * flow by hand is also supported - {@link UploadManager.createBatch},
+ * {@link UploadManager.putDirect}, {@link UploadManager.attachBlobs} and the
+ * `multipart*` methods are public precisely so that a caller can drive the
+ * three phases itself and count bytes however it likes.
  */
 import { Resource, type ApiClient } from "../../http";
 import { type FetchLike, type FileInput, type Id, type OperationOptions, type ProgressCallback, type RequestOptions } from "../../types";
 import type { FsNode } from "../storage";
-/** Files at or above this size take the multipart path. Mirrors the backend. */
+/**
+ * Files at or above this size take the multipart path: 32 MiB, exactly.
+ *
+ * This is a PROTOCOL constant, not a tuning knob, and it is the SDK's public
+ * copy of it. Import this rather than writing `32 * 1024 * 1024` again:
+ *
+ * ```ts
+ * 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 `>=`.
+ *
+ * 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.
+ */
 export declare const MULTIPART_THRESHOLD: number;
 /**
  * Part size for the multipart path. Mirrors the backend, but it is only a
@@ -190,6 +255,12 @@ export interface UploadInput {
      * Read the finished nodes back with one extra listing per batch. On by
      * default, and worth it: a normal listing hides nodes whose bytes never
      * landed, so a node coming back at all is proof the blob is bound.
+     *
+     * Turning it off costs more than the listing. `UploadResult.node` is then
+     * `null` for every file, and `oms.storage.upload()` - which returns exactly
+     * the nodes it read back - answers with an EMPTY array on a run where every
+     * byte landed. Use {@link UploadManager.upload} directly if you switch this
+     * off, and read `fs_node_id` instead.
      */
     readonly verify?: boolean;
     /** Replacement for the built-in MD5. See {@link Md5Base64Fn}. */
@@ -238,11 +309,40 @@ export declare class StorageRateGate {
 /** Constructor options for {@link UploadManager}. */
 export interface UploadManagerOptions {
     /**
-     * The fetch used for the presigned PUTs.
+     * The fetch used for the presigned PUTs at the object store.
      *
      * Defaults to the one the {@link ApiClient} was built with, so bytes travel
-     * on the same transport as everything else. Pass one only to send the object
-     * store's traffic somewhere different from the API's.
+     * on the same transport as everything else. Only the PUTs go through it; the
+     * control plane always uses the client's own transport.
+     *
+     * This is also the supported way to get BYTE-LEVEL upload progress in a
+     * browser, which `fetch` cannot give (see the module note). Wrap XHR in a
+     * {@link FetchLike}, hand it in here, and keep the rest of the driver:
+     *
+     * ```ts
+     * const uploads = new UploadManager(oms.http, {
+     *   fetch: (url, init) =>
+     *     new Promise((resolve, reject) => {
+     *       const xhr = new XMLHttpRequest();
+     *       xhr.open(init?.method ?? "PUT", url);
+     *       for (const [k, v] of Object.entries(init?.headers ?? {})) xhr.setRequestHeader(k, v as string);
+     *       xhr.upload.onprogress = (event) => onBytes(url, event.loaded, event.total);
+     *       xhr.onload = () =>
+     *         resolve(new Response(xhr.response, { status: xhr.status, headers: parseXhrHeaders(xhr) }));
+     *       xhr.onerror = () => reject(new Error("network"));
+     *       xhr.send(init?.body as XMLHttpRequestBodyInit);
+     *     }),
+     * });
+     * await uploads.upload({ parentId, files });
+     * ```
+     *
+     * 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
+     * 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
+     * `Access-Control-Expose-Headers`.
      */
     readonly fetch?: FetchLike;
     /** Replacement for the built-in MD5. See {@link Md5Base64Fn}. */
@@ -273,10 +373,16 @@ export declare class UploadManager extends Resource {
      * the server reports them. Only a structural failure (bad parent, empty or
      * oversized batch) throws.
      *
-     * Progress granularity is a whole direct PUT or a whole multipart part, not
-     * a byte counter. `fetch` has no upload-progress event and a streamed request
-     * body is neither universally supported nor usable against a presigned PUT,
-     * which needs a `Content-Length`.
+     * `options.onProgress` reports the WHOLE RUN: `loaded` counts bytes across
+     * every file and `total` is their sum, so the number only ever climbs. It
+     * ticks once per finished direct PUT and once per finished multipart part -
+     * never per byte, for the reasons in the module note - and it fires once with
+     * `loaded: 0` before anything is sent, so a bar can render immediately.
+     *
+     * That callback is deliberately NOT forwarded to the per-file drivers. They
+     * take an `onProgress` of their own that talks about ONE file, and letting
+     * the run-level callback reach them would interleave "3 MB of 3 MB" with
+     * "12 MB of 40 MB" on the same bar.
      *
      * Every multipart session this call opened is aborted before the error
      * leaves, so a torn run does not strand parts (and reserved quota) on the
@@ -292,6 +398,14 @@ export declare class UploadManager extends Resource {
      * (invalid parent, empty batch, over {@link MAX_BATCH}, a `..` segment)
      * is a 400.
      *
+     * Public because it is phase 1 of the protocol: a caller that wants its own
+     * 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.
+     *
      * @throws {OmsApiError} 400 on a structural problem, 404 when the parent is
      *   not a directory the caller may write to.
      */
@@ -310,6 +424,16 @@ export declare class UploadManager extends Resource {
      * expired signature or a checksum mismatch is deterministic and a retry only
      * costs the bytes again.
      *
+     * Phase 2 of the protocol for a file below {@link MULTIPART_THRESHOLD}, and
+     * public so a caller can drive its own flow. `onProgress` fires EXACTLY ONCE
+     * here, after the store has accepted the body, with `loaded === total`. It is
+     * not a byte counter and cannot be one: see the module note, and
+     * {@link UploadManagerOptions.fetch} for the XHR escape hatch that can.
+     *
+     * Between this and {@link attachBlobs} the node exists with no bytes bound and
+     * is hidden from every listing, so a caller that stops here leaves a pending
+     * node behind.
+     *
      * @returns The ETag the store reported, or `null` when it was not readable -
      *   which happens in a browser whose bucket CORS policy does not expose
      *   `ETag`. The direct tier does not need it; multipart does.
@@ -322,8 +446,11 @@ export declare class UploadManager extends Resource {
      * their nodes. Until this lands the node exists with no bytes and is hidden
      * from every listing.
      *
-     * Answers 200 with per-item results even when every item failed. Read
-     * `attached` on each one; do not infer success from the status.
+     * Phase 3 of the protocol, and the last one for the direct tier. Answers 200
+     * 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`.
      */
     attachBlobs(attachments: Array<{
         fs_node_id: Id;
@@ -380,11 +507,30 @@ export declare class UploadManager extends Resource {
      * {@link MULTIPART_PART_SIZE}, so a change on the backend does not silently
      * corrupt an upload here.
      *
+     * Phases 2 and 3 at once for a file at or above {@link MULTIPART_THRESHOLD}:
+     * `multipart/complete` creates the blob row itself, so there is no
+     * {@link attachBlobs} call on this tier.
+     *
+     * This is the tier where a progress bar is actually useful, because the parts
+     * are 32 MiB and each one that lands is a real tick. `onProgress` reports
+     * THIS file cumulatively - `loaded` climbing towards `total === body.size` -
+     * and fires once up front so a bar can render before the first part is sent.
+     * On a resumed session it starts at the bytes already stored rather than at
+     * zero, which is the difference between "resuming at 60%" and a bar that
+     * appears to lose an hour of work. `onPart` is the lower-level twin: one call
+     * per part, with that part's byte count and its ETag.
+     *
+     * NOTHING here is per-byte; see the module note for why, and
+     * {@link UploadManagerOptions.fetch} for the way around it.
+     *
      * @param options.resume A session from a previous attempt plus the parts that
      *   already landed. The matching parts are skipped.
      * @param options.onSession Called with the upload token as soon as there is
-     *   one, so a caller can persist it and abort later.
+     *   one, so a caller can persist it and abort later. A failed run MUST reach
+     *   {@link multipartAbort} with that token or the parts stay charged against
+     *   the quota until a reaper notices.
      * @param options.onPart Called with the byte count of each finished part.
+     * @param options.onProgress Called with this file's cumulative byte count.
      */
     uploadMultipart(fsNodeId: Id, body: Blob, options?: RequestOptions & {
         concurrency?: number;
@@ -395,6 +541,7 @@ export declare class UploadManager extends Resource {
         };
         onSession?: (uploadToken: string, partSize: number) => void;
         onPart?: (bytes: number, part: MultipartPart) => void;
+        onProgress?: ProgressCallback;
     }): Promise<MultipartCompletion>;
     /**
      * PUTs bytes at the object store on the injected transport, with no

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

@@ -27,20 +27,51 @@
  * - the general 600/min for everything else.
  * - the direct PUTs at the object store, which rack-attack never sees at all.
  */
-import { Resource, type ApiClient } from "../http";
-import type { BaseRecord, FileInput, FileOutput, Id, OperationOptions, Paginated, PageParams, RequestOptions } from "../types";
+/**
+ * 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.
+ *
+ * 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.
+ */
+import { type ApiClient, Resource } from "../http";
+import type { BaseRecord, FileOutput, Id, OperationOptions, Paginated, PageParams, RequestOptions } from "../types";
 import type { User } from "./account";
 import { StorageRateGate, UploadManager } from "./storage/upload";
+import type { UploadInput } from "./storage/upload";
 /** What a node is. */
 export type FsNodeKind = "file" | "directory";
 /**
  * A node in the virtual filesystem.
  *
- * These are exactly the fields the server's blueprint emits - `id`,
- * `created_at`, `updated_at`, `name`, `parent_id`, `kind`, `size`, `max_size` -
- * and the `:extended` view adds nothing. In particular there is no
- * `content_type` and no `path`: the type of a file is decided from its name at
- * download time, and the path is gone.
+ * 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.
+ *
+ * There is no `data` and no `url` field either: 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.
  */
 export interface FsNode extends BaseRecord {
     readonly name: string;
@@ -109,6 +140,12 @@ export interface ListFsNodesParams extends PageParams {
     /**
      * 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
+     * {@link StorageNamespace.list}.
      */
     readonly includeSelf?: boolean;
 }
@@ -252,13 +289,39 @@ export declare class StorageNamespace extends Resource {
      */
     roots(options?: RequestOptions): Promise<FsRoots>;
     /**
-     * `GET /fs_nodes` - the children of a directory.
+     * `GET /fs_nodes` - the children of a directory, or the roots when
+     * `parentId` is `null`.
      *
      * Anonymous callers get an empty listing, always: the listing scope is the
      * caller's own tree plus what was explicitly shared with them, and a public
      * grant is deliberately NOT enumerable. Reach a publicly-shared node by id
      * with {@link get} or {@link shared} instead.
      *
+     * 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.
+     *
+     * 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
@@ -312,25 +375,28 @@ export declare class StorageNamespace extends Resource {
      * intake, presigns, sends the bytes straight to object storage, binds the
      * blobs and reads the finished nodes back.
      *
-     * Files at or above 32 MiB 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.
+     * 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.
      *
      * A per-file rejection - a quota that ran out, a name that collides with a
      * directory - does not throw. It comes back in
      * {@link UploadManager.upload}'s results, which is why that method is the one
      * to call when partial success matters; this wrapper returns only the nodes
-     * that landed.
-     *
-     * Progress arrives per finished part or file, not per byte: `fetch` exposes
-     * no upload-progress event.
-     */
-    upload(input: {
-        parentId: Id;
-        files: FileInput[];
-        relativePaths?: string[];
-        concurrency?: number;
-    }, options?: OperationOptions): Promise<FsNode[]>;
+     * that landed, and throws only when EVERY file was refused.
+     *
+     * `options.onProgress` counts bytes across the whole run and only ever
+     * climbs. It ticks once per finished direct PUT and once per finished
+     * multipart part, never per byte - `fetch` has no upload-progress event, and
+     * the alternatives are argued out in `storage/upload.ts`. A caller that needs
+     * true byte granularity in a browser builds an `UploadManager` with an
+     * XHR-backed transport; a caller that wants to drive the three phases itself
+     * has {@link UploadManager.createBatch}, {@link UploadManager.putDirect},
+     * {@link UploadManager.attachBlobs} and the `multipart*` methods, all public
+     * for that purpose.
+     */
+    upload(input: UploadInput, options?: OperationOptions): Promise<FsNode[]>;
     /**
      * `POST /fs_nodes/create_directories` - creates a subtree in one call.
      *

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

@@ -213,15 +213,94 @@ export declare class TicketsNamespace extends Resource {
     /**
      * `GET /tickets/:id/attachment/:blob_id` - one attachment's bytes.
      *
-     * The endpoint answers 302 towards object storage and `fetch` follows it.
-     * The redirect is cross-origin, so the platform drops the `Authorization`
-     * header on the way: the credential never reaches the storage host.
+     * Unlike `account.picture` and `chests.entries.download`, this one CANNOT be
+     * asked for anonymously. The action resolves the ticket through
+     * `Ticket.viewable_by(Current.user)` and declares `oauth_scope
+     * "tickets:write"`, so a request with no credential is a 404 on someone
+     * else's ticket and a 401 on your own. The credential has to ride the first
+     * hop, which is exactly what makes this awkward.
+     *
+     * The awkward part. Rails answers `302` to `minio.omelhorsite.pt` and `fetch`
+     * follows it. Two different things then happen depending on how the client
+     * was built:
+     *
+     * - **token mode** (`credentials: "omit"`). The Fetch standard strips
+     *   `Authorization` on a cross-origin redirect, so the store gets a clean
+     *   presigned request. The hop also swaps the origin for an opaque one, so
+     *   MinIO sees `Origin: null` and answers `Access-Control-Allow-Origin: *` -
+     *   which an uncredentialed request accepts. This works, in a browser and
+     *   out of one.
+     * - **cookie mode** (`sessionCookie: true`, the production web app). Same
+     *   `Origin: null`, same `*` back, but now the request carries credentials,
+     *   and wildcard plus credentials is illegal in CORS regardless of
+     *   `Access-Control-Allow-Credentials`. The browser rejects the response and
+     *   `fetch` rejects with an opaque "Failed to fetch".
+     *
+     * And it cannot be repaired the way the other two were, because the obvious
+     * repair does not exist in a browser: `redirect: "manual"` there yields an
+     * OPAQUE-REDIRECT response - status 0, empty header list - so `Location` is
+     * unreadable and the second hop cannot be re-issued without credentials.
+     * `redirect: "error"` and `XMLHttpRequest` are no better. Reading `Location`
+     * works only off-browser, where nothing was broken to begin with. The other
+     * two endpoints escape by needing no credential at all; this one has no such
+     * escape, and the backend exposes no `..._url` companion route the way
+     * `fs_nodes` does with `data_url`.
+     *
+     * So in a browser in cookie mode, use {@link attachmentUrl} and let the
+     * platform fetch the bytes - an `<img>`, a `<video>`, an `<a download>` make
+     * no-cors requests and follow the redirect with no CORS check at all. This
+     * method stays for every other context, and turns the browser failure into an
+     * error that says so instead of an unexplained network fault.
      *
      * Take `blobId` from {@link TicketAttachment.blob_id}; the filename and
      * content type are on the same record, which is why this hands back bare
      * bytes.
+     *
+     * @throws {OmsError} `unsupported` when the redirect was blocked by CORS,
+     *   naming {@link attachmentUrl} as the way through.
+     * @throws {OmsApiError} 404 when the blob is not on that ticket, or the
+     *   ticket is not yours.
      */
     attachment(id: TicketId, blobId: number, options?: RequestOptions): Promise<Blob>;
+    /**
+     * Absolute URL for one attachment, for an `<img>`, an `<a download>` or a new
+     * tab. In a browser in cookie mode this is the ONLY way to get at the bytes;
+     * see {@link attachment} for why.
+     *
+     * Asynchronous, unlike `account.pictureUrl` and
+     * `chests.entries.downloadUrl`, and the difference is not an accident: those
+     * two routes are anonymous, this one is not, so a credential has to be
+     * resolved before the URL means anything. Resolving it may involve a token
+     * refresh, which is why it cannot be a getter.
+     *
+     * How the URL authenticates depends on the client, matching what the backend
+     * accepts (`Session.candidate_tokens` reads the `Authorization` header, then
+     * `?token=`, then the `oms_session` cookie):
+     *
+     * - **cookie mode**: no credential in the URL. The browser attaches the
+     *   `oms_session` cookie itself. It is host-only on the API host and
+     *   `SameSite=Lax`, so this works from a page on `omelhorsite.pt` or another
+     *   host under it, and from nowhere else. Do not add `crossorigin` to the
+     *   element: it turns a no-cors load into a CORS one and re-creates the exact
+     *   failure this method exists to avoid.
+     * - **token mode**: the token is appended as `?token=`. Rails accepts a query
+     *   credential on API routes precisely because a native client has no cookie
+     *   jar and an `<img>` cannot carry a header.
+     *
+     * THE TOKEN-MODE URL CONTAINS A LIVE CREDENTIAL. It goes into the DOM, into
+     * the server access log, and into anything that records URLs. Build it at the
+     * moment of use, never store it, never log it, and never put it somewhere
+     * another person can read - anyone holding it holds the session until it is
+     * revoked. When the URL is destined for something outside your own page,
+     * fetch the bytes with {@link attachment} and hand over a `blob:` URL
+     * instead.
+     *
+     * ```tsx
+     * const src = await oms.tickets.attachmentUrl(ticket.id, file.blob_id);
+     * <img src={src} alt={file.filename} />
+     * ```
+     */
+    attachmentUrl(id: TicketId, blobId: number): Promise<string>;
 }
 /**
  * Encodes a file as a `data:<mime>;base64,<...>` URI.

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

@@ -14,10 +14,25 @@
 import { Resource } from "../../http";
 import type { FileInput, Id, RequestOptions } from "../../types";
 import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOptions } from "./index";
-/** A background removal run. */
+/**
+ * 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.
+ *
+ * `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.
+ */
 export interface BackgroundRemoval extends ToolRecord {
-    /** URL of the cut-out PNG, once the status is `"complete"`. */
-    readonly result_url?: string | null;
+    /**
+     * Signed URL of the cut-out PNG, or `null` - for the run not having
+     * finished, for it having failed, or for the 24-hour sweep having taken the
+     * attachment. {@link BackgroundRemovalNamespace.resultUrl} tells the three
+     * apart.
+     */
+    readonly result_url: string | null;
 }
 /** What `POST /background_removals` answers with. */
 export type BackgroundRemovalCreated = BackgroundRemoval & ToolJobHandle;