nohead 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4381c6ca769b33734069a6b117b59f03d1ebfa3b283698f2f20047b527bf376f
-  data.tar.gz: 9b6dbcf5e1cc441cc10356a2d4b18ae0ae7485faeb4bba79a474ce045aa0150e
+  metadata.gz: e94f698ee3cb6906c1b21535666bdefc57f6d864dbad5eb3436c9e0a7a4bff2f
+  data.tar.gz: a47d275d02c1b5111b0eadc5f14dedf2a201c5fdcf01ae0eaba306c3bdb87ad2
 SHA512:
-  metadata.gz: c3491a32b9f27da5dc3ca67b2dbed3952508130cc04ee129954c8ecc4684e4e7fa36806e5914f34bba73ac2da4c43162ffd025891f03f77ad3d6151faa55d1fe
-  data.tar.gz: 5da0e9d7a4869ae460a70737dd34a4e4b9a20fa61d3524a2f5bd0a1e8fa67de2f61886e0e1f003a0b575b0e20006f5529933dc49433e2d2d3d68189ce4913947
+  metadata.gz: bbac1644f34a8ea9ff5b41b342facdfea9df8de606cca48e00fcbde9adcb0d3564c65973f43f087d8d6acc4f9443057107c7eb244ab47f557d96bb6b1f1d14cb
+  data.tar.gz: e650ba515324f59b5cd141534be18d49ae4530e5fe89d7d19bf3aac1e2a6c97fc502b6094b06e43e580b771391d110ad72e32c166235eab6492b8592aaba4a0c

data/CHANGELOG.md

