@omelhorsite/sdk 0.3.0 → 0.4.0

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

@@ -47,14 +47,7 @@
  *    per IP, after a bot pushed roughly 200 notification emails through it in
  *    one burst, plus a three-minute de-duplication window inside the
  *    controller. See {@link FeedbacksNamespace.create}.
- * 9. **"Intel" is two unrelated things sharing a prefix.** `GET /intel/*path`
- *    is a generic forwarder to a sidecar whose routes are not in the backend
- *    repository, so it stays untyped on purpose ({@link IntelProxyNamespace}).
- *    The `/intel_articles`, `/intel_reports`, `/intel_sources`,
- *    `/intel_scripts`, `/intel_items`, `/intel_config` and `/intel_stats`
- *    routes are ordinary Rails controllers with blueprints, and they are fully
- *    typed ({@link IntelNamespace}). Reach for the second set.
- * 10. **Two blog routes are private by accident.** `allow_unauthenticated_access`
+ * 9. **Two blog routes are private by accident.** `allow_unauthenticated_access`
  *    lists `index` and `show` on both blog controllers and nothing else, so the
  *    public PERMALINK (`GET /blogs/:blog/posts/:slug`) rejects anonymous
  *    readers while `GET /blog_posts/:id` serves them the same post, and the
@@ -84,35 +77,25 @@
  * rather than a throttle. See {@link ServicesStatusNamespace.uptime}.
  */
 import { ApiClient, Resource } from "../http";
-import type { FileOutput, Id, Json, PageParams, Paginated, QueryParams, QueryValue, RequestOptions, Timestamp } from "../types";
+import type { ListParams } from "../listing";
+import type { FileOutput, Id, Json, Paginated, RequestOptions, Timestamp } from "../types";
 import type { FsNode } from "./storage";
-/**
- * Filters accepted by the four listings in this file that really are the list
- * DSL. Mirrors the shape the other namespaces use.
- *
- * `search` is a partial, accent-insensitive match; `exact_search` is equality,
- * with an array meaning `IN` and `null` meaning `IS NULL`. Both fail CLOSED:
- * a key the controller did not declare is `400 "Unknown search filter: x"`,
- * never a silently wider result. The declared keys differ per endpoint and are
- * documented on each `list()`; they are much narrower here than you would
- * guess, because most of these controllers declare no `search_params` at all
- * and inherit only `id`, `created_at` and `updated_at`.
- */
-export interface ContentListParams extends PageParams {
-    /** Partial, accent-insensitive match. Only the columns the endpoint declares. */
-    readonly search?: Record<string, QueryValue>;
-    /** Exact match. Array means `IN`, `null` means `IS NULL`. */
-    readonly exactSearch?: Record<string, QueryValue>;
-    /**
-     * Ask for rows in random order. Mutually useful with a small `pageSize`.
-     *
-     * Two side effects worth knowing: `QueryModifier` applies `RANDOM()` with
-     * `reorder`, so it REPLACES any `order` the controller set for itself, and
-     * `CrudActions#resources_stale?` short-circuits for a random listing, so the
-     * response carries no `ETag` and can never answer `304`.
-     */
-    readonly random?: boolean;
-}
+/** Filter columns of `GET /notifications`, on top of {@link BASE_FILTER_COLUMNS}. `read` and `kind` are not filterable. */
+export declare const NOTIFICATION_FILTER_COLUMNS: readonly ["user_id"];
+/** Filters for {@link NotificationsNamespace.list}. */
+export type ListNotificationsParams = ListParams<(typeof NOTIFICATION_FILTER_COLUMNS)[number]>;
+/** Filter columns of `GET /feedbacks`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const FEEDBACK_FILTER_COLUMNS: readonly ["status", "user_id"];
+/** Filters for {@link FeedbacksNamespace.list}. */
+export type ListFeedbacksParams = ListParams<(typeof FEEDBACK_FILTER_COLUMNS)[number]>;
+/** `GET /jokes` filters on {@link BASE_FILTER_COLUMNS} only. */
+export declare const JOKE_FILTER_COLUMNS: readonly [];
+/** Filters for {@link JokesNamespace.list}. */
+export type ListJokesParams = ListParams<(typeof JOKE_FILTER_COLUMNS)[number]>;
+/** `GET /space_invaders_games` filters on {@link BASE_FILTER_COLUMNS} only; there is no player filter. */
+export declare const SPACE_INVADERS_GAME_FILTER_COLUMNS: readonly [];
+/** Filters for {@link SpaceInvadersNamespace.list}. */
+export type ListSpaceInvadersGamesParams = ListParams<(typeof SPACE_INVADERS_GAME_FILTER_COLUMNS)[number]>;
 /** Primary key of a blog. An INTEGER: `blogs` kept its auto-increment id. */
 export type BlogId = number;
 /** Primary key of a blog post. An integer, like the blog it hangs off. */
