@omelhorsite/sdk 0.2.0 → 0.4.0

package/dist/types/resources/library/chat.d.ts

@@ -0,0 +1,259 @@
+/** The `library.chat` namespace: the streaming study assistant, its payloads, limits and helpers. */
+import { OmsError } from "../../errors";
+import { Resource } from "../../http";
+import type { RequestOptions } from "../../types";
+import type { BookId } from "./types";
+/**
+ * Requests per minute allowed against `POST /books/:id/chat`.
+ *
+ * Keyed on the `Authorization` header when there is one, and on the client IP
+ * when there is not - so a cookie-authenticated web client shares one budget
+ * with every other visitor behind the same address. Over it: `429`.
+ */
+export declare const BOOK_CHAT_RATE_LIMIT_PER_MINUTE = 15;
+/**
+ * Largest chat request body the server agrees to parse: 512 KiB. Over it,
+ * `413`.
+ *
+ * This is a bound on what is PARSED, not on what reaches the model - the model
+ * caps below are applied afterwards.
+ */
+export declare const BOOK_CHAT_MAX_BODY_BYTES = 524288;
+/**
+ * Characters of {@link BookChatContext.text} the assistant will read.
+ *
+ * Silently truncated server-side, not refused. Sending a whole chapter costs
+ * the bytes and buys nothing past this point.
+ */
+export declare const BOOK_CHAT_MAX_CONTEXT_CHARS = 12000;
+/** Turns of history the assistant reads, newest kept. */
+export declare const BOOK_CHAT_MAX_HISTORY_MESSAGES = 12;
+/** Characters kept per history turn. */
+export declare const BOOK_CHAT_MAX_MESSAGE_CHARS = 4000;
+/** Characters kept across the whole history. */
+export declare const BOOK_CHAT_MAX_HISTORY_CHARS = 8000;
+/** One turn of the conversation, as the client remembers it. */
+export interface BookChatTurn {
+    /**
+     * Only `"user"` and `"assistant"` reach the model: everything else is
+     * dropped, precisely so a client cannot inject a `"system"` turn into our
+     * own framing.
+     */
+    readonly role: "user" | "assistant";
+    readonly content: string;
+}
+/**
+ * The passage the question is about. The CLIENT decides what that is - the
+ * current selection, the chapter on screen, or whatever its search index
+ * retrieved - and the server only frames it.
+ */
+export interface BookChatContext {
+    readonly kind: "selection" | "chapter" | "passages";
+    /** Chapter or section title, for the framing line. Truncated to 200 chars. */
+    readonly title?: string;
+    /** Truncated to {@link BOOK_CHAT_MAX_CONTEXT_CHARS} server-side, in silence. */
+    readonly text: string;
+}
+/** Arguments for {@link BookChatNamespace.stream} and {@link BookChatNamespace.ask}. */
+export interface BookChatInput {
+    /**
+     * The whole conversation, oldest first, INCLUDING the question being asked.
+     * There is no server-side session: what you do not send did not happen.
+     */
+    readonly messages: readonly BookChatTurn[];
+    /** The passage in front of the reader. Omit it and the assistant is told so. */
+    readonly context?: BookChatContext | null;
+}
+/**
+ * One decoded SSE frame from the chat stream.
+ *
+ * Exactly one field is set per frame. `delta` carries text to append, `done`
+ * marks a complete answer, and `error` is a failure that happened AFTER the
+ * `200` was written.
+ */
+export interface BookChatEvent {
+    readonly delta?: string;
+    readonly done?: boolean;
+    readonly error?: string;
+}
+/** Why a chat stream failed. See {@link BookChatError}. */
+export type BookChatFailureReason = 
+/** The server wrote an `error` frame: generation failed after the 200. */
+"assistant_unavailable"
+/** The stream ended without a `done` frame, so the answer is cut short. */
+ | "truncated";
+/**
+ * The chat stream failed AFTER the response status was written.
+ *
+ * This is not an {@link OmsApiError}, and that is the whole point of it
+ * existing. The server writes `200` and the SSE headers before the
+ * model has produced a single token, so anything that goes wrong from then on -
+ * the inference sidecar erroring, the proxy dropping a stream that went quiet -
+ * arrives INSIDE a successful response. Code that decides success by status
+ * alone reports a truncated answer, or an empty one, as a complete reply.
+ *
+ * `code` is `"server_error"`, so `error.retryable` is `true`: asking again is
+ * the right move for both reasons, subject to
+ * {@link BOOK_CHAT_RATE_LIMIT_PER_MINUTE}.
+ */
+export declare class BookChatError extends OmsError {
+    static readonly errorName: string;
+    /** Which of the two post-200 failures this is. */
+    readonly reason: BookChatFailureReason;
+    /** Text already yielded before the failure. Usually worth showing, marked as incomplete. */
+    readonly partial: string;
+    constructor(message: string, reason: BookChatFailureReason, partial: string, url?: string);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * True when this error is the assistant refusing because every generation slot
+ * is taken.
+ *
+ * The server fails closed rather than queueing - a caller parked waiting for
+ * a slot would be holding the very server thread the slots exist to protect -
+ * so the answer is `503` with `"The assistant is busy, try again in a moment"`.
+ * It is transient and it is NOT a rate limit: the caller did nothing wrong and
+ * `Retry-After` is not sent, so back off on your own and try again.
+ */
+export declare function isBookChatBusy(error: unknown): boolean;
+/**
+ * Whether {@link BookChatNamespace.stream} will deliver this answer in pieces
+ * on THIS runtime.
+ *
+ * `true` in a browser and in Bun, `false` in React Native, whose `fetch` hands
+ * the whole body over at the end and has no `ReadableStream` at all. Both
+ * paths reach the same endpoint and produce the same final text; only the
+ * arrival differs, and this is the question to ask before a UI promises a
+ * typing indicator. A typing indicator that never types is worse than a
+ * spinner that admits it is waiting.
+ *
+ * Read it at the point of use, never cached at module load: a host may install
+ * a polyfill after the SDK is imported.
+ */
+export declare function bookChatIsIncremental(): boolean;
+/** Options for {@link BookChatNamespace.stream} and {@link BookChatNamespace.ask}. */
+export interface BookChatStreamOptions extends RequestOptions {
+    /**
+     * How long to wait for the NEXT piece of the answer before giving up, in
+     * milliseconds. Defaults to the transport's 45 seconds; `0` disables it.
+     *
+     * A silence limit, not a total: an answer that keeps producing runs as long
+     * as it likes. It exists because a stalled sidecar once answered `200` and
+     * then said nothing for two minutes at a time, and `await reader.read()` has
+     * no deadline of its own, so the chat panel span for as long as the tab
+     * stayed open. `timeoutMs` cannot cover this: it is disposed the moment the
+     * headers arrive, or no stream could outlive it.
+     *
+     * It has to sit well clear of a cold model's first token - the 8B model has
+     * to be paged in before it can answer - which is why 45 seconds and not five.
+     *
+     * IGNORED on the buffered path (React Native), where there is one read and
+     * the caller's `signal` is what bounds it.
+     */
+    readonly silenceTimeoutMs?: number;
+}
+/**
+ * The `library.chat` namespace: the reader's study assistant.
+ *
+ * `POST /books/:id/chat` is the only STREAMING endpoint in the whole API.
+ *
+ * ## What it costs, and why it refuses rather than queues
+ *
+ * One request parks a server thread for the whole generation, tens of seconds
+ * on the local model. The server caps how many generations run at once and
+ * FAILS CLOSED when they are all taken - a caller parked waiting for a slot
+ * would be holding the very thread the slots exist to protect. That refusal is
+ * a `503`; see {@link isBookChatBusy}. On top of it, one client may only START
+ * {@link BOOK_CHAT_RATE_LIMIT_PER_MINUTE} generations a minute, so a loop
+ * cannot take whatever slot frees up next.
+ *
+ * ## The client owns the conversation
+ *
+ * There is no server-side session and no history storage. Every request carries
+ * the whole conversation and the passage the question is about; what you do not
+ * send did not happen. The server owns the framing and the caps, and it drops
+ * any role other than `user` and `assistant` so a client cannot inject a
+ * `system` turn into our own prompt.
+ */
+export declare class BookChatNamespace extends Resource {
+    /**
+     * `POST /books/:id/chat` - asks the assistant and yields the answer as it
+     * arrives.
+     *
+     * Yields TEXT DELTAS, already unwrapped from their SSE frames: concatenating
+     * everything this yields is the complete answer. Framing is handled here
+     * because a chunk is not a frame - a `data:` line can arrive split across two
+     * network chunks - and every client that tried to parse the raw stream itself
+     * got that wrong at least once.
+     *
+     * ## The two runtimes do not deliver the same way, and the difference is real
+     *
+     * - **browser and Bun**: one yield per delta, as the model produces it. A
+     *   typing UI works, and abandoning the loop (a `break`, or an early
+     *   `return`) cancels the reader, closes the connection, and the server
+     *   notices the disconnect and RELEASES ITS GENERATION SLOT. Stopping early
+     *   genuinely stops the work.
+     * - **React Native**: ONE yield, containing the entire answer, after the
+     *   server has finished generating. RN's `fetch` is `XMLHttpRequest` under a
+     *   shim, the whole body is accumulated natively and handed over at the end,
+     *   and `response.body` does not exist. This is not a gap to polyfill.
+     *   Consequences to design around: a typing indicator will sit still and then
+     *   snap to the finished answer, so ask {@link bookChatIsIncremental} and
+     *   show a spinner instead; and `break`ing out of the loop cancels NOTHING,
+     *   because the request already completed - only an `AbortSignal` can stop
+     *   the work, and only by tearing down the whole request.
+     *
+     * The final text is identical on both. Nothing is lost, nothing is
+     * reordered, and no chunk boundary is invented to make one look like the
+     * other.
+     *
+     * ## A `200` does not mean the answer worked
+     *
+     * The status and the SSE headers are written before the model has produced a
+     * token, so every later failure is in-band. Two of them, both raised as
+     * {@link BookChatError} with the text already yielded attached:
+     *
+     * - an `error` frame (`reason: "assistant_unavailable"`) - the inference
+     *   client raised, and the upstream message is deliberately withheld because
+     *   it can carry the sidecar's internals;
+     * - the stream ending without a `done` frame (`reason: "truncated"`) - the
+     *   proxy dropped a stream that went quiet, or the connection was cut
+     *   mid-answer. Returning quietly here would report a half-answer as a
+     *   complete one, which is the whole reason the `done` frame exists.
+     *
+     * @example
+     * ```ts
+     * let answer = "";
+     * for await (const delta of oms.library.chat.stream(bookId, { messages, context })) {
+     *   answer += delta;
+     *   render(answer);            // one paint per delta, or one paint on RN
+     * }
+     * ```
+     *
+     * @throws {OmsAuthError} 401 `"Session required"` when anonymous.
+     * @throws {OmsApiError} 404 `"Book not found"` when the book is not viewable;
+     *   413 `"Request too big"` over {@link BOOK_CHAT_MAX_BODY_BYTES}; 429 over
+     *   {@link BOOK_CHAT_RATE_LIMIT_PER_MINUTE}; 503 when every generation slot
+     *   is taken ({@link isBookChatBusy}).
+     * @throws {BookChatError} for either post-`200` failure. Check `reason` and
+     *   `partial`.
+     * @throws {OmsTimeoutError} when the stream goes quiet for
+     *   {@link BookChatStreamOptions.silenceTimeoutMs}. Streaming path only.
+     */
+    stream(bookId: BookId, input: BookChatInput, options?: BookChatStreamOptions): AsyncGenerator<string, void, undefined>;
+    /**
+     * The same call as {@link stream}, waited out and handed back as one string.
+     *
+     * For anywhere a partial answer has nowhere to go. It is exactly `stream`
+     * drained into a buffer, so it raises the same
+     * errors for the same reasons - including {@link BookChatError} on a
+     * truncated stream, which is the case a naive `await response.text()` would
+     * hand back as a successful half-answer.
+     *
+     * It does NOT make the request cheaper or faster anywhere. On a browser and
+     * on Bun the answer still streams in and is merely accumulated here; on React
+     * Native it was going to arrive in one piece regardless. Choose it because
+     * the CALLER has no use for pieces, never as a way to avoid streaming.
+     */
+    ask(bookId: BookId, input: BookChatInput, options?: BookChatStreamOptions): Promise<string>;
+}

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

@@ -0,0 +1,39 @@
+/** The `library` domain: books, shelves, annotations and the study assistant, reachable as `oms.library`. */
+import { Resource } from "../../http";
+import type { RequestOptions } from "../../types";
+import { LibraryAnnotationsNamespace } from "./annotations";
+import { LibraryBooksNamespace } from "./books";
+import { BookChatNamespace } from "./chat";
+import { LibraryShelvesNamespace } from "./shelves";
+import type { PublicLibrary } from "./types";
+export * from "./types";
+export * from "./books";
+export * from "./shelves";
+export * from "./annotations";
+export * from "./chat";
+/**
+ * The `library` namespace, reachable as `oms.library`.
+ *
+ * A thin holder for the four sub-namespaces. Each of them is exported on its
+ * own too, so a host that would rather write `oms.books` can construct
+ * {@link LibraryBooksNamespace} directly with the same `ApiClient`.
+ */
+export declare class LibraryNamespace extends Resource {
+    /** Books: upload, browse, share, read the bytes. */
+    readonly books: LibraryBooksNamespace;
+    /** Shelves: named, ordered, shareable groups of your own books. */
+    readonly shelves: LibraryShelvesNamespace;
+    /** Highlights, notes, bookmarks and reading progress. Always private. */
+    readonly annotations: LibraryAnnotationsNamespace;
+    /** The streaming study assistant. */
+    readonly chat: BookChatNamespace;
+    /**
+     * `GET /books/libraries` - the public-library directory.
+     *
+     * Delegates to {@link LibraryBooksNamespace.libraries}. It lives on the books
+     * route because that is where Rails mounted it, and it is surfaced here
+     * because it is a directory of READERS, which is what a caller looking for it
+     * expects `oms.library` to have.
+     */
+    publicLibraries(options?: RequestOptions): Promise<PublicLibrary[]>;
+}

package/dist/types/resources/library/shelves.d.ts

@@ -0,0 +1,237 @@
+/** The `library.shelves` namespace, with the record, inputs and limits only it uses. */
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../../types";
+import type { Book, BookId, BookVisibility } from "./types";
+/** Primary key of a shelf. A number, like every id in this file. */
+export type BookShelfId = number;
+/** Longest shelf name accepted. */
+export declare const BOOK_SHELF_NAME_MAX_LENGTH = 120;
+/** Longest shelf description accepted. */
+export declare const BOOK_SHELF_DESCRIPTION_MAX_LENGTH = 1000;
+/**
+ * Most shelves one user may own.
+ *
+ * Checked on creation only, so the 101st shelf fails with a `400` carrying
+ * `"You have reached the maximum of 100 shelves"`; existing shelves keep saving.
+ */
+export declare const BOOK_SHELVES_MAX_PER_USER = 100;
+/**
+ * A shelf: a named, ordered group of one reader's own books.
+ *
+ * `books` is present ONLY on the `:extended` view, which means
+ * {@link LibraryShelvesNamespace.get} and the three arrange calls carry it and
+ * {@link LibraryShelvesNamespace.list} does not. That is not an oversight to
+ * work around by listing and hoping - it is why `get` exists.
+ */
+export interface BookShelf {
+    readonly id: BookShelfId;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly name: string;
+    readonly description: string | null;
+    readonly visibility: BookVisibility;
+    /** The owner's ordering of their own shelves. Ascending. */
+    readonly position: number;
+    /** Owner. A string id. */
+    readonly user_id: Id;
+    readonly owner_handle: string | null;
+    readonly owner_name: string | null;
+    /** Whether the ASKING user may edit the shelf. */
+    readonly editable: boolean;
+    /**
+     * How many of this shelf's books the ASKING user may actually open, which is
+     * not how many are on it: a shelf can hold a book its owner later made
+     * private again, and counting those would promise a stranger rows they
+     * cannot see. So `book_count` can be smaller than `books.length` would be
+     * for the owner, and it costs one extra query PER SHELF in a listing.
+     */
+    readonly book_count: number;
+    /**
+     * The shelf's books, in `position` order, filtered to what the asking user
+     * may see. Present on the `:extended` view only - see the note above.
+     */
+    readonly books?: Book[];
+}
+/** Filter columns of `GET /book_shelves`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const BOOK_SHELF_FILTER_COLUMNS: readonly ["user_id", "visibility"];
+/** Arguments for {@link LibraryShelvesNamespace.list}. */
+export interface ListBookShelvesParams extends ListParams<(typeof BOOK_SHELF_FILTER_COLUMNS)[number]> {
+    /** Exact owner id. The only way to ask for one person's shelves. */
+    readonly userId?: Id;
+    /** Exact visibility. */
+    readonly visibility?: BookVisibility;
+    /** Exact ids. An array becomes `IN (...)`. */
+    readonly ids?: readonly BookShelfId[];
+    /** `"column:asc"` / `"column:desc"`. Defaults to the endpoint's own ordering. */
+    readonly order?: string;
+}
+/** Arguments for {@link LibraryShelvesNamespace.create}. */
+export interface CreateBookShelfInput {
+    readonly name: string;
+    readonly description?: string | null;
+    /** Defaults to `"private"` server-side. */
+    readonly visibility?: BookVisibility;
+}
+/**
+ * Arguments for {@link LibraryShelvesNamespace.update}.
+ *
+ * `position` is writable here and nowhere else: it orders the owner's SHELVES
+ * against each other, and has nothing to do with the order of books ON a shelf
+ * (that is {@link LibraryShelvesNamespace.reorder}).
+ */
+export interface UpdateBookShelfInput {
+    readonly name?: string;
+    readonly description?: string | null;
+    readonly visibility?: BookVisibility;
+    readonly position?: number;
+}
+/** The `library.shelves` namespace, reachable as `oms.library.shelves`. */
+export declare class LibraryShelvesNamespace extends Resource {
+    /**
+     * `GET /book_shelves` - browse shelves.
+     *
+     * Same two-axis visibility rule as books: every `public` shelf plus, for a
+     * signed-in caller, their own whatever their visibility. An `unlisted`
+     * shelf opens by its link and appears in no listing.
+     *
+     * Ordered by `(position, created_at)` unless you override it, so the owner's
+     * own arrangement is the default and a paged walk is stable without asking.
+     *
+     * **The rows here carry no `books`.** `index` renders the default view and
+     * only the `:extended` one inlines the association. Every other method in
+     * this namespace returns the extended shape; this one does not. Do not build
+     * a shelf screen by listing and reading `books` - it is `undefined`.
+     *
+     * Note also that `book_count` costs one query per shelf (per row, because
+     * it depends on who is asking). A 100-shelf page is 100 extra counts. Page
+     * it.
+     *
+     * @throws {OmsApiError} 400 naming the offending key when a filter is not
+     *   one of `user_id`, `visibility`, `id`, `created_at`, `updated_at`. There
+     *   are no `extra_options` on this endpoint at all, so ANY key in that
+     *   bucket is a 400.
+     */
+    list(params?: ListBookShelvesParams, options?: RequestOptions): Promise<Paginated<BookShelf>>;
+    /**
+     * `GET /book_shelves/:id` - one shelf, WITH its books.
+     *
+     * The `:extended` view, so {@link BookShelf.books} is populated here and
+     * nowhere in {@link list}. The books are filtered to what the ASKING user may
+     * open, in shelf order: a shelf that holds a book its owner later made
+     * private again shows that book to the owner and silently omits it for
+     * everyone else, which is also why `book_count` and `books.length` can
+     * disagree between two viewers of the same shelf.
+     *
+     * Works anonymously, through the wider visibility scope, which is how an
+     * `unlisted` shelf link resolves.
+     *
+     * @throws {OmsApiError} 404 for an unknown id and for someone else's private
+     *   shelf, indistinguishably.
+     */
+    get(id: BookShelfId, options?: RequestOptions): Promise<BookShelf>;
+    /**
+     * `POST /book_shelves` - creates an empty shelf owned by the caller.
+     *
+     * The owner is taken from the session and cannot be sent. Visibility
+     * defaults to `private`.
+     *
+     * Not retried by default, like every create: a replay after a lost answer
+     * makes a second identical shelf, and shelves are capped per user.
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     * @throws {OmsApiError} 400 `"You have reached the maximum of 100 shelves"`
+     *   at {@link BOOK_SHELVES_MAX_PER_USER}, or the model's validation messages
+     *   for a missing or over-long name.
+     */
+    create(input: CreateBookShelfInput, options?: RequestOptions): Promise<BookShelf>;
+    /**
+     * `PATCH /book_shelves/:id` - renames, re-describes, re-shares, or moves the
+     * shelf among the owner's other shelves.
+     *
+     * {@link UpdateBookShelfInput.position} orders SHELVES, not the books on one.
+     * Nothing renumbers the others, so two shelves can share a position and the
+     * `(position, created_at)` sort then decides between them by age.
+     *
+     * @throws {OmsAuthError} 401 when the shelf is not yours.
+     * @throws {OmsApiError} 404 for an unknown id or someone else's private
+     *   shelf; 400 with the model's validation messages.
+     */
+    update(id: BookShelfId, input: UpdateBookShelfInput, options?: RequestOptions): Promise<BookShelf>;
+    /**
+     * `DELETE /book_shelves/:id` - removes the shelf.
+     *
+     * The BOOKS SURVIVE. Only the `book_shelf_items` join rows are destroyed, so
+     * this un-files the books rather than deleting them - the opposite of
+     * {@link LibraryBooksNamespace.delete}, and worth saying in the confirmation
+     * dialog.
+     *
+     * @throws {OmsAuthError} 401 when the shelf is not yours.
+     * @throws {OmsApiError} 404 the second time round.
+     */
+    delete(id: BookShelfId, options?: RequestOptions): Promise<void>;
+    /**
+     * `POST /book_shelves/:id/add_book` - puts one of YOUR books on the shelf.
+     *
+     * IDEMPOTENT: adding a book that is already there is a no-op with a `200`,
+     * not a duplicate and not a 422. Position is assigned automatically at the
+     * end of the shelf.
+     *
+     * The book must be the shelf owner's own: somebody else's book - public or
+     * not - is a `404 "Book not found"` rather than a permission error, and a
+     * shelf can never hold a book whose owner might later make it private and
+     * leak it through the shelf's visibility.
+     *
+     * Answers the whole shelf in its `:extended` view, so the response already
+     * contains the new arrangement and there is no need to re-fetch.
+     *
+     * @throws {OmsApiError} 404 `"Shelf not found"` for an unknown shelf,
+     *   `"Book not found"` for a book that is not yours; 403 `"Not your shelf"`
+     *   for someone else's shelf - note this action answers **403** where
+     *   {@link update} answers 401 for the same offence.
+     * @throws {OmsApiError} 422 with the item's validation messages, which in
+     *   practice only fires if the ownership check is ever relaxed.
+     */
+    addBook(id: BookShelfId, bookId: BookId, options?: RequestOptions): Promise<BookShelf>;
+    /**
+     * `DELETE /book_shelves/:id/remove_book` - takes a book off the shelf.
+     *
+     * The book itself is untouched; only the join row goes.
+     *
+     * IDEMPOTENT to the point of being silent: removing a book that was never
+     * on the shelf answers `200` with the unchanged shelf. There is no way to
+     * tell the two
+     * apart from the response - compare `book_count` yourself if you need to.
+     *
+     * The book id travels as a QUERY PARAMETER rather than in a body. The server
+     * reads it from either, and a `DELETE` with a body is the shape
+     * that intermediaries are least reliable about forwarding; the transport
+     * also has no body slot on `delete`. Nothing here is a filter bucket, so the
+     * unknown-key guard does not apply.
+     *
+     * @throws {OmsApiError} 404 `"Shelf not found"`; 403 `"Not your shelf"`.
+     */
+    removeBook(id: BookShelfId, bookId: BookId, options?: RequestOptions): Promise<BookShelf>;
+    /**
+     * `POST /book_shelves/:id/reorder` - sets the order of the books on a shelf.
+     *
+     * SEND THE COMPLETE LIST, in the order you want, every time. The action
+     * writes `position = index + 1` for each id it was given and touches nothing
+     * else, so a partial list leaves the omitted books on their OLD positions -
+     * which now collide with the new ones, and the shelf comes back interleaved
+     * in an order nobody chose. There is no error: it is a `200` and a shelf that
+     * looks shuffled.
+     *
+     * Ids that are not on this shelf are ignored in silence, and so are ids of
+     * books that do not exist. So this cannot
+     * be used to add a book - use {@link addBook} first, then reorder.
+     *
+     * The whole thing runs in one transaction, so a shelf is never left half
+     * renumbered.
+     *
+     * @throws {TypeError} before any request for an empty list, which the server
+     *   would answer `400 "No order given"`.
+     * @throws {OmsApiError} 404 `"Shelf not found"`; 403 `"Not your shelf"`.
+     */
+    reorder(id: BookShelfId, bookIds: readonly BookId[], options?: RequestOptions): Promise<BookShelf>;
+}

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

@@ -0,0 +1,120 @@
+/** Identifiers, enumerations and records shared by every library namespace. */
+import type { Id, Timestamp } from "../../types";
+/**
+ * Primary key of a book. A NUMBER: `books` never moved to the opaque string
+ * ids the account-side tables use, even though its `user_id` and its three
+ * `*_fs_node_id` columns are strings.
+ */
+export type BookId = number;
+/** Primary key of an annotation. A number. */
+export type BookAnnotationId = number;
+/** The two file formats the library accepts. */
+export declare const BOOK_FORMATS: readonly ["pdf", "epub"];
+/** One of {@link BOOK_FORMATS}. */
+export type BookFormat = (typeof BOOK_FORMATS)[number];
+/**
+ * Visibility of a book or a shelf. The same three levels apply to both.
+ *
+ * - `private` - owner only.
+ * - `unlisted` - anyone holding the link. Reachable by `GET /books/:id`,
+ *   absent from every listing. This is the level a "share" button sets.
+ * - `public` - anyone, AND listed in the owner's library and in explore.
+ */
+export declare const BOOK_VISIBILITIES: readonly ["private", "unlisted", "public"];
+/** One of {@link BOOK_VISIBILITIES}. */
+export type BookVisibility = (typeof BOOK_VISIBILITIES)[number];
+/** Kinds of annotation. */
+export declare const BOOK_ANNOTATION_KINDS: readonly ["highlight", "note", "bookmark", "progress"];
+/** One of {@link BOOK_ANNOTATION_KINDS}. */
+export type BookAnnotationKind = (typeof BOOK_ANNOTATION_KINDS)[number];
+/**
+ * A book.
+ *
+ * `editable` is computed against the ASKING user, which is what lets one
+ * listing mix your own books with strangers' public ones and still know which
+ * ones offer an edit affordance. It is also the answer for "may I delete
+ * this".
+ */
+export interface Book {
+    /** Integer primary key. See {@link BookId}. */
+    readonly id: BookId;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly title: string;
+    readonly author: string | null;
+    readonly description: string | null;
+    /** Detected at upload from the extension or the content type, never from the caller. */
+    readonly format: BookFormat;
+    readonly isbn: string | null;
+    readonly language: string | null;
+    readonly page_count: number | null;
+    /** Size of the stored file. `null` only on rows that predate the column. */
+    readonly file_size_bytes: number | null;
+    /** Always an array, never `null`: the column is `jsonb NOT NULL DEFAULT '[]'`. */
+    readonly tags: string[];
+    readonly visibility: BookVisibility;
+    /** Owner. A string id, next to an integer `id`. */
+    readonly user_id: Id;
+    /** Storage node of the cover the owner uploaded. A STRING id. */
+    readonly cover_fs_node_id: Id | null;
+    /** Storage node of the WebP thumbnail the server derived from it. A STRING id. */
+    readonly compressed_cover_fs_node_id: Id | null;
+    /** True when either cover node is set. Branch on this, not on the two ids. */
+    readonly has_cover: boolean;
+    readonly owner_handle: string | null;
+    readonly owner_name: string | null;
+    /** Whether the ASKING user may edit the book. Also answers "may I delete this". */
+    readonly editable: boolean;
+}
+/**
+ * One row of the public-library directory: a person, not a book.
+ *
+ * Unlike every other payload in the namespace it carries no `id`, no
+ * `created_at` and no `updated_at`, and the owner is addressed by `handle`.
+ * Feed that handle back as {@link ListBooksParams.ownerHandle}.
+ */
+export interface PublicLibrary {
+    readonly handle: string;
+    readonly name: string;
+    /** What the owner named their library, or `null` if they never did. */
+    readonly library_name: string | null;
+    readonly library_description: string | null;
+    /** PUBLIC books only. An owner's unlisted and private books are not counted. */
+    readonly book_count: number;
+}
+/**
+ * Where in the book an annotation sits. Format-specific and opaque to the API:
+ * the column is `jsonb NOT NULL DEFAULT '{}'` and nothing server-side reads
+ * inside it.
+ *
+ * The two shapes the readers agree on today:
+ * - EPUB: `{ cfiRange }` for a range, `{ cfi }` for a point;
+ * - PDF: `{ pageNumber, rects: [{ x, y, w, h }] }`, page-normalised to `[0,1]`
+ *   so a highlight survives a zoom.
+ *
+ * A new reader may write a new shape. Read defensively.
+ */
+export type BookAnnotationLocation = Record<string, unknown>;
+/**
+ * A highlight, a note, a bookmark, or a reading-progress marker.
+ *
+ * ALWAYS PRIVATE to the reader who made it, even on a public book: an
+ * anonymous caller sees none, and a signed-in caller sees only their own.
+ * There is no sharing of highlights, and `GET /book_annotations` therefore
+ * needs no user filter - it can only ever return your own.
+ */
+export interface BookAnnotation {
+    readonly id: BookAnnotationId;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly book_id: BookId;
+    /** Author. Always the caller, since nobody else's are visible. */
+    readonly user_id: Id;
+    readonly kind: BookAnnotationKind;
+    readonly location: BookAnnotationLocation;
+    /** Free-form, usually a CSS colour. Not validated server-side. */
+    readonly color: string | null;
+    readonly note: string | null;
+    /** The passage the reader selected, kept so a highlight can be listed without opening the book. */
+    readonly selected_text: string | null;
+}