@nohead/sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.5.0
+
+- **Breaking:** field migrations are created under their collection:
+  `migrations.create(collection, { field_id, ...changes, dry_run? })`
+  (`POST /v1/collections/{collection_id}/migrations`) replaces
+  `fields.migrate(field, ...)`. It returns a preview for a dry run and the
+  `FieldMigration` otherwise, as before. `FieldMigrateParams` is
+  `MigrationCreateParams`, with `field_id`.
+- **Breaking:** `drafts.list` no longer takes `record_id`; a record's drafts
+  are `records.drafts(record)`.
+- **Breaking:** `assets.list`'s `content_type` is one MIME type or `type/*`
+  wildcard as a string, or several as a list (sent as
+  `filter[content_type][in]`). A comma-separated string no longer lists
+  several types: pass a list.
+- **Breaking:** `auditEvents.list` sorts by `created_at` or `-created_at`
+  (the default), not `id`, and records no longer sort by `id`.
+- Webhook events always carry `actor` and `via` (now required in
+  `WebhookEventPayload`), and `Via` no longer has `import` or `migration`,
+  which were never sent.
+
 ## 0.4.0
 
 - **Breaking:** a field's `api_key` is its `key` (in fields, their aliases,

package/README.md

@@ -118,7 +118,7 @@ await nohead.drafts.merge(draft.id) // or drafts.schedule(draft.id, { merge_at }
 
 - A record has at most one draft; starting a second is a `ConflictError` (detail code `draft_exists`, with its `draft_id`).
 - A merge changes content only: a live record stays live, an unpublished one unpublished. Publishing a live record with a pending draft is a `ConflictError` (`draft_pending`).
-- `records.drafts(id)` lists a record's draft, and `drafts.list(collection, { record_id })` a collection's (`record_id` takes up to 100 IDs).
+- `records.drafts(id)` lists a record's draft, and `drafts.list(collection)` a collection's.
 - `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`).
 
@@ -315,11 +315,15 @@ await nohead.fields.create("posts", {
 })
 
 // Changes that rewrite records go through a migration; preview first
