nohead 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3b6ddca7dac0c2e2e1056aabba232a26b27fce7eae7eea1244519a88d0388fe
-  data.tar.gz: e9c0c92435a093999388ef2a84c73870c12dead425ada3c3bdf691c9fe993069
+  metadata.gz: 4381c6ca769b33734069a6b117b59f03d1ebfa3b283698f2f20047b527bf376f
+  data.tar.gz: 9b6dbcf5e1cc441cc10356a2d4b18ae0ae7485faeb4bba79a474ce045aa0150e
 SHA512:
-  metadata.gz: 3ab6ef2e8d3d027b07a2ff536cf3f14833970b4d80cbc51fcf2b65a3a10684012a4a1e70088b426e0c77a55927a21f2816d13991c869321bbdff84d705d30f8c
-  data.tar.gz: 2c73018868bc99808615f989f735149122b655705eac1f0af62a9bccfab465582857bbad1fb91a5f635230f2af272404f831d20e05f2387295ada5b901b0798a
+  metadata.gz: c3491a32b9f27da5dc3ca67b2dbed3952508130cc04ee129954c8ecc4684e4e7fa36806e5914f34bba73ac2da4c43162ffd025891f03f77ad3d6151faa55d1fe
+  data.tar.gz: 5da0e9d7a4869ae460a70737dd34a4e4b9a20fa61d3524a2f5bd0a1e8fa67de2f61886e0e1f003a0b575b0e20006f5529933dc49433e2d2d3d68189ce4913947

data/CHANGELOG.md

@@ -5,6 +5,103 @@ 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.3.0
+
+- **Upgrade required:** 0.1 and 0.2 no longer work with the current API,
+  whose paths changed.
+- `change_note` is sent percent-encoded (UTF-8), so change notes work in any
+  language: a note outside ASCII used to fail the request.
+- Drafts: changes to a record that wait until they are merged into it, now
+  or at a set time. `drafts.create`, `list`, `get` (with `expand`, for
+  previews), `update`, `discard`, `merge`, `schedule` and `unschedule`, and
+  `records.drafts`. `records.publish` on a live record with a pending draft
+  raises `ConflictError` (`draft_pending`). Webhook events of `draft.*` carry
+  the `draft` and its `draft_id`, and a merge's `record.updated` its
+  `draft_id`.
+- **Breaking:** the API is resource-oriented. Method names stay; what they
+  return and take follows it:
+  - Records have no `status`, `schedule` or `deleted`: a record is published
+    when `published_at` is set, and has `deleted_at` and `purge_after`.
+    Filter with `{ published_at: { exists: true } }`. `records.get` returns
+    deleted records too (no `include_deleted`).
+  - `records.schedule` replaces the whole schedule: a time left out is
+    cleared, and `clear:` is gone. It and `unschedule` return the schedule,
+    and `records.get_schedule`, `records.publication` and
+    `records.scheduled_changes` are new. A scheduled change has no
+    `last_error`. `records.bulk` returns a record batch.
+  - `search` takes `filter:` as `records.list` does
+    (`filter: { published_at: { exists: true } }`) instead of
+    `status: "published"`.
+  - `records.diff(record, from:, to:)` and
+    `fields.reorder(collection, field_ids:)` take keywords.
+  - `audit_events.list` filters by `type` (was `action`), `resource_type`
+    (a type, or an Array of them), `resource_id`, `actor_type`, `actor_id`
+    and a `created_at` range (`{ gte: ..., lt: ... }`, was `since` and
+    `until`); the API refuses other filters. Events have `object: "event"`
+    and their name in `type`, and a field's events the resource type
+    `field`.
+  - `records.revisions.list` filters by a `created_at` range (was `since`
+    and `until`), and a revision's `operation` can be `merge` (no
+    `import`).
+  - Schema changes have no `status`.
+  - Collections, fields, assets and webhooks have `deleted_at` and
+    `purge_after` instead of `deleted`, and migrations
+    `cancel_requested_at`.
+  - `assets.create_upload` returns the asset with its `upload`.
+  - `fields.reorder` returns the field order; `fields.order` reads it.
+  - Webhook event types are the same as the activity log's
+    (`record.restored`, `field.updated`, ..., and wildcards such as
+    `record.*`), and events carry
+    `actor` and `via`. `webhooks.rotate_secret` returns the new webhook
+    secret with its value; the old secret signs for 24 hours more.
+    `webhooks.secrets.list`, `webhooks.secrets.retire`, `webhooks.restore`
+    and `webhooks.list(deleted: true)` are new. There is no
+    `record.imported` event; `field.*` events carry the `field_id`, and
+    schema events' `collection` its `object`.
+  - `if_match` and `change_note` go where the API takes them:
+    `records.restore` takes `if_match` and `records.revisions.revert`
+    `change_note`. Methods that take fields as keywords
+    (`webhooks.create`, `assets.create_upload`...) raise ArgumentError for
+    an `if_match` or `change_note` they don't take, instead of sending it
+    as a field.
+  - Timestamps are the ones the API declares, so `purge_after`, a
+    scheduled change's `at` and `health.check`'s `time` are Times too, and
+    a record's field values are left as they come (a field whose name
+    ended in `_at` used to be a Time).
+- **Breaking:** the `datetime` field type is now `date`. A plain date field holds
+  `YYYY-MM-DD`; with `include_time` it holds a moment, written in the field's
+  `time_zone` when it has one. Field migrations take `time_zone`, the zone
+  whose day each moment falls on when the time is removed.
+- Boolean fields can't be `required`: a boolean is true or false, and no
+  value reads as false.
+- Text fields take a `format` (`email`, `url`, `slug`; slugs are always
+  unique) and text and integer fields `unique`; a taken value's error detail
+  has the `record_id` that has it (`code: "taken"`).
+- Filters take operators: `{ price: { lt: 50 } }`, with `eq`, `ne`, `gt`,
+  `gte`, `lt`, `lte`, `in` (an array) and `exists`, and record lists sort by
+  a field's value. Commas and backslashes in array values are escaped, so a
+  value can hold a comma.
+- Date filters take `today`, and dates with a time `now`.
+- `assets.usage`: where an asset is used, as counts of the records that use
+  it (and of those, the published ones) and the 10 most recently updated with
+  the fields that use it. Needs the `records:read` scope too.
+- `assets.purge`: permanently deletes a deleted asset now, instead of at its
+  `purge_after`, and frees its storage.
+- `fields.get`.
+- `assets.upload` with an `idempotency_key` resumes: an asset that is
+  already `ready` comes back without sending the bytes again, and one whose
+  upload URL expired raises `UploadError` (start over with a new key).
+- An error reads only the fields of the API's error envelope that have the
+  right type, so JSON from a proxy or gateway that merely looks like one no
+  longer gives it a non-string `message`, `type` or `request_id`, turns a
+  `details` object into key-value pairs, or makes `current_revision` raise on
+  a detail that isn't an object.
+
+## 0.2.0
+
+- Types follow the API's current contract. They add types only for
+  operations an API key can't call, so no method changed.
+
 ## 0.1.0
 
 The first release.

data/README.md

@@ -7,18 +7,19 @@ require "nohead"
 
 nohead = Nohead::Client.new # reads NOHEAD_API_KEY
 