@@ -5,6 +5,39 @@ Changes to the `nohead` gem 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:, ..., dry_run: true)`
+  (`POST /v1/collections/{collection_id}/migrations`) replaces
+  `fields.migrate(field, ...)`. It returns a preview for a dry run, and the
+  FieldMigration otherwise.
+- **Breaking:** `drafts.list` no longer takes `record_id:`; a record's draft
+  is `records.drafts(record)`.
+- **Breaking:** `assets.list(content_type:)` takes one MIME type or `type/*`
+  wildcard (`"image/*"`), or an Array of them, sent as
+  `filter[content_type][in]` (an empty Array is any type). A
+  comma-separated string is no longer several types.
+- **Breaking:** `audit_events.list` sorts by `created_at` or `-created_at`
+  (the default; was `id` and `-id`), and `records.list` no longer sorts by
+  `id`.
+- Webhook events always carry `actor` and `via`, and `via` is no longer
+  `import` or `migration`.
+
+## 0.4.0
+
+- **Breaking:** a field's `api_key` is its `key` (in fields, their aliases,
+  `fields.create(..., key:)` and `fields.update(..., key:)`), as the
+  editor's "Field key" says. API keys keep their name.
+- **Breaking:** `collections.schema_changes.get(schema_change)` takes the
+  schema change's ID alone (`GET /v1/schema-changes/{id}`).
+- **Breaking:** `fields.update` no longer takes `type` or `multiple`; they
+  rewrite record values, so they are `fields.migrate`. The API refuses a
+  body key an operation doesn't take with `400` (`unknown_parameter`,
+  naming it), so a misspelt keyword no longer passes unnoticed.
+- The contract types each field's `configuration` by field type; the API
+  reference lists each type's options.
+
 ## 0.3.0
 
 - **Upgrade required:** 0.1 and 0.2 no longer work with the current API,

data/README.md

@@ -95,7 +95,7 @@ nohead.drafts.merge(draft.id) # or drafts.schedule(draft.id, merge_at: ...)
 
 - A record has at most one draft; starting a second raises `Nohead::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 raises `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.
 
 ## Pagination
@@ -229,12 +229,12 @@ Search needs `search_enabled` collections and the `search:read` scope. It pages
 
 ```ruby
 nohead.collections.create(name: "Posts", slug: "posts",
-                          fields: [{ name: "Title", api_key: "title", type: "text", required: true }])
-nohead.fields.create("posts", name: "Summary", api_key: "summary", type: "long_text")
+                          fields: [{ name: "Title", key: "title", type: "text", required: true }])
+nohead.fields.create("posts", name: "Summary", key: "summary", type: "long_text")
 
 # Changes that rewrite records go through a migration; preview first
-preview = nohead.fields.migrate("fld_...", type: "long_text", dry_run: true)
-migration = nohead.fields.migrate("fld_...", type: "long_text")
+preview = nohead.migrations.create("posts", field_id: "fld_...", type: "long_text", dry_run: true)
+migration = nohead.migrations.create("posts", field_id: "fld_...", type: "long_text")
 nohead.migrations.get(migration.id)
 ```
 
@@ -279,8 +279,8 @@ The API's resources come back as `Nohead::NoheadObject`s.
 | `collections` | `list`, `get`, `create`, `update`, `delete`, `restore`, `schema` |
 | `collections.schema_changes` | `list`, `get` |
 | `collections.search_index` | `get`, `rebuild` |
-| `fields` | `list`, `get`, `create`, `update`, `delete`, `restore`, `order`, `reorder`, `remove_alias`, `migrate` |
-| `migrations` | `list`, `get`, `cancel` |
+| `fields` | `list`, `get`, `create`, `update`, `delete`, `restore`, `order`, `reorder`, `remove_alias` |
+| `migrations` | `create`, `list`, `get`, `cancel` |
 | `assets` | `upload`, `create_upload`, `complete`, `list`, `get`, `delete`, `restore`, `purge`, `usage`, `image_url`, `download_url` |
 | `webhooks` | `list`, `get`, `create`, `update`, `delete`, `restore`, `rotate_secret`, `test`, `unwrap` |
 | `webhooks.secrets` | `list`, `retire` |

data/lib/nohead/client.rb

@@ -148,6 +148,10 @@ module Nohead
 
     def build_url(template, values)
       values = values.transform_keys(&:to_s)
+      # A value the template doesn't take is a method out of step with its operation.
+      unknown = values.keys - template.scan(/\{(\w+)\}/).flatten
+      raise ArgumentError, "#{unknown.join(', ')} is not a path parameter of #{template}" if unknown.any?
+
       values["project_id"] ||= project_id if template.include?("{project_id}")
       path = template.gsub(/\{(\w+)\}/) do
         value = values[Regexp.last_match(1)]

data/lib/nohead/operations.rb

@@ -37,7 +37,6 @@ module Nohead
     "fields_get" => ["GET", "/v1/fields/{field_id}"],
     "fields_get_order" => ["GET", "/v1/collections/{collection_id}/field-order"],
     "fields_list" => ["GET", "/v1/collections/{collection_id}/fields"],
-    "fields_migrate" => ["POST", "/v1/fields/{field_id}/migrations"],
     "fields_remove_alias" => ["DELETE", "/v1/fields/{field_id}/aliases/{alias}"],
     "fields_reorder" => ["PUT", "/v1/collections/{collection_id}/field-order"],
     "fields_restore" => ["POST", "/v1/fields/{field_id}/restore"],
@@ -45,6 +44,7 @@ module Nohead
     "health_check" => ["GET", "/v1/health"],
     "me_get" => ["GET", "/v1/me"],
     "migrations_cancel" => ["POST", "/v1/migrations/{migration_id}/cancel"],
+    "migrations_create" => ["POST", "/v1/collections/{collection_id}/migrations"],
     "migrations_get" => ["GET", "/v1/migrations/{migration_id}"],
     "migrations_list" => ["GET", "/v1/collections/{collection_id}/migrations"],
     "projects_search" => ["GET", "/v1/projects/{project_id}/search"],
@@ -68,7 +68,7 @@ module Nohead
     "records_unschedule" => ["DELETE", "/v1/records/{record_id}/schedule"],
     "records_update" => ["PATCH", "/v1/records/{record_id}"],
     "scheduled_changes_list" => ["GET", "/v1/collections/{collection_id}/scheduled-changes"],
-    "schema_changes_get" => ["GET", "/v1/collections/{collection_id}/schema-changes/{schema_change_id}"],
+    "schema_changes_get" => ["GET", "/v1/schema-changes/{schema_change_id}"],
     "schema_changes_list" => ["GET", "/v1/collections/{collection_id}/schema-changes"],
     "search_index_get" => ["GET", "/v1/collections/{collection_id}/search-index"],
     "search_index_rebuild" => ["POST", "/v1/collections/{collection_id}/search-index/rebuild"],

data/lib/nohead/resources/assets.rb

@@ -54,10 +54,12 @@ module Nohead
         @client.request("assets_complete", path: { asset_id: asset }, idempotency_key: idempotency_key)
       end
 
-      # `content_type` lists only assets of those MIME types or `type/*`
-      # wildcards (["image/*", "application/pdf"]), for example the ones an
-      # asset field accepts (its `accepted_types`).
+      # `content_type` lists only assets of a MIME type or `type/*` wildcard
+      # ("image/*"), or of several (["image/*", "application/pdf"]), for
+      # example the ones an asset field accepts (its `accepted_types`; an
+      # empty list, like a field's, means any type).
       def list(content_type: nil, deleted: nil, limit: nil, cursor: nil)
+        content_type = (content_type.empty? ? nil : { in: content_type }) if content_type.is_a?(Array)
         @client.paginate("assets_list", query: { filter: { content_type: content_type, deleted: deleted },
                                                  limit: limit, cursor: cursor })
       end

data/lib/nohead/resources/drafts.rb

@@ -16,16 +16,11 @@ module Nohead
                                          idempotency_key: idempotency_key)
       end
 
-      # A collection's drafts, most recently changed first. `record_id`
-      # narrows them to one record, or to several (an Array of 1 to 100; an
-      # empty one raises ArgumentError, since it would match no record).
-      def list(collection, record_id: nil, sort: nil, limit: nil, cursor: nil)
-        raise ArgumentError, "record_id needs at least one record ID" if record_id == []
-
-        record_filter = record_id.is_a?(Array) ? { in: record_id } : record_id
+      # A collection's drafts, most recently changed first. One record's
+      # draft is `records.drafts(record)`.
+      def list(collection, sort: nil, limit: nil, cursor: nil)
         @client.paginate("drafts_list", path: { collection_id: collection },
-                                        query: { filter: { record_id: record_filter }, sort: sort,
-                                                 limit: limit, cursor: cursor })
+                                        query: { sort: sort, limit: limit, cursor: cursor })
       end
 
       # With `data` as the record reads after the merge, for previews.

data/lib/nohead/resources/other.rb

@@ -10,6 +10,8 @@ module Nohead
       #
       #   audit_events.list(filter: { type: "record.*", resource_type: %w[record draft],
       #                               created_at: { gte: Time.utc(2026, 10, 1) } })
+      #
+      # `sort` is "-created_at" (the default) or "created_at".
       def list(filter: nil, sort: nil, limit: nil, cursor: nil)
         filter = filter&.transform_keys(&:to_sym)
         types = filter&.[](:resource_type)

data/lib/nohead/resources/schema.rb

@@ -60,9 +60,8 @@ module Nohead
                                                 query: { limit: limit, cursor: cursor })
       end
 
-      def get(collection, schema_change)
-        @client.request("schema_changes_get",
-                        path: { collection_id: collection, schema_change_id: schema_change })
+      def get(schema_change)
+        @client.request("schema_changes_get", path: { schema_change_id: schema_change })
       end
     end
 
@@ -96,7 +95,7 @@ module Nohead
       end
 
       # 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`.
       def update(field, idempotency_key: nil, change_note: nil, **params)
         @client.request("fields_update", path: { field_id: field }, body: body_of(params),
                                          idempotency_key: idempotency_key, change_note: change_note)
@@ -126,23 +125,26 @@ module Nohead
                                           idempotency_key: idempotency_key, change_note: change_note)
       end
 
-      # Stops accepting a renamed field's old API key before its 6 months end.
+      # Stops accepting a renamed field's old key before its 6 months end.
       def remove_alias(field, alias_key, idempotency_key: nil)
         @client.request("fields_remove_alias", path: { field_id: field, alias: alias_key },
                                                idempotency_key: idempotency_key)
       end
-
-      # Starts a field migration (type, multiple, tighter configuration or a
-      # backfill) that rewrites every record. With dry_run: true, previews it.
-      def migrate(field, dry_run: false, idempotency_key: nil, change_note: nil, **params)
-        @client.request("fields_migrate", path: { field_id: field }, query: { dry_run: dry_run || nil },
-                                          body: body_of(params), idempotency_key: idempotency_key,
-                                          change_note: change_note)
-      end
     end
 
     # Field migrations. While one runs, its collection is read-only.
     class Migrations < Resource
+      # Starts a migration of one of the collection's fields (`field_id`):
+      # its type, multiple, a tighter configuration or a backfill, which
+      # rewrites every record. Returns the FieldMigration, or with
+      # dry_run: true a preview (counts and sample records, nothing written).
+      def create(collection, field_id:, dry_run: false, idempotency_key: nil, change_note: nil, **params)
+        @client.request("migrations_create", path: { collection_id: collection },
+                                             query: { dry_run: dry_run || nil },
+                                             body: { field_id: field_id, **body_of(params) },
+                                             idempotency_key: idempotency_key, change_note: change_note)
+      end
+
       def list(collection, limit: nil, cursor: nil)
         @client.paginate("migrations_list", path: { collection_id: collection },
                                             query: { limit: limit, cursor: cursor })

data/lib/nohead/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nohead
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nohead
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nohead