nohead 0.1.0

data/lib/nohead/resources/schema.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Nohead
+  module Resources
+    # Collections of the key's project. `collection` is an ID or slug.
+    class Collections < Resource
+      attr_reader :schema_changes, :search_index
+
+      def initialize(client)
+        super
+        @schema_changes = SchemaChanges.new(client)
+        @search_index = SearchIndexes.new(client)
+      end
+
+      # deleted: true lists deleted collections instead (restorable for 30 days).
+      def list(deleted: nil, limit: nil, cursor: nil)
+        @client.paginate("collections_list", query: { deleted: deleted, limit: limit, cursor: cursor })
+      end
+
+      def get(collection)
+        @client.request("collections_get", path: { collection_id: collection })
+      end
+
+      # 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,
+                                              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,
+                                              idempotency_key: idempotency_key, change_note: change_note)
+      end
+
+      # Soft-deletes the collection and its records for 30 days.
+      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)
+      end
+
+      def restore(collection, idempotency_key: nil, change_note: nil)
+        @client.request("collections_restore", path: { collection_id: collection },
+                                               idempotency_key: idempotency_key, change_note: change_note)
+      end
+
+      # The collection's schema, now or at a past `version`.
+      def schema(collection, version: nil)
+        @client.request("collections_get_schema", path: { collection_id: collection },
+                                                  query: { version: version })
+      end
+    end
+
+    # A collection's schema history, newest first.
+    class SchemaChanges < Resource
+      def list(collection, limit: nil, cursor: nil)
+        @client.paginate("schema_changes_list", path: { collection_id: collection },
+                                                query: { limit: limit, cursor: cursor })
+      end
+
+      def get(collection, schema_change)
+        @client.request("schema_changes_get",
+                        path: { collection_id: collection, schema_change_id: schema_change })
+      end
+    end
+
+    # A collection's search index.
+    class SearchIndexes < Resource
+      def get(collection)
+        @client.request("search_index_get", path: { collection_id: collection })
+      end
+
+      # Rebuilds the index from the records; searches keep working meanwhile.
+      def rebuild(collection, idempotency_key: nil)
+        @client.request("search_index_rebuild", path: { collection_id: collection },
+                                                idempotency_key: idempotency_key)
+      end
+    end
+
+    # Fields of a collection. `field` is a field ID ("fld_...").
+    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 })
+      end
+
+      def create(collection, idempotency_key: nil, change_note: nil, **params)
+        @client.request("fields_create", path: { collection_id: collection }, body: 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,
+                                         idempotency_key: idempotency_key, change_note: change_note)
+      end
+
+      # Soft-deletes the field: its values return with `restore` for 30 days.
+      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)
+      end
+
+      def restore(field, idempotency_key: nil, change_note: nil)
+        @client.request("fields_restore", path: { field_id: field },
+                                          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)
+        @client.request("fields_reorder", path: { collection_id: collection },
+                                          body: { field_ids: field_ids },
+                                          idempotency_key: idempotency_key, change_note: change_note)
+      end
+
+      # Stops accepting a renamed field's old API 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: params, idempotency_key: idempotency_key,
+                                          change_note: change_note)
+      end
+    end
+
+    # Field migrations. While one runs, its collection is read-only.
+    class Migrations < Resource
+      def list(collection, limit: nil, cursor: nil)
+        @client.paginate("migrations_list", path: { collection_id: collection },
+                                            query: { limit: limit, cursor: cursor })
+      end
+
+      def get(migration)
+        @client.request("migrations_get", path: { migration_id: migration })
+      end
+
+      def cancel(migration, idempotency_key: nil)
+        @client.request("migrations_cancel", path: { migration_id: migration },
+                                             idempotency_key: idempotency_key)
+      end
+    end
+  end
+end

data/lib/nohead/transport.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Nohead
+  # A response: status, headers (lowercase names) and body text.
+  Response = Struct.new(:status, :headers, :body)
+
+  # Sends requests with Net::HTTP. A client's `transport:` can be anything
+  # with the same `call`, e.g. for tests.
+  class Transport
+    # `body` is a String, an IO (streamed, with Content-Length), or nil.
+    def call(method, url, headers, body, timeout)
+      uri = URI(url)
+      request = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri, headers)
+      if body.respond_to?(:read)
+        request.body_stream = body
+      elsif body
+        request.body = body
+      end
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = http.read_timeout = http.write_timeout = timeout
+      response = http.start { http.request(request) }
+      Response.new(response.code.to_i, response.each_header.to_h, response.body.to_s)
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+      raise TimeoutError, "The request to #{uri.host} timed out after #{timeout} s"
+    rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+      raise ConnectionError, "Could not reach #{uri.host}: #{e.message}"
+    end
+  end
+end