-nohead.records.list("posts", filter: { status: "published" }).each do |post|
+nohead.records.list("posts", filter: { published_at: { exists: true } }).each do |post|
   puts post.data["title"]
 end
 ```
 
-> **Status:** 0.x, not yet published to RubyGems. Until it is, use it from GitHub: `gem "nohead", github: "nohead-io/nohead-ruby"`.
+> **Status:** 0.x until the Nohead API launches.
 
 ## Contents
 
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Records](#records)
+- [Drafts](#drafts)
 - [Pagination](#pagination)
 - [Errors](#errors)
 - [Retries and idempotency](#retries-and-idempotency)
@@ -64,11 +65,12 @@ API keys belong to a project, so methods like `collections.list` need no project
 ## Records
 
 ```ruby
-draft = nohead.records.create("posts", data: { title: "Hello", author: "rec_01J9..." })
-post = nohead.records.get(draft.id, expand: ["author"])
+created = nohead.records.create("posts", data: { title: "Hello", author: "rec_01J9..." })
+post = nohead.records.get(created.id, expand: ["author"])
 nohead.records.update(post.id, data: { title: "Hello again" }) # nil clears a field
 nohead.records.publish(post.id)
-nohead.records.schedule(post.id, unpublish_at: Time.utc(2027, 1, 1))
+nohead.records.publication(post.id) # since when, by whom, which revision
+nohead.records.schedule(post.id, unpublish_at: Time.utc(2027, 1, 1)) # the whole schedule: a time left out is cleared
 nohead.records.delete(post.id) # soft delete; records.restore undoes it
 ```
 
@@ -77,8 +79,24 @@ Methods return the API's resources (see [Results](#results)) and raise on failur
 **More:**
 
 - `count`, and `bulk` (up to 100 records at once)
-- `diff(record, from_revision, to_revision)`
-- `revisions.list`, `revisions.get` and `revisions.revert` (with `dry_run: true` for a preview)
+- `diff(record, from: 1, to: 2)`
+- `revisions.list` (`filter:` `operation`, `actor_id` and a `created_at` range such as `{ gte: Time.utc(2026, 10, 1) }`), `revisions.get` and `revisions.revert` (with `dry_run: true` for a preview)
+
+## Drafts
+
+A draft holds changes to a record until they are merged, now or at a set time, while the record keeps its current content: changes to review before they go live, or changes due later.
+
+```ruby
+draft = nohead.drafts.create(post.id, data: { title: "Hello, revised" })
+nohead.drafts.update(draft.id, data: { summary: "..." }, if_match: draft)
+preview = nohead.drafts.get(draft.id, expand: ["author"]) # data as it would read
+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).
+- `drafts.discard` deletes one for good.
 
 ## Pagination
 
@@ -99,11 +117,14 @@ page = page.next_page while page.next_page?
 nohead.records.list("posts", cursor: saved_cursor)
 ```
 
-Filters are equality filters (for fields with several values: "contains"), and accept strings, numbers, booleans and Times:
+Filters take a value to equal, or operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in` (an array) and `exists`. They combine with AND. On fields with several values, equal means "contains". Values are strings, numbers, booleans, Times (for date fields with a time) and Dates (for plain date fields, sent as `YYYY-MM-DD`); dates take `"today"` too, and dates with a time `"now"`. Lists sort by a field as well, with records that have no value last:
 
 ```ruby
-nohead.records.list("posts", filter: { status: "published", featured: true, author: "rec_01J9..." },
+nohead.records.list("posts", filter: { published_at: { exists: true }, featured: true, author: "rec_01J9..." },
                              sort: "-published_at", expand: %w[author tags])
+
+nohead.records.list("products", filter: { price: { lt: 50 }, category: { in: %w[shoes bags] }, cover: { exists: true } },
+                                sort: "price")
 ```
 
 ## Errors
@@ -151,7 +172,7 @@ Every write gets an `Idempotency-Key` that stays the same across its retries, so
 nohead.records.create("posts", data: data, idempotency_key: "import-#{row.id}")
 ```
 
-Writes also take `change_note:`, a reason shown in history.
+Writes that change records or the schema also take `change_note:`, a reason shown in history.
 
 ## Concurrency
 
@@ -166,7 +187,7 @@ rescue Nohead::PreconditionFailedError => e
 end
 ```
 
-`if_match:` takes a record or a revision number, on `update`, `delete`, `publish`, `unpublish` and `revisions.revert`.
+`if_match:` takes a record (or draft) or a revision number, on `records.update`, `delete`, `restore`, `publish`, `unpublish` and `revisions.revert`, and on `drafts.update`, `discard` and `merge`.
 
 ## Assets
 
@@ -187,6 +208,8 @@ url = nohead.assets.image_url(asset.id, width: 1200, format: "webp").url
 
 **Errors:** `UploadError` if storage refuses the bytes; `ValidationError` if the file fails the checks.
 
+**Resuming:** with an `idempotency_key:`, running the same upload again resumes it: the key starts the upload, and an asset that is already `ready` comes back without sending the bytes again. Once the upload's URL has expired (its `upload.expires_at`), it raises `UploadError`: start over with a new key.
+
 **Uploading from a browser:** create the upload on your server with `create_upload`, `PUT` the file from the browser, then `complete` it.
 
 ## Search
@@ -196,7 +219,7 @@ url = nohead.assets.image_url(asset.id, width: 1200, format: "webp").url
 nohead.records.search("posts", "content model").each { |hit| ... }
 
 # Across the project
-results = nohead.search("content model", collections: %w[posts pages])
+results = nohead.search("content model", collections: %w[posts pages], filter: { published_at: { exists: true } })
 results.meta.total_estimate
 ```
 
@@ -231,7 +254,7 @@ end
 head :no_content
 ```
 
-`unwrap` checks the signature and the timestamp (Standard Webhooks), and raises `Nohead::WebhookVerificationError` if either is off. Pass the raw body: parsing and re-serializing JSON changes the bytes.
+Event types are the same as the activity log's (`record.published`, `record.restored`, `field.updated`, `asset.purged`, ...), and a webhook subscribes to types or wildcards (`record.*`, `*`). `event.actor` says who made the change, and `event.via` through which client. `unwrap` checks the signature and the timestamp (Standard Webhooks), and raises `Nohead::WebhookVerificationError` if either is off. After `rotate_secret`, requests carry a signature for the old secret and the new one for 24 hours, so switch the receiver's secret within that day (or end it sooner with `webhooks.secrets.retire`). Pass the raw body: parsing and re-serializing JSON changes the bytes.
 
 It's also available as `nohead.webhooks.unwrap` on a client. Events can arrive more than once, so deduplicate by the `webhook-id` header.
 
@@ -241,7 +264,7 @@ The API's resources come back as `Nohead::NoheadObject`s.
 
 - **Reading fields:** use methods (`record.data`) or `[]` (`record[:data]`, `record["data"]`), at any depth.
 - **Fields named like Ruby's own methods** (`method`, `hash`…) need `[]`.
-- **Timestamps** (`*_at`) are `Time`s.
+- **Timestamps** (the API's: `created_at`, `purge_after`, a scheduled change's `at`...) are `Time`s. A record's field values (`record.data`) stay as they come.
 - **Unknown fields are kept**, because the API adds fields and values without notice.
 - **`to_h`** gives the raw Hash.
 
