nohead 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e94f698ee3cb6906c1b21535666bdefc57f6d864dbad5eb3436c9e0a7a4bff2f
-  data.tar.gz: a47d275d02c1b5111b0eadc5f14dedf2a201c5fdcf01ae0eaba306c3bdb87ad2
+  metadata.gz: 9b3361c68d640e8b2774b8e797bbf4108e19be21f0019600788d9f45e04457fe
+  data.tar.gz: d3c200b25b6afd1db440dced441f142da3d38b1731e34780356c373c2bc4b67c
 SHA512:
-  metadata.gz: bbac1644f34a8ea9ff5b41b342facdfea9df8de606cca48e00fcbde9adcb0d3564c65973f43f087d8d6acc4f9443057107c7eb244ab47f557d96bb6b1f1d14cb
-  data.tar.gz: e650ba515324f59b5cd141534be18d49ae4530e5fe89d7d19bf3aac1e2a6c97fc502b6094b06e43e580b771391d110ad72e32c166235eab6492b8592aaba4a0c
+  metadata.gz: 409ee914aaf232ce8f7109b4628f260f47f6b83861dceb48aebeaee661873c03f5ebef3ccbbd6e269504febad9325505a3b97a2f42905bb279e81d76aef70f18
+  data.tar.gz: 87b158ed9116745555538a9ef4297c584050251e69d0bab6101b823e239b3586262f161901f519973b1b07c4f2f2b76dfcd78ac86c55eedb905b208867d96d60

data/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.7.0
+
+- `assets.list(q:, kind:)`: `q` finds assets whose filename or alt text has
+  every word, ignoring case; `kind` lists only `image`, `video`, `audio`,
+  `document` or `other` assets, or several kinds as an array.
+
+## 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:

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
 
@@ -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
 
@@ -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` |
 | `migrations` | `create`, `list`, `get`, `cancel` |
-| `assets` | `upload`, `create_upload`, `complete`, `list`, `get`, `delete`, `restore`, `purge`, `usage`, `image_url`, `download_url` |
+| `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"],
@@ -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,20 +54,33 @@ module Nohead
         @client.request("assets_complete", path: { asset_id: asset }, idempotency_key: idempotency_key)
       end
 
+      # `q` finds assets whose filename or alt text has every word, ignoring
+      # case ("hero jpg" finds `Hero-banner.jpg`). `kind` lists only assets of
+      # a kind ("image", "video", "audio", "document" or "other"), or of
+      # several (%w[image video]).
+      #
       # `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 })
+      def list(q: nil, kind: nil, content_type: nil, deleted: nil, limit: nil, cursor: nil)
+        filter = { kind: one_or_in(kind), content_type: one_or_in(content_type), deleted: deleted }
+        @client.paginate("assets_list", query: { q: q, filter: filter, limit: limit, cursor: cursor })
       end
 
       def get(asset)
         @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)
@@ -93,17 +106,20 @@ 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
+
+      private
+
+      # One value as it is, several as `[in]`; an empty list (like an asset
+      # field's accepted_types) is no filter.
+      def one_or_in(value)
+        return value unless value.is_a?(Array)
+
+        value.empty? ? nil : { in: value }
+      end
     end
   end
 end

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.
@@ -122,9 +126,9 @@ module Nohead
         @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.
+      # A collection's pending scheduled changes, soonest first: publishes,
+      # unpublishes and draft merges, 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 })
@@ -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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nohead
-  VERSION = "0.5.0"
+  VERSION = "0.7.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.5.0
+  version: 0.7.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