data/lib/nohead/uploads.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Nohead
+  # Reading files for assets.upload: a path (String or Pathname) or an IO
+  # opened in binary mode (File, StringIO).
+  class UploadSource
+    CONTENT_TYPES = {
+      ".avif" => "image/avif", ".gif" => "image/gif", ".jpeg" => "image/jpeg",
+      ".jpg" => "image/jpeg", ".png" => "image/png", ".svg" => "image/svg+xml",
+      ".webp" => "image/webp", ".pdf" => "application/pdf", ".json" => "application/json",
+      ".txt" => "text/plain", ".md" => "text/markdown", ".csv" => "text/csv",
+      ".mp3" => "audio/mpeg", ".mp4" => "video/mp4", ".webm" => "video/webm",
+      ".zip" => "application/zip"
+    }.freeze
+
+    attr_reader :filename, :content_type, :byte_size, :io
+
+    def initialize(file, filename: nil, content_type: nil, byte_size: nil)
+      name, size = file.is_a?(String) || file.is_a?(Pathname) ? open_path(Pathname(file)) : open_io(file)
+      @filename = filename || name || "upload"
+      @byte_size = byte_size || size or
+        raise UploadError, "Uploading a stream that cannot seek needs byte_size:"
+      @content_type = content_type ||
+                      CONTENT_TYPES.fetch(File.extname(@filename).downcase, "application/octet-stream")
+      @start = @io.respond_to?(:pos) ? @io.pos : 0
+    end
+
+    # Whether the bytes can be sent again (for retries).
+    def replayable? = @io.respond_to?(:rewind) && @io.respond_to?(:pos)
+
+    def rewind
+      @io.pos = @start if replayable?
+    end
+
+    def close
+      @io.close if @owned
+    end
+
+    private
+
+    def open_path(path)
+      @io = path.open("rb")
+      @owned = true
+      [path.basename.to_s, path.size]
+    end
+
+    def open_io(io)
+      raise ArgumentError, "Upload a path or an IO; wrap bytes in StringIO.new(bytes)" unless io.respond_to?(:read)
+
+      @io = io
+      name = File.basename(io.path) if io.respond_to?(:path) && io.path
+      [name, remaining(io)]
+    end
+
+    def remaining(io)
+      return io.size - io.pos if io.respond_to?(:size) && io.respond_to?(:pos)
+
+      nil
+    rescue IOError, SystemCallError
+      nil
+    end
+  end
+end

data/lib/nohead/version.rb

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

