@omelhorsite/sdk 0.3.0 → 0.4.1

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/dynamicQrs.d.ts

@@ -2,9 +2,9 @@
  * The `dynamicQrs` namespace: QR codes whose destination can be changed after
  * the code has been printed.
  *
- * Under the hood each one is a `ShortLink` in the reserved `"qr"` namespace
- * with a server-minted UUID endpoint, plus the styling the renderer needs. It
- * is a separate resource because the endpoint is not user-chosen, the payload
+ * Each one is a short link in the reserved `"qr"` namespace with a
+ * server-minted UUID endpoint, plus the styling a renderer needs. It is a
+ * separate resource because the endpoint is not user-chosen, the payload
  * carries `settings`, and the plain short-link listing filters system
  * namespaces out - a dynamic QR will never appear in `oms.shortLinks.list()`.
  *
@@ -20,30 +20,28 @@ import { type ShortLinkId, type ShortLinkStats } from "./shortLinks";
 /**
  * The reserved short-link namespace every dynamic QR lives in.
  *
- * `ShortLink::DYNAMIC_QR_NAMESPACE`. It is not a user choice and it never
- * changes on a record, which is why {@link DynamicQr.namespace} is typed as
- * this literal rather than as a string.
+ * It is not a user choice and it never changes on a record, which is why
+ * {@link DynamicQr.namespace} is typed as this literal rather than as a string.
  */
 export declare const DYNAMIC_QR_NAMESPACE = "qr";
 /** Public prefix a dynamic QR resolves under. */
 export declare const DYNAMIC_QR_BASE_URL = "https://omelhor.site/qr";
-/** Module shapes `DynamicQrs::SettingsSanitizer` accepts. Anything else is dropped. */
+/** Module shapes the server accepts. Anything else is dropped. */
 export type DynamicQrStyle = "classic" | "rounded" | "dots" | "extraRounded" | "classy" | "classyRounded";
 /**
  * Styling of a dynamic QR.
  *
- * The backend runs this bag through `DynamicQrs::SettingsSanitizer`, which
- * **silently drops** every key it does not recognise and every value that fails
- * its check - a bad `style`, a colour that is not `#rrggbb`. An unknown or
- * malformed key is therefore a no-op, not an error, and the only way to know
- * what stuck is to read `settings` back off the response.
+ * The server **silently drops** every key it does not recognise and every
+ * value that fails its check - a bad `style`, a colour that is not `#rrggbb`.
+ * An unknown or malformed key is therefore a no-op, not an error, and the only
+ * way to know what stuck is to read `settings` back off the response.
  *
  * The two exceptions that DO fail loudly are `logo` and `bg_image`: a value
  * that is neither `null`/`""` nor a `data:image/...` URI under the size cap is
  * a 400.
  *
- * The SDK does not render any of this; it is what the web tool's renderer
- * consumes. `oms.local.qr` draws a plain symbol from the matrix instead.
+ * The SDK does not render any of this. `oms.local.qr` draws a plain symbol
+ * from the matrix instead.
  */
 export interface DynamicQrSettings {
     /** Module shape. Values outside {@link DynamicQrStyle} are dropped. */
@@ -75,51 +73,38 @@ export interface DynamicQrSettings {
     /** How the background image sits against `bg_color`. Anything but `"replace"` reads as `"behind"`. */
     readonly bg_image_mode?: "replace" | "behind";
     /**
-     * The stored bag is free-form JSON, so a code saved by an older version of
-     * the web tool can carry keys this interface does not name.
+     * The stored bag is free-form JSON, so a code saved by an older client can
+     * carry keys this interface does not name.
      */
     readonly [key: string]: unknown;
 }
 /**
  * A dynamic QR code.
  *
- * `DynamicQrBlueprint` renders `ApplicationBlueprint`'s three automatic keys
- * (`id`, `created_at`, `updated_at`) plus exactly five more, and that is the
- * whole record. Two keys a client migrating off the old web service will
- * expect are NOT here and never were on this endpoint: `website_id` and
- * `website_managed`. They are residue of the websites feature, which was
- * extracted out of this backend entirely - there is no such column on
- * `short_links` and no such field on any blueprint, so anything declaring them
- * has been reading `undefined`.
- *
- * The blueprint is also never resolved automatically. A dynamic QR IS a
- * `ShortLink`, and `ShortLinkBlueprint` already owns that name with a
- * different shape (associations, no `settings`), so every call site passes
- * this blueprint explicitly. That is why the two records disagree about which
- * fields exist even though they are rows in one table.
+ * Eight keys, and that is the whole record. There is no `website_id` and no
+ * `website_managed`. A dynamic QR is a short link, but the two records carry
+ * different fields: this one has `settings` and no associations.
  */
 export interface DynamicQr extends Omit<BaseRecord, "id"> {
-    /** Integer primary key: a dynamic QR is a `short_links` row. See {@link ShortLinkId}. */
+    /** Integer primary key: a dynamic QR is a short link. See {@link ShortLinkId}. */
     readonly id: number;
     /** Current destination. Changing it re-points every printed copy at once. */
     readonly url: string;
     /** Server-assigned UUID the QR image encodes. Not choosable, not renameable. */
     readonly endpoint: string;
     /**
-     * Always {@link DYNAMIC_QR_NAMESPACE}. The controller writes it on create
-     * and nothing can change it afterwards, and the listing scope filters on it,
-     * so a record that reached you through this namespace cannot hold anything
-     * else.
+     * Always {@link DYNAMIC_QR_NAMESPACE}. Set on create, never changeable, and
+     * the listing filters on it, so a record that reached you through this
+     * namespace cannot hold anything else.
      */
     readonly namespace: typeof DYNAMIC_QR_NAMESPACE;
     /**
-     * Owner. The column is nullable because anonymous short links exist, but
-     * every route on this resource requires a credential and the controller
-     * always sets the owner, so in practice this is never `null` for a dynamic
-     * QR.
+     * Owner. Nullable because anonymous short links exist, but every route on
+     * this resource requires a credential and always sets the owner, so in
+     * practice this is never `null` for a dynamic QR.
      */
     readonly user_id: Id | null;
-    /** Never `null`: the blueprint substitutes `{}` for an unset bag. */
+    /** Never `null`: `{}` for an unset bag. */
     readonly settings: DynamicQrSettings & JsonObject;
 }
 /** Arguments for creating a dynamic QR. */
@@ -132,7 +117,7 @@ export interface CreateDynamicQrInput {
 /**
  * Fields that can change afterwards.
  *
- * `settings` is **merged** into the stored bag by the backend, not replaced, so
+ * `settings` is **merged** into the stored bag server-side, not replaced, so
  * an update can never unset a key by omitting it. To clear one, send it
  * explicitly with the value that means empty (`null` for `logo`/`bg_image`).
  */
@@ -146,10 +131,9 @@ export declare class DynamicQrsNamespace extends Resource {
      * `GET /dynamic_qrs` - every code you own, newest first.
      *
      * Returns a plain array rather than a page object, and that is not an
-     * oversight: this controller does not use `CrudActions` and ignores
-     * `modifiers[page]` entirely, so it always answers with the complete set. A
-     * `Paginated` here would be a fiction with a `next()` that refetched
-     * everything.
+     * oversight: the endpoint ignores `modifiers[page]` entirely and always
+     * answers with the complete set. A `Paginated` here would be a fiction with
+     * a `next()` that refetched everything.
      *
      * @throws {OmsAuthError} 401 when anonymous.
      */