nohead 0.1.0

data/lib/nohead/errors.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Nohead
+  # The base of every error the SDK raises.
+  class Error < StandardError; end
+
+  # The API answered with an error status. Subclasses follow the error `type`.
+  class APIError < Error
+    # The HTTP status.
+    attr_reader :status
+    # The error `type`, e.g. "validation_error"; nil if the body had none.
+    attr_reader :type
+    # The request's ID ("req_..."), for support requests and logs.
+    attr_reader :request_id
+    # Field-level details: objects with `field`, `code` and `message`.
+    attr_reader :details
+    # The response headers (lowercase names).
+    attr_reader :headers
+    # The parsed response body, or its text when it was not JSON.
+    attr_reader :body
+
+    def initialize(status, body, headers)
+      error = body.is_a?(Hash) && body["error"].is_a?(Hash) ? body["error"] : {}
+      @status = status
+      @type = error["type"]
+      @request_id = error["request_id"] || headers["x-request-id"]
+      @details = Array(error["details"]).map { |detail| NoheadObject.wrap(detail) }
+      @headers = headers
+      @body = body
+      super(error["message"] || "Request failed with status #{status}")
+    end
+
+    def to_s
+      suffix = request_id ? " (request #{request_id})" : ""
+      "#{status} #{type || 'error'}: #{super}#{suffix}"
+    end
+  end
+
+  class InvalidRequestError < APIError; end
+  class AuthenticationError < APIError; end
+  class PlanLimitExceededError < APIError; end
+  class AuthorizationError < APIError; end
+  class NotFoundError < APIError; end
+  class ConflictError < APIError; end
+
+  # An `if_match` revision was not the current one: reload and try again.
+  class PreconditionFailedError < APIError
+    # The resource's current revision, when the API reports it.
+    def current_revision
+      details.find { |detail| detail["code"] == "revision_mismatch" }&.[]("current_revision")
+    end
+  end
+
+  class ValidationError < APIError; end
+
+  class RateLimitError < APIError
+    # Seconds to wait before retrying, from `Retry-After`.
+    def retry_after
+      Nohead.retry_after_seconds(headers)
+    end
+  end
+
+  class InternalServerError < APIError; end
+  class ServiceUnavailableError < APIError; end
+
+  # The request never got a response: DNS, TLS, a reset connection.
+  class ConnectionError < Error; end
+
+  # An attempt took longer than the `timeout` option.
+  class TimeoutError < ConnectionError; end
+
+  # A presigned upload to storage failed (`assets.upload`).
+  class UploadError < Error
+    # Storage's HTTP status, when it answered.
+    attr_reader :status
+
+    def initialize(message, status = nil)
+      @status = status
+      super(message)
+    end
+  end
+
+  # A webhook request's signature or timestamp did not check out.
+  class WebhookVerificationError < Error; end
+
+  ERROR_CLASSES = {
+    "invalid_request" => InvalidRequestError,
+    "authentication_error" => AuthenticationError,
+    "plan_limit_exceeded" => PlanLimitExceededError,
+    "authorization_error" => AuthorizationError,
+    "not_found" => NotFoundError,
+    "conflict" => ConflictError,
+    "precondition_failed" => PreconditionFailedError,
+    "validation_error" => ValidationError,
+    "rate_limited" => RateLimitError,
+    "internal_error" => InternalServerError,
+    "service_unavailable" => ServiceUnavailableError
+  }.freeze
+
+  # 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] ||
+            if status == 503 then ServiceUnavailableError
+            elsif status >= 500 then InternalServerError
+            else APIError
+            end
+    klass.new(status, body, headers)
+  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/)
+
+    [Time.httpdate(value) - Time.now, 0].max
+  rescue ArgumentError
+    nil
+  end
+end