-const preview = await nohead.fields.migrate("fld_…", {
+const preview = await nohead.migrations.create("posts", {
+  field_id: "fld_…",
   type: "long_text",
   dry_run: true,
 })
-const migration = await nohead.fields.migrate("fld_…", { type: "long_text" })
+const migration = await nohead.migrations.create("posts", {
+  field_id: "fld_…",
+  type: "long_text",
+})
 await nohead.migrations.get(migration.id)
 ```
 
@@ -370,8 +374,8 @@ response.headers.get("RateLimit-Remaining")
 | `collections`               | `list`, `get`, `create`, `update`, `delete`, `restore`, `schema`                                                                                                                                        |
 | `collections.schemaChanges` | `list`, `get`                                                                                                                                                                                           |
 | `collections.searchIndex`   | `get`, `rebuild`                                                                                                                                                                                        |
-| `fields`                    | `list`, `get`, `create`, `update`, `delete`, `restore`, `order`, `reorder`, `removeAlias`, `migrate`                                                                                                    |
-| `migrations`                | `list`, `get`, `cancel`                                                                                                                                                                                 |
+| `fields`                    | `list`, `get`, `create`, `update`, `delete`, `restore`, `order`, `reorder`, `removeAlias`                                                                                                               |
+| `migrations`                | `create`, `list`, `get`, `cancel`                                                                                                                                                                       |
 | `assets`                    | `upload`, `createUpload`, `complete`, `list`, `get`, `delete`, `restore`, `purge`, `usage`, `imageUrl`, `downloadUrl`                                                                                   |
 | `webhooks`                  | `list`, `get`, `create`, `update`, `delete`, `restore`, `rotateSecret`, `test`, `unwrap`                                                                                                                |
 | `webhooks.secrets`          | `list`, `retire`                                                                                                                                                                                        |

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

@@ -132,10 +132,6 @@ export declare const OPERATIONS: {
         readonly method: "GET";
         readonly path: "/v1/collections/{collection_id}/fields";
     };
-    readonly fields_migrate: {
-        readonly method: "POST";
-        readonly path: "/v1/fields/{field_id}/migrations";
-    };
     readonly fields_remove_alias: {
         readonly method: "DELETE";
         readonly path: "/v1/fields/{field_id}/aliases/{alias}";
@@ -164,6 +160,10 @@ export declare const OPERATIONS: {
         readonly method: "POST";
         readonly path: "/v1/migrations/{migration_id}/cancel";
     };
+    readonly migrations_create: {
+        readonly method: "POST";
+        readonly path: "/v1/collections/{collection_id}/migrations";
+    };
     readonly migrations_get: {
         readonly method: "GET";
         readonly path: "/v1/migrations/{migration_id}";
@@ -459,10 +459,6 @@ export interface Operations {
         data: T.FieldsListData;
         response: T.FieldsListResponse;
     };
-    fields_migrate: {
-        data: T.FieldsMigrateData;
-        response: T.FieldsMigrateResponse;
-    };
     fields_remove_alias: {
         data: T.FieldsRemoveAliasData;
         response: T.FieldsRemoveAliasResponse;
@@ -491,6 +487,10 @@ export interface Operations {
         data: T.MigrationsCancelData;
         response: T.MigrationsCancelResponse;
     };
+    migrations_create: {
+        data: T.MigrationsCreateData;
+        response: T.MigrationsCreateResponse;
+    };
     migrations_get: {
         data: T.MigrationsGetData;
         response: T.MigrationsGetResponse;

package/dist/generated/operations.gen.js

@@ -32,7 +32,6 @@ export const OPERATIONS = {
     fields_get: { method: "GET", path: "/v1/fields/{field_id}" },
     fields_get_order: { method: "GET", path: "/v1/collections/{collection_id}/field-order" },
     fields_list: { method: "GET", path: "/v1/collections/{collection_id}/fields" },
-    fields_migrate: { method: "POST", path: "/v1/fields/{field_id}/migrations" },
     fields_remove_alias: { method: "DELETE", path: "/v1/fields/{field_id}/aliases/{alias}" },
     fields_reorder: { method: "PUT", path: "/v1/collections/{collection_id}/field-order" },
     fields_restore: { method: "POST", path: "/v1/fields/{field_id}/restore" },
@@ -40,6 +39,7 @@ export const OPERATIONS = {
     health_check: { method: "GET", path: "/v1/health" },
     me_get: { method: "GET", path: "/v1/me" },
     migrations_cancel: { method: "POST", path: "/v1/migrations/{migration_id}/cancel" },
+    migrations_create: { method: "POST", path: "/v1/collections/{collection_id}/migrations" },
     migrations_get: { method: "GET", path: "/v1/migrations/{migration_id}" },
     migrations_list: { method: "GET", path: "/v1/collections/{collection_id}/migrations" },
     projects_search: { method: "GET", path: "/v1/projects/{project_id}/search" },

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

@@ -683,9 +683,13 @@ export type FieldDefinition = {
     required: boolean;
 };
 /**
- * The parts of the definition to change; omitted parts stay as they are.
+ * The field, and the parts of its definition to change; omitted parts stay as they are.
  */
 export type FieldMigrationRequest = {
+    /**
+     * One of the collection's fields (`422` otherwise).
+     */
+    field_id: string;
     type?: FieldType;
     /**
      * The complete new configuration. When the type changes and this is omitted, only `description`, `searchable`, `filterable` and `sortable` carry over.
@@ -870,9 +874,9 @@ export type TimeFilter = {
     lt?: string;
 };
 /**
- * The client a change came through; `scheduler` for scheduled changes. `import` and `migration` are not sent yet.
+ * The client a change came through; `scheduler` for scheduled changes.
  */
-export type Via = 'ui' | 'api' | 'cli' | 'sdk' | 'import' | 'migration' | 'system' | 'scheduler';
+export type Via = 'ui' | 'api' | 'cli' | 'sdk' | 'system' | 'scheduler';
 /**
  * Changes to a record's content that wait until they are merged into
  * it, now or at `schedule.merge_at`. Content only: whether the record
@@ -1365,16 +1369,16 @@ export type WebhookEventPayload = {
     created_at: Timestamp;
     project_id: string;
     /**
-     * Who made the change. Always sent.
+     * Who made the change.
      */
-    actor?: Actor;
+    actor: Actor;
     /**
-     * The client the change came through (null when not known). Always
-     * sent. An integration that writes back can skip changes made with its own
-     * API key (`actor`).
+     * The client the change came through (null when not known). An
+     * integration that writes back can skip changes made with its own API
+     * key (`actor`).
      *
      */
-    via?: null | Via;
+    via: null | Via;
     data: RecordEventData | DraftEventData | AssetEventData | SchemaEventData | FieldAliasEventData | WebhookTestEventData;
 };
 /**
@@ -1700,7 +1704,7 @@ export type RecordRevisionFilter = {
     actor_id?: string;
     created_at?: TimeFilter;
 };
-export type AuditEventSort = 'id' | '-id';
+export type AuditEventSort = 'created_at' | '-created_at';
 /**
  * Page size.
  */
@@ -1717,14 +1721,20 @@ export type DeletedFilter = {
 };
 /**
  * `filter[deleted]=true` lists deleted assets instead.
- * `filter[content_type]` lists only assets of those types: comma-separated
- * MIME types or `type*` wildcards, for example the ones an asset field
- * accepts (its `accepted_types`).
+ * `filter[content_type]` lists only assets of a type: a MIME type or a
+ * `type*` wildcard, or several with
+ * `filter[content_type][in]=image*,application/pdf`, for example the
+ * ones an asset field accepts (its `accepted_types`).
  *
  */
 export type AssetFilter = {
     deleted?: 'true' | 'false';
-    content_type?: string;
+    content_type?: string | {
+        /**
+         * Up to 50 comma-separated MIME types or `type*` wildcards.
+         */
+        in: string;
+    };
 };
 /**
  * The revision you last read (the record's, or the draft's for a draft), e.g. `"7"`. Stale writes fail with 412.
@@ -1794,8 +1804,8 @@ export type RecordsListData = {
             [key: string]: RecordFilterValue;
         };
         /**
-         * `id`, `created_at`, `updated_at`, `published_at` (unpublished
-         * records first), or the key of a text, number, boolean, date or
+         * `created_at`, `updated_at`, `published_at` (unpublished records
+         * first), or the key of a text, number, boolean, date or
          * enum field with one value (records without a value last, in both
          * directions; text by code point). `-` for descending.
          *
@@ -3195,14 +3205,6 @@ export type DraftsListData = {
         collection_id: string;
     };
     query?: {
-        filter?: {
-            record_id?: string | {
-                /**
-                 * Up to 100 comma-separated record IDs.
-                 */
-                in: string;
-            };
-        };
         sort?: 'updated_at' | '-updated_at';
         /**
          * Page size.
@@ -4878,7 +4880,7 @@ export type MigrationsListResponses = {
     200: FieldMigrationList;
 };
 export type MigrationsListResponse = MigrationsListResponses[keyof MigrationsListResponses];
-export type FieldsMigrateData = {
+export type MigrationsCreateData = {
     body: FieldMigrationRequest;
     headers?: {
         /**
@@ -4907,14 +4909,17 @@ export type FieldsMigrateData = {
         'Nohead-Change-Note'?: string;
     };
     path: {
-        field_id: string;
+        /**
+         * Collection ID, or the collection slug when authenticating with an API key.
+         */
+        collection_id: string;
     };
     query?: {
         dry_run?: boolean;
     };
-    url: '/v1/fields/{field_id}/migrations';
+    url: '/v1/collections/{collection_id}/migrations';
 };
-export type FieldsMigrateErrors = {
+export type MigrationsCreateErrors = {
     /**
      * The request was malformed: unparseable JSON, an invalid query parameter, or a body key the operation doesn't take (detail code `unknown_parameter`, naming the key).
      */
@@ -4948,8 +4953,8 @@ export type FieldsMigrateErrors = {
      */
     429: Error;
 };
-export type FieldsMigrateError = FieldsMigrateErrors[keyof FieldsMigrateErrors];
-export type FieldsMigrateResponses = {
+export type MigrationsCreateError = MigrationsCreateErrors[keyof MigrationsCreateErrors];
+export type MigrationsCreateResponses = {
     /**
      * A preview (dry runs only).
      */
@@ -4959,7 +4964,7 @@ export type FieldsMigrateResponses = {
      */
     202: FieldMigration;
 };
-export type FieldsMigrateResponse = FieldsMigrateResponses[keyof FieldsMigrateResponses];
+export type MigrationsCreateResponse = MigrationsCreateResponses[keyof MigrationsCreateResponses];
 export type MigrationsGetData = {
     body?: never;
     path: {
@@ -5080,14 +5085,20 @@ export type AssetsListData = {
         cursor?: string;
         /**
          * `filter[deleted]=true` lists deleted assets instead.
-         * `filter[content_type]` lists only assets of those types: comma-separated
-         * MIME types or `type*` wildcards, for example the ones an asset field
-         * accepts (its `accepted_types`).
+         * `filter[content_type]` lists only assets of a type: a MIME type or a
+         * `type*` wildcard, or several with
+         * `filter[content_type][in]=image*,application/pdf`, for example the
+         * ones an asset field accepts (its `accepted_types`).
          *
          */
         filter?: {
             deleted?: 'true' | 'false';
-            content_type?: string;
+            content_type?: string | {
+                /**
+                 * Up to 50 comma-separated MIME types or `type*` wildcards.
+                 */
+                in: string;
+            };
         };
     };
     url: '/v1/projects/{project_id}/assets';
@@ -6725,7 +6736,7 @@ export type AuditEventsListData = {
             actor_id?: string;
             created_at?: TimeFilter;
         };
-        sort?: 'id' | '-id';
+        sort?: 'created_at' | '-created_at';
     };
     url: '/v1/projects/{project_id}/audit-events';
 };

package/dist/resources/assets.d.ts

@@ -38,7 +38,7 @@ export declare class Assets extends Resource {
     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>;
+    list({ content_type, ...params }?: AssetListParams, options?: RequestOptions): PagePromise<Asset>;
     get(asset: string, options?: RequestOptions): APIPromise<Asset>;
     /**
      * Soft-deletes the asset: `restore` brings it back until its

package/dist/resources/assets.js

@@ -74,8 +74,15 @@ export class Assets extends Resource {
     complete(asset, options) {
         return this.core.request("assets_complete", { path: { asset_id: asset } }, options);
     }
-    list(params = {}, options) {
-        return this.core.paginate("assets_list", { query: listQuery(params, ["deleted", "content_type"]) }, options);
+    list({ content_type, ...params } = {}, options) {
+        return this.core.paginate("assets_list", {
+            query: listQuery({
+                ...params,
+                content_type: Array.isArray(content_type)
+                    ? { in: content_type }
+                    : content_type,
+            }, ["deleted", "content_type"]),
+        }, options);
     }
     get(asset, options) {
         return this.core.request("assets_get", { path: { asset_id: asset } }, options);

package/dist/resources/drafts.d.ts

@@ -19,11 +19,10 @@ export declare class Drafts extends Resource {
      */
     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).
+     * A collection's drafts, most recently changed first. One record's draft
+     * is `records.drafts(record)`.
      */
-    list<D = RecordData>(collection: string, { record_id, ...params }?: DraftListParams, options?: RequestOptions): PagePromise<NoheadDraft<D>>;
+    list<D = RecordData>(collection: string, 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. */

package/dist/resources/drafts.js

@@ -17,22 +17,11 @@ export class Drafts extends Resource {
         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).
+     * A collection's drafts, most recently changed first. One record's draft
+     * is `records.drafts(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);
+    list(collection, params = {}, options) {
+        return this.core.paginate("drafts_list", { path: { collection_id: collection }, query: params }, options);
     }
     /** With `data` as the record reads after the merge, for previews. */
     get(draft, params = {}, options) {

package/dist/resources/schema.d.ts

@@ -1,7 +1,7 @@
 import type { APIPromise, PagePromise } from "../api-promise.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 type { DeletedListParams, DryRunParams, FieldReorderParams, ListParams, MigrationCreateParams, 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 {
@@ -39,7 +39,7 @@ export declare class Fields extends Resource {
     get(field: string, options?: RequestOptions): APIPromise<Field>;
     /**
      * Renames, describes or loosens a field. Changes that rewrite record
-     * values (type, `multiple`, tighter rules) are `migrate`.
+     * values (type, `multiple`, tighter rules) are `migrations.create`.
      */
     update(field: string, params: FieldUpdate, options?: WriteOptions): APIPromise<Field>;
     /**
@@ -54,17 +54,18 @@ export declare class Fields extends Resource {
     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>;
+}
+/** Field migrations. While one runs, its collection is read-only. */
+export declare class Migrations extends Resource {
     /**
-     * Starts a field migration (type, `multiple`, tighter configuration or a
-     * backfill) that rewrites every record. With `dry_run`, previews it.
+     * Starts a migration of one of the collection's fields (`field_id`): a
+     * type, `multiple`, tighter configuration or a backfill, which rewrites
+     * every record. With `dry_run`, previews it.
      */
-    migrate(field: string, params: FieldMigrateParams & {
+    create(collection: string, params: MigrationCreateParams & {
         dry_run: true;
     }, 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 {
+    create(collection: string, params: MigrationCreateParams & DryRunParams, options?: WriteOptions): APIPromise<FieldMigration>;
     list(collection: string, params?: ListParams, options?: RequestOptions): PagePromise<FieldMigration>;
     get(migration: string, options?: RequestOptions): APIPromise<FieldMigration>;
     cancel(migration: string, options?: RequestOptions): APIPromise<FieldMigration>;

package/dist/resources/schema.js

@@ -66,7 +66,7 @@ export class Fields extends Resource {
     }
     /**
      * Renames, describes or loosens a field. Changes that rewrite record
-     * values (type, `multiple`, tighter rules) are `migrate`.
+     * values (type, `multiple`, tighter rules) are `migrations.create`.
      */
     update(field, params, options) {
         return this.core.request("fields_update", { path: { field_id: field }, body: params }, options);
@@ -93,12 +93,12 @@ export class Fields extends Resource {
     removeAlias(field, alias, options) {
         return this.core.request("fields_remove_alias", { path: { field_id: field, alias } }, options);
     }
-    migrate(field, { dry_run, ...body }, options) {
-        return this.core.request("fields_migrate", { path: { field_id: field }, query: { dry_run }, body }, options);
-    }
 }
 /** Field migrations. While one runs, its collection is read-only. */
 export class Migrations extends Resource {
+    create(collection, { dry_run, ...body }, options) {
+        return this.core.request("migrations_create", { path: { collection_id: collection }, query: { dry_run }, body }, options);
+    }
     list(collection, params = {}, options) {
         return this.core.paginate("migrations_list", { path: { collection_id: collection }, query: params }, options);
     }

package/dist/types.d.ts

@@ -88,8 +88,6 @@ export interface DraftGetParams {
     expand?: string[];
 }
 export interface DraftListParams extends ListParams {
-    /** One record's draft, or several records' (up to 100). */
-    record_id?: string | string[];
     sort?: "updated_at" | "-updated_at";
 }
 export interface DraftScheduleParams {
@@ -155,9 +153,9 @@ export interface DeletedListParams extends ListParams {
 }
 export interface AssetListParams extends DeletedListParams {
     /**
-     * Only assets of these MIME types or `type/*` wildcards, e.g.
-     * `["image/*", "application/pdf"]`, such as an asset field's
-     * `accepted_types`.
+     * Only assets of a MIME type or `type/*` wildcard (`"image/*"`), or of any
+     * of several: `["image/*", "application/pdf"]`, such as an asset
+     * field's `accepted_types`.
      */
     content_type?: string | string[];
 }
@@ -165,7 +163,8 @@ export interface SchemaParams {
     /** A past schema version; the current one otherwise. */
     version?: number;
 }
-export type FieldMigrateParams = G.FieldMigrationRequest;
+/** `field_id`, one of the collection's fields, and the parts of its definition to change. */
+export type MigrationCreateParams = G.FieldMigrationRequest;
 export interface FieldReorderParams {
     /** Every active field of the collection, once each, in the new order. */
     field_ids: string[];
@@ -188,7 +187,8 @@ export interface AuditEventFilter {
 }
 export interface AuditEventListParams extends ListParams {
     filter?: AuditEventFilter;
-    sort?: "id" | "-id";
+    /** Newest first by default (`-created_at`). */
+    sort?: "created_at" | "-created_at";
 }
 /** The metadata of a search page: also an estimate of the total hits. */
 export type SearchMeta = G.SearchResults["meta"];

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.0";

package/package.json

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