@@ -249,16 +272,18 @@ The API's resources come back as `Nohead::NoheadObject`s.
 
 | Resource | Methods |
 |---|---|
-| `records` | `list`, `get`, `create`, `update`, `delete`, `restore`, `publish`, `unpublish`, `schedule`, `unschedule`, `count`, `bulk`, `diff`, `search` |
+| `records` | `list`, `get`, `create`, `update`, `delete`, `restore`, `publish`, `unpublish`, `publication`, `get_schedule`, `schedule`, `unschedule`, `scheduled_changes`, `drafts`, `count`, `bulk`, `diff`, `search` |
+| `drafts` | `create`, `list`, `get`, `update`, `discard`, `merge`, `schedule`, `unschedule` |
 | `records.revisions` | `list`, `get`, `revert` |
 | `search` | across the project |
 | `collections` | `list`, `get`, `create`, `update`, `delete`, `restore`, `schema` |
 | `collections.schema_changes` | `list`, `get` |
 | `collections.search_index` | `get`, `rebuild` |
-| `fields` | `list`, `create`, `update`, `delete`, `restore`, `reorder`, `remove_alias`, `migrate` |
+| `fields` | `list`, `get`, `create`, `update`, `delete`, `restore`, `order`, `reorder`, `remove_alias`, `migrate` |
 | `migrations` | `list`, `get`, `cancel` |
-| `assets` | `upload`, `create_upload`, `complete`, `list`, `get`, `delete`, `restore`, `image_url`, `download_url` |
-| `webhooks` | `list`, `get`, `create`, `update`, `delete`, `rotate_secret`, `test`, `unwrap` |
+| `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` |
 | `webhooks.deliveries` | `list`, `get`, `retry` |
 | `audit_events` | `list` |
 | `feature_flags` | `list` |
@@ -281,7 +306,7 @@ bundle exec rake samples    # after changing test/calls.rb (the docs' code sampl
 
 - `openapi.json` is the API's published contract. `rake generate` derives the operation table, `lib/nohead/operations.rb`, from it.
 - The methods are written by hand.
-- `test/contract_test.rb` runs every call in `test/calls.rb`. It fails when an API-key operation in the contract has no method, or when a request doesn't match its operation.
+- `test/contract_test.rb` runs every call in `test/calls.rb`. It fails when an API-key operation in the contract has no method, when a query parameter is never sent (no method takes it, or no call passes it), or when a request doesn't match its operation (method, path, query parameters and JSON body, against their schemas). Each call gets an example of its operation's response, built from the contract's schema, and must return it.
 
 The smoke test (`smoke/smoke.rb`) runs the core flow against a real API, with the gem as installed from its built package. Nohead's own CI runs it on every API contract change.
 
@@ -291,7 +316,7 @@ The smoke test (`smoke/smoke.rb`) runs the core flow against a real API, with th
 2. Add a section for the version to `CHANGELOG.md` (`## 1.2.3`), which becomes the release's notes.
 3. Merge to `main`. Its ruleset requires the **CI passed** check, so the commit goes through a pull request or a branch whose CI passed, and force pushes are refused.
 4. Run the **SDK release** workflow in the Nohead API repository. It runs this commit's smoke test against the API and pushes the tag `v1.2.3`. Nobody else can push `v*` tags: a tag ruleset lets only that workflow's deploy key through.
-5. The tag starts `.github/workflows/release.yml`. Its publishing job runs in the `release` environment, which only `v*` tags can use, and the registry's trusted publisher accepts only that environment. It checks the version and its notes, tests, and pushes the gem to RubyGems through trusted publishing (no API key, with an attestation). Then it creates the GitHub release.
+5. The tag starts `.github/workflows/release.yml`. A build job checks the tag is on `main` and matches the version and its notes, and packs the gem, with no publishing credential. Its publishing job runs in the `release` environment, which only `v*` tags can use, and the registry's trusted publisher accepts only that environment. It pushes that gem to RubyGems through trusted publishing (no API key), then creates the GitHub release with the gem.
 
 ## License
 

data/lib/nohead/client.rb

@@ -15,7 +15,7 @@ module Nohead
     RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
     MAX_RETRY_AFTER = 60
 
-    attr_reader :records, :collections, :fields, :migrations, :assets, :webhooks,
+    attr_reader :records, :drafts, :collections, :fields, :migrations, :assets, :webhooks,
                 :audit_events, :feature_flags, :me, :health
 
     # api_key::     A project API key ("sk_live_..."). Defaults to NOHEAD_API_KEY.
@@ -40,6 +40,7 @@ module Nohead
       @warned = {}
 
       @records = Resources::Records.new(self)
+      @drafts = Resources::Drafts.new(self)
       @collections = Resources::Collections.new(self)
       @fields = Resources::Fields.new(self)
       @migrations = Resources::Migrations.new(self)
@@ -52,12 +53,12 @@ module Nohead
     end
 
     # Full-text search across the key's project (or some of its collections),
-    # most relevant first, through the first 1,000 hits.
-    def search(query, collections: nil, status: nil, limit: nil, cursor: nil)
-      paginate("projects_search", query: {
-                 q: query, collections: collections, filter: { status: status }, limit: limit,
-                 cursor: cursor
-               })
+    # most relevant first, through the first 1,000 hits. `filter` takes
+    # `published_at` ({ published_at: { exists: true } } for published
+    # records), as records.list does.
+    def search(query, collections: nil, filter: nil, limit: nil, cursor: nil)
+      filter = { collection: (collections.nil? ? nil : { in: collections }), **filter.to_h.transform_keys(&:to_sym) }
+      paginate("projects_search", query: { q: query, filter: filter, limit: limit, cursor: cursor })
     end
 
     # The API key's project, from GET /v1/me the first time.
@@ -158,8 +159,9 @@ module Nohead
     end
 
     # Query parameters as the API reads them: hashes become key[sub]=...
-    # (filter[status]=published), arrays are comma-separated (expand=author,tags),
-    # times are ISO 8601. nil values are left out.
+    # (filter[price][lt]=50), arrays are comma-separated (expand=author,tags)
+    # with \, for a comma inside a value and \\ for a backslash, times are
+    # ISO 8601. nil values are left out.
     def query_string(params)
       pairs = []
       add = lambda do |key, value|
@@ -167,7 +169,7 @@ module Nohead
         when nil then nil
         when Hash then value.each { |name, inner| add.call("#{key}[#{name}]", inner) }
         when Array
-          items = value.compact.map { |item| scalar(item) }
+          items = value.compact.map { |item| scalar(item).gsub(/[\\,]/) { |char| "\\#{char}" } }
           pairs << [key, items.join(",")] unless items.empty?
         else pairs << [key, scalar(value)]
         end
@@ -208,7 +210,12 @@ module Nohead
         revision = if_match.respond_to?(:revision) ? if_match.revision : if_match
         headers["If-Match"] = %("#{revision}")
       end
-      headers["Nohead-Change-Note"] = change_note if change_note
+      # Percent-encoded UTF-8, as encodeURIComponent: header values are bytes
+      # (the API decodes it). Notes in other encodings are converted first.
+      if change_note
+        note = change_note.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        headers["Nohead-Change-Note"] = URI.encode_uri_component(note)
+      end
       headers
     end
 

