@omelhorsite/sdk 0.3.0 → 0.4.1

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

@@ -7,16 +7,12 @@
  * an anonymous respondent hits. The SDK exposes both; the public calls work
  * without a credential unless the form turns `settings.require_login` on.
  *
- * The endpoint is not a column on the form: it lives on a short link paired
- * with it, which is why renaming it is a real operation and why availability
- * has its own lookup.
+ * The endpoint belongs to a short link paired with the form, which is why
+ * renaming it is a real operation and why availability has its own lookup.
  */
 import { type ApiClient, Resource } from "../http";
 import type { BaseRecord, FileInput, Id, Json, RequestOptions, Timestamp } from "../types";
-/**
- * The reserved short-link namespace a published form is served under.
- * `Form::NAMESPACE` / `ShortLink::FORM_NAMESPACE`.
- */
+/** The reserved short-link namespace a published form is served under. */
 export declare const FORM_NAMESPACE = "f";
 /**
  * Public prefix a published form resolves under, and the prefix
@@ -35,9 +31,8 @@ export type FormSchemaFieldType = "short_text" | "long_text" | "email" | "number
  * READ back off a form.
  *
  * `id` is not optional here even though it is optional when writing: the
- * sanitiser mints `SecureRandom.uuid` for any option that arrives without one,
- * so a stored option always has one. Write with
- * {@link FormSchemaFieldOptionInput}.
+ * server mints a UUID for any option that arrives without one, so a stored
+ * option always has one. Write with {@link FormSchemaFieldOptionInput}.
  */
 export interface FormSchemaFieldOption {
     /** Stable within the form. */
@@ -54,13 +49,13 @@ export interface FormSchemaFieldOptionInput {
  *
  * `id` is the key answers are filed under - NOT the label.
  *
- * Four of these keys are non-optional because `Forms::InputSanitizer#field`
- * writes them on EVERY field it keeps, whatever arrived: `id` (minted when
- * absent), `type`, `label` and `description` (both coerced with `.to_s`, so an
- * absent one is stored as `""`, not dropped) and `required` (cast to a real
- * boolean). The three that stay optional are genuinely absent from the stored
- * object when unused: `placeholder` is only kept when present, `options` only
- * for the three choice types, and `min`/`max` only for `number`.
+ * Five of these keys are non-optional because the server writes them on EVERY
+ * field it keeps, whatever arrived: `id` (minted when absent), `type`, `label`
+ * and `description` (an absent one is stored as `""`, not dropped) and
+ * `required` (always a real boolean). The rest are genuinely absent from the
+ * stored object when unused: `placeholder` is only kept when present,
+ * `options` only for the three choice types, and `min`/`max` only for
+ * `number`.
  *
  * Write with {@link FormSchemaFieldInput}, where all of that is optional.
  */
@@ -84,8 +79,8 @@ export interface FormSchemaField {
  * One field as WRITTEN.
  *
  * Every key but `type` may be omitted. `type` may not: a field whose type is
- * not one of `Form::FIELD_TYPES` is dropped from the schema in silence, which
- * looks exactly like a field that was never sent.
+ * not one of {@link FormSchemaFieldType} is dropped from the schema in
+ * silence, which looks exactly like a field that was never sent.
  *
  * A {@link FormSchemaField} read off a form is assignable here, so the
  * read-edit-write round trip needs no mapping.
@@ -105,8 +100,8 @@ export interface FormSchemaFieldInput {
 }
 /**
  * The field definition of a form, as read. Always `{ fields: [...] }`, never
- * `null` and never a bare array: the column is `NOT NULL DEFAULT
- * '{"fields":[]}'` and the sanitiser rebuilds the envelope on every write.
+ * `null` and never a bare array: a new form starts with an empty envelope and
+ * the server rebuilds it on every write.
  */
 export interface FormSchema {
     readonly fields: FormSchemaField[];
@@ -114,8 +109,8 @@ export interface FormSchema {
 /**
  * The field definition as written. The server rebuilds it from scratch keeping
  * only the keys {@link FormSchemaFieldInput} names, so anything extra is lost
- * without a word - and a write that is not a Hash at all is silently read as
- * `{ fields: [] }`, which empties the form rather than failing.
+ * without a word - and a write that is not an object at all is silently read
+ * as `{ fields: [] }`, which empties the form rather than failing.
  */
 export interface FormSchemaInput {
     readonly fields: FormSchemaFieldInput[];
@@ -153,10 +148,9 @@ export interface FormSettings {
 /**
  * A hosted form, owner view.
  *
- * One shape, not two: `FormsController` renders `form.render` with no view on
- * index, show, create AND update, so the `:extended` view `ApplicationBlueprint`
- * declares is never reached here and there is no richer variant to ask for.
- * Every key below is therefore on every response.
+ * One shape, not two: index, show, create AND update all answer the same
+ * record, and there is no richer variant to ask for. Every key below is on
+ * every response.
  */
 export interface Form extends BaseRecord {
     readonly user_id: Id;
@@ -180,19 +174,14 @@ export interface Form extends BaseRecord {
     readonly published_at: Timestamp | null;
     /** Bumped by every `getPublic` call, the SDK's included. Never `null`. */
     readonly views_count: number;
-    /**
-     * Answers recorded. Computed per request - batched into one grouped COUNT
-     * for a whole listing, one COUNT for a single render - so it is always
-     * current and never cached.
-     */
+    /** Answers recorded. Computed per request, so it is always current. */
     readonly submissions_count: number;
 }
 /**
  * The reduced form a public respondent is allowed to see.
  *
- * NOT a subset of {@link Form}: the controller builds this hash by hand rather
- * than rendering a blueprint view, so it carries `require_login` - which is not
- * a field on `Form` at all, only a key inside `settings` - and carries no
+ * NOT a subset of {@link Form}: it carries `require_login` - which is not a
+ * field on `Form` at all, only a key inside `settings` - and carries no
  * timestamps, no `user_id`, no counts and no `status`. Seven keys, always all
  * seven.
  */
@@ -208,14 +197,10 @@ export interface PublicForm {
 /**
  * One answered form.
  *
- * Deliberately has no `updated_at`: a submission is never edited, and
- * `FormSubmissionBlueprint` is the one blueprint in the API that inherits
- * `Blueprinter::Base` directly rather than `ApplicationBlueprint`, precisely so
- * that the automatic `updated_at` cannot creep in. Do not add it here on the
- * assumption that every record has one.
+ * Deliberately has no `updated_at`: a submission is never edited. Do not add
+ * it here on the assumption that every record has one.
  *
- * The other seven keys are all declared unconditionally, so all seven are
- * always present; four of them are nullable columns.
+ * All seven keys are always present; four of them are nullable.
  */
 export interface FormSubmission {
     readonly id: Id;
@@ -240,23 +225,18 @@ export interface FormSubmission {
     /** Parsed from the respondent's user agent. `null` when unparseable. */
     readonly device_name: string | null;
     /**
-     * When the answers were recorded. The controller writes `Time.current` on
-     * every submission it creates, so this is `null` only for a row predating
-     * that - but the column is nullable, so check before formatting it.
+     * When the answers were recorded. Set on every submission the API creates,
+     * so this is `null` only for an old row - but it is nullable, so check
+     * before formatting it.
      */
     readonly completed_at: Timestamp | null;
     readonly created_at: Timestamp;
 }
-/**
- * What `POST /form_attachments` answers with.
- *
- * Built by hand in the controller rather than by a blueprint, so this is the
- * literal four-key hash it renders and there is no `created_at` to read.
- */
+/** What `POST /form_attachments` answers with. Four keys, no `created_at`. */
 export interface FormAttachment {
     readonly id: Id;
     readonly filename: string;
-    /** One of `FormAttachment::ALLOWED_TYPES`; a save with anything else is a 400. */
+    /** JPEG, PNG, WebP, GIF or HEIC; a save with anything else is a 400. */
     readonly content_type: string;
     /** Absolute URL that serves the bytes inline, no credential required. */
     readonly url: string;
@@ -266,8 +246,8 @@ export interface FormAttachment {
  * conditional and mutually exclusive.
  *
  * `reason` appears only on the rejected branch and only ever holds
- * `"invalid"` - the controller has a single rejection reason for forms,
- * covering both a bad shape and a reserved word. (Link trees, which look
+ * `"invalid"` - the server has a single rejection reason for forms, covering
+ * both a bad shape and a reserved word. (Link trees, which look
  * identical, do distinguish the two; see `LinkTreeSlugAvailability`.)
  * `suggestions` appears only on the well-formed-but-taken branch.
  */
@@ -289,10 +269,9 @@ export interface FormEndpointAvailability {
  */
 export interface CreateFormInput {
     /**
-     * Optional, despite being the thing a person names the form by: the
-     * controller runs it through `.to_s.strip` and the model only validates its
-     * LENGTH (200 maximum), so an omitted title saves an untitled form rather
-     * than failing. Pass one.
+     * Optional, despite being the thing a person names the form by: the server
+     * trims it and only validates its LENGTH (200 maximum), so an omitted title
+     * saves an untitled form rather than failing. Pass one.
      */
     readonly title?: string;
     /**

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

@@ -11,11 +11,10 @@
  * {@link JobsNamespace.wait}, so the polling policy lives here once. Do not
  * write a second polling loop inside a tool module.
  *
- * Only two tools enqueue through the generic `jobs` table - background removal
- * and upscale. The other five are polled by re-reading their own row, which is
- * still not a reason to write a loop there: {@link pollUntilTerminal} is the
- * same engine with a different `poll` function, and that is what those modules
- * call.
+ * Only two tools hand back a generic job - background removal and upscale.
+ * The other five are polled by re-reading their own record, which is still not
+ * a reason to write a loop there: {@link pollUntilTerminal} is the same engine
+ * with a different `poll` function, and that is what those modules call.
  *
  * The loop is deliberately dumb and bounded:
  *
@@ -44,9 +43,10 @@
  * 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.
+ * The five status strings, spelled the way the API spells them.
  *
  * `complete`, not `completed`. `canceled`, one L. Reach for this object instead
  * of typing the literal: a loop that waits for `"completed"` waits forever.
@@ -70,31 +70,24 @@ export declare function isJobTerminal(status: string): boolean;
 /**
  * A background job.
  *
- * `JobBlueprint` declares thirteen fields and nothing else, so EVERY key below
- * is present on every response. A `?` here would mean "the server sometimes
- * leaves this out", and it never does; what varies is the VALUE, because most
- * of these are nullable columns that fill in as the job moves.
+ * EVERY key below is present on every response. A `?` here would mean "the
+ * server sometimes leaves this out", and it never does; what varies is the
+ * VALUE, because most of these are nullable and fill in as the job moves.
  *
- * Two keys are deliberately NOT here, and a client migrating off the old web
- * service will expect them: `updater_id` and `destroyer_id`. Both columns
- * exist on the `jobs` table and both are indexed, but `JobBlueprint` renders
- * NEITHER, so anything declaring them has been reading `undefined` for as long
- * as it has existed. Declaring them here would only move the lie.
+ * There is no `updater_id` and no `destroyer_id`; anything declaring them
+ * reads `undefined`.
  */
 export interface Job extends BaseRecord {
     readonly status: JobStatus;
     /**
-     * Feature-level kind of the run. `Job::JOB_TYPES` holds exactly two strings:
-     * `"omsvs"` (vocal separation) and `"unknown"`, which is the column default
-     * every generic enqueue gets - the upscale and background-removal proxies
-     * included. It is NOT the worker's class name, and a third value cannot
-     * appear without a model change, because an inclusion validation rejects it.
+     * Feature-level kind of the run: `"omsvs"` (vocal separation) or
+     * `"unknown"`, which is what every generic enqueue gets - the upscale and
+     * background-removal runs included. It is NOT the name of the work done.
      */
     readonly job_type: string;
     /**
-     * Enqueue-time arguments. The column is `jsonb DEFAULT '{}'`, so a row whose
-     * enqueuer wrote nothing carries `{}` rather than `null`. Shape depends on
-     * `job_type`.
+     * Enqueue-time arguments. `{}` rather than `null` when the enqueuer wrote
+     * nothing. Shape depends on `job_type`.
      */
     readonly payload: Json;
     /** Set when a worker claimed the job; `null` while it is still `"pending"`. */
@@ -102,22 +95,20 @@ export interface Job extends BaseRecord {
     /** Set when the job reached a terminal state, cancellation included. */
     readonly finished_at: Timestamp | null;
     /**
-     * Percentage, an integer in `[0, 100]`. The column is `NOT NULL DEFAULT 0`
-     * and the model validates the range, so this is a real number from the
-     * moment the row exists: `0` means "not started", never "unknown".
+     * Percentage, an integer in `[0, 100]`. A real number from the moment the
+     * row exists: `0` means "not started", never "unknown".
      */
     readonly progress: number;
     /**
      * Failure message once `status === "failed"` - and ALSO the reason once
-     * `"canceled"`, because `Job#cancel!` writes it into this same column. A
+     * `"canceled"`, because a cancellation writes its reason here too. A
      * non-null `error` therefore does not by itself mean the work failed. Read
      * `status`.
      */
     readonly error: string | null;
     /**
-     * Whatever the worker returned, stored by `ApplicationJob`'s
-     * `around_perform`. Shape depends on `job_type`, and the two proxies worth
-     * naming both answer an object carrying a signed download link:
+     * Whatever the work returned. Shape depends on `job_type`, and the two
+     * tools worth naming both answer an object carrying a signed download link:
      *
      * - upscale: `{ upscale_id, result_url }`;
      * - background removal: `{ background_removal_id, result_url }`.
@@ -143,10 +134,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;
@@ -210,9 +203,8 @@ export declare class JobsNamespace extends Resource {
      * an anonymous caller sees an empty page - never a 401, because the scope is
      * empty rather than forbidden.
      *
-     * @throws {OmsApiError} 400 naming the key when a filter is not on the
-     *   controller's allowlist (`id`, `job_type`, `status`, `created_at`,
-     *   `updated_at`, `finished_at`).
+     * @throws {OmsApiError} 400 naming the key when a filter is not one of
+     *   `id`, `job_type`, `status`, `created_at`, `updated_at`, `finished_at`.
      */
     list(params?: ListJobsParams, options?: RequestOptions): Promise<Paginated<Job>>;
     /**
@@ -224,7 +216,7 @@ export declare class JobsNamespace extends Resource {
      *
      * @throws {OmsApiError} 404 when the job is gone, which for a finished job
      *   also happens once its retention window expires. A wrong, expired or
-     *   missing watch token is the same 404, not a 401: the controller never says
+     *   missing watch token is the same 404, not a 401: the server never says
      *   whether the id exists.
      */
     get(ref: JobRef | Id, options?: RequestOptions): Promise<Job>;
@@ -262,13 +254,12 @@ export declare function jobRef(ref: JobRef | Id): JobRef;
  * Renders a job as a {@link Progress}.
  *
  * `total` is 100 rather than `undefined` because `progress` is a percentage the
- * server always has: the column is `NOT NULL DEFAULT 0`, so there is no
- * "unknown" to be honest about.
+ * server always has: there is no "unknown" to be honest about.
  *
  * The `typeof` guard is not defensive typing for its own sake. `Job.progress`
- * is declared non-nullable because the column is, but this function is also
- * handed rows that came off `JobChannel` and rows a host deserialised itself,
- * and reading `undefined` as `NaN%` would put a broken number on a progress
- * bar rather than a zero.
+ * is declared non-nullable, but this function is also handed rows that came
+ * off the realtime job channel and rows a host deserialised itself, and
+ * reading `undefined` as `NaN%` would put a broken number on a progress bar
+ * rather than a zero.
  */
 export declare function jobProgress(job: Job): Progress;

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>;
+}