data/lib/nohead/nohead_object.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "time"
+
+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.
+  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)
+      case value
+      when Hash then new(value)
+      when Array then value.map { |item| wrap(item) }
+      when String
+        key.to_s.end_with?("_at") && value.match?(ISO_TIME) ? Time.iso8601(value) : value
+      else value
+      end
+    end
+
+    def initialize(values)
+      @values = values.to_h { |key, value| [key.to_s, value] }
+    end
+
+    def [](key)
+      key = key.to_s
+      self.class.wrap(@values[key], key)
+    end
+
+    def key?(key) = @values.key?(key.to_s)
+    def keys = @values.keys
+
+    def dig(key, *rest)
+      value = self[key]
+      rest.empty? || value.nil? ? value : value.dig(*rest)
+    end
+
+    # The fields as a plain Hash with string keys (raw values).
+    def to_h = @values
+
+    def ==(other) = other.is_a?(NoheadObject) && other.to_h == to_h
+
+    def respond_to_missing?(name, include_private = false)
+      @values.key?(name.to_s) || super
+    end
+
+    def method_missing(name, *args)
+      key = name.to_s
+      return super unless args.empty? && @values.key?(key)
+
+      self[key]
+    end
+
+    def inspect
+      label = @values["object"] ? "#{@values['object']} " : ""
+      "#<Nohead::NoheadObject #{label}#{@values.inspect}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/nohead/operations.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Generated by scripts/generate.rb from openapi.json. Do not edit.
+module Nohead
+  # Every operation an API key can call: [method, path].
+  OPERATIONS = {
+    "assets_complete" => ["POST", "/v1/assets/{asset_id}/complete"],
+    "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_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"],
+    "collections_create" => ["POST", "/v1/projects/{project_id}/collections"],
+    "collections_delete" => ["DELETE", "/v1/collections/{collection_id}"],
+    "collections_get" => ["GET", "/v1/collections/{collection_id}"],
+    "collections_get_schema" => ["GET", "/v1/collections/{collection_id}/schema"],
+    "collections_list" => ["GET", "/v1/projects/{project_id}/collections"],
+    "collections_restore" => ["POST", "/v1/collections/{collection_id}/restore"],
+    "collections_search" => ["GET", "/v1/collections/{collection_id}/search"],
+    "collections_update" => ["PATCH", "/v1/collections/{collection_id}"],
+    "feature_flags_list" => ["GET", "/v1/feature-flags"],
+    "fields_create" => ["POST", "/v1/collections/{collection_id}/fields"],
+    "fields_delete" => ["DELETE", "/v1/fields/{field_id}"],
+    "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_restore" => ["POST", "/v1/fields/{field_id}/restore"],
+    "fields_update" => ["PATCH", "/v1/fields/{field_id}"],
+    "health_check" => ["GET", "/v1/health"],
+    "me_get" => ["GET", "/v1/me"],
+    "migrations_cancel" => ["POST", "/v1/migrations/{migration_id}/cancel"],
+    "migrations_get" => ["GET", "/v1/migrations/{migration_id}"],
+    "migrations_list" => ["GET", "/v1/collections/{collection_id}/migrations"],
+    "projects_search" => ["GET", "/v1/projects/{project_id}/search"],
+    "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_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_list" => ["GET", "/v1/collections/{collection_id}/records"],
+    "records_publish" => ["POST", "/v1/records/{record_id}/publish"],
+    "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_unschedule" => ["DELETE", "/v1/records/{record_id}/schedule"],
+    "records_update" => ["PATCH", "/v1/records/{record_id}"],
+    "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"],
+    "search_index_rebuild" => ["POST", "/v1/collections/{collection_id}/search-index/rebuild"],
+    "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"],
+    "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_test" => ["POST", "/v1/webhooks/{webhook_id}/test"],
+    "webhooks_update" => ["PATCH", "/v1/webhooks/{webhook_id}"]
+  }.freeze
+end

data/lib/nohead/page.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Nohead
+  # One page of a list. `each` (and so `map`, `first`, `to_a`...) walks every
+  # item from here on, fetching later pages as needed:
+  #
+  #   nohead.records.list("posts").each { |record| puts record.data["title"] }
+  #
+  #   page = nohead.records.list("posts", limit: 100)
+  #   page.data # this page's items
+  #   page = page.next_page while page.next_page?
+  class Page
+    include Enumerable
+
+    # The items on this page.
+    attr_reader :data
+    # `next_cursor` and `has_more` (and `total_estimate` for search).
+    attr_reader :meta
+
+    def initialize(data, meta, &fetch)
+      @data = data
+      @meta = meta
+      @fetch = fetch
+    end
+
+    def next_page?
+      meta["has_more"] == true && !meta["next_cursor"].nil?
+    end
+
+    # The next page; raises Nohead::Error when there is none.
+    def next_page
+      raise Error, "There is no next page" unless next_page?
+
+      @fetch.call(meta["next_cursor"])
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      page = self
+      loop do
+        page.data.each(&block)
+        break unless page.next_page?
+
+        page = page.next_page
+      end
+      self
+    end
+
+    def inspect = "#<Nohead::Page #{data.size} items, more: #{next_page?}>"
+  end
+end

