@nohead/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { Nohead } from "./client.ts";
 export { APIPromise, Page, PagePromise, type APIResponse, } from "./api-promise.ts";
-export type { ClientOptions, ConditionalRequestOptions, RequestOptions, RetryEvent, } from "./core.ts";
+export type { ClientOptions, ConditionalRequestOptions, ConditionalWriteOptions, RequestOptions, RetryEvent, 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";
-export { unwrapWebhook, type AssetEvent, type RecordEvent, type SchemaChangedEvent, type UnwrapOptions, type WebhookEvent, type WebhookHeaders, type WebhookTestEvent, } from "./webhooks.ts";
+export { unwrapWebhook, type AssetEvent, type DraftEvent, type RecordEvent, type SchemaEvent, type FieldAliasRemovedEvent, type UnwrapOptions, type WebhookEvent, type WebhookHeaders, type WebhookTestEvent, } from "./webhooks.ts";
 export { VERSION } from "./version.ts";

package/dist/resources/assets.d.ts

@@ -1,6 +1,6 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
 import type { RequestOptions } from "../core.ts";
-import type { Asset, AssetUpload, AssetUploadCreate, DownloadUrl, ImageUrl } from "../generated/types.gen.ts";
+import type { Asset, AssetUploadCreate, AssetWithUpload, AssetUsage, DownloadUrl, ImageUrl } from "../generated/types.gen.ts";
 import type { AssetListParams, ImageUrlParams } from "../types.ts";
 import { Resource } from "./resource.ts";
 /** What `assets.upload` accepts. A stream needs `byte_size`. */
@@ -23,24 +23,43 @@ export declare class Assets extends Resource {
      *
      * With an `idempotencyKey`, running the same upload again resumes it: the
      * key starts the upload, and an asset that is already `ready` is returned
-     * without sending the bytes again.
+     * without sending the bytes again. Once the upload's URL has expired
+     * (`upload.expires_at`), it throws `UploadError`: start over with a new key.
      *
      *   import { openAsBlob } from "node:fs"
      *   const asset = await nohead.assets.upload(await openAsBlob("a.jpg"), { filename: "a.jpg" })
      */
     upload(file: Uploadable, params?: UploadParams, options?: RequestOptions): Promise<Asset>;
     /**
-     * The first step of an upload: a `pending` asset and a presigned URL to
-     * `PUT` the bytes to (for example from a browser). Then `complete` it.
+     * The first step of an upload: a `pending` asset with its `upload`, a
+     * presigned URL to `PUT` the bytes to (for example from a browser). Then
+     * `complete` it.
      */
-    createUpload(params: AssetUploadCreate, options?: RequestOptions): APIPromise<AssetUpload>;
+    createUpload(params: AssetUploadCreate, options?: RequestOptions): APIPromise<AssetWithUpload>;
     /** Checks an uploaded file and marks the asset `ready`. */
     complete(asset: string, options?: RequestOptions): APIPromise<Asset>;
     list(params?: AssetListParams, options?: RequestOptions): PagePromise<Asset>;
     get(asset: string, options?: RequestOptions): APIPromise<Asset>;
-    /** Soft-deletes the asset; the file is purged after 30 days. */
+    /**
+     * Soft-deletes the asset: `restore` brings it back until its
+     * `purge_after`, when the file is purged (or now, with `purge`).
+     */
     delete(asset: string, options?: RequestOptions): APIPromise<Asset>;
     restore(asset: string, options?: RequestOptions): APIPromise<Asset>;
+    /**
+     * Permanently deletes a deleted asset now, instead of at its
+     * `purge_after`, and frees its storage. It can't be restored, records that use
+     * it keep an ID that no longer resolves, and its image URLs stop working
+     * within a minute or so. Returns the asset as it was. An asset that isn't
+     * deleted is a `ConflictError`: delete it first.
+     */
+    purge(asset: string, options?: RequestOptions): APIPromise<Asset>;
+    /**
+     * Where the asset is used: how many undeleted records use it (`records`),
+     * how many of those are published (`published`), and the 10 most recently
+     * updated with the fields that use it (`uses`). Needs `records:read` too.
+     */
+    usage(asset: string, options?: RequestOptions): APIPromise<AssetUsage>;
     /** A signed, cacheable URL of an image rendition (`url`). */
     imageUrl(asset: string, params?: ImageUrlParams, options?: RequestOptions): APIPromise<ImageUrl>;
     /** A 15-minute link to download the original file (`url`). */

package/dist/resources/assets.js

@@ -1,5 +1,5 @@
 import { AbortError, UploadError } from "../errors.js";
-import { Resource } from "./resource.js";
+import { listQuery, Resource } from "./resource.js";
 /** Files of the key's project. `asset` is an asset ID (`ast_…`). */
 export class Assets extends Resource {
     /**
@@ -10,7 +10,8 @@ export class Assets extends Resource {
      *
      * With an `idempotencyKey`, running the same upload again resumes it: the
      * key starts the upload, and an asset that is already `ready` is returned
-     * without sending the bytes again.
+     * without sending the bytes again. Once the upload's URL has expired
+     * (`upload.expires_at`), it throws `UploadError`: start over with a new key.
      *
      *   import { openAsBlob } from "node:fs"
      *   const asset = await nohead.assets.upload(await openAsBlob("a.jpg"), { filename: "a.jpg" })
@@ -20,7 +21,7 @@ export class Assets extends Resource {
         if (byteSize === undefined) {
             throw new UploadError("Uploading a stream needs `byte_size`");
         }
-        const { asset, upload } = await this.createUpload({
+        const { upload, ...asset } = await this.createUpload({
             filename: params.filename ??
                 (typeof File !== "undefined" && file instanceof File
                     ? file.name
@@ -34,10 +35,13 @@ export class Assets extends Resource {
             const current = await this.get(asset.id, {
                 ...options,
                 idempotencyKey: undefined,
-                changeNote: undefined,
             });
             if (current.status === "ready")
                 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`);
+            }
         }
         const stream = file instanceof ReadableStream;
         const response = await this.core
@@ -59,8 +63,9 @@ export class Assets extends Resource {
         return this.complete(asset.id, { ...options, idempotencyKey: undefined });
     }
     /**
-     * The first step of an upload: a `pending` asset and a presigned URL to
-     * `PUT` the bytes to (for example from a browser). Then `complete` it.
+     * The first step of an upload: a `pending` asset with its `upload`, a
+     * presigned URL to `PUT` the bytes to (for example from a browser). Then
+     * `complete` it.
      */
     createUpload(params, options) {
         return this.core.request("assets_upload", { body: params }, options);
@@ -70,18 +75,39 @@ export class Assets extends Resource {
         return this.core.request("assets_complete", { path: { asset_id: asset } }, options);
     }
     list(params = {}, options) {
-        return this.core.paginate("assets_list", { query: params }, options);
+        return this.core.paginate("assets_list", { query: listQuery(params, ["deleted", "content_type"]) }, options);
     }
     get(asset, options) {
         return this.core.request("assets_get", { path: { asset_id: asset } }, options);
     }
-    /** Soft-deletes the asset; the file is purged after 30 days. */
+    /**
+     * Soft-deletes the asset: `restore` brings it back until its
+     * `purge_after`, when the file is purged (or now, with `purge`).
+     */
     delete(asset, options) {
         return this.core.request("assets_delete", { path: { asset_id: asset } }, options);
     }
     restore(asset, options) {
         return this.core.request("assets_restore", { path: { asset_id: asset } }, options);
     }
+    /**
+     * Permanently deletes a deleted asset now, instead of at its
+     * `purge_after`, and frees its storage. It can't be restored, records that use
+     * it keep an ID that no longer resolves, and its image URLs stop working
+     * within a minute or so. Returns the asset as it was. An asset that isn't
+     * deleted is a `ConflictError`: delete it first.
+     */
+    purge(asset, options) {
+        return this.core.request("assets_purge", { path: { asset_id: asset } }, options);
+    }
+    /**
+     * Where the asset is used: how many undeleted records use it (`records`),
+     * how many of those are published (`published`), and the 10 most recently
+     * updated with the fields that use it (`uses`). Needs `records:read` too.
+     */
+    usage(asset, options) {
+        return this.core.request("assets_usage", { path: { asset_id: asset } }, options);
+    }
     /** A signed, cacheable URL of an image rendition (`url`). */
     imageUrl(asset, params = {}, options) {
         return this.core.request("assets_image_url", { path: { asset_id: asset }, query: params }, options);

package/dist/resources/drafts.d.ts

@@ -0,0 +1,41 @@
+import type { APIPromise, PagePromise } from "../api-promise.ts";
+import type { ConditionalRequestOptions, ConditionalWriteOptions, RequestOptions } 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";
+/**
+ * Drafts: changes to a record's content that wait until they are merged into
+ * it, now or at a set time, while the record keeps its current content. A
+ * record has at most one. `draft` is a draft ID (`drf_…`); `record` a record
+ * ID; `collection` a collection ID or slug. Like records, drafts take the
+ * type of their data: `drafts.get<Post>(id)`.
+ */
+export declare class Drafts extends Resource {
+    /**
+     * Starts the record's draft, from the record's values (`data` over them),
+     * or from an earlier revision's (`from_revision`). A second is a
+     * `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>>;
+    /**
+     * A collection's drafts, most recently changed first. `record_id` narrows
+     * them to one record, or to several (1 to 100; an empty list is a
+     * `TypeError`, since it would match no record).
+     */
+    list<D = RecordData>(collection: string, { record_id, ...params }?: DraftListParams, options?: RequestOptions): 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>>;
+    /** 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>>;
+    /** Deletes the draft for good; returns it as it was. */
+    discard<D = RecordData>(draft: string, options?: ConditionalRequestOptions): 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>>;
+    /** 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>>;
+}

package/dist/resources/drafts.js

@@ -0,0 +1,63 @@
+import { Resource } from "./resource.js";
+/**
+ * Drafts: changes to a record's content that wait until they are merged into
+ * it, now or at a set time, while the record keeps its current content. A
+ * record has at most one. `draft` is a draft ID (`drf_…`); `record` a record
+ * ID; `collection` a collection ID or slug. Like records, drafts take the
+ * type of their data: `drafts.get<Post>(id)`.
+ */
+export class Drafts extends Resource {
+    /**
+     * Starts the record's draft, from the record's values (`data` over them),
+     * or from an earlier revision's (`from_revision`). A second is a
+     * `ConflictError` (detail code `draft_exists`, with its `draft_id`): update
+     * that one instead.
+     */
+    create(record, params = {}, options) {
+        return this.core.request("drafts_create", { path: { record_id: record }, body: params }, options);
+    }
+    /**
+     * A collection's drafts, most recently changed first. `record_id` narrows
+     * them to one record, or to several (1 to 100; an empty list is a
+     * `TypeError`, since it would match no record).
+     */
+    list(collection, { record_id, ...params } = {}, options) {
+        if (Array.isArray(record_id) && record_id.length === 0)
+            throw new TypeError("record_id needs at least one record ID");
+        const filter = record_id === undefined
+            ? undefined
+            : {
+                record_id: Array.isArray(record_id) ? { in: record_id } : record_id,
+            };
+        return this.core.paginate("drafts_list", {
+            path: { collection_id: collection },
+            query: { ...params, ...(filter && { filter }) },
+        }, options);
+    }
+    /** With `data` as the record reads after the merge, for previews. */
+    get(draft, params = {}, options) {
+        return this.core.request("drafts_get", { path: { draft_id: draft }, query: params }, options);
+    }
+    /** Sets the given fields (`null` clears one), as a record update does. */
+    update(draft, params, options) {
+        return this.core.request("drafts_update", { path: { draft_id: draft }, body: params }, options);
+    }
+    /** Deletes the draft for good; returns it as it was. */
+    discard(draft, options) {
+        return this.core.request("drafts_discard", { path: { draft_id: draft } }, options);
+    }
+    /**
+     * Applies the draft to its record now, as one `merge` revision, and
+     * returns the record. Content only: the record stays live or not.
+     */
+    merge(draft, options) {
+        return this.core.request("drafts_merge", { path: { draft_id: draft } }, options);
+    }
+    /** Merges the draft at `merge_at`, a future time; returns the draft. */
+    schedule(draft, params, options) {
+        return this.core.request("drafts_schedule", { path: { draft_id: draft }, body: params }, options);
+    }
+    unschedule(draft, options) {
+        return this.core.request("drafts_unschedule", { path: { draft_id: draft } }, options);
+    }
+}

package/dist/resources/other.d.ts

@@ -3,7 +3,12 @@ import type { RequestOptions } from "../core.ts";
 import type { AuditEvent, FeatureFlags as FeatureFlagList, Health as HealthStatus, Principal } from "../generated/types.gen.ts";
 import type { AuditEventListParams } from "../types.ts";
 import { Resource } from "./resource.ts";
-/** The project's activity log, newest first. Needs the `audit:read` scope. */
+/**
+ * The project's activity log, newest first. Needs the `audit:read` scope.
+ * Filter by `type` (`record.*` for a prefix), `resource_type` (one or
+ * several), `resource_id`, `actor_type`, `actor_id` and `created_at`
+ * (`{ gte, lt }`).
+ */
 export declare class AuditEvents extends Resource {
     list(params?: AuditEventListParams, options?: RequestOptions): PagePromise<AuditEvent>;
 }

package/dist/resources/other.js

@@ -1,8 +1,22 @@
 import { Resource } from "./resource.js";
-/** The project's activity log, newest first. Needs the `audit:read` scope. */
+/**
+ * The project's activity log, newest first. Needs the `audit:read` scope.
+ * Filter by `type` (`record.*` for a prefix), `resource_type` (one or
+ * several), `resource_id`, `actor_type`, `actor_id` and `created_at`
+ * (`{ gte, lt }`).
+ */
 export class AuditEvents extends Resource {
     list(params = {}, options) {
-        return this.core.paginate("audit_events_list_for_project", { query: params }, options);
+        const { filter, ...rest } = params;
+        const resourceType = filter?.resource_type;
+        return this.core.paginate("audit_events_list", {
+            query: {
+                ...rest,
+                filter: Array.isArray(resourceType)
+                    ? { ...filter, resource_type: { in: resourceType } }
+                    : filter,
+            },
+        }, options);
     }
 }
 export class FeatureFlags extends Resource {

package/dist/resources/records.d.ts

@@ -1,7 +1,7 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
-import type { ConditionalRequestOptions, RequestOptions } from "../core.ts";
-import type { RecordData, RecordDiff, RecordRevision, RecordRevisionDetail, RevertPreview, BulkRecordsResult, RecordCount } from "../generated/types.gen.ts";
-import type { DryRunParams, NoheadRecord, RecordBulkParams, RecordCountParams, RecordCreateParams, RecordDiffParams, RecordGetParams, RecordListParams, RecordScheduleParams, RecordSearchParams, RecordUpdateParams, RevisionListParams, SearchMeta } from "../types.ts";
+import type { ConditionalWriteOptions, RequestOptions, 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";
 /**
  * Records: the content of a collection. `collection` is a collection ID or
@@ -12,25 +12,54 @@ export declare class Records extends Resource {
     /** 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>>;
-    /** Creates a draft. */
-    create<D = RecordData>(collection: string, params: RecordCreateParams<D>, options?: RequestOptions): APIPromise<NoheadRecord<D>>;
+    /** Creates an unpublished record. */
+    create<D = RecordData>(collection: string, params: RecordCreateParams<D>, options?: WriteOptions): APIPromise<NoheadRecord<D>>;
     /** Sets the given fields (`null` clears one); others keep their values. */
-    update<D = RecordData>(record: string, params: RecordUpdateParams<D>, options?: ConditionalRequestOptions): APIPromise<NoheadRecord<D>>;
-    /** Soft-deletes the record: `restore` brings it back within 30 days. */
-    delete<D = RecordData>(record: string, options?: ConditionalRequestOptions): APIPromise<NoheadRecord<D>>;
-    restore<D = RecordData>(record: string, options?: RequestOptions): APIPromise<NoheadRecord<D>>;
-    publish<D = RecordData>(record: string, options?: ConditionalRequestOptions): APIPromise<NoheadRecord<D>>;
-    unpublish<D = RecordData>(record: string, options?: ConditionalRequestOptions): APIPromise<NoheadRecord<D>>;
-    /** Publishes and/or unpublishes the record later. */
-    schedule<D = RecordData>(record: string, params: RecordScheduleParams, options?: RequestOptions): APIPromise<NoheadRecord<D>>;
+    update<D = RecordData>(record: string, params: RecordUpdateParams<D>, options?: ConditionalWriteOptions): 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>>;
+    /**
+     * 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>>;
+    /**
+     * What is live: since when, by whom, and the revision. A record that
+     * isn't published is a `NotFoundError` (detail code `not_published`).
+     */
+    publication(record: string, options?: RequestOptions): APIPromise<RecordPublication>;
+    /**
+     * When the record publishes or unpublishes on its own. One with no
+     * schedule is a `NotFoundError` (detail code `not_scheduled`).
+     */
+    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>>;
+    /**
+     * Sets when the record publishes and unpublishes on its own. This is the
+     * whole schedule: a time left out is cleared (`{}` clears both, as
+     * `unschedule` does).
+     */
+    schedule(record: string, params: RecordScheduleParams, options?: RequestOptions): APIPromise<RecordSchedule>;
     /** Clears both scheduled times. */
-    unschedule<D = RecordData>(record: string, options?: RequestOptions): APIPromise<NoheadRecord<D>>;
+    unschedule(record: string, options?: RequestOptions): APIPromise<RecordSchedule>;
+    /**
+     * A collection's pending scheduled publishes and unpublishes, soonest
+     * first: one per change, so a record due to publish and later unpublish
+     * appears twice.
+     */
+    scheduledChanges(collection: string, params?: ScheduledChangeListParams, options?: RequestOptions): PagePromise<ScheduledChange>;
     count(collection: string, params?: RecordCountParams, options?: RequestOptions): APIPromise<RecordCount>;
     /**
      * 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?: RequestOptions): APIPromise<BulkRecordsResult>;
+    bulk(collection: string, params: RecordBulkParams, options?: WriteOptions): APIPromise<RecordBatch>;
     /** The changes between two revisions. */
     diff(record: string, params: RecordDiffParams, options?: RequestOptions): APIPromise<RecordDiff>;
     /**
@@ -47,6 +76,6 @@ 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?: ConditionalRequestOptions): APIPromise<RevertPreview>;
-    revert<D = RecordData>(record: string, revision: number, params?: DryRunParams, options?: ConditionalRequestOptions): APIPromise<NoheadRecord<D>>;
+    }, options?: ConditionalWriteOptions): APIPromise<RevertPreview>;
+    revert<D = RecordData>(record: string, revision: number, params?: DryRunParams, options?: ConditionalWriteOptions): APIPromise<NoheadRecord<D>>;
 }

package/dist/resources/records.js

@@ -12,7 +12,7 @@ export class Records extends Resource {
     get(record, params = {}, options) {
         return this.core.request("records_get", { path: { record_id: record }, query: params }, options);
     }
-    /** Creates a draft. */
+    /** Creates an unpublished record. */
     create(collection, params, options) {
         return this.core.request("records_create", { path: { collection_id: collection }, body: params }, options);
     }
@@ -20,20 +20,49 @@ export class Records extends Resource {
     update(record, params, options) {
         return this.core.request("records_update", { path: { record_id: record }, body: params }, options);
     }
-    /** Soft-deletes the record: `restore` brings it back within 30 days. */
+    /**
+     * Soft-deletes the record: `restore` brings it back until its
+     * `purge_after`. Deleting a deleted record changes nothing.
+     */
     delete(record, options) {
         return this.core.request("records_delete", { path: { record_id: record } }, options);
     }
     restore(record, options) {
         return this.core.request("records_restore", { path: { record_id: record } }, options);
     }
+    /**
+     * A live record with a pending draft is a `ConflictError` (detail code
+     * `draft_pending`): publishing never merges a draft (`drafts.merge` does).
+     */
     publish(record, options) {
         return this.core.request("records_publish", { path: { record_id: record } }, options);
     }
     unpublish(record, options) {
         return this.core.request("records_unpublish", { path: { record_id: record } }, options);
     }
-    /** Publishes and/or unpublishes the record later. */
+    /**
+     * What is live: since when, by whom, and the revision. A record that
+     * isn't published is a `NotFoundError` (detail code `not_published`).
+     */
+    publication(record, options) {
+        return this.core.request("records_get_publication", { path: { record_id: record } }, options);
+    }
+    /**
+     * When the record publishes or unpublishes on its own. One with no
+     * schedule is a `NotFoundError` (detail code `not_scheduled`).
+     */
+    getSchedule(record, options) {
+        return this.core.request("records_get_schedule", { path: { record_id: record } }, options);
+    }
+    /** The record's drafts: at most one for now. */
+    drafts(record, params = {}, options) {
+        return this.core.paginate("record_drafts_list", { path: { record_id: record }, query: params }, options);
+    }
+    /**
+     * Sets when the record publishes and unpublishes on its own. This is the
+     * whole schedule: a time left out is cleared (`{}` clears both, as
+     * `unschedule` does).
+     */
     schedule(record, params, options) {
         return this.core.request("records_schedule", { path: { record_id: record }, body: params }, options);
     }
@@ -41,6 +70,14 @@ export class Records extends Resource {
     unschedule(record, options) {
         return this.core.request("records_unschedule", { path: { record_id: record } }, options);
     }
+    /**
+     * A collection's pending scheduled publishes and unpublishes, soonest
+     * first: one per change, so a record due to publish and later unpublish
+     * appears twice.
+     */
+    scheduledChanges(collection, params = {}, options) {
+        return this.core.paginate("scheduled_changes_list", { path: { collection_id: collection }, query: params }, options);
+    }
     count(collection, params = {}, options) {
         return this.core.request("records_count", { path: { collection_id: collection }, query: params }, options);
     }

package/dist/resources/resource.d.ts

@@ -3,3 +3,8 @@ export declare abstract class Resource {
     protected readonly core: Core;
     constructor(core: Core);
 }
+/**
+ * A list's query: the options the API reads as filters (`deleted`,
+ * `content_type`, `status`) go under `filter[...]`, the rest stay as they are.
+ */
+export declare function listQuery(params: object, filters: readonly string[]): Record<string, unknown>;

package/dist/resources/resource.js

@@ -4,3 +4,17 @@ export class Resource {
         this.core = core;
     }
 }
+/**
+ * A list's query: the options the API reads as filters (`deleted`,
+ * `content_type`, `status`) go under `filter[...]`, the rest stay as they are.
+ */
+export function listQuery(params, filters) {
+    const query = { ...params };
+    const filter = {};
+    for (const name of filters) {
+        if (query[name] !== undefined)
+            filter[name] = query[name];
+        delete query[name];
+    }
+    return Object.keys(filter).length > 0 ? { ...query, filter } : query;
+}

package/dist/resources/schema.d.ts

@@ -1,7 +1,7 @@
 import type { APIPromise, PagePromise } from "../api-promise.ts";
-import type { RequestOptions } from "../core.ts";
-import type { Collection, CollectionCreate, CollectionUpdate, Field, FieldCreate, FieldMigration, FieldMigrationPreview, FieldUpdate, Schema, SchemaChange, SchemaChangeDetail, SearchIndex } from "../generated/types.gen.ts";
-import type { DeletedListParams, DryRunParams, FieldMigrateParams, ListParams, SchemaParams } from "../types.ts";
+import type { RequestOptions, WriteOptions } from "../core.ts";
+import type { Collection, FieldOrder, CollectionCreate, CollectionUpdate, Field, FieldCreate, FieldMigration, FieldMigrationPreview, FieldUpdate, Schema, SchemaChange, SchemaChangeDetail, SearchIndex } from "../generated/types.gen.ts";
+import type { DeletedListParams, DryRunParams, FieldMigrateParams, FieldReorderParams, ListParams, SchemaParams } from "../types.ts";
 import { Resource } from "./resource.ts";
 /** Collections of the key's project. `collection` is an ID or slug. */
 export declare class Collections extends Resource {
@@ -10,11 +10,14 @@ export declare class Collections extends Resource {
     list(params?: DeletedListParams, options?: RequestOptions): PagePromise<Collection>;
     get(collection: string, options?: RequestOptions): APIPromise<Collection>;
     /** Creates a collection, optionally with its fields. */
-    create(params: CollectionCreate, options?: RequestOptions): APIPromise<Collection>;
-    update(collection: string, params: CollectionUpdate, options?: RequestOptions): APIPromise<Collection>;
-    /** Soft-deletes the collection and its records for 30 days. */
-    delete(collection: string, options?: RequestOptions): APIPromise<Collection>;
-    restore(collection: string, options?: RequestOptions): APIPromise<Collection>;
+    create(params: CollectionCreate, options?: WriteOptions): APIPromise<Collection>;
+    update(collection: string, params: CollectionUpdate, options?: WriteOptions): APIPromise<Collection>;
+    /**
+     * Soft-deletes the collection and its records: `restore` brings them back
+     * until its `purge_after`.
+     */
+    delete(collection: string, options?: WriteOptions): APIPromise<Collection>;
+    restore(collection: string, options?: WriteOptions): APIPromise<Collection>;
     /** The collection's schema, now or at a past `version`. */
     schema(collection: string, params?: SchemaParams, options?: RequestOptions): APIPromise<Schema>;
 }
@@ -32,19 +35,23 @@ export declare class SearchIndexes extends Resource {
 /** Fields of a collection. `field` is a field ID (`fld_…`). */
 export declare class Fields extends Resource {
     list(collection: string, params?: DeletedListParams, options?: RequestOptions): PagePromise<Field>;
-    create(collection: string, params: FieldCreate, options?: RequestOptions): APIPromise<Field>;
+    create(collection: string, params: FieldCreate, options?: WriteOptions): APIPromise<Field>;
+    get(field: string, options?: RequestOptions): APIPromise<Field>;
     /**
      * Renames, describes or loosens a field. Changes that rewrite record
      * values (type, `multiple`, tighter rules) are `migrate`.
      */
-    update(field: string, params: FieldUpdate, options?: RequestOptions): APIPromise<Field>;
-    /** Soft-deletes the field: its values return with `restore` for 30 days. */
-    delete(field: string, options?: RequestOptions): APIPromise<Field>;
-    restore(field: string, options?: RequestOptions): APIPromise<Field>;
-    /** Puts the collection's fields in this order. */
-    reorder(collection: string, params: {
-        field_ids: string[];
-    }, options?: RequestOptions): APIPromise<Collection>;
+    update(field: string, params: FieldUpdate, options?: WriteOptions): APIPromise<Field>;
+    /**
+     * Soft-deletes the field: its values come back with `restore` until its
+     * `purge_after`.
+     */
+    delete(field: string, options?: WriteOptions): APIPromise<Field>;
+    restore(field: string, options?: WriteOptions): APIPromise<Field>;
+    /** The collection's active fields, in order. */
+    order(collection: string, options?: RequestOptions): APIPromise<FieldOrder>;
+    /** Puts the collection's fields in this order; lists every active field once. */
+    reorder(collection: string, params: FieldReorderParams, options?: WriteOptions): APIPromise<FieldOrder>;
     /** Stops accepting a renamed field's old API key before its 6 months end. */
     removeAlias(field: string, alias: string, options?: RequestOptions): APIPromise<Field>;
     /**
@@ -53,8 +60,8 @@ export declare class Fields extends Resource {
      */
     migrate(field: string, params: FieldMigrateParams & {
         dry_run: true;
-    }, options?: RequestOptions): APIPromise<FieldMigrationPreview>;
-    migrate(field: string, params: FieldMigrateParams & DryRunParams, options?: RequestOptions): APIPromise<FieldMigration>;
+    }, options?: WriteOptions): APIPromise<FieldMigrationPreview>;
+    migrate(field: string, params: FieldMigrateParams & DryRunParams, options?: WriteOptions): APIPromise<FieldMigration>;
 }
 /** Field migrations. While one runs, its collection is read-only. */
 export declare class Migrations extends Resource {