@@ -693,7 +676,7 @@ export declare class NotificationsNamespace extends Resource {
      * Sends an `ETag`, so an unchanged page answers `304` and costs nothing -
      * except with `random: true`, which disables the check.
      */
-    list(params?: ContentListParams, options?: RequestOptions): Promise<Paginated<Notification>>;
+    list(params?: ListNotificationsParams, options?: RequestOptions): Promise<Paginated<Notification>>;
     /**
      * `GET /notifications/unread_count` - how many unread notifications the
      * caller has. Unwraps the `{"count": n}` the server sends.
@@ -939,10 +922,10 @@ export declare class FeedbacksNamespace extends Resource {
      * `created_at`, `updated_at`). Any other key is `400`.
      *
      * The scope is ordered `created_at DESC` before the DSL runs, and
-     * `modifiers[order]` uses `reorder`, so passing {@link ContentListParams.order}
+     * `modifiers[order]` uses `reorder`, so passing {@link ListParams.order}
      * REPLACES that default rather than refining it.
      */
-    list(params?: ContentListParams, options?: RequestOptions): Promise<Paginated<Feedback>>;
+    list(params?: ListFeedbacksParams, options?: RequestOptions): Promise<Paginated<Feedback>>;
     /**
      * `GET /feedbacks/:id` - one report in full. **Admin only**; anybody else
      * gets `401` with a `null` body.
@@ -1047,7 +1030,7 @@ export declare class JokesNamespace extends Resource {
      * ordering (`"lang:asc:pt,en"` puts those languages first), which the rest
      * of the SDK does not advertise because almost nothing needs it.
      */
-    list(params?: ContentListParams, options?: RequestOptions): Promise<Paginated<Joke>>;
+    list(params?: ListJokesParams, options?: RequestOptions): Promise<Paginated<Joke>>;
     /**
      * `POST /jokes` - adds a joke. `201`. **Admin only.**
      *
@@ -1558,7 +1541,7 @@ export declare class SpaceInvadersNamespace extends Resource {
      *
      * No default ordering, so pass one. Sends an `ETag`.
      */
-    list(params?: ContentListParams, options?: RequestOptions): Promise<Paginated<SpaceInvadersGame>>;
+    list(params?: ListSpaceInvadersGamesParams, options?: RequestOptions): Promise<Paginated<SpaceInvadersGame>>;
     /**
      * `POST /space_invaders_games` - records a finished run. `201`.
      *
@@ -1593,156 +1576,6 @@ export declare class SpaceInvadersNamespace extends Resource {
     destroy(id: SpaceInvadersGameId, options?: RequestOptions): Promise<void>;
 }
 /**
- * The two path prefixes the proxy will forward. Mirrors
- * `IntelController::ALLOWED_PREFIXES`.
- *
- * `api` is the sidecar's JSON surface; `img` is its image surface. Anything
- * else - and any path containing `..` - is `400 "Invalid intel path."` before
- * a byte leaves the backend.
- */
-export declare const INTEL_ALLOWED_PREFIXES: readonly ["api", "img"];
-/** Connect timeout the backend applies to the sidecar, in milliseconds. */
-export declare const INTEL_UPSTREAM_OPEN_TIMEOUT_MS = 5000;
-/** Read timeout the backend applies to the sidecar, in milliseconds. */
-export declare const INTEL_UPSTREAM_READ_TIMEOUT_MS = 60000;
-/**
- * The `intel` proxy: a read-only passthrough to an internal service.
- *
- * ## Why this namespace has no types
- *
- * `GET /intel/*path` is not an API. It is a generic forwarder:
- * `IntelController#proxy` checks who is asking, refuses anything outside
- * {@link INTEL_ALLOWED_PREFIXES}, joins the rest of the path onto the
- * sidecar's base URL, replays the query string VERBATIM, injects an
- * `X-API-Key` that never reaches the browser, and hands back whatever comes
- * out - the upstream body, the upstream `Content-Type`, the upstream
- * `Cache-Control` and the upstream STATUS CODE, unexamined.
- *
- * The SDK cannot see that service, its routes are not in this repository, and
- * nothing in the backend validates or reshapes its answers. Publishing typed
- * `getStories()` / `getReport()` methods here would be inventing a contract
- * nobody can hold up, and it would rot the first time the sidecar changed. So
- * this namespace offers exactly what the endpoint offers: a path, a query bag,
- * and a caller-supplied result type it is the CALLER's job to justify.
- *
- * If you want typed intel data, use the native Rails endpoints instead -
- * they are real controllers with real blueprints, the web frontend moved onto
- * them and left this proxy behind, and they ARE wrapped, one family per
- * sub-namespace under {@link IntelNamespace}. This class is only for the
- * embedded hub the old page still renders and for its image bytes.
- *
- * ## Access
- *
- * Effectively a single-user endpoint. `Intel::Access.allowed?` is an admin
- * check OR a hard-coded handle allowlist, so every other authenticated caller
- * gets `403 "Intel access is restricted."` and an anonymous one gets the
- * ordinary `401` first. Do not build a shared feature on this.
- *
- * ## Errors are not the API's errors
- *
- * The upstream status is forwarded as-is, so a 4xx or 5xx here carries the
- * SIDECAR's body - which may be JSON, may be HTML, may be empty, and is
- * certainly not this API's usual bare JSON string. Read
- * {@link OmsApiError.body} defensively.
- *
- * When the sidecar cannot be reached at all - refused connection, DNS
- * failure, or a timeout past
- * {@link INTEL_UPSTREAM_OPEN_TIMEOUT_MS} / {@link INTEL_UPSTREAM_READ_TIMEOUT_MS} -
- * the backend answers `502 "Intel service unreachable."`, which is a normal
- * bare-string error.
- *
- * Only `GET` is routed. There is no way to write anything through this proxy.
- *
- * @deprecated Intel now lives ENTIRELY inside Rails. The analysis pipeline
- *   moved into Ruby and Solid Queue, and sources became per-user records with
- *   sandboxed TS scripts, so the `omelhorsite-intel-analise` sidecar this
- *   forwards to is on its way out. The route still answers today, which is why
- *   this class is still here rather than deleted, but nothing new should be
- *   built on it: when the sidecar goes, every call through here becomes a
- *   `502 "Intel service unreachable."` with no deprecation window, because the
- *   backend cannot tell a retired sidecar from a broken one.
- *
- *   Use the typed families under {@link IntelNamespace} instead: `articles`,
- *   `reports`, `sources`, `scripts`, `items`, `config` and `stats` are real
- *   controllers with real blueprints over the API's own tables.
- */
-export declare class IntelProxyNamespace extends Resource {
-    /**
-     * `GET /intel/<path>` - forwards a read and parses the answer as JSON.
-     *
-     * The type parameter is a PROMISE YOU are making, not one the SDK or the
-     * backend can check. Default it to `unknown` and narrow at the call site
-     * unless you own the sidecar's route.
-     *
-     * `path` is relative and must start with `api/` or `img/`
-     * (see {@link INTEL_ALLOWED_PREFIXES}). A leading slash is stripped, and
-     * each segment is percent-encoded while the separators are kept, so
-     * `"api/articles/abc def"` reaches the sidecar as `api/articles/abc%20def`.
-     * Pass an unencoded path; passing a pre-encoded one double-encodes it.
-     *
-     * `query` is encoded by the SDK's normal rules and then replayed to the
-     * sidecar untouched, `null` sentinel and all - which is worth knowing,
-     * because the sentinel is a Rails convention the sidecar has never heard of.
-     * Prefer plain values here.
-     *
-     * The route is declared `format: false`, so a trailing `.json` stays part of
-     * the path instead of being read as a Rails format.
-     *
-     * If the answer is not JSON it comes back as the raw text (the transport
-     * falls back to a string rather than throwing), so a `T` of `unknown`
-     * genuinely can be a `string`.
-     *
-     * Cost: the backend buffers the entire upstream body in memory before
-     * sending it on - there is no streaming - and holds a Puma thread for up to
-     * {@link INTEL_UPSTREAM_READ_TIMEOUT_MS} while it waits.
-     *
-     * @throws {OmsApiError} 400 `"Invalid intel path."` for a path outside the
-     *   allowed prefixes or containing `..`; 403 `"Intel access is restricted."`;
-     *   502 `"Intel service unreachable."`; or anything at all, forwarded from
-     *   the sidecar.
-     */
-    get<T = unknown>(path: string, query?: QueryParams, options?: RequestOptions): Promise<T>;
-    /**
-     * `GET /intel/<path>` - forwards a read and keeps the bytes.
-     *
-     * For the `img/` prefix, and for any `api/` route that answers with
-     * something other than JSON. Buffers the whole body, so do not point it at
-     * anything large.
-     *
-     * {@link FileOutput.filename} will be `undefined`: the backend sends
-     * `Content-Disposition: inline` with no filename. `contentType` is whatever
-     * the sidecar declared.
-     */
-    fetch(path: string, query?: QueryParams, options?: RequestOptions): Promise<FileOutput>;
-    /**
-     * The absolute URL of a proxied path, for an `<img src>` or an `<a href>`.
-     *
-     * Builds the string and makes no request. Useful only for a cookie-session
-     * browser client on the API's origin: the proxy requires an authenticated,
-     * allowlisted caller, so a bare URL opened without a credential is a `401`.
-     */
-    url(path: string, query?: QueryParams): string;
-}
-/**
- * ## Why these ARE typed, when the proxy above is not
- *
- * The two halves of "intel" look alike and are nothing alike.
- * {@link IntelProxyNamespace} forwards `GET /intel/*path` to a service whose
- * routes are not in the backend repository, so its answers are genuinely
- * unknowable. Everything below is the opposite: seven ordinary Rails
- * controllers over eight of the backend's own tables, each with a Blueprinter
- * blueprint that names every key it emits. `IntelArticleBlueprint`,
- * `IntelReportBlueprint`, `IntelSourceBlueprint`, `IntelScriptBlueprint`,
- * `IntelItemBlueprint` and `IntelConfigBlueprint` are the contract, and
- * `IntelStatsController#show` hand-writes its hash literally. Nothing here is
- * forwarded, nothing here is opaque, and the SDK types it the way it types any
- * other resource.
- *
- * Where the two meet: the sidecar behind the proxy is the OLD, separate intel
- * product embedded in the web app's `/intel` page. The routes below are the one
- * that replaced it. Reach for these first; the proxy is for the embedded hub
- * and for image bytes.
- *
  * ## Access: this is effectively a one-user feature
  *
  * `IntelAccess` runs `before_action :require_intel_access` on all seven
@@ -2221,8 +2054,10 @@ export interface IntelStats {
     /** Stories touched in the last 24 hours. */
     readonly last24h: number;
 }
