nohead 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 747275a28bad0e0410f52109f1bac03d8d703fedccafe3110f21ae904421d511
-  data.tar.gz: 696d827a38b169e1a047b38a40d9263417cff3f111cec74d825a77236072a62c
+  metadata.gz: 4f80d6fdee7ba3b00716d16b5a0e0203b8e2b0c12e35cbf9747bb2e17a40335f
+  data.tar.gz: 413cce95b1bc00ae8c68ca6d4c951975940b5e5e61e1bb0ab9a807c4b9b32f5b
 SHA512:
-  metadata.gz: e82adbab22c4ea949feccc1c347926b5c2a6795f087b02a8915255f4c7a49f56b53e088ae4b8579374c3db27a59c8bf12c428970d28f83124f047f120c08c7bb
-  data.tar.gz: 6c0c8b4dfc63a7eb8d89cc76030e7cf9797ba28541bd677b1da117b7975039d5b3742677230057ff29c4826ac7abf47acd1e3cfba3b38bb84809c4fa4cf233da
+  metadata.gz: 3a0ef2d3ca637467739881a7bc9ccf667d47d8419dafb2959290b2108e6ad8b7204661452272e218c73b5dee7c8c3f69611404a2253cb2b998f7ff1b3daec207
+  data.tar.gz: 3658e753b524d77745c43947edf2a5f4926b615adfa6fbd30bf46bea84a2c6f02210d9b40fdb7323497d879f2e96c59372dd483a8cde4402d9b41246b1c28517

data/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.6.0
+
+- API keys now start `nohead_sk_`, or `nohead_pk_` for published-only keys;
+  keys in the old `sk_live_` format no longer work. The gem sends whatever key
+  it's given, so only the docs and examples change.
+
+- `assets.update(asset, filename:, alt:)` renames an asset and sets its alt
+  text (`PATCH /v1/assets/{asset_id}`). Assets have `alt` (a string or
+  `nil`), and webhooks can subscribe to `asset.updated`.
+
+- Image URLs are open. Assets have `image_url`, the whole image, and the new
+  `Nohead::Images.url` writes any of imgproxy's processing options into it,
+  without a request.
+
+- **Breaking:** `assets.image_url` is gone, with the API's
+  `GET /v1/assets/{asset_id}/image-url`: use `Nohead::Images.url`, which
+  needs no request.
+
+- **Breaking:** collections have no `search_enabled`, and search indexes no
+  `enabled`, and collections' `create` and `update` no longer take
+  `search_enabled:`: API keys search every collection they can read.
+
+- `revisions.get(revision)` reads a revision by its own `rev_` ID, as
+  webhooks and the activity log name it (`GET /v1/revisions/{revision_id}`).
+
+- `records.create` takes `upsert_on:`, a unique field's key: the record
+  holding that value is updated instead, if one exists, and `if_match:`
+  applies to that update.
+
+- Collections have `public_search`: whether the project's search tokens find
+  their published records. Off by default;
+  `collections.create(public_search: ...)` and `collections.update` take it. A
+  collection's search index has `index`, the name a token searches it by.
+
+## 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,

data/README.md