data/lib/nohead/webhooks.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Nohead
+  # Verifying webhook requests (Standard Webhooks), with or without a client:
+  #
+  #   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"
+  module Webhooks
+    # Checks a webhook request's signature and timestamp and returns its event
+    # (a NoheadObject: `type`, `data`...). Pass the raw body exactly as
+    # received: parsing and re-serializing JSON changes the bytes, and the
+    # signature with them. Raises WebhookVerificationError when anything does
+    # not match. `headers` is a Hash or anything with `[]` (any case).
+    def self.unwrap(body, headers, secret:, tolerance: 300)
+      id = header(headers, "webhook-id")
+      timestamp = header(headers, "webhook-timestamp")
+      signatures = header(headers, "webhook-signature")
+      unless id && timestamp && signatures
+        raise WebhookVerificationError, "Missing webhook-id, webhook-timestamp or webhook-signature header"
+      end
+      unless timestamp.match?(/\A\d+\z/) && (Time.now.to_i - timestamp.to_i).abs <= tolerance
+        raise WebhookVerificationError, "The webhook timestamp is too far from the current time"
+      end
+
+      key = secret.delete_prefix("whsec_").unpack1("m0")
+      expected = [OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{body}")].pack("m0")
+      matched = signatures.split.any? do |entry|
+        version, signature = entry.split(",", 2)
+        version == "v1" && signature && OpenSSL.secure_compare(signature, expected)
+      end
+      raise WebhookVerificationError, "No webhook signature matches" unless matched
+
+      NoheadObject.wrap(JSON.parse(body))
+    rescue ArgumentError
+      raise WebhookVerificationError, "The webhook secret is not base64"
+    rescue JSON::ParserError
+      raise WebhookVerificationError, "The webhook body is not JSON"
+    end
+
+    def self.header(headers, name)
+      return headers[name] || headers[name.split("-").map(&:capitalize).join("-")] unless headers.is_a?(Hash)
+
+      headers.find { |key, _| key.to_s.downcase == name }&.last
+    end
+    private_class_method :header
+  end
+
+  module Resources
+    # Webhooks of the key's project. `webhook` is a webhook ID ("wh_...").
+    class Webhooks < Resource
+      attr_reader :deliveries
+
+      def initialize(client)
+        super
+        @deliveries = Deliveries.new(client)
+      end
+
+      def list(limit: nil, cursor: nil)
+        @client.paginate("webhooks_list", query: { limit: limit, cursor: cursor })
+      end
+
+      def get(webhook)
+        @client.request("webhooks_get", path: { webhook_id: webhook })
+      end
+
+      # 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)
+      end
+
+      def update(webhook, idempotency_key: nil, **params)
+        @client.request("webhooks_update", path: { webhook_id: webhook }, body: params,
+                                           idempotency_key: idempotency_key)
+      end
+
+      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 rotate_secret(webhook, idempotency_key: nil)
+        @client.request("webhooks_rotate_secret", path: { webhook_id: webhook },
+                                                  idempotency_key: idempotency_key)
+      end
+
+      # Sends a `webhook.test` event to the URL.
+      def test(webhook, idempotency_key: nil)
+        @client.request("webhooks_test", path: { webhook_id: webhook }, idempotency_key: idempotency_key)
+      end
+
+      # Checks a webhook request's signature and returns its event (see
+      # Nohead::Webhooks.unwrap, which needs no client).
+      def unwrap(body, headers, secret:, tolerance: 300)
+        Nohead::Webhooks.unwrap(body, headers, secret: secret, tolerance: tolerance)
+      end
+    end
+
+    # Delivery attempts of a webhook's events.
+    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 })
+      end
+
+      def get(delivery)
+        @client.request("webhook_deliveries_get", path: { delivery_id: delivery })
+      end
+
+      # Sends the event again.
+      def retry(delivery, idempotency_key: nil)
+        @client.request("webhook_deliveries_retry", path: { delivery_id: delivery },
+                                                    idempotency_key: idempotency_key)
+      end
+    end
+  end
+end

data/lib/nohead.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# The official Ruby SDK for the Nohead API.
+#
+#   require "nohead"
+#
+#   nohead = Nohead::Client.new # NOHEAD_API_KEY
+#   nohead.records.list("posts", filter: { status: "published" }).each do |post|
+#     puts post.data["title"]
+#   end
+module Nohead; end
+
+require_relative "nohead/version"
+require_relative "nohead/nohead_object"
+require_relative "nohead/errors"
+require_relative "nohead/operations"
+require_relative "nohead/page"
+require_relative "nohead/transport"
+require_relative "nohead/uploads"
+require_relative "nohead/resources/records"
+require_relative "nohead/resources/schema"
+require_relative "nohead/resources/assets"
+require_relative "nohead/resources/other"
+require_relative "nohead/webhooks"
+require_relative "nohead/client"

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: nohead
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nohead
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'A client for the Nohead API: records, collections, fields, assets, webhooks
+  and search, with pagination, safe retries, uploads and webhook verification. No
+  runtime dependencies.'
+email:
+- hello@nohead.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/nohead.rb
+- lib/nohead/client.rb
+- lib/nohead/errors.rb
+- lib/nohead/nohead_object.rb
+- lib/nohead/operations.rb
+- lib/nohead/page.rb
+- lib/nohead/resources/assets.rb
+- lib/nohead/resources/other.rb
+- lib/nohead/resources/records.rb
+- lib/nohead/resources/schema.rb
+- lib/nohead/transport.rb
+- lib/nohead/uploads.rb
+- lib/nohead/version.rb
+- lib/nohead/webhooks.rb
+homepage: https://nohead.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://nohead.io
+  source_code_uri: https://github.com/nohead-io/nohead-ruby
+  changelog_uri: https://github.com/nohead-io/nohead-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/nohead-io/nohead-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Official Ruby SDK for the Nohead API
+test_files: []