+/** Filter columns of `GET /intel_articles`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_ARTICLE_FILTER_COLUMNS: readonly ["title", "summary", "category", "importance", "enriched"];
 /** Filters for {@link IntelArticlesNamespace.list}. */
-export interface ListIntelArticlesParams extends ContentListParams {
+export interface ListIntelArticlesParams extends ListParams<(typeof INTEL_ARTICLE_FILTER_COLUMNS)[number]> {
     /**
      * Free-text search over `title`, `summary` AND `details`.
      *
@@ -2231,7 +2066,7 @@ export interface ListIntelArticlesParams extends ContentListParams {
      * not in `search_params` at all) and why an unknown-filter 400 cannot
      * happen for it.
      *
-     * Three ways it differs from {@link ContentListParams.search}:
+     * Three ways it differs from {@link ListParams.search}:
      *
      * - it is **accent-SENSITIVE**. The controller does `LOWER(col) LIKE
      *   LOWER(term)`, with no unaccenting, while the list DSL's `search` strips
@@ -2266,20 +2101,24 @@ export interface ListIntelArticlesParams extends ContentListParams {
      */
     readonly sort?: "recent" | "importance";
 }
+/** Filter columns of `GET /intel_reports`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_REPORT_FILTER_COLUMNS: readonly ["kind"];
 /** Filters for {@link IntelReportsNamespace.list}. */
-export interface ListIntelReportsParams extends ContentListParams {
+export interface ListIntelReportsParams extends ListParams<(typeof INTEL_REPORT_FILTER_COLUMNS)[number]> {
     /**
      * Narrow to one window, e.g. `"day"`. Sent as `exact_search[kind]`, so it is
      * equality rather than a prefix match - `"6h"` will not also match `"6hx"`.
      *
-     * Passing it through {@link ContentListParams.search} instead would be a
+     * Passing it through {@link ListParams.search} instead would be a
      * partial match and would work too; `kind` is on this controller's
      * `search_params` allowlist. Equality is what you want.
      */
     readonly kind?: IntelReportKind;
 }
+/** Filter columns of `GET /intel_sources`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_SOURCE_FILTER_COLUMNS: readonly ["name", "health", "enabled", "intel_script_id"];
 /** Filters for {@link IntelSourcesNamespace.list}. */
-export interface ListIntelSourcesParams extends ContentListParams {
+export interface ListIntelSourcesParams extends ListParams<(typeof INTEL_SOURCE_FILTER_COLUMNS)[number]> {
     /** Only healthy / only broken feeds. Sent as `exact_search[health]`. */
     readonly health?: IntelSourceHealth;
     /** Only enabled, or only the ones that switched themselves off. */
@@ -2287,8 +2126,10 @@ export interface ListIntelSourcesParams extends ContentListParams {
     /** Every source driven by one script. */
     readonly scriptId?: Id;
 }
+/** Filter columns of `GET /intel_scripts`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_SCRIPT_FILTER_COLUMNS: readonly ["name", "builtin", "slug"];
 /** Filters for {@link IntelScriptsNamespace.list}. */
-export interface ListIntelScriptsParams extends ContentListParams {
+export interface ListIntelScriptsParams extends ListParams<(typeof INTEL_SCRIPT_FILTER_COLUMNS)[number]> {
     /**
      * `true` for the platform scripts, `false` for yours. Omit for both - the
      * listing scope is `builtin OR mine`, so both populations are mixed by
@@ -2296,8 +2137,10 @@ export interface ListIntelScriptsParams extends ContentListParams {
      */
     readonly builtin?: boolean;
 }
+/** Filter columns of `GET /intel_items`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const INTEL_ITEM_FILTER_COLUMNS: readonly ["intel_source_id", "external_id", "title", "content", "url"];
 /** Filters for {@link IntelItemsNamespace.list}. */
-export interface ListIntelItemsParams extends ContentListParams {
+export interface ListIntelItemsParams extends ListParams<(typeof INTEL_ITEM_FILTER_COLUMNS)[number]> {
     /** Only items produced by one source. Sent as `exact_search[intel_source_id]`. */
     readonly sourceId?: Id;
 }
@@ -2864,13 +2707,6 @@ export declare function intelArticleImageUrl(imageUrl: string | null | undefined
 /**
  * The `intel` namespace, reachable as `oms.content.intel`.
  *
- * Seven typed families over the backend's own tables, plus {@link proxy} for
- * the untyped passthrough to the old sidecar. The three proxy methods are also
- * mirrored on this class so that code written against 0.3.0's
- * `oms.content.intel.get(path)` keeps working; new code should say
- * `oms.content.intel.proxy.get(path)`, which cannot be confused with
- * {@link IntelArticlesNamespace.get}.
- *
  * A tour of the data model, because the names do not give it away:
  *
  * 1. a {@link IntelScript} knows HOW to fetch one kind of feed;
@@ -2902,38 +2738,7 @@ export declare class IntelNamespace extends Resource {
     readonly config: IntelConfigNamespace;
     /** Dashboard counters, in one expensive call. */
     readonly stats: IntelStatsNamespace;
-    /**
-     * The untyped passthrough to the old intel sidecar.
-     *
-     * @deprecated See {@link IntelProxyNamespace}. Kept only because the route
-     *   still answers; the typed families above are the intel API now.
-     */
-    readonly proxy: IntelProxyNamespace;
     constructor(http: ApiClient);
-    /**
-     * Alias for {@link IntelProxyNamespace.get}. Kept so 0.3.0 call sites still
-     * compile; prefer `oms.content.intel.proxy.get(path)`.
-     *
-     * @deprecated The intel sidecar is being retired: intel now lives entirely
-     *   inside Rails. See {@link IntelProxyNamespace}.
-     */
-    get<T = unknown>(path: string, query?: QueryParams, options?: RequestOptions): Promise<T>;
-    /**
-     * Alias for {@link IntelProxyNamespace.fetch}. Kept so 0.3.0 call sites still
-     * compile; prefer `oms.content.intel.proxy.fetch(path)`.
-     *
-     * @deprecated The intel sidecar is being retired: intel now lives entirely
-     *   inside Rails. See {@link IntelProxyNamespace}.
-     */
-    fetch(path: string, query?: QueryParams, options?: RequestOptions): Promise<FileOutput>;
-    /**
-     * Alias for {@link IntelProxyNamespace.url}. Kept so 0.3.0 call sites still
-     * compile; prefer `oms.content.intel.proxy.url(path)`.
-     *
-     * @deprecated The intel sidecar is being retired: intel now lives entirely
-     *   inside Rails. See {@link IntelProxyNamespace}.
-     */
-    url(path: string, query?: QueryParams): string;
 }
 /**
  * The `content` namespace, reachable as `oms.content`.

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

@@ -44,7 +44,8 @@
  * that deserves an exception.
  */
 import { Resource } from "../http";
-import type { BaseRecord, Id, Json, JobStatus, Paginated, PageParams, Progress, RequestOptions, Timestamp, WaitOptions } from "../types";
+import type { ListParams } from "../listing";
+import type { BaseRecord, Id, Json, JobStatus, Paginated, Progress, RequestOptions, Timestamp, WaitOptions } from "../types";
 /**
  * The five status strings, spelled the way the backend spells them.
  *
@@ -143,10 +144,12 @@ export interface JobRef {
     /** Signed token scoped to this one job. Required when anonymous. */
     readonly watchToken?: string;
 }
+/** Filter columns of `GET /jobs`. */
+export declare const JOB_FILTER_COLUMNS: readonly ["id", "job_type", "status", "created_at", "updated_at", "finished_at"];
 /** Filters for {@link JobsNamespace.list}. */
-export interface ListJobsParams extends PageParams {
-    readonly status?: JobStatus | JobStatus[];
-    readonly jobType?: string | string[];
+export interface ListJobsParams extends ListParams<(typeof JOB_FILTER_COLUMNS)[number]> {
+    readonly status?: JobStatus | readonly JobStatus[];
+    readonly jobType?: string | readonly string[];
 }
 /** Pause before the second poll, in milliseconds. */
 export declare const DEFAULT_POLL_INTERVAL_MS = 1000;

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

@@ -0,0 +1,162 @@
+/** The `library.annotations` namespace, with the inputs and limits only it uses. */
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { Paginated, RequestOptions } from "../../types";
+import type { BookAnnotation, BookAnnotationId, BookAnnotationKind, BookAnnotationLocation, BookId } from "./types";
+/** Longest note accepted. */
+export declare const BOOK_ANNOTATION_NOTE_MAX_LENGTH = 5000;
+/** Longest selected text accepted. */
+export declare const BOOK_ANNOTATION_SELECTED_TEXT_MAX_LENGTH = 8000;
+/** Filter columns of `GET /book_annotations`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const BOOK_ANNOTATION_FILTER_COLUMNS: readonly ["book_id", "kind"];
+/** Arguments for {@link LibraryAnnotationsNamespace.list}. */
+export interface ListBookAnnotationsParams extends ListParams<(typeof BOOK_ANNOTATION_FILTER_COLUMNS)[number]> {
+    /** Exact book id. The filter every reader screen uses. */
+    readonly bookId?: BookId;
+    /** Exact kind, or an array of kinds (which becomes `IN (...)`). */
+    readonly kind?: BookAnnotationKind | readonly BookAnnotationKind[];
+    /** `"column:asc"` / `"column:desc"`. Defaults to `created_at:asc`. */
+    readonly order?: string;
+}
+/** Arguments for {@link LibraryAnnotationsNamespace.create}. */
+export interface CreateBookAnnotationInput {
+    readonly bookId: BookId;
+    readonly kind: BookAnnotationKind;
+    /** Omitted or empty becomes `{}`, which is a valid annotation with no anchor. */
+    readonly location?: BookAnnotationLocation;
+    readonly color?: string | null;
+    readonly note?: string | null;
+    readonly selectedText?: string | null;
+}
+/**
+ * Arguments for {@link LibraryAnnotationsNamespace.update}.
+ *
+ * `kind`, `book_id` and `selected_text` are NOT updatable: only `color`,
+ * `note` and `location` are read. Anything else is dropped in silence - a 200
+ * with an unchanged row.
+ */
+export interface UpdateBookAnnotationInput {
+    readonly color?: string | null;
+    readonly note?: string | null;
+    /**
+     * Only sent when the key is present, because the server tests for the key
+     * rather than for a value. Passing `{}` therefore CLEARS the anchor rather
+     * than leaving it alone.
+     */
+    readonly location?: BookAnnotationLocation;
+}
+/** The `library.annotations` namespace, reachable as `oms.library.annotations`. */
+export declare class LibraryAnnotationsNamespace extends Resource {
+    /**
+     * `GET /book_annotations` - the caller's own highlights, notes, bookmarks and
+     * progress markers.
+     *
+     * There is no owner filter and there does not need to be one: a caller can
+     * only ever see its own rows - even on a book a thousand people have public
+     * access to.
+     *
+     * Unlike every read in the other two namespaces, this one needs a session,
+     * so an anonymous call is a `401`, not an empty list.
+     *
+     * Ordered by `created_at` ascending by default (the controller adds the
+     * `order(:created_at)` itself), which is reading order for a set of
+     * highlights. Override it with `order` for a "recently annotated" view.
+     *
+     * Filtering by `bookId` is the normal call, and it is what opens a reader:
+     * one request per book, not one per highlight.
+     *
+     * @throws {OmsApiError} 400 naming the offending key when a filter is not
+     *   one of `book_id`, `kind`, `id`, `created_at`, `updated_at`.
+     */
+    list(params?: ListBookAnnotationsParams, options?: RequestOptions): Promise<Paginated<BookAnnotation>>;
+    /**
+     * Every annotation on one book, in reading order, following pages until the
+     * book is exhausted.
+     *
+     * A convenience over {@link list} because this is what a reader does on open
+     * and because a heavily annotated book genuinely passes 500 rows - the point
+     * at which one page stops being enough and a naive caller silently loses the
+     * rest.
+     *
+     * `kinds` narrows to, say, highlights only. It becomes an `IN (...)`.
+     */
+    forBook(bookId: BookId, params?: {
+        kinds?: readonly BookAnnotationKind[];
+        pageSize?: number;
+    }, options?: RequestOptions): Promise<BookAnnotation[]>;
+    /**
+     * The reader's "where I left off" marker for one book, or `null` when they
+     * have never opened it.
+     *
+     * There is at most one, because
+     * {@link LibraryBooksNamespace.saveProgress} upserts on
+     * `(book, user, kind: "progress")`. This reads it back; that writes it.
+     */
+    progressFor(bookId: BookId, options?: RequestOptions): Promise<BookAnnotation | null>;
+    /**
+     * "What am I in the middle of?" - the reader's most recently touched progress
+     * markers, newest first.
+     *
+     * One request for the whole continue-reading shelf, which is the point: the
+     * alternative is one request per cover. The rows carry `book_id` and nothing
+     * about the book, so pair it with
+     * {@link LibraryBooksNamespace.list} filtered by `ids` to get the titles in a
+     * second request rather than in N.
+     *
+     * @param limit rows to return. Clamped to 500 by the server like any page.
+     */
+    continueReading(limit?: number, options?: RequestOptions): Promise<BookAnnotation[]>;
+    /**
+     * `POST /book_annotations` - records a highlight, a note or a bookmark.
+     *
+     * The author is taken from the session, so `user_id` is not sendable. The
+     * book additionally has to be visible to the caller, which is what lets a
+     * reader annotate somebody else's public book while keeping the annotation
+     * entirely private to them.
+     *
+     * Do NOT use this for reading progress. It would create a SECOND `progress`
+     * row - nothing here de-duplicates by kind - and the reader would then have
+     * two conflicting "where I left off" markers with no way to tell which is
+     * live. {@link LibraryBooksNamespace.saveProgress} upserts; this does not.
+     *
+     * Not retried by default: a replay after a lost answer duplicates the
+     * highlight.
+     *
+     * @throws {OmsAuthError} 401 twice over, with different bodies: `"Session
+     *   required to access this resource."` when anonymous, and `"You are not
+     *   authorized to create this resource"` when the book is not visible to
+     *   the caller - a 401 rather than the 404 you might expect.
+     * @throws {OmsApiError} 400 for a `kind` outside
+     *   {@link BOOK_ANNOTATION_KINDS}, or a note or selection over its length
+     *   cap.
+     */
+    create(input: CreateBookAnnotationInput, options?: RequestOptions): Promise<BookAnnotation>;
+    /**
+     * `PATCH /book_annotations/:id` - edits the note or the colour of an existing
+     * annotation, and optionally moves it.
+     *
+     * Only `color`, `note` and `location` are writable. `kind`, `book_id` and
+     * `selected_text` are dropped in silence - a `200` with an unchanged row,
+     * which is the failure mode worth knowing about here. To change a highlight
+     * into a note, delete and recreate.
+     *
+     * `location` is only sent when you pass one, because the server tests for
+     * the key: passing `{}` therefore CLEARS the anchor rather than leaving it
+     * alone.
+     *
+     * @throws {OmsAuthError} 401 when the annotation is not yours.
+     * @throws {OmsApiError} 404 for an unknown id - and for anyone else's
+     *   annotation, since nobody else's are ever visible.
+     */
+    update(id: BookAnnotationId, input: UpdateBookAnnotationInput, options?: RequestOptions): Promise<BookAnnotation>;
+    /**
+     * `DELETE /book_annotations/:id` - removes one annotation.
+     *
+     * Deleting a `progress` row is how a reader is put back at the start of a
+     * book; there is no other reset.
+     *
+     * @throws {OmsAuthError} 401 when the annotation is not yours.
+     * @throws {OmsApiError} 404 the second time round.
+     */
+    delete(id: BookAnnotationId, options?: RequestOptions): Promise<void>;
+}