@nohead/sdk 0.8.0 → 0.10.0

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

@@ -1,5 +1,5 @@
 export type ClientOptions = {
-    baseUrl: 'https://api.nohead.io' | 'http://localhost:3000' | (string & {});
+    baseUrl: 'https://api.nohead.io' | (string & {});
 };
 export type Webhooks = WebhookEventWebhookRequest;
 export type RequestId = string;
@@ -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 = {
@@ -1129,7 +1162,7 @@ export type Principal = {
         email: string;
         name: string | null;
         /**
-         * Nohead staff (internal tooling access).
+         * Whether the user is Nohead staff.
          */
         staff: boolean;
     };
@@ -1523,9 +1556,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 +1571,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;
     /**
@@ -1550,7 +1585,10 @@ export type AssetProperties = {
     /**
      * The URL that plays a ready video or audio file inline, for
      * `<video>` and `<audio>` (with range requests, so players can seek),
-     * deleted ones included until they are purged; null for other types.
+     * deleted ones included until they are purged: MP4, QuickTime, M4A,
+     * 3GP, WebM, Matroska, MP3, AAC, FLAC, WAV and Ogg (whose content is
+     * checked when the upload completes). Null for other types, which
+     * `file_url` downloads.
      * Open, never expiring and cached on a CDN, like `file_url`.
      *
      */
@@ -1619,7 +1657,7 @@ export type AssetUploadTarget = {
     expires_at: Timestamp;
 };
 /**
- * What a project API key may do. `records:write` also publishes, unpublishes and schedules records (the `records:publish` permission). `webhooks:read` includes delivery payloads and `webhooks:write` can subscribe an endpoint to every event, so both give access to the record, schema and asset data in events, unpublished records included; published-only keys cannot have them.
+ * What a project API key may do. `records:write` also publishes, unpublishes and schedules records. `webhooks:read` includes delivery payloads and `webhooks:write` can subscribe an endpoint to every event, so both give access to the record, schema and asset data in events, unpublished records included; published-only keys cannot have them.
  */
 export type ApiKeyScope = 'records:read' | 'records:write' | 'schema:read' | 'schema:write' | 'assets:read' | 'assets:write' | 'search:read' | 'webhooks:read' | 'webhooks:write' | 'audit:read';
 /**
@@ -1684,6 +1722,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).
  */
@@ -1692,8 +1734,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.
@@ -1833,12 +1874,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.
@@ -1961,7 +2005,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 = {
@@ -2060,7 +2109,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 = {
@@ -2116,6 +2170,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).
          */
@@ -2195,7 +2253,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 = {
@@ -2262,8 +2325,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.
@@ -2362,7 +2424,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 = {
@@ -2445,7 +2512,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 = {
@@ -2536,7 +2608,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 = {
@@ -2666,7 +2743,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 = {
@@ -3152,6 +3234,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';
@@ -3261,6 +3347,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.
          */
@@ -3330,7 +3420,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 = {
@@ -3387,6 +3482,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.
@@ -3461,7 +3560,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 = {
@@ -3517,6 +3621,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).
          */
@@ -3586,7 +3694,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 = {
@@ -3675,7 +3788,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 = {
@@ -3750,7 +3868,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 = {
@@ -3815,7 +3938,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 = {
@@ -5935,6 +6063,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.
          */
@@ -5951,8 +6083,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.
@@ -6036,6 +6167,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/images.js

@@ -16,8 +16,13 @@ export function imageUrl(image, options = {}) {
     const at = base.indexOf("/plain/");
     if (at < 0)
         throw new TypeError(`Not a Nohead image URL: ${base}`);
-    const { width, height, fit = "contain", format, quality, dpr, gravity, } = options;
-    for (const option of [gravity, ...(options.options ?? [])])
+    // Empty options count as unset.
+    const { width, height, format, quality, dpr, gravity } = options;
+    const fit = options.fit || "contain";
+    if (!Object.hasOwn(FITS, fit))
+        throw new TypeError(`fit must be one of ${Object.keys(FITS).join(", ")}`);
+    const others = (options.options ?? []).filter(Boolean);
+    for (const option of [gravity, ...others])
         if (option && /[/@?#]/.test(option))
             throw new TypeError(`Not an imgproxy option: ${option}`);
     const segments = [];
@@ -29,7 +34,7 @@ export function imageUrl(image, options = {}) {
         segments.push(`dpr:${dpr}`);
     if (quality)
         segments.push(`q:${quality}`);
-    segments.push(...(options.options ?? []));
+    segments.push(...others);
     // The source comes last; a format replaces any the URL already names.
     let source = base.slice(at);
     if (format)

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 type { ClientOptions, ConditionalRequestOptions, ConditionalWriteOptions, RequestOptions, RetryEvent, 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/index.js

@@ -1,5 +1,6 @@
 export { Nohead } from "./client.js";
 export { APIPromise, Page, PagePromise, } from "./api-promise.js";
+export { DEFAULT_BASE_URL, } from "./core.js";
 export { APIError, AbortError, AuthenticationError, AuthorizationError, ConflictError, ConnectionError, InternalServerError, InvalidRequestError, NoheadError, NotFoundError, PlanLimitExceededError, PreconditionFailedError, RateLimitError, ServiceUnavailableError, TimeoutError, UploadError, ValidationError, WebhookVerificationError, } from "./errors.js";
 export { unwrapWebhook, } from "./webhooks.js";
 export { VERSION } from "./version.js";

package/dist/resources/assets.d.ts

@@ -8,11 +8,15 @@ export type Uploadable = Blob | ArrayBuffer | Uint8Array | ReadableStream;
 export interface UploadParams {
     /** Defaults to a `File`'s name, else `upload`. */
     filename?: string;
-    /** Defaults to the `Blob`'s type, else `application/octet-stream`. */
+    /**
+     * Defaults to the `Blob`'s type, else the filename's extension's for
+     * common files, else `application/octet-stream`.
+     */
     content_type?: string;
     /** Required for a `ReadableStream`; known for everything else. */
     byte_size?: number;
 }
+/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 export declare class Assets extends Resource {
     /**
      * Uploads a file and returns the `ready` asset: creates the upload, sends

package/dist/resources/assets.js

@@ -1,6 +1,5 @@
 import { AbortError, UploadError } from "../errors.js";
 import { listQuery, Resource } from "./resource.js";
-/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 /** Common files' types by extension, as the other SDKs guess them. */
 const CONTENT_TYPES = {
     avif: "image/avif",
@@ -26,6 +25,7 @@ function contentTypeOf(filename) {
         ? CONTENT_TYPES[filename.slice(dot + 1).toLowerCase()]
         : undefined;
 }
+/** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 export class Assets extends Resource {
     /**
      * Uploads a file and returns the `ready` asset: creates the upload, sends
@@ -45,23 +45,28 @@ export class Assets extends Resource {
      * extension's for common files.
      */
     async upload(file, params = {}, options) {
+        // Never a path: the Python and Ruby SDKs take one, so it would be easy
+        // to send its text instead.
+        if (typeof file === "string") {
+            throw new TypeError("upload takes a Blob, File, ArrayBuffer, Uint8Array or ReadableStream; to upload a file from disk, pass await fs.openAsBlob(path)");
+        }
         const byteSize = params.byte_size ?? sizeOf(file);
         if (byteSize === undefined) {
             throw new UploadError("Uploading a stream needs `byte_size`");
         }
-        const filename = params.filename ??
-            (typeof File !== "undefined" && file instanceof File
-                ? file.name
-                : "upload");
+        // Empty ones count as unset.
+        const filename = params.filename ||
+            (typeof File !== "undefined" && file instanceof File && file.name) ||
+            "upload";
         const { upload, ...asset } = await this.createUpload({
             filename,
             // The Blob's own type, or one the filename's extension implies (a
             // Blob from Node's openAsBlob has none), as the Python and Ruby
             // SDKs do.
-            content_type: params.content_type ??
-                ((file instanceof Blob && file.type) ||
-                    contentTypeOf(filename) ||
-                    "application/octet-stream"),
+            content_type: params.content_type ||
+                (file instanceof Blob && file.type) ||
+                contentTypeOf(filename) ||
+                "application/octet-stream",
             byte_size: byteSize,
         }, options);
         // A replayed start returns the first run's asset, which may be done.
@@ -74,24 +79,28 @@ export class Assets extends Resource {
                 return current;
             // The key replays the first run's upload URL, which expires sooner.
             if (Date.parse(upload.expires_at) <= Date.now()) {
-                throw new UploadError(`The upload of ${asset.filename} expired: start it again with a new idempotencyKey`);
+                throw new UploadError(`The upload of ${filename} expired: start it again with a new idempotencyKey`);
             }
         }
         const stream = file instanceof ReadableStream;
         const response = await this.core
             .fetchWithRetries(upload.url, {
             method: upload.method,
-            headers: upload.headers,
+            // The URL is signed for this size; fetch would send a stream
+            // in chunks, without one.
+            headers: stream
+                ? { ...upload.headers, "Content-Length": String(byteSize) }
+                : upload.headers,
             body: file,
             ...(stream ? { duplex: "half" } : {}),
-        }, { ...options, retry: !stream })
+        }, { ...options, retry: !stream, byteSize })
             .catch((error) => {
             if (error instanceof AbortError)
                 throw error;
-            throw new UploadError(`Could not upload ${asset.filename}: ${error.message}`, undefined, { cause: error });
+            throw new UploadError(`Could not upload ${filename}: ${error.message}`, undefined, { cause: error });
         });
         if (!response.ok) {
-            throw new UploadError(`Storage refused the upload of ${asset.filename} (${response.status})`, response.status);
+            throw new UploadError(`Storage refused the upload of ${filename} (${response.status})`, response.status);
         }
         // The key belongs to the start: the API refuses one key on two requests.
         return this.complete(asset.id, { ...options, idempotencyKey: undefined });