@@ -52,7 +52,7 @@ nohead = Nohead::Client.new(
 
 | Option | Default | |
 |---|---|---|
-| `api_key:` | `NOHEAD_API_KEY` | A project API key (`sk_live_...`). Required. |
+| `api_key:` | `NOHEAD_API_KEY` | A project API key (`nohead_sk_...`, or `nohead_pk_...` when published-only). Required. |
 | `base_url:` | `NOHEAD_API_URL`, else `https://api.nohead.io` | |
 | `project_id:` | the key's project | Looked up once with `GET /v1/me` when omitted. |
 | `max_retries:` | `2` | See [retries](#retries-and-idempotency). |
@@ -76,11 +76,14 @@ nohead.records.delete(post.id) # soft delete; records.restore undoes it
 
 Methods return the API's resources (see [Results](#results)) and raise on failure. Field values are under `data`, keyed by field API key.
 
+**Upserts.** With `upsert_on:`, the key of a `unique` field, `create` updates the record holding that value instead, if one exists, so a content sync can run again without duplicates: `nohead.records.create("products", data: { sku: "TEE-01", title: "Tee" }, upsert_on: "sku")`.
+
 **More:**
 
 - `count`, and `bulk` (up to 100 records at once)
 - `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)
+- a revision by its own ID, as webhooks and the activity log name it: `nohead.revisions.get("rev_...")`
 
 ## Drafts
 
@@ -95,7 +98,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
@@ -195,9 +198,17 @@ end
 asset = nohead.assets.upload("cover.jpg")
 nohead.records.update(id, data: { cover: asset.id })
 
-url = nohead.assets.image_url(asset.id, width: 1200, format: "webp").url
 ```
 
+**Images.** Image URLs are open: an image's `image_url` serves the whole image, and any of [imgproxy's processing options](https://docs.imgproxy.net/usage/processing) written into it transform it. `Nohead::Images.url` builds them without a request:
+
+```ruby
+Nohead::Images.url(asset, width: 1200, height: 630, fit: "cover", gravity: "sm", format: "webp")
+Nohead::Images.url(asset.image_url, width: 400, dpr: 2, options: ["bl:2"])
+```
+
+Thumbnails: an image's `preview_url` fits in 640×640, as WebP.
+
 **What `upload` accepts:** a path (String or Pathname), or an IO opened in binary mode. For bytes in memory, pass `StringIO.new(bytes)`.
 
 **What it does:**
@@ -212,6 +223,12 @@ url = nohead.assets.image_url(asset.id, width: 1200, format: "webp").url
 
 **Uploading from a browser:** create the upload on your server with `create_upload`, `PUT` the file from the browser, then `complete` it.
 
+**Renaming and alt text:** `update` changes an asset's `filename:` and `alt:` text, the default wherever the asset is used (`expand:` returns it with the asset). The file itself never changes.
+
+```ruby
+nohead.assets.update(asset.id, alt: "The spring menu, on a chalkboard")
+```
+
 ## Search
 
 ```ruby
@@ -223,7 +240,7 @@ results = nohead.search("content model", collections: %w[posts pages], filter: {
 results.meta.total_estimate
 ```
 
-Search needs `search_enabled` collections and the `search:read` scope. It pages through the first 1,000 hits.
+Search needs the `search:read` scope and covers every collection the key can read, matching their `searchable` fields. It pages through the first 1,000 hits. For search straight from a site's browser, without the API, use a search token from the web app with Meilisearch's own clients or InstantSearch.
 
 ## Schema
 
@@ -233,8 +250,8 @@ nohead.collections.create(name: "Posts", slug: "posts",
 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)
 ```
 
@@ -275,13 +292,14 @@ The API's resources come back as `Nohead::NoheadObject`s.
 | `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` |
+| `revisions` | `get` (by its own `rev_` ID) |
 | `search` | across the project |
 | `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` |
-| `assets` | `upload`, `create_upload`, `complete`, `list`, `get`, `delete`, `restore`, `purge`, `usage`, `image_url`, `download_url` |
+| `fields` | `list`, `get`, `create`, `update`, `delete`, `restore`, `order`, `reorder`, `remove_alias` |
+| `migrations` | `create`, `list`, `get`, `cancel` |
+| `assets` | `upload`, `create_upload`, `complete`, `list`, `get`, `update`, `delete`, `restore`, `purge`, `usage`, `download_url` |
 | `webhooks` | `list`, `get`, `create`, `update`, `delete`, `restore`, `rotate_secret`, `test`, `unwrap` |
 | `webhooks.secrets` | `list`, `retire` |
 | `webhooks.deliveries` | `list`, `get`, `retry` |

data/lib/nohead/client.rb

@@ -15,10 +15,11 @@ module Nohead
     RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
     MAX_RETRY_AFTER = 60
 
-    attr_reader :records, :drafts, :collections, :fields, :migrations, :assets, :webhooks,
+    attr_reader :records, :revisions, :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.
+    # api_key::     A project API key ("nohead_sk_...", or "nohead_pk_..." when
+    #               published-only). Defaults to NOHEAD_API_KEY.
     # base_url::    Defaults to NOHEAD_API_URL, else https://api.nohead.io.
     # project_id::  The key's project. Looked up once with GET /v1/me when omitted.
     # max_retries:: Retries of failed requests (see the README, "Retries").
@@ -40,6 +41,7 @@ module Nohead
       @warned = {}
 
       @records = Resources::Records.new(self)
+      @revisions = Resources::RevisionsById.new(self)
       @drafts = Resources::Drafts.new(self)
       @collections = Resources::Collections.new(self)
       @fields = Resources::Fields.new(self)

data/lib/nohead/images.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Nohead
+  # Image renditions without a request. Image URLs are open: an image asset's
+  # `image_url` serves the whole image, and any of imgproxy's processing
+  # options written into it transform it
+  # (https://docs.imgproxy.net/usage/processing).
+  #
+  #   Nohead::Images.url(asset, width: 800, height: 600, fit: "cover", format: "webp")
+  module Images
+    FITS = { "contain" => "fit", "cover" => "fill", "fill" => "force" }.freeze
+
+    module_function
+
+    # A rendition of an image (an asset, as an object or a Hash, or its `image_url`). fit: "contain"
+    # fits inside the box, "cover" fills it, cropping, "fill" stretches to it.
+    # gravity: is what a crop keeps ("sm" for smart, "fp:0.5:0.3" for a focal
+    # point); options: any other processing options, as written in a URL
+    # (["bl:2"]).
+    def url(image, width: nil, height: nil, fit: "contain", format: nil, quality: nil, dpr: nil,
+            gravity: nil, options: [])
+      base = base_of(image)
+      check_options([gravity, *options])
+      at = base.index("/plain/")
+      parts = [resize(fit, width, height), ("g:#{gravity}" if gravity), ("dpr:#{dpr}" if dpr),
+               ("q:#{quality}" if quality), *options].compact
+      base[0...at] + parts.map { |part| "/#{part}" }.join + source(base[at..], format)
+    end
+
+    # rs:<fit>:<width>:<height>, or nothing without a size (0 is none).
+    def resize(fit, width, height)
+      type = FITS.fetch(fit.to_s) { raise ArgumentError, "fit must be one of #{FITS.keys.join(', ')}" }
+      width = nil if width&.zero?
+      height = nil if height&.zero?
+      "rs:#{type}:#{width || 0}:#{height || 0}" if width || height
+    end
+    private_class_method :resize
+
+    def base_of(image)
+      base = case image
+             when String then image
+             when Hash then image["image_url"] || image[:image_url]
+             else image.image_url
+             end
+      raise ArgumentError, "Not a ready image: it has no image_url" if base.nil? || base.empty?
+      raise ArgumentError, "Not a Nohead image URL: #{base}" unless base.include?("/plain/")
+
+      base
+    end
+    private_class_method :base_of
+
+    def check_options(values)
+      bad = values.compact.find { |value| value.to_s.match?(%r{[/@?#]}) }
+      raise ArgumentError, "Not an imgproxy option: #{bad}" if bad
+    end
+    private_class_method :check_options
+
+    # The source comes last; a format replaces any the URL already names.
+    def source(source, format)
+      format ? "#{source.sub(/@[a-z]+\z/, '')}@#{format}" : source
+    end
+    private_class_method :source
+  end
+end

data/lib/nohead/operations.rb

@@ -8,10 +8,10 @@ module Nohead
     "assets_delete" => ["DELETE", "/v1/assets/{asset_id}"],
     "assets_download_url" => ["GET", "/v1/assets/{asset_id}/download-url"],
     "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_update" => ["PATCH", "/v1/assets/{asset_id}"],
     "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"],
@@ -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"],
@@ -67,6 +67,7 @@ module Nohead
     "records_unpublish" => ["DELETE", "/v1/records/{record_id}/publication"],
     "records_unschedule" => ["DELETE", "/v1/records/{record_id}/schedule"],
     "records_update" => ["PATCH", "/v1/records/{record_id}"],
+    "revisions_get" => ["GET", "/v1/revisions/{revision_id}"],
     "scheduled_changes_list" => ["GET", "/v1/collections/{collection_id}/scheduled-changes"],
     "schema_changes_get" => ["GET", "/v1/schema-changes/{schema_change_id}"],
     "schema_changes_list" => ["GET", "/v1/collections/{collection_id}/schema-changes"],

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
@@ -66,6 +68,15 @@ module Nohead
         @client.request("assets_get", path: { asset_id: asset })
       end
 
+      # Renames the asset (`filename:`) or sets its `alt:` text (nil or ""
+      # clears it). The file itself can't change: upload a new asset for that.
+      # `alt` is the default wherever the asset is used. A deleted asset is a
+      # ConflictError: restore it first.
+      def update(asset, idempotency_key: nil, **params)
+        @client.request("assets_update", path: { asset_id: asset }, body: body_of(params),
+                                         idempotency_key: idempotency_key)
+      end
+
       # Soft-deletes the asset: restore brings it back until its `purge_after`,
       # when the file is purged.
       def delete(asset, idempotency_key: nil)
@@ -91,14 +102,7 @@ module Nohead
         @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: {
-                          width: width, height: height, fit: fit, format: format, quality: quality
-                        })
-      end
-
-      # A 15-minute link to download the original file (`url`).
+      # A link to download the original file (`url`), valid for 2 minutes.
       def download_url(asset)
         @client.request("assets_download_url", path: { asset_id: asset })
       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/records.rb

@@ -52,9 +52,13 @@ module Nohead
       end
 
       # Creates an unpublished record: create("posts", data: { title: "Hello" }).
-      def create(collection, idempotency_key: nil, change_note: nil, **params)
+      # With upsert_on:, the key of a unique field, it updates the record holding
+      # that value instead, if one exists, so a sync can run again without
+      # duplicates; if_match: then applies to that update.
+      def create(collection, if_match: nil, idempotency_key: nil, change_note: nil, **params)
         @client.request("records_create", path: { collection_id: collection }, body: body_of(params),
-                                          idempotency_key: idempotency_key, change_note: change_note)
+                                          if_match: if_match, idempotency_key: idempotency_key,
+                                          change_note: change_note)
       end
 
       # Sets the given fields (nil clears one); others keep their values.
@@ -147,7 +151,7 @@ module Nohead
         @client.request("records_diff", path: { record_id: record }, query: { from: from, to: to })
       end
 
-      # Full-text search in one collection (search_enabled collections), most
+      # Full-text search in one collection, matching its searchable fields, most
       # relevant first, through the first 1,000 hits.
       def search(collection, query, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil)
         @client.paginate("collections_search", path: { collection_id: collection }, query: {
@@ -178,5 +182,13 @@ module Nohead
                                                    idempotency_key: idempotency_key, change_note: change_note)
       end
     end
+
+    # A revision by its own ID ("rev_..."), as webhooks and the activity log name
+    # it. Readable while its record is deleted.
+    class RevisionsById < Resource
+      def get(revision)
+        @client.request("revisions_get", path: { revision_id: revision })
+      end
+    end
   end
 end

data/lib/nohead/resources/schema.rb

@@ -95,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)
@@ -125,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.4.0"
+  VERSION = "0.6.0"
 end

data/lib/nohead.rb

@@ -23,4 +23,5 @@ require_relative "nohead/resources/schema"
 require_relative "nohead/resources/assets"
 require_relative "nohead/resources/other"
 require_relative "nohead/webhooks"
+require_relative "nohead/images"
 require_relative "nohead/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nohead
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Nohead
@@ -24,6 +24,7 @@ files:
 - lib/nohead.rb
 - lib/nohead/client.rb
 - lib/nohead/errors.rb
+- lib/nohead/images.rb
 - lib/nohead/nohead_object.rb
 - lib/nohead/operations.rb
 - lib/nohead/page.rb