@nohead/sdk 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ Changes to `@nohead/sdk` that you can notice. Versions follow
 releases; a change that could break your code is a major one. Each release's
 section is its GitHub release's notes.
 
+## 0.11.0
+
+- `records.diff` takes `richText`, and the client's `richText` now applies to
+  it: a rich text field's `before` and `after` read as HTML or Markdown
+  instead of documents. A revert preview's `changes` follow `richText` too.
+
+## 0.10.0
+
+- Rich text reads as HTML or Markdown: `richText: "html"` (or `"markdown"`)
+  on the client, or in a request's options, sends the API's `rich_text`
+  query parameter on the methods that return records or drafts, so a rich
+  text field's value in `data` is a string instead of the document. A
+  request's `richText` overrides the client's, and `withOptions` can change
+  it. Writing Markdown already worked: `data` is sent as it is.
+
 ## 0.9.0
 
 - **Breaking:** the client no longer reads `NOHEAD_API_URL`: a stray value

package/README.md

@@ -22,6 +22,7 @@ for await (const post of nohead.records.list("posts", {
 - [Configuration](#configuration)
 - [Records](#records)
 - [Drafts](#drafts)
+- [Rich text](#rich-text)
 - [Pagination](#pagination)
 - [Errors](#errors)
 - [Retries and idempotency](#retries-and-idempotency)
@@ -65,10 +66,11 @@ const nohead = new Nohead({
 | `headers`    | `{}`                    | Added to every request.                                                                   |
 | `warnings`   | `true`                  | Logs deprecation and plan usage warnings, once each.                                      |
 | `onRetry`    |                         | Called before each retry. See [retries](#retries-and-idempotency).                        |
+| `richText`   | `"document"`            | How rich text reads: `"html"` or `"markdown"`. See [rich text](#rich-text).               |
 
 An empty option counts as unset, as an empty environment variable does: `apiKey: ""` falls back to `NOHEAD_API_KEY`, and `baseUrl: ""` to `https://api.nohead.io`. The base URL comes only from `baseUrl`, never from the environment. A `baseUrl` that isn't an `http` or `https` URL throws.
 
-`withOptions` copies a client with another `timeout`, `maxRetries` or `onRetry`, or more `headers` (added to the client's). The copy shares the key's project, so it doesn't look it up again:
+`withOptions` copies a client with another `timeout`, `maxRetries`, `onRetry` or `richText`, or more `headers` (added to the client's). The copy shares the key's project, so it doesn't look it up again:
 
 ```ts
 const patient = nohead.withOptions({ timeout: 120_000, maxRetries: 5 })
@@ -142,6 +144,24 @@ await nohead.drafts.merge(draft.id) // or drafts.schedule(draft.id, { merge_at }
 - `drafts.discard` deletes one for good.
 - Drafts take the type of their data as records do: `drafts.get<Post>(id)` is a `Nohead.Draft<Post>` (also exported as `NoheadDraft`).
 
+## Rich text
+
+A rich text field takes Markdown or a ProseMirror document, and reads as the document. To read it as HTML or Markdown, set `richText` on the client, or on one request:
+
+```ts
+await nohead.records.update(id, { data: { body: "Hello **world**" } })
+
+const site = nohead.withOptions({ richText: "html" })
+const post = await site.records.get<{ body: string }>(id)
+const html = `<article>${post.data.body}</article>` // safe to put in a page as it is
+
+await nohead.drafts.get(draftId, {}, { richText: "markdown" })
+```
+
+- A rich text field's value is then a string: type it as one in the data's type, as above.
+- It applies to the methods that return records or drafts, to the records they embed with `expand`, and to the `before` and `after` of a `diff` or a revert preview's `changes`; a request's `richText` overrides the client's. History (`revisions`) and webhooks keep documents.
+- A string you write is read as Markdown, so write back Markdown or the document, never the HTML: with `richText: "html"` on the client, writes answer with HTML too.
+
 ## Pagination
 
 List methods return a promise of the first page that you can also loop over:

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { PagePromise } from "./api-promise.ts";
-import { type ClientOptions, type CopyOptions, type RequestOptions } from "./core.ts";
+import { type ClientOptions, type CopyOptions, type RichTextOptions } from "./core.ts";
 import type * as G from "./generated/types.gen.ts";
 import { Assets } from "./resources/assets.ts";
 import { Drafts } from "./resources/drafts.ts";
@@ -32,8 +32,8 @@ export declare class Nohead {
     readonly health: Health;
     constructor(options?: ClientOptions);
     /**
-     * A copy of the client with another `timeout`, `maxRetries` or `onRetry`,
-     * or more `headers` (added to this client's). It shares the key's project,
+     * A copy of the client with another `timeout`, `maxRetries`, `onRetry` or
+     * `richText`, or more `headers` (added to this client's). It shares the key's project,
      * so it doesn't look it up again.
      *
      *   await nohead.withOptions({ timeout: 5_000 }).records.get(id)
@@ -43,7 +43,7 @@ export declare class Nohead {
      * Full-text search across the key's project (or some of its
      * collections), most relevant first, through the first 1,000 hits.
      */
-    search<D = RecordData>(query: string, params?: ProjectSearchParams, options?: RequestOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
+    search<D = RecordData>(query: string, params?: ProjectSearchParams, options?: RichTextOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
 }
 /** The main types, also reachable as `Nohead.Record`, `Nohead.Collection`… */
 export declare namespace Nohead {

package/dist/client.js

@@ -44,8 +44,8 @@ export class Nohead {
         this.health = new Health(core);
     }
     /**
-     * A copy of the client with another `timeout`, `maxRetries` or `onRetry`,
-     * or more `headers` (added to this client's). It shares the key's project,
+     * A copy of the client with another `timeout`, `maxRetries`, `onRetry` or
+     * `richText`, or more `headers` (added to this client's). It shares the key's project,
      * so it doesn't look it up again.
      *
      *   await nohead.withOptions({ timeout: 5_000 }).records.get(id)

package/dist/core.d.ts

@@ -2,6 +2,7 @@ import { APIPromise, PagePromise } from "./api-promise.ts";
 import { NoheadError } from "./errors.ts";
 import { type OperationId, type Operations } from "./generated/operations.gen.ts";
 import type { ListMeta } from "./generated/types.gen.ts";
+import type { RichText } from "./types.ts";
 export declare const DEFAULT_BASE_URL = "https://api.nohead.io";
 export interface ClientOptions {
     /**
@@ -31,9 +32,15 @@ export interface ClientOptions {
     warnings?: boolean;
     /** Called before each retry, for example to report it. */
     onRetry?: (retry: RetryEvent) => void;
+    /**
+     * How rich text fields read in the records and drafts returned: as HTML
+     * or Markdown strings, or as the stored document (the API's default). A
+     * request's `richText` overrides it.
+     */
+    richText?: RichText;
 }
 /** What `withOptions` changes in a client's copy. */
-export type CopyOptions = Pick<ClientOptions, "timeout" | "maxRetries" | "headers" | "onRetry">;
+export type CopyOptions = Pick<ClientOptions, "timeout" | "maxRetries" | "headers" | "onRetry" | "richText">;
 /** A retry about to happen (`onRetry`). */
 export interface RetryEvent {
     /** 1 for the first retry of the request, 2 for the second… */
@@ -57,6 +64,15 @@ export interface RequestOptions {
     maxRetries?: number;
     headers?: Record<string, string>;
 }
+/** Options of operations that return records or drafts. */
+export interface RichTextOptions extends RequestOptions {
+    /**
+     * How rich text fields read in the records or drafts returned (and in
+     * records they embed with `expand`), overriding the client's `richText`:
+     * `"html"` or `"markdown"` strings, or the stored `"document"`.
+     */
+    richText?: RichText;
+}
 /** Options of writes that change records or the schema. */
 export interface WriteOptions extends RequestOptions {
     /**
@@ -83,15 +99,21 @@ export interface ConditionalWriteOptions extends WriteOptions, ConditionalReques
 type HeadersOf<Op extends OperationId> = Operations[Op]["data"] extends {
     headers?: infer H;
 } ? keyof NonNullable<H> : never;
+/** The query parameters an operation declares. */
+type QueryOf<Op extends OperationId> = Operations[Op]["data"] extends {
+    query?: infer Q;
+} ? keyof NonNullable<Q> : never;
 /**
- * The options an operation takes: `ifMatch` and `changeNote` only where it
- * declares `If-Match` and `Nohead-Change-Note`, so a method can't offer them
- * elsewhere.
+ * The options an operation takes: `ifMatch`, `changeNote` and `richText`
+ * only where it declares `If-Match`, `Nohead-Change-Note` and `rich_text`,
+ * so a method can't offer them elsewhere.
  */
 export type OptionsOf<Op extends OperationId> = RequestOptions & ("If-Match" extends HeadersOf<Op> ? Pick<ConditionalRequestOptions, "ifMatch"> : {
     ifMatch?: never;
 }) & ("Nohead-Change-Note" extends HeadersOf<Op> ? Pick<WriteOptions, "changeNote"> : {
     changeNote?: never;
+}) & ("rich_text" extends QueryOf<Op> ? Pick<RichTextOptions, "richText"> : {
+    richText?: never;
 });
 export interface RequestInput {
     path?: Record<string, string | number | undefined>;
@@ -109,7 +131,7 @@ export declare class Core {
     projectId(): Promise<string>;
     request<Op extends OperationId>(operation: Op, input?: RequestInput, options?: OptionsOf<Op>): APIPromise<Operations[Op]["response"]>;
     /** A list operation as pages of `Item`. */
-    paginate<Item, Meta extends ListMeta = ListMeta>(operation: OperationId, input: RequestInput, options?: RequestOptions): PagePromise<Item, Meta>;
+    paginate<Item, Meta extends ListMeta = ListMeta, Op extends OperationId = OperationId>(operation: Op, input: RequestInput, options?: OptionsOf<Op>): PagePromise<Item, Meta>;
     /**
      * `fetch` with this client's retries, for an upload's presigned URL. fetch
      * shows no upload progress, so each attempt may take as long as sending

package/dist/core.js

@@ -1,6 +1,6 @@
 import { APIPromise, Page, PagePromise, } from "./api-promise.js";
 import { AbortError, ConnectionError, NoheadError, TimeoutError, apiError, isObject, retryAfterSeconds, } from "./errors.js";
-import { OPERATIONS, } from "./generated/operations.gen.js";
+import { OPERATIONS, RICH_TEXT_OPERATIONS, } from "./generated/operations.gen.js";
 import { VERSION } from "./version.js";
 export const DEFAULT_BASE_URL = "https://api.nohead.io";
 const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
@@ -18,6 +18,7 @@ export class Core {
     #timeout;
     #warnings;
     #onRetry;
+    #richText;
     // The project lookup, shared with the client's copies (`withOptions`).
     #project;
     constructor(options, project = {}) {
@@ -34,6 +35,7 @@ export class Core {
         this.#timeout = options.timeout ?? 60_000;
         this.#warnings = options.warnings ?? true;
         this.#onRetry = options.onRetry;
+        this.#richText = options.richText;
         this.#project = project;
         if (options.projectId)
             project.id ??= Promise.resolve(options.projectId);
@@ -49,6 +51,7 @@ export class Core {
             timeout: options.timeout ?? this.#timeout,
             warnings: this.#warnings,
             onRetry: options.onRetry ?? this.#onRetry,
+            richText: options.richText || this.#richText,
         }, this.#project);
     }
     /** The API key's project, from `GET /v1/me` the first time. */
@@ -117,6 +120,11 @@ export class Core {
         const { method, path } = OPERATIONS[operation];
         const url = new URL(this.#baseUrl + (await this.#path(path, input.path)));
         appendQuery(url.searchParams, input.query);
+        // The call's, else the client's, and only where the operation takes it.
+        const richText = options.richText || this.#richText;
+        if (richText && RICH_TEXT_OPERATIONS.has(operation)) {
+            url.searchParams.set("rich_text", richText);
+        }
         // Each name once, whatever its case: the defaults, then the client's
         // headers, the call's, and those of the request options, which win.
         const headers = {};

package/dist/generated/operations.gen.d.ts

@@ -326,6 +326,8 @@ export declare const OPERATIONS: {
     };
 };
 export type OperationId = keyof typeof OPERATIONS;
+/** The operations that take `rich_text`: those returning records or drafts. */
+export declare const RICH_TEXT_OPERATIONS: ReadonlySet<OperationId>;
 export interface Operations {
     assets_complete: {
         data: T.AssetsCompleteData;

package/dist/generated/operations.gen.js

@@ -81,3 +81,28 @@ export const OPERATIONS = {
     webhooks_test: { method: "POST", path: "/v1/webhooks/{webhook_id}/test" },
     webhooks_update: { method: "PATCH", path: "/v1/webhooks/{webhook_id}" },
 };
+/** The operations that take `rich_text`: those returning records or drafts. */
+export const RICH_TEXT_OPERATIONS = new Set([
+    "collections_search",
+    "drafts_create",
+    "drafts_discard",
+    "drafts_get",
+    "drafts_list",
+    "drafts_merge",
+    "drafts_schedule",
+    "drafts_unschedule",
+    "drafts_update",
+    "projects_search",
+    "record_drafts_list",
+    "record_revisions_revert",
+    "records_bulk",
+    "records_create",
+    "records_delete",
+    "records_diff",
+    "records_get",
+    "records_list",
+    "records_publish",
+    "records_restore",
+    "records_unpublish",
+    "records_update",
+]);

package/dist/generated/types.gen.d.ts

@@ -219,6 +219,9 @@ export type LongTextFieldConfiguration = {
     min_length?: number;
     max_length?: number;
 };
+/**
+ * A rich text document up to 1,000,000 bytes (`too_large`), written as Markdown or a document (see `RecordData`).
+ */
 export type RichTextFieldConfiguration = {
     /**
      * Help text for editors.
@@ -388,6 +391,9 @@ export type RelationFieldConfiguration = {
      */
     target_collection_id: string;
 };
+/**
+ * Any JSON value up to 100,000 bytes (`too_large`), nested at most 32 levels deep (`too_deep`): for data with a shape of its own, such as settings or another service's payload. Content belongs in typed fields, and large data in an asset.
+ */
 export type JsonFieldConfiguration = {
     /**
      * Help text for editors.
@@ -595,6 +601,9 @@ export type CollectionCreate = {
     slug: string;
     description?: string | null;
     public_search?: boolean;
+    /**
+     * At most 100 (`too_many`).
+     */
     fields?: Array<FieldCreate>;
 };
 export type CollectionUpdate = {
@@ -967,14 +976,38 @@ export type MergedDraft = {
     edited_by: Array<Actor>;
 };
 /**
- * Field values keyed by field `key`. A rich text value is a
- * ProseMirror/Tiptap JSON document (`{"type": "doc", "content": [...]}`).
- * An image of an asset in it is `{"type": "image", "attrs": {"asset_id":
- * "ast_...", "alt": "..."}}`, between the document's blocks (not inside
- * a list or quote), at most 100 per document (`too_many_images`); a
- * newly shown image must be an uploaded JPEG, PNG, GIF, WebP or AVIF of
- * the project (`invalid_reference`, `type_not_accepted`). `expand` embeds the assets, and published-only
- * keys can read the images of published records.
+ * Field values keyed by field `key`.
+ *
+ * A rich text value is written as Markdown (GitHub Flavored, a string)
+ * or as a ProseMirror JSON document (`{"type": "doc", "content": [...]}`),
+ * and stored and read as the document (`rich_text` reads it as HTML or
+ * Markdown). Markdown is converted as closely as the vocabulary allows:
+ * headings below h3 become h3, task list items plain items, footnotes and
+ * raw HTML text. A document uses the web editor's vocabulary (Tiptap's
+ * StarterKit and tables) and nothing else; another name is refused with
+ * `invalid_format`, naming ours where one fits (`strong` is `bold`):
+ *
+ * - blocks: `paragraph`, `heading` (`level` 1-3), `blockquote`,
+ * `bulletList` and `orderedList` (`start`, `type`) of `listItem`
+ * (starting with a paragraph), `codeBlock` (`language`),
+ * `horizontalRule`, and `table` of `tableRow` of `tableHeader` or
+ * `tableCell` (`colspan`, `rowspan`, `colwidth`, `align`); any block
+ * may have `dir` (`auto`, `ltr`, `rtl`);
+ * - inline: `text` (non-empty) and `hardBreak`;
+ * - marks on text: `bold`, `italic`, `strike`, `underline`, `code` (alone),
+ * and `link` (`href`, and `target`, `rel`, `class`, `title`); a link's
+ * `href` is an `http`, `https`, `mailto`, `tel` or relative URL.
+ *
+ * An image of an asset is `{"type": "image", "attrs": {"asset_id":
+ * "ast_...", "alt": "..."}}` (in Markdown `![alt](ast_...)`, or the
+ * asset's `image_url`), between the document's blocks (not inside a list,
+ * quote or table), at most 100 per document (`too_many_images`); a newly
+ * shown image must be an uploaded JPEG, PNG, GIF, WebP, AVIF or SVG of
+ * the project (`invalid_reference`, `type_not_accepted`). `expand` embeds
+ * the assets, and published-only keys can read the images of published
+ * records. A record holds at
+ * most 2,000,000 bytes of values, all fields together (`too_large` on
+ * `data`); one already larger can still be edited without growing.
  *
  */
 export type RecordData = {
@@ -1050,8 +1083,14 @@ export type RecordList = {
  *
  */
 export type Change = {
+    /**
+     * The field's key now, after any rename (its last key if it was deleted); null if the field no longer exists.
+     */
     field?: string | null;
     field_id?: string;
+    /**
+     * Whether the field has been deleted since.
+     */
     field_deleted?: boolean;
     attribute?: 'published_at' | 'deleted_at';
     kind: 'added' | 'changed' | 'removed';
@@ -1108,6 +1147,9 @@ export type RevertPreview = {
     record_id: string;
     to_revision: number;
     data: RecordData;
+    /**
+     * What the revert would change. Rich text values read as `rich_text` asks, like `data`; a change that HTML or Markdown can't show (an underline, in Markdown) reads the same on both sides.
+     */
     changes: Array<Change>;
 };
 export type FeatureFlags = {
@@ -1523,9 +1565,11 @@ export type AssetProperties = {
      */
     purge_after: NullableTimestamp;
     /**
-     * The URL of the whole image, for ready images (JPEG, PNG, GIF, WebP
-     * or AVIF), deleted ones included until they are purged; null
-     * otherwise. Image URLs are open and never expire. For a rendition,
+     * The URL of the whole image, for ready images (JPEG, PNG, GIF, WebP,
+     * AVIF or SVG), deleted ones included until they are purged; null
+     * otherwise. Image URLs are open and never expire. An SVG is served
+     * as SVG without its scripts, unless a format such as `@webp`
+     * rasterizes it. For a rendition,
      * write [imgproxy processing options](https://docs.imgproxy.net/usage/processing)
      * before `/plain/`, and a format after `@`: for example
      * `https://images.nohead.io/rs:fill:800:600/g:sm/plain/…@webp`. Renditions
@@ -1536,7 +1580,7 @@ export type AssetProperties = {
      */
     image_url: string | null;
     /**
-     * The URL of a small rendition (fits in 640×640, WebP), for ready images and SVGs (rasterized; SVGs have no `image_url`), deleted ones included until they are purged; null otherwise.
+     * The URL of a small rendition (fits in 640×640, WebP), for ready images and SVGs (rasterized), deleted ones included until they are purged; null otherwise.
      */
     preview_url: string | null;
     /**
@@ -1687,6 +1731,10 @@ export type RevisionId = string;
  * Per-record revision number.
  */
 export type RevisionNumber = number;
+/**
+ * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+ */
+export type RichText = 'document' | 'html' | 'markdown';
 /**
  * Comma-separated relation, asset or rich text field keys whose records or assets to embed under `expanded` (at most 5); for a rich text field, the assets its images show. Embedding needs permission to read what is embedded: `records:read` for relations, `assets:read` for assets and rich text (`403` otherwise).
  */
@@ -1695,8 +1743,7 @@ export type Expand = string;
  * `filter[<key>]=value` (equal), or `filter[<key>][<operator>]=value`;
  * filters combine with AND. Keys are field keys, `published_at`,
  * `deleted` (`true` lists soft-deleted records instead) and, in record
- * lists and counts, `created_at` and `updated_at`. In search,
- * `published_at` takes only `exists`.
+ * lists and counts, `created_at` and `updated_at`.
  *
  * - `eq`, `ne`: equal, not equal. For fields with several values,
  * "contains" and "does not contain". `ne` matches records with no value.
@@ -1836,12 +1883,15 @@ export type RecordsListData = {
         collection_id: string;
     };
     query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
         /**
          * `filter[<key>]=value` (equal), or `filter[<key>][<operator>]=value`;
          * filters combine with AND. Keys are field keys, `published_at`,
          * `deleted` (`true` lists soft-deleted records instead) and, in record
-         * lists and counts, `created_at` and `updated_at`. In search,
-         * `published_at` takes only `exists`.
+         * lists and counts, `created_at` and `updated_at`.
          *
          * - `eq`, `ne`: equal, not equal. For fields with several values,
          * "contains" and "does not contain". `ne` matches records with no value.
@@ -1964,7 +2014,12 @@ export type RecordsCreateData = {
          */
         collection_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/collections/{collection_id}/records';
 };
 export type RecordsCreateErrors = {
@@ -2063,7 +2118,12 @@ export type RecordsDeleteData = {
     path: {
         record_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/records/{record_id}';
 };
 export type RecordsDeleteErrors = {
@@ -2119,6 +2179,10 @@ export type RecordsGetData = {
         record_id: string;
     };
     query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
         /**
          * Comma-separated relation, asset or rich text field keys whose records or assets to embed under `expanded` (at most 5); for a rich text field, the assets its images show. Embedding needs permission to read what is embedded: `records:read` for relations, `assets:read` for assets and rich text (`403` otherwise).
          */
@@ -2198,7 +2262,12 @@ export type RecordsUpdateData = {
     path: {
         record_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/records/{record_id}';
 };
 export type RecordsUpdateErrors = {
@@ -2265,8 +2334,7 @@ export type RecordsCountData = {
          * `filter[<key>]=value` (equal), or `filter[<key>][<operator>]=value`;
          * filters combine with AND. Keys are field keys, `published_at`,
          * `deleted` (`true` lists soft-deleted records instead) and, in record
-         * lists and counts, `created_at` and `updated_at`. In search,
-         * `published_at` takes only `exists`.
+         * lists and counts, `created_at` and `updated_at`.
          *
          * - `eq`, `ne`: equal, not equal. For fields with several values,
          * "contains" and "does not contain". `ne` matches records with no value.
@@ -2365,7 +2433,12 @@ export type RecordsBulkData = {
          */
         collection_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/collections/{collection_id}/record-batches';
 };
 export type RecordsBulkErrors = {
@@ -2448,7 +2521,12 @@ export type RecordsRestoreData = {
     path: {
         record_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/records/{record_id}/restore';
 };
 export type RecordsRestoreErrors = {
@@ -2539,7 +2617,12 @@ export type RecordsUnpublishData = {
     path: {
         record_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/records/{record_id}/publication';
 };
 export type RecordsUnpublishErrors = {
@@ -2669,7 +2752,12 @@ export type RecordsPublishData = {
     path: {
         record_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/records/{record_id}/publication';
 };
 export type RecordsPublishErrors = {
@@ -3155,6 +3243,10 @@ export type RecordRevisionsRevertData = {
         revision: number;
     };
     query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
         dry_run?: boolean;
     };
     url: '/v1/records/{record_id}/revisions/{revision}/revert';
@@ -3218,6 +3310,10 @@ export type RecordsDiffData = {
     query: {
         from: number;
         to: number;
+        /**
+         * How rich text values read in `changes`: `document`, the stored ProseMirror JSON document, or written as `html` or `markdown`, as records read with `rich_text`. Record history and webhooks keep documents. A change that HTML or Markdown can't show (an underline, in Markdown) reads the same on both sides. In HTML and Markdown, text from before a field became rich text reads as paragraphs; an older value that is no document of today's vocabulary, or a redacted one, is kept as stored.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
     };
     url: '/v1/records/{record_id}/diff';
 };
@@ -3264,6 +3360,10 @@ export type RecordDraftsListData = {
         record_id: string;
     };
     query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
         /**
          * Page size.
          */
@@ -3333,7 +3433,12 @@ export type DraftsCreateData = {
     path: {
         record_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/records/{record_id}/drafts';
 };
 export type DraftsCreateErrors = {
@@ -3390,6 +3495,10 @@ export type DraftsListData = {
         collection_id: string;
     };
     query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
         sort?: 'updated_at' | '-updated_at';
         /**
          * Page size.
@@ -3464,7 +3573,12 @@ export type DraftsDiscardData = {
     path: {
         draft_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/drafts/{draft_id}';
 };
 export type DraftsDiscardErrors = {
@@ -3520,6 +3634,10 @@ export type DraftsGetData = {
         draft_id: string;
     };
     query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
         /**
          * Comma-separated relation, asset or rich text field keys whose records or assets to embed under `expanded` (at most 5); for a rich text field, the assets its images show. Embedding needs permission to read what is embedded: `records:read` for relations, `assets:read` for assets and rich text (`403` otherwise).
          */
@@ -3589,7 +3707,12 @@ export type DraftsUpdateData = {
     path: {
         draft_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/drafts/{draft_id}';
 };
 export type DraftsUpdateErrors = {
@@ -3678,7 +3801,12 @@ export type DraftsMergeData = {
     path: {
         draft_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/drafts/{draft_id}/merge';
 };
 export type DraftsMergeErrors = {
@@ -3753,7 +3881,12 @@ export type DraftsUnscheduleData = {
     path: {
         draft_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/drafts/{draft_id}/schedule';
 };
 export type DraftsUnscheduleErrors = {
@@ -3818,7 +3951,12 @@ export type DraftsScheduleData = {
     path: {
         draft_id: string;
     };
-    query?: never;
+    query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
+    };
     url: '/v1/drafts/{draft_id}/schedule';
 };
 export type DraftsScheduleErrors = {
@@ -5938,6 +6076,10 @@ export type CollectionsSearchData = {
         collection_id: string;
     };
     query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
         /**
          * The words to search for; empty matches everything.
          */
@@ -5954,8 +6096,7 @@ export type CollectionsSearchData = {
          * `filter[<key>]=value` (equal), or `filter[<key>][<operator>]=value`;
          * filters combine with AND. Keys are field keys, `published_at`,
          * `deleted` (`true` lists soft-deleted records instead) and, in record
-         * lists and counts, `created_at` and `updated_at`. In search,
-         * `published_at` takes only `exists`.
+         * lists and counts, `created_at` and `updated_at`.
          *
          * - `eq`, `ne`: equal, not equal. For fields with several values,
          * "contains" and "does not contain". `ne` matches records with no value.
@@ -6039,6 +6180,10 @@ export type ProjectsSearchData = {
         project_id: string;
     };
     query?: {
+        /**
+         * How rich text fields read in the records and drafts returned (and in records they embed with `expand`): `document`, the stored ProseMirror JSON document; `html`, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or `markdown` (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no `expand`: in HTML a WebP rendition at most 1600 pixels wide with its `width` and `height` (an SVG as itself), in Markdown the asset's `image_url`. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.
+         */
+        rich_text?: 'document' | 'html' | 'markdown';
         /**
          * The words to search for; empty matches everything.
          */

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Nohead } from "./client.ts";
 export { APIPromise, Page, PagePromise, type APIResponse, } from "./api-promise.ts";
-export { DEFAULT_BASE_URL, type ClientOptions, type ConditionalRequestOptions, type ConditionalWriteOptions, type CopyOptions, type RequestOptions, type RetryEvent, type WriteOptions, } from "./core.ts";
+export { DEFAULT_BASE_URL, type ClientOptions, type ConditionalRequestOptions, type ConditionalWriteOptions, type CopyOptions, type RequestOptions, type RetryEvent, type RichTextOptions, type WriteOptions, } from "./core.ts";
 export { APIError, AbortError, AuthenticationError, AuthorizationError, ConflictError, ConnectionError, InternalServerError, InvalidRequestError, NoheadError, NotFoundError, PlanLimitExceededError, PreconditionFailedError, RateLimitError, ServiceUnavailableError, TimeoutError, UploadError, ValidationError, WebhookVerificationError, } from "./errors.ts";
 export type { Uploadable, UploadParams } from "./resources/assets.ts";
 export type * from "./types.ts";

package/dist/resources/drafts.d.ts

@@ -1,5 +1,5 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
-import type { ConditionalRequestOptions, ConditionalWriteOptions, RequestOptions } from "../core.ts";
+import type { ConditionalRequestOptions, ConditionalWriteOptions, RichTextOptions } from "../core.ts";
 import type { RecordData } from "../generated/types.gen.ts";
 import type { DraftCreateParams, DraftGetParams, DraftListParams, DraftScheduleParams, DraftUpdateParams, NoheadDraft, NoheadRecord } from "../types.ts";
 import { Resource } from "./resource.ts";
@@ -17,24 +17,24 @@ export declare class Drafts extends Resource {
      * `ConflictError` (detail code `draft_exists`, with its `draft_id`): update
      * that one instead.
      */
-    create<D = RecordData>(record: string, params?: DraftCreateParams<D>, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
+    create<D = RecordData>(record: string, params?: DraftCreateParams<D>, options?: RichTextOptions): APIPromise<NoheadDraft<D>>;
     /**
      * A collection's drafts, most recently changed first. One record's draft
      * is `records.drafts(record)`.
      */
-    list<D = RecordData>(collection: string, params?: DraftListParams, options?: RequestOptions): PagePromise<NoheadDraft<D>>;
+    list<D = RecordData>(collection: string, params?: DraftListParams, options?: RichTextOptions): PagePromise<NoheadDraft<D>>;
     /** With `data` as the record reads after the merge, for previews. */
-    get<D = RecordData>(draft: string, params?: DraftGetParams, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
+    get<D = RecordData>(draft: string, params?: DraftGetParams, options?: RichTextOptions): APIPromise<NoheadDraft<D>>;
     /** Sets the given fields (`null` clears one), as a record update does. */
-    update<D = RecordData>(draft: string, params: DraftUpdateParams<D>, options?: ConditionalRequestOptions): APIPromise<NoheadDraft<D>>;
+    update<D = RecordData>(draft: string, params: DraftUpdateParams<D>, options?: ConditionalRequestOptions & RichTextOptions): APIPromise<NoheadDraft<D>>;
     /** Deletes the draft for good; returns it as it was. */
-    discard<D = RecordData>(draft: string, options?: ConditionalRequestOptions): APIPromise<NoheadDraft<D>>;
+    discard<D = RecordData>(draft: string, options?: ConditionalRequestOptions & RichTextOptions): APIPromise<NoheadDraft<D>>;
     /**
      * Applies the draft to its record now, as one `merge` revision, and
      * returns the record. Content only: the record stays live or not.
      */
-    merge<D = RecordData>(draft: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    merge<D = RecordData>(draft: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /** Merges the draft at `merge_at`, a future time; returns the draft. */
-    schedule<D = RecordData>(draft: string, params: DraftScheduleParams, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
-    unschedule<D = RecordData>(draft: string, options?: RequestOptions): APIPromise<NoheadDraft<D>>;
+    schedule<D = RecordData>(draft: string, params: DraftScheduleParams, options?: RichTextOptions): APIPromise<NoheadDraft<D>>;
+    unschedule<D = RecordData>(draft: string, options?: RichTextOptions): APIPromise<NoheadDraft<D>>;
 }

package/dist/resources/records.d.ts

@@ -1,5 +1,5 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
-import type { ConditionalWriteOptions, RequestOptions, WriteOptions } from "../core.ts";
+import type { ConditionalWriteOptions, RequestOptions, RichTextOptions, WriteOptions } from "../core.ts";
 import type { RecordData, RecordDiff, RecordRevision, RecordRevisionDetail, RevertPreview, RecordBatch, RecordCount, RecordPublication, RecordSchedule, ScheduledChange } from "../generated/types.gen.ts";
 import type { DryRunParams, NoheadDraft, NoheadRecord, RecordBulkParams, RecordCountParams, RecordCreateParams, RecordDiffParams, RecordGetParams, RecordListParams, RecordScheduleParams, RecordSearchParams, RecordUpdateParams, ListParams, RevisionListParams, ScheduledChangeListParams, SearchMeta } from "../types.ts";
 import { Resource } from "./resource.ts";
@@ -10,28 +10,28 @@ import { Resource } from "./resource.ts";
 export declare class Records extends Resource {
     readonly revisions: Revisions;
     /** A collection's records, newest first by default. */
-    list<D = RecordData>(collection: string, params?: RecordListParams, options?: RequestOptions): PagePromise<NoheadRecord<D>>;
-    get<D = RecordData>(record: string, params?: RecordGetParams, options?: RequestOptions): APIPromise<NoheadRecord<D>>;
+    list<D = RecordData>(collection: string, params?: RecordListParams, options?: RichTextOptions): PagePromise<NoheadRecord<D>>;
+    get<D = RecordData>(record: string, params?: RecordGetParams, options?: RichTextOptions): APIPromise<NoheadRecord<D>>;
     /**
      * Creates an unpublished record. With `upsert_on`, updates the record
      * holding that unique value instead, if one exists, so a sync can run
      * again without duplicates; `ifMatch` then applies to that update.
      */
-    create<D = RecordData>(collection: string, params: RecordCreateParams<D>, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    create<D = RecordData>(collection: string, params: RecordCreateParams<D>, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /** Sets the given fields (`null` clears one); others keep their values. */
-    update<D = RecordData>(record: string, params: RecordUpdateParams<D>, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    update<D = RecordData>(record: string, params: RecordUpdateParams<D>, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /**
      * Soft-deletes the record: `restore` brings it back until its
      * `purge_after`. Deleting a deleted record changes nothing.
      */
-    delete<D = RecordData>(record: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
-    restore<D = RecordData>(record: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    delete<D = RecordData>(record: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
+    restore<D = RecordData>(record: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /**
      * A live record with a pending draft is a `ConflictError` (detail code
      * `draft_pending`): publishing never merges a draft (`drafts.merge` does).
      */
-    publish<D = RecordData>(record: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
-    unpublish<D = RecordData>(record: string, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    publish<D = RecordData>(record: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
+    unpublish<D = RecordData>(record: string, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
     /**
      * What is live: since when, by whom, and the revision. A record that
      * isn't published is a `NotFoundError` (detail code `not_published`).
@@ -43,7 +43,7 @@ export declare class Records extends Resource {
      */
     getSchedule(record: string, options?: RequestOptions): APIPromise<RecordSchedule>;
     /** The record's drafts: at most one for now. */
-    drafts<D = RecordData>(record: string, params?: ListParams, options?: RequestOptions): PagePromise<NoheadDraft<D>>;
+    drafts<D = RecordData>(record: string, params?: ListParams, options?: RichTextOptions): PagePromise<NoheadDraft<D>>;
     /**
      * Sets when the record publishes and unpublishes on its own. This is the
      * whole schedule: a time left out is cleared (`{}` clears both, as
@@ -63,14 +63,17 @@ export declare class Records extends Resource {
      * Publishes, unpublishes, deletes, restores or updates up to 100 records.
      * Each record succeeds or fails on its own; see `results`.
      */
-    bulk(collection: string, params: RecordBulkParams, options?: WriteOptions): APIPromise<RecordBatch>;
-    /** The changes between two revisions. */
-    diff(record: string, params: RecordDiffParams, options?: RequestOptions): APIPromise<RecordDiff>;
+    bulk(collection: string, params: RecordBulkParams, options?: WriteOptions & RichTextOptions): APIPromise<RecordBatch>;
+    /**
+     * The changes between two revisions; with `richText`, rich text fields'
+     * `before` and `after` read as HTML or Markdown.
+     */
+    diff(record: string, params: RecordDiffParams, options?: RichTextOptions): APIPromise<RecordDiff>;
     /**
      * Full-text search in one collection, matching its `searchable` fields.
      * Pages through the first 1,000 hits, most relevant first.
      */
-    search<D = RecordData>(collection: string, query: string, params?: RecordSearchParams, options?: RequestOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
+    search<D = RecordData>(collection: string, query: string, params?: RecordSearchParams, options?: RichTextOptions): PagePromise<NoheadRecord<D>, SearchMeta>;
 }
 /** A record's version history. `revision` is a revision number. */
 export declare class Revisions extends Resource {
@@ -80,8 +83,8 @@ export declare class Revisions extends Resource {
     /** Restores the record's data as of `revision`, as a new revision. */
     revert(record: string, revision: number, params: {
         dry_run: true;
-    }, options?: ConditionalWriteOptions): APIPromise<RevertPreview>;
-    revert<D = RecordData>(record: string, revision: number, params?: DryRunParams, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
+    }, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<RevertPreview>;
+    revert<D = RecordData>(record: string, revision: number, params?: DryRunParams, options?: ConditionalWriteOptions & RichTextOptions): APIPromise<NoheadRecord<D>>;
 }
 /**
  * A revision by its own ID (`rev_…`), as webhooks and the activity log name

package/dist/resources/records.js

@@ -92,7 +92,10 @@ export class Records extends Resource {
     bulk(collection, params, options) {
         return this.core.request("records_bulk", { path: { collection_id: collection }, body: params }, options);
     }
-    /** The changes between two revisions. */
+    /**
+     * The changes between two revisions; with `richText`, rich text fields'
+     * `before` and `after` read as HTML or Markdown.
+     */
     diff(record, params, options) {
         return this.core.request("records_diff", { path: { record_id: record }, query: params }, options);
     }

package/dist/types.d.ts

@@ -21,6 +21,13 @@ export type NoheadDraft<D = G.RecordData> = Omit<G.Draft, "data"> & {
 export type RecordDataUpdate<D> = {
     [K in keyof D]?: D[K] | null;
 };
+/**
+ * How rich text fields read (`richText`): `"document"`, the stored
+ * ProseMirror JSON document (the default); `"html"`, an HTML fragment safe
+ * to put in a page as it is; or `"markdown"` (GitHub Flavored). As HTML or
+ * Markdown, a rich text field's value is a string.
+ */
+export type RichText = G.RichText;
 export type FilterValue = string | number | boolean | Date;
 /**
  * Operators for one key. `ne` matches records without a value; on fields

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.9.0";
+export declare const VERSION = "0.11.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.9.0";
+export const VERSION = "0.11.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nohead/sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Official TypeScript SDK for the Nohead API",
   "license": "MIT",
   "homepage": "https://nohead.io",