data/lib/nohead/errors.rb

@@ -20,7 +20,7 @@ module Nohead
     attr_reader :body
 
     def initialize(status, body, headers)
-      error = body.is_a?(Hash) && body["error"].is_a?(Hash) ? body["error"] : {}
+      error = Nohead.error_envelope(body)
       @status = status
       @type = error["type"]
       @request_id = error["request_id"] || headers["x-request-id"]
@@ -99,8 +99,7 @@ module Nohead
 
   # The error for a response, by its `type`, or by status when it has none.
   def self.api_error(status, body, headers)
-    type = body.is_a?(Hash) && body["error"].is_a?(Hash) ? body["error"]["type"] : nil
-    klass = ERROR_CLASSES[type] ||
+    klass = ERROR_CLASSES[error_envelope(body)["type"]] ||
             if status == 503 then ServiceUnavailableError
             elsif status >= 500 then InternalServerError
             else APIError
@@ -108,6 +107,18 @@ module Nohead
     klass.new(status, body, headers)
   end
 
+  # The error envelope's fields that have the right type: a proxy or gateway
+  # in front of the API may answer with any JSON.
+  def self.error_envelope(body)
+    error = body["error"] if body.is_a?(Hash)
+    return {} unless error.is_a?(Hash)
+
+    fields = error.slice("type", "message", "request_id").select { |_, value| value.is_a?(String) }
+    # Only hashes: current_revision reads each detail's fields.
+    fields["details"] = error["details"].grep(Hash) if error["details"].is_a?(Array)
+    fields
+  end
+
   def self.retry_after_seconds(headers)
     value = headers["retry-after"] or return nil
     return [Float(value), 0].max if value.match?(/\A\d+(\.\d+)?\z/)

data/lib/nohead/nohead_object.rb

@@ -6,28 +6,34 @@ module Nohead
   # What the SDK returns for the API's resources: read fields as methods
   # (`record.data`) or with `[]` (`record["data"]`), nested objects included.
   # Fields named like Ruby's own methods (`method`, `hash`...) need `[]`.
-  # Timestamps (`*_at`) are Times. Unknown fields are kept: the API adds
-  # fields without notice.
+  # Timestamps (the contract's: `created_at`, `purge_after`, `at`...) are
+  # Times; a record's field values (`record.data`) are left as they come,
+  # but for the resources `expand` embeds in them. Unknown fields are kept:
+  # the API adds fields without notice.
   class NoheadObject
     ISO_TIME = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})\z/
 
-    def self.wrap(value, key = nil)
+    # `fields`: the value is (in) a record's field values, whose keys are
+    # api_keys, so no timestamps.
+    def self.wrap(value, key = nil, fields: false)
       case value
-      when Hash then new(value)
-      when Array then value.map { |item| wrap(item) }
+      when Hash then new(value, fields: fields && !value.key?("object"))
+      when Array then value.map { |item| wrap(item, fields: fields) }
       when String
-        key.to_s.end_with?("_at") && value.match?(ISO_TIME) ? Time.iso8601(value) : value
+        !fields && TIMESTAMPS.include?(key.to_s) && value.match?(ISO_TIME) ? Time.iso8601(value) : value
       else value
       end
     end
 
-    def initialize(values)
+    def initialize(values, fields: false)
       @values = values.to_h { |key, value| [key.to_s, value] }
+      @fields = fields
     end
 
     def [](key)
       key = key.to_s
-      self.class.wrap(@values[key], key)
+      fields = @fields || (key == "data" && RECORD_DATA_OBJECTS.include?(@values["object"]))
+      self.class.wrap(@values[key], key, fields: fields)
     end
 
     def key?(key) = @values.key?(key.to_s)

data/lib/nohead/operations.rb

@@ -10,9 +10,11 @@ module Nohead
     "assets_get" => ["GET", "/v1/assets/{asset_id}"],
     "assets_image_url" => ["GET", "/v1/assets/{asset_id}/image-url"],
     "assets_list" => ["GET", "/v1/projects/{project_id}/assets"],
+    "assets_purge" => ["POST", "/v1/assets/{asset_id}/purge"],
     "assets_restore" => ["POST", "/v1/assets/{asset_id}/restore"],
-    "assets_upload" => ["POST", "/v1/projects/{project_id}/assets/uploads"],
-    "audit_events_list_for_project" => ["GET", "/v1/projects/{project_id}/audit-events"],
+    "assets_upload" => ["POST", "/v1/projects/{project_id}/assets"],
+    "assets_usage" => ["GET", "/v1/assets/{asset_id}/usage"],
+    "audit_events_list" => ["GET", "/v1/projects/{project_id}/audit-events"],
     "collections_create" => ["POST", "/v1/projects/{project_id}/collections"],
     "collections_delete" => ["DELETE", "/v1/collections/{collection_id}"],
     "collections_get" => ["GET", "/v1/collections/{collection_id}"],
@@ -21,13 +23,23 @@ module Nohead
     "collections_restore" => ["POST", "/v1/collections/{collection_id}/restore"],
     "collections_search" => ["GET", "/v1/collections/{collection_id}/search"],
     "collections_update" => ["PATCH", "/v1/collections/{collection_id}"],
+    "drafts_create" => ["POST", "/v1/records/{record_id}/drafts"],
+    "drafts_discard" => ["DELETE", "/v1/drafts/{draft_id}"],
+    "drafts_get" => ["GET", "/v1/drafts/{draft_id}"],
+    "drafts_list" => ["GET", "/v1/collections/{collection_id}/drafts"],
+    "drafts_merge" => ["POST", "/v1/drafts/{draft_id}/merge"],
+    "drafts_schedule" => ["PUT", "/v1/drafts/{draft_id}/schedule"],
+    "drafts_unschedule" => ["DELETE", "/v1/drafts/{draft_id}/schedule"],
+    "drafts_update" => ["PATCH", "/v1/drafts/{draft_id}"],
     "feature_flags_list" => ["GET", "/v1/feature-flags"],
     "fields_create" => ["POST", "/v1/collections/{collection_id}/fields"],
     "fields_delete" => ["DELETE", "/v1/fields/{field_id}"],
+    "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" => ["POST", "/v1/collections/{collection_id}/fields/reorder"],
+    "fields_reorder" => ["PUT", "/v1/collections/{collection_id}/field-order"],
     "fields_restore" => ["POST", "/v1/fields/{field_id}/restore"],
     "fields_update" => ["PATCH", "/v1/fields/{field_id}"],
     "health_check" => ["GET", "/v1/health"],
@@ -36,22 +48,26 @@ module Nohead
     "migrations_get" => ["GET", "/v1/migrations/{migration_id}"],
     "migrations_list" => ["GET", "/v1/collections/{collection_id}/migrations"],
     "projects_search" => ["GET", "/v1/projects/{project_id}/search"],
+    "record_drafts_list" => ["GET", "/v1/records/{record_id}/drafts"],
     "record_revisions_get" => ["GET", "/v1/records/{record_id}/revisions/{revision}"],
     "record_revisions_list" => ["GET", "/v1/records/{record_id}/revisions"],
     "record_revisions_revert" => ["POST", "/v1/records/{record_id}/revisions/{revision}/revert"],
-    "records_bulk" => ["POST", "/v1/collections/{collection_id}/records/bulk"],
+    "records_bulk" => ["POST", "/v1/collections/{collection_id}/record-batches"],
     "records_count" => ["GET", "/v1/collections/{collection_id}/records/count"],
     "records_create" => ["POST", "/v1/collections/{collection_id}/records"],
     "records_delete" => ["DELETE", "/v1/records/{record_id}"],
     "records_diff" => ["GET", "/v1/records/{record_id}/diff"],
     "records_get" => ["GET", "/v1/records/{record_id}"],
+    "records_get_publication" => ["GET", "/v1/records/{record_id}/publication"],
+    "records_get_schedule" => ["GET", "/v1/records/{record_id}/schedule"],
     "records_list" => ["GET", "/v1/collections/{collection_id}/records"],
-    "records_publish" => ["POST", "/v1/records/{record_id}/publish"],
+    "records_publish" => ["POST", "/v1/records/{record_id}/publication"],
     "records_restore" => ["POST", "/v1/records/{record_id}/restore"],
     "records_schedule" => ["PUT", "/v1/records/{record_id}/schedule"],
-    "records_unpublish" => ["POST", "/v1/records/{record_id}/unpublish"],
+    "records_unpublish" => ["DELETE", "/v1/records/{record_id}/publication"],
     "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_list" => ["GET", "/v1/collections/{collection_id}/schema-changes"],
     "search_index_get" => ["GET", "/v1/collections/{collection_id}/search-index"],
@@ -59,12 +75,26 @@ module Nohead
     "webhook_deliveries_get" => ["GET", "/v1/webhook-deliveries/{delivery_id}"],
     "webhook_deliveries_list" => ["GET", "/v1/webhooks/{webhook_id}/deliveries"],
     "webhook_deliveries_retry" => ["POST", "/v1/webhook-deliveries/{delivery_id}/retry"],
+    "webhook_secrets_list" => ["GET", "/v1/webhooks/{webhook_id}/secrets"],
+    "webhook_secrets_retire" => ["DELETE", "/v1/webhook-secrets/{secret_id}"],
     "webhooks_create" => ["POST", "/v1/projects/{project_id}/webhooks"],
     "webhooks_delete" => ["DELETE", "/v1/webhooks/{webhook_id}"],
     "webhooks_get" => ["GET", "/v1/webhooks/{webhook_id}"],
     "webhooks_list" => ["GET", "/v1/projects/{project_id}/webhooks"],
-    "webhooks_rotate_secret" => ["POST", "/v1/webhooks/{webhook_id}/rotate-secret"],
+    "webhooks_restore" => ["POST", "/v1/webhooks/{webhook_id}/restore"],
+    "webhooks_rotate_secret" => ["POST", "/v1/webhooks/{webhook_id}/secrets"],
     "webhooks_test" => ["POST", "/v1/webhooks/{webhook_id}/test"],
     "webhooks_update" => ["PATCH", "/v1/webhooks/{webhook_id}"]
   }.freeze
+
+  # The names of the timestamp fields in responses and webhook events.
+  TIMESTAMPS = %w[
+    at cancel_requested_at completed_at created_at deleted_at expires_at
+    last_attempt_at last_built_at merge_at next_attempt_at publish_at published_at
+    purge_after rebuild_requested_at started_at succeeded_at time unpublish_at
+    updated_at uploaded_at
+  ].to_set.freeze
+
+  # The objects whose `data` is a record's field values.
+  RECORD_DATA_OBJECTS = %w[draft record record_revision revert_preview].to_set.freeze
 end

data/lib/nohead/resources/assets.rb

@@ -9,12 +9,27 @@ module Nohead
       # file). `file` is a path or an IO; for bytes, pass StringIO.new(bytes).
       # Raises UploadError if storage refuses the bytes, and ValidationError if
       # the file fails the checks.
+      #
+      # With an `idempotency_key`, 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. Once the upload's URL has
+      # expired (`upload.expires_at`), it raises UploadError: start over with
+      # a new key.
       def upload(file, filename: nil, content_type: nil, byte_size: nil, idempotency_key: nil)
         source = UploadSource.new(file, filename: filename, content_type: content_type,
                                         byte_size: byte_size)
         begin
           created = create_upload(filename: source.filename, content_type: source.content_type,
                                   byte_size: source.byte_size, idempotency_key: idempotency_key)
+          # A replayed start returns the first run's asset, which may be done.
+          if idempotency_key
+            current = get(created.id)
+            return current if current.status == "ready"
+            # The key replays the first run's upload URL, which expires sooner.
+            if created.upload.expires_at <= Time.now
+              raise UploadError, "The upload of #{source.filename} expired: start it again with a new idempotency_key"
+            end
+          end
           upload = created.upload
           response = @client.put_upload(upload.url, upload["method"], upload.headers.to_h, source)
         ensure
@@ -24,13 +39,14 @@ module Nohead
           raise UploadError.new("Storage refused the upload of #{source.filename} (#{response.status})",
                                 response.status)
         end
-        complete(created.asset.id)
+        complete(created.id)
       end
 
-      # 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.
       def create_upload(idempotency_key: nil, **params)
-        @client.request("assets_upload", body: params, idempotency_key: idempotency_key)
+        @client.request("assets_upload", body: body_of(params), idempotency_key: idempotency_key)
       end
 
       # Checks an uploaded file and marks the asset `ready`.
@@ -38,15 +54,20 @@ module Nohead
         @client.request("assets_complete", path: { asset_id: asset }, idempotency_key: idempotency_key)
       end
 
-      def list(deleted: nil, limit: nil, cursor: nil)
-        @client.paginate("assets_list", query: { deleted: deleted, limit: limit, cursor: cursor })
+      # `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`).
+      def list(content_type: nil, deleted: nil, limit: nil, cursor: nil)
+        @client.paginate("assets_list", query: { filter: { content_type: content_type, deleted: deleted },
+                                                 limit: limit, cursor: cursor })
       end
 
       def get(asset)
         @client.request("assets_get", path: { asset_id: asset })
       end
 
-      # 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.
       def delete(asset, idempotency_key: nil)
         @client.request("assets_delete", path: { asset_id: asset }, idempotency_key: idempotency_key)
       end
@@ -55,6 +76,21 @@ module Nohead
         @client.request("assets_restore", path: { asset_id: asset }, idempotency_key: idempotency_key)
       end
 
+      # Deletes a deleted asset for good, now instead of at its `purge_after`,
+      # and returns it as it was. It can't be restored, and its image
+      # URLs stop working. Raises ConflictError if the asset isn't deleted.
+      def purge(asset, idempotency_key: nil)
+        @client.request("assets_purge", path: { asset_id: asset }, idempotency_key: idempotency_key)
+      end
+
+      # 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 they use it in (`uses`). Needs
+      # `records:read` too.
+      def usage(asset)
+        @client.request("assets_usage", path: { asset_id: asset })
+      end
+
       # A signed, cacheable URL of an image rendition (`url`).
       def image_url(asset, width: nil, height: nil, fit: nil, format: nil, quality: nil)
         @client.request("assets_image_url", path: { asset_id: asset }, query: {

data/lib/nohead/resources/drafts.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Nohead
+  module Resources
+    # 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 and `collection` a collection ID or slug.
+    class Drafts < Resource
+      # Starts the record's draft: `data` over the record's values, or with
+      # `from_revision`, over an earlier revision's. A second draft raises
+      # ConflictError (detail code `draft_exists`, with its `draft_id`).
+      def create(record, data: {}, from_revision: nil, idempotency_key: nil)
+        @client.request("drafts_create", path: { record_id: record },
+                                         body: { data: data, from_revision: from_revision }.compact,
+                                         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
+        @client.paginate("drafts_list", path: { collection_id: collection },
+                                        query: { filter: { record_id: record_filter }, sort: sort,
+                                                 limit: limit, cursor: cursor })
+      end
+
+      # With `data` as the record reads after the merge, for previews.
+      def get(draft, expand: nil)
+        @client.request("drafts_get", path: { draft_id: draft }, query: { expand: expand })
+      end
+
+      # Sets the given fields (nil clears one), as a record update does.
+      def update(draft, data:, if_match: nil, idempotency_key: nil)
+        @client.request("drafts_update", path: { draft_id: draft }, body: { data: data },
+                                         if_match: if_match, idempotency_key: idempotency_key)
+      end
+
+      # Deletes the draft for good; returns it as it was.
+      def discard(draft, if_match: nil, idempotency_key: nil)
+        @client.request("drafts_discard", path: { draft_id: draft }, if_match: if_match,
+                                          idempotency_key: idempotency_key)
+      end
+
+      # Applies the draft to its record now, as one `merge` revision, and
+      # returns the record. Content only: the record stays live or not.
+      def merge(draft, if_match: nil, idempotency_key: nil, change_note: nil)
+        @client.request("drafts_merge", path: { draft_id: draft }, if_match: if_match,
+                                        idempotency_key: idempotency_key, change_note: change_note)
+      end
+
+      # Merges the draft at `merge_at` (a Time or ISO 8601 string in the
+      # future); returns the draft.
+      def schedule(draft, merge_at:, idempotency_key: nil)
+        @client.request("drafts_schedule", path: { draft_id: draft }, body: { merge_at: merge_at },
+                                           idempotency_key: idempotency_key)
+      end
+
+      def unschedule(draft, idempotency_key: nil)
+        @client.request("drafts_unschedule", path: { draft_id: draft }, idempotency_key: idempotency_key)
+      end
+    end
+  end
+end

data/lib/nohead/resources/other.rb

@@ -4,10 +4,17 @@ module Nohead
   module Resources
     # The project's activity log, newest first. Needs the audit:read scope.
     class AuditEvents < Resource
-      # `filter` takes action (exact, or a "record.*" prefix), resource_type,
-      # resource_id, actor_type, actor_id, since and until.
+      # `filter` takes `type` (exact, or a "record.*" prefix), `resource_type`
+      # (a type, or an Array of them), `resource_id`, `actor_type`, `actor_id`
+      # and a `created_at` range:
+      #
+      #   audit_events.list(filter: { type: "record.*", resource_type: %w[record draft],
+      #                               created_at: { gte: Time.utc(2026, 10, 1) } })
       def list(filter: nil, sort: nil, limit: nil, cursor: nil)
-        @client.paginate("audit_events_list_for_project",
+        filter = filter&.transform_keys(&:to_sym)
+        types = filter&.[](:resource_type)
+        filter = filter.merge(resource_type: { in: types }) if types.is_a?(Array)
+        @client.paginate("audit_events_list",
                          query: { filter: filter, sort: sort, limit: limit, cursor: cursor })
       end
     end

data/lib/nohead/resources/records.rb

@@ -4,11 +4,27 @@ module Nohead
   module Resources
     # The base of the resources: each holds the client it sends requests with.
     class Resource
+      # Request options that are headers, not body fields.
+      OPTIONS = %i[change_note if_match].freeze
+
       def initialize(client)
         @client = client
       end
 
       def inspect = "#<#{self.class.name}>"
+
+      private
+
+      # The keyword arguments a method sends as the body. SDK options would
+      # land there when the method doesn't take them (its operation doesn't
+      # declare the header), so they raise ArgumentError as Ruby does for
+      # unknown keywords.
+      def body_of(params)
+        option = OPTIONS.find { |name| params.key?(name) }
+        raise ArgumentError, "unknown keyword: :#{option}" if option
+
+        params
+      end
     end
 
     # Records: the content of a collection. `collection` is a collection ID or
@@ -22,43 +38,46 @@ module Nohead
       end
 
       # A collection's records, newest first by default. `filter` holds
-      # equality filters ({ status: "published" }), `expand` relation or asset
-      # fields to embed under `expanded` (at most 5).
+      # filters ({ published_at: { exists: true } } for published records),
+      # `expand` relation or asset fields to embed under `expanded` (at most 5).
       def list(collection, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil)
         @client.paginate("records_list", path: { collection_id: collection }, query: {
                            filter: filter, sort: sort, expand: expand, limit: limit, cursor: cursor
                          })
       end
 
-      def get(record, expand: nil, include_deleted: nil)
-        @client.request("records_get", path: { record_id: record },
-                                       query: { expand: expand, include_deleted: include_deleted })
+      # A deleted record too, with `deleted_at` and `purge_after`.
+      def get(record, expand: nil)
+        @client.request("records_get", path: { record_id: record }, query: { expand: expand })
       end
 
-      # Creates a draft: create("posts", data: { title: "Hello" }).
+      # Creates an unpublished record: create("posts", data: { title: "Hello" }).
       def create(collection, idempotency_key: nil, change_note: nil, **params)
-        @client.request("records_create", path: { collection_id: collection }, body: params,
+        @client.request("records_create", path: { collection_id: collection }, body: body_of(params),
                                           idempotency_key: idempotency_key, change_note: change_note)
       end
 
       # Sets the given fields (nil clears one); others keep their values.
       def update(record, if_match: nil, idempotency_key: nil, change_note: nil, **params)
-        @client.request("records_update", path: { record_id: record }, body: params,
+        @client.request("records_update", path: { record_id: record }, body: body_of(params),
                                           if_match: if_match, idempotency_key: idempotency_key,
                                           change_note: change_note)
       end
 
-      # 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.
       def delete(record, if_match: nil, idempotency_key: nil, change_note: nil)
         @client.request("records_delete", path: { record_id: record }, if_match: if_match,
                                           idempotency_key: idempotency_key, change_note: change_note)
       end
 
-      def restore(record, idempotency_key: nil, change_note: nil)
-        @client.request("records_restore", path: { record_id: record },
+      def restore(record, if_match: nil, idempotency_key: nil, change_note: nil)
+        @client.request("records_restore", path: { record_id: record }, if_match: if_match,
                                            idempotency_key: idempotency_key, change_note: change_note)
       end
 
+      # A live record with a pending draft raises ConflictError (detail code
+      # `draft_pending`): publishing never merges a draft (drafts.merge does).
       def publish(record, if_match: nil, idempotency_key: nil, change_note: nil)
         @client.request("records_publish", path: { record_id: record }, if_match: if_match,
                                            idempotency_key: idempotency_key, change_note: change_note)
@@ -69,13 +88,26 @@ module Nohead
                                              idempotency_key: idempotency_key, change_note: change_note)
       end
 
-      # Publishes and/or unpublishes the record later. Times left out keep
-      # their value; name them in `clear` to remove them.
-      def schedule(record, publish_at: nil, unpublish_at: nil, clear: [], idempotency_key: nil)
-        body = clear.to_h { |name| [name.to_s, nil] }
-        body["publish_at"] = publish_at unless publish_at.nil?
-        body["unpublish_at"] = unpublish_at unless unpublish_at.nil?
-        @client.request("records_schedule", path: { record_id: record }, body: body,
+      # What is live: since when, by whom, and the revision. Raises
+      # NotFoundError (detail code `not_published`) for a record that isn't
+      # published.
+      def publication(record)
+        @client.request("records_get_publication", path: { record_id: record })
+      end
+
+      # When the record publishes or unpublishes on its own. Raises
+      # NotFoundError (detail code `not_scheduled`) for a record with no
+      # schedule.
+      def get_schedule(record)
+        @client.request("records_get_schedule", path: { record_id: record })
+      end
+
+      # Sets when the record publishes and/or unpublishes on its own, and
+      # returns the schedule. It replaces the whole schedule: a time left out
+      # is cleared (schedule(record, publish_at: t) drops a set unpublish_at).
+      def schedule(record, publish_at: nil, unpublish_at: nil, idempotency_key: nil)
+        @client.request("records_schedule", path: { record_id: record },
+                                            body: { publish_at: publish_at, unpublish_at: unpublish_at }.compact,
                                             idempotency_key: idempotency_key)
       end
 
@@ -85,6 +117,19 @@ module Nohead
                                               idempotency_key: idempotency_key)
       end
 
+      # The record's drafts: at most one for now.
+      def drafts(record, limit: nil, cursor: nil)
+        @client.paginate("record_drafts_list", path: { record_id: record }, query: { limit: limit, cursor: cursor })
+      end
+
+      # A collection's pending scheduled publishes and unpublishes, soonest
+      # first: one per change, so a record due to publish and later unpublish
+      # appears twice.
+      def scheduled_changes(collection, sort: nil, limit: nil, cursor: nil)
+        @client.paginate("scheduled_changes_list", path: { collection_id: collection },
+                                                   query: { sort: sort, limit: limit, cursor: cursor })
+      end
+
       def count(collection, filter: nil)
         @client.request("records_count", path: { collection_id: collection },
                                          query: { filter: filter })
@@ -93,14 +138,13 @@ module Nohead
       # Publishes, unpublishes, deletes, restores or updates up to 100 records.
       # Each record succeeds or fails on its own; see `results`.
       def bulk(collection, idempotency_key: nil, change_note: nil, **params)
-        @client.request("records_bulk", path: { collection_id: collection }, body: params,
+        @client.request("records_bulk", path: { collection_id: collection }, body: body_of(params),
                                         idempotency_key: idempotency_key, change_note: change_note)
       end
 
-      # The changes between two revisions.
-      def diff(record, from_revision, to_revision)
-        @client.request("records_diff", path: { record_id: record },
-                                        query: { from: from_revision, to: to_revision })
+      # The changes between two revisions: diff(record, from: 1, to: 2).
+      def diff(record, from:, to:)
+        @client.request("records_diff", path: { record_id: record }, query: { from: from, to: to })
       end
 
       # Full-text search in one collection (search_enabled collections), most
@@ -115,7 +159,8 @@ module Nohead
 
     # A record's version history. `revision` is a revision number.
     class Revisions < Resource
-      # Newest first. `filter` takes operation, actor_id, since and until.
+      # Newest first. `filter` takes `operation`, `actor_id` and a `created_at`
+      # range ({ created_at: { gte: Time.utc(2026, 10, 1) } }).
       def list(record, filter: nil, limit: nil, cursor: nil)
         @client.paginate("record_revisions_list", path: { record_id: record },
                                                   query: { filter: filter, limit: limit, cursor: cursor })
@@ -127,10 +172,10 @@ module Nohead
 
       # Restores the record's data as of `revision`, as a new revision. With
       # dry_run: true, previews it.
-      def revert(record, revision, dry_run: false, if_match: nil, idempotency_key: nil)
+      def revert(record, revision, dry_run: false, if_match: nil, idempotency_key: nil, change_note: nil)
         @client.request("record_revisions_revert", path: { record_id: record, revision: revision },
-                                                   query: { dry_run: dry_run || nil },
-                                                   if_match: if_match, idempotency_key: idempotency_key)
+                                                   query: { dry_run: dry_run || nil }, if_match: if_match,
+                                                   idempotency_key: idempotency_key, change_note: change_note)
       end
     end
   end

data/lib/nohead/resources/schema.rb

@@ -12,9 +12,11 @@ module Nohead
         @search_index = SearchIndexes.new(client)
       end
 
-      # deleted: true lists deleted collections instead (restorable for 30 days).
+      # deleted: true lists deleted collections instead (restorable until
+      # their `purge_after`).
       def list(deleted: nil, limit: nil, cursor: nil)
-        @client.paginate("collections_list", query: { deleted: deleted, limit: limit, cursor: cursor })
+        @client.paginate("collections_list",
+                         query: { filter: { deleted: deleted }, limit: limit, cursor: cursor })
       end
 
       def get(collection)
@@ -23,16 +25,17 @@ module Nohead
 
       # Creates a collection, optionally with its fields.
       def create(idempotency_key: nil, change_note: nil, **params)
-        @client.request("collections_create", body: params, idempotency_key: idempotency_key,
+        @client.request("collections_create", body: body_of(params), idempotency_key: idempotency_key,
                                               change_note: change_note)
       end
 
       def update(collection, idempotency_key: nil, change_note: nil, **params)
-        @client.request("collections_update", path: { collection_id: collection }, body: params,
+        @client.request("collections_update", path: { collection_id: collection }, body: body_of(params),
                                               idempotency_key: idempotency_key, change_note: change_note)
       end
 
-      # Soft-deletes the collection and its records for 30 days.
+      # Soft-deletes the collection and its records: restore brings them back
+      # until its `purge_after`.
       def delete(collection, idempotency_key: nil, change_note: nil)
         @client.request("collections_delete", path: { collection_id: collection },
                                               idempotency_key: idempotency_key, change_note: change_note)
@@ -80,22 +83,27 @@ module Nohead
     class Fields < Resource
       def list(collection, deleted: nil, limit: nil, cursor: nil)
         @client.paginate("fields_list", path: { collection_id: collection },
-                                        query: { deleted: deleted, limit: limit, cursor: cursor })
+                                        query: { filter: { deleted: deleted }, limit: limit, cursor: cursor })
+      end
+
+      def get(field)
+        @client.request("fields_get", path: { field_id: field })
       end
 
       def create(collection, idempotency_key: nil, change_note: nil, **params)
-        @client.request("fields_create", path: { collection_id: collection }, body: params,
+        @client.request("fields_create", path: { collection_id: collection }, body: body_of(params),
                                          idempotency_key: idempotency_key, change_note: change_note)
       end
 
       # Renames, describes or loosens a field. Changes that rewrite record
       # values (type, multiple, tighter rules) are `migrate`.
       def update(field, idempotency_key: nil, change_note: nil, **params)
-        @client.request("fields_update", path: { field_id: field }, body: params,
+        @client.request("fields_update", path: { field_id: field }, body: body_of(params),
                                          idempotency_key: idempotency_key, change_note: change_note)
       end
 
-      # Soft-deletes the field: its values return with `restore` for 30 days.
+      # Soft-deletes the field: its values return with `restore` until its
+      # `purge_after`.
       def delete(field, idempotency_key: nil, change_note: nil)
         @client.request("fields_delete", path: { field_id: field },
                                          idempotency_key: idempotency_key, change_note: change_note)
@@ -106,8 +114,13 @@ module Nohead
                                           idempotency_key: idempotency_key, change_note: change_note)
       end
 
-      # Puts the collection's fields in this order.
-      def reorder(collection, field_ids, idempotency_key: nil, change_note: nil)
+      # The collection's active fields, in order.
+      def order(collection)
+        @client.request("fields_get_order", path: { collection_id: collection })
+      end
+
+      # Puts the collection's fields in this order; lists every active field once.
+      def reorder(collection, field_ids:, idempotency_key: nil, change_note: nil)
         @client.request("fields_reorder", path: { collection_id: collection },
                                           body: { field_ids: field_ids },
                                           idempotency_key: idempotency_key, change_note: change_note)
@@ -123,7 +136,7 @@ module Nohead
       # 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: params, idempotency_key: idempotency_key,
+                                          body: body_of(params), idempotency_key: idempotency_key,
                                           change_note: change_note)
       end
     end

data/lib/nohead/version.rb

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

data/lib/nohead/webhooks.rb

@@ -9,6 +9,11 @@ module Nohead
   #   event = Nohead::Webhooks.unwrap(request.raw_post, request.headers,
   #                                   secret: ENV.fetch("NOHEAD_WEBHOOK_SECRET"))
   #   puts event.data.record.id if event.type == "record.published"
+  #
+  # Event types are the same as the activity log's (record.published,
+  # record.restored, field.updated, asset.purged, ...). While a secret
+  # rotation overlaps, requests carry a signature for each secret, so either
+  # one verifies.
   module Webhooks
     # Checks a webhook request's signature and timestamp and returns its event
     # (a NoheadObject: `type`, `data`...). Pass the raw body exactly as
@@ -52,15 +57,18 @@ module Nohead
   module Resources
     # Webhooks of the key's project. `webhook` is a webhook ID ("wh_...").
     class Webhooks < Resource
-      attr_reader :deliveries
+      attr_reader :deliveries, :secrets
 
       def initialize(client)
         super
         @deliveries = Deliveries.new(client)
+        @secrets = Secrets.new(client)
       end
 
-      def list(limit: nil, cursor: nil)
-        @client.paginate("webhooks_list", query: { limit: limit, cursor: cursor })
+      # deleted: true lists deleted webhooks instead (restorable until their
+      # `purge_after`).
+      def list(deleted: nil, limit: nil, cursor: nil)
+        @client.paginate("webhooks_list", query: { filter: { deleted: deleted }, limit: limit, cursor: cursor })
       end
 
       def get(webhook)
@@ -69,19 +77,26 @@ module Nohead
 
       # Subscribes a URL. The response is the only time `secret` is shown.
       def create(idempotency_key: nil, **params)
-        @client.request("webhooks_create", body: params, idempotency_key: idempotency_key)
+        @client.request("webhooks_create", body: body_of(params), idempotency_key: idempotency_key)
       end
 
       def update(webhook, idempotency_key: nil, **params)
-        @client.request("webhooks_update", path: { webhook_id: webhook }, body: params,
+        @client.request("webhooks_update", path: { webhook_id: webhook }, body: body_of(params),
                                            idempotency_key: idempotency_key)
       end
 
+      # Soft-deletes the webhook: restore brings it back until its `purge_after`.
       def delete(webhook, idempotency_key: nil)
         @client.request("webhooks_delete", path: { webhook_id: webhook }, idempotency_key: idempotency_key)
       end
 
-      # A new signing secret; the old one stops working at once.
+      def restore(webhook, idempotency_key: nil)
+        @client.request("webhooks_restore", path: { webhook_id: webhook }, idempotency_key: idempotency_key)
+      end
+
+      # A new signing secret (`secret`, shown only here). The ones before it
+      # keep signing for 24 hours, so receivers can switch without rejecting
+      # deliveries; secrets.retire ends one sooner.
       def rotate_secret(webhook, idempotency_key: nil)
         @client.request("webhooks_rotate_secret", path: { webhook_id: webhook },
                                                   idempotency_key: idempotency_key)
@@ -103,18 +118,35 @@ module Nohead
     class Deliveries < Resource
       def list(webhook, status: nil, limit: nil, cursor: nil)
         @client.paginate("webhook_deliveries_list", path: { webhook_id: webhook },
-                                                    query: { status: status, limit: limit, cursor: cursor })
+                                                    query: { filter: { status: status }, limit: limit,
+                                                             cursor: cursor })
       end
 
       def get(delivery)
         @client.request("webhook_deliveries_get", path: { delivery_id: delivery })
       end
 
-      # Sends the event again.
+      # Sends the event again now, as a new attempt.
       def retry(delivery, idempotency_key: nil)
         @client.request("webhook_deliveries_retry", path: { delivery_id: delivery },
                                                     idempotency_key: idempotency_key)
       end
     end
+
+    # A webhook's signing secrets. `secret` is a secret ID ("whs_...").
+    class Secrets < Resource
+      # Those signing deliveries now, oldest first, without their values.
+      def list(webhook, limit: nil, cursor: nil)
+        @client.paginate("webhook_secrets_list", path: { webhook_id: webhook },
+                                                 query: { limit: limit, cursor: cursor })
+      end
+
+      # Stops signing with it now. The newest can't be retired (ConflictError,
+      # detail code `newest_secret`): rotate first.
+      def retire(secret, idempotency_key: nil)
+        @client.request("webhook_secrets_retire", path: { secret_id: secret },
+                                                  idempotency_key: idempotency_key)
+      end
+    end
   end
 end

data/lib/nohead.rb

@@ -5,7 +5,7 @@
 #   require "nohead"
 #
 #   nohead = Nohead::Client.new # NOHEAD_API_KEY
-#   nohead.records.list("posts", filter: { status: "published" }).each do |post|
+#   nohead.records.list("posts", filter: { published_at: { exists: true } }).each do |post|
 #     puts post.data["title"]
 #   end
 module Nohead; end
@@ -18,6 +18,7 @@ require_relative "nohead/page"
 require_relative "nohead/transport"
 require_relative "nohead/uploads"
 require_relative "nohead/resources/records"
+require_relative "nohead/resources/drafts"
 require_relative "nohead/resources/schema"
 require_relative "nohead/resources/assets"
 require_relative "nohead/resources/other"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nohead
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nohead
@@ -28,6 +28,7 @@ files:
 - lib/nohead/operations.rb
 - lib/nohead/page.rb
 - lib/nohead/resources/assets.rb
+- lib/nohead/resources/drafts.rb
 - lib/nohead/resources/other.rb
 - lib/nohead/resources/records.rb
 - lib/nohead/resources/schema.rb