data/lib/nohead/resources/assets.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Nohead
+  module Resources
+    # Files of the key's project. `asset` is an asset ID ("ast_...").
+    class Assets < Resource
+      # Uploads a file and returns the `ready` asset: creates the upload, sends
+      # the bytes straight to storage, then completes it (which checks the
+      # 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.
+      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)
+          upload = created.upload
+          response = @client.put_upload(upload.url, upload["method"], upload.headers.to_h, source)
+        ensure
+          source.close
+        end
+        unless response.status.between?(200, 299)
+          raise UploadError.new("Storage refused the upload of #{source.filename} (#{response.status})",
+                                response.status)
+        end
+        complete(created.asset.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.
+      def create_upload(idempotency_key: nil, **params)
+        @client.request("assets_upload", body: params, idempotency_key: idempotency_key)
+      end
+
+      # Checks an uploaded file and marks the asset `ready`.
+      def complete(asset, idempotency_key: nil)
+        @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 })
+      end
+
+      def get(asset)
+        @client.request("assets_get", path: { asset_id: asset })
+      end
+
+      # Soft-deletes the asset; the file is purged after 30 days.
+      def delete(asset, idempotency_key: nil)
+        @client.request("assets_delete", path: { asset_id: asset }, idempotency_key: idempotency_key)
+      end
+
+      def restore(asset, idempotency_key: nil)
+        @client.request("assets_restore", path: { asset_id: asset }, idempotency_key: idempotency_key)
+      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`).
+      def download_url(asset)
+        @client.request("assets_download_url", path: { asset_id: asset })
+      end
+    end
+  end
+end

data/lib/nohead/resources/other.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+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.
+      def list(filter: nil, sort: nil, limit: nil, cursor: nil)
+        @client.paginate("audit_events_list_for_project",
+                         query: { filter: filter, sort: sort, limit: limit, cursor: cursor })
+      end
+    end
+
+    # Feature flags evaluated for the key's project.
+    class FeatureFlags < Resource
+      # Flags evaluated for the key's project.
+      def list
+        @client.request("feature_flags_list")
+      end
+    end
+
+    # The credentials the client uses.
+    class Me < Resource
+      # The API key: its project, scopes, published_only and expiry.
+      def get
+        @client.request("me_get")
+      end
+    end
+
+    # Whether the API is up.
+    class Health < Resource
+      def check
+        @client.request("health_check")
+      end
+    end
+  end
+end

data/lib/nohead/resources/records.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Nohead
+  module Resources
+    # The base of the resources: each holds the client it sends requests with.
+    class Resource
+      def initialize(client)
+        @client = client
+      end
+
+      def inspect = "#<#{self.class.name}>"
+    end
+
+    # Records: the content of a collection. `collection` is a collection ID or
+    # slug; `record` a record ID ("rec_...").
+    class Records < Resource
+      attr_reader :revisions
+
+      def initialize(client)
+        super
+        @revisions = Revisions.new(client)
+      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).
+      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 })
+      end
+
+      # Creates a draft: 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,
+                                          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,
+                                          if_match: if_match, idempotency_key: idempotency_key,
+                                          change_note: change_note)
+      end
+
+      # Soft-deletes the record: restore brings it back within 30 days.
+      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 },
+                                           idempotency_key: idempotency_key, change_note: change_note)
+      end
+
+      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)
+      end
+
+      def unpublish(record, if_match: nil, idempotency_key: nil, change_note: nil)
+        @client.request("records_unpublish", path: { record_id: record }, if_match: if_match,
+                                             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,
+                                            idempotency_key: idempotency_key)
+      end
+
+      # Clears both scheduled times.
+      def unschedule(record, idempotency_key: nil)
+        @client.request("records_unschedule", path: { record_id: record },
+                                              idempotency_key: idempotency_key)
+      end
+
+      def count(collection, filter: nil)
+        @client.request("records_count", path: { collection_id: collection },
+                                         query: { filter: filter })
+      end
+
+      # 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,
+                                        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 })
+      end
+
+      # Full-text search in one collection (search_enabled collections), 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: {
+                           q: query, filter: filter, sort: sort, expand: expand, limit: limit,
+                           cursor: cursor
+                         })
+      end
+    end
+
+    # A record's version history. `revision` is a revision number.
+    class Revisions < Resource
+      # Newest first. `filter` takes operation, actor_id, since and until.
+      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 })
+      end
+
+      def get(record, revision)
+        @client.request("record_revisions_get", path: { record_id: record, revision: revision })
+      end
+
+      # 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)
+        @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)
+      end
+    end
+  end
+end