cloudflare-ruby 0.0.1 → 0.1.2

data/lib/cloudflare/resource.rb

@@ -0,0 +1,309 @@
+module Cloudflare
+  # Base class for every Cloudflare resource — Meeting, Bucket, Zone, Record,
+  # Script, etc. Provides Active-Record-flavored CRUD on top of REST endpoints,
+  # plus an `attribute` macro for explicit, source-visible attribute readers.
+  #
+  # Subclasses declare paths and attributes:
+  #
+  #   class Cloudflare::RealtimeKit::Meeting < Cloudflare::Resource
+  #     collection_path "/accounts/{account_id}/realtime/kit/{app_id}/meetings"
+  #     member_path     "/accounts/{account_id}/realtime/kit/{app_id}/meetings/{id}"
+  #     scope_required  :app_id
+  #
+  #     attribute :id,            String
+  #     attribute :title,         String
+  #     attribute :location_hint, String, wire_name: "locationHint"
+  #   end
+  class Resource
+    # Cloudflare uses two response envelope shapes:
+    #   - V4 API: { result: ..., success, errors, messages }    — most products
+    #   - RealtimeKit (Dyte heritage): { data: ..., success }
+    ENVELOPE_KEYS = %w[result data].freeze
+
+    class << self
+      attr_reader :_collection_path, :_member_path, :_attributes
+
+      def collection_path(path = nil)
+        path ? @_collection_path = path : @_collection_path
+      end
+
+      def member_path(path = nil)
+        path ? @_member_path = path : @_member_path
+      end
+
+      def scope_required(*keys)
+        @_explicit_scope = keys.map(&:to_sym).freeze
+      end
+
+      def scope_params
+        ((@_explicit_scope || []) + [ :account_id ]).uniq
+      end
+
+      # Mark this resource as read-only — i.e., the upstream spec exposes only
+      # GET endpoints and no POST/PATCH/PUT/DELETE. Use when a child resource
+      # surfaced by +has_many+ inherits a +.create+ from +Resource+ that would
+      # silently 404 against the spec, e.g., +SessionParticipant+. Overrides
+      # the writer methods to raise +NoMethodError+ with a spec-citing
+      # message before any HTTP call.
+      def read_only
+        @_read_only = true
+        define_singleton_method(:create) do |**|
+          raise NoMethodError, "#{name} is read-only — upstream has no POST endpoint"
+        end
+        define_method(:update) do |**|
+          raise NoMethodError, "#{self.class.name} is read-only — upstream has no PATCH endpoint"
+        end
+        define_method(:destroy) do
+          raise NoMethodError, "#{self.class.name} is read-only — upstream has no DELETE endpoint"
+        end
+      end
+
+      def read_only? = @_read_only == true
+
+      # Declare a typed attribute reader. Coerces on read for known types
+      # (Time, Integer, Float). For :boolean, also defines a `name?` predicate.
+      # Use wire_name when the on-the-wire field name differs from the
+      # snake_case Ruby identifier (e.g., camelCase fields like `locationHint`).
+      #
+      # Readers gate through +ensure_loaded!+: a stub created by +has_one+
+      # auto-fetches its attrs on the first attribute read. Action methods
+      # (+kick+, +mute+, etc.) skip the gate, so action-only flows never pay
+      # for an unwanted GET.
+      def attribute(name, type = nil, wire_name: nil)
+        key      = name.to_sym
+        wire_key = wire_name&.to_s || name.to_s
+        (@_attributes ||= {})[key] = { type: type, wire_name: wire_key }
+
+        # +#id+ is special — it's used internally by +member_path+ which
+        # +reload+ depends on, so a gated reader would cause infinite
+        # recursion. Subclasses can still declare +attribute :id, String+
+        # for type documentation; we just don't override the base reader.
+        return if key == :id
+
+        define_method(name)        { ensure_loaded!; coerce_attribute(@attrs[wire_key], type) }
+        define_method("#{name}?")  { ensure_loaded!; !!@attrs[wire_key] } if type == :boolean
+      end
+
+      def attributes = @_attributes ||= {}
+
+      # Records the on-the-wire field name for a request body kwarg. Use this
+      # when the request shape uses a different name than the response (e.g.,
+      # R2 sends `storageClass` but reads back `storage_class`), or when a
+      # kwarg isn't represented as an attribute at all (write-only fields).
+      def wire_kwarg(ruby_name, wire_name)
+        (@_request_wire_names ||= {})[ruby_name.to_sym] = wire_name.to_s
+      end
+
+      # Wire name used when sending a kwarg in a request body or query.
+      # Lookup order: explicit wire_kwarg → attribute's wire_name → ruby key as string.
+      def wire_name_for_request(ruby_key)
+        sym = ruby_key.to_sym
+        (@_request_wire_names || {})[sym] ||
+          attributes.dig(sym, :wire_name) ||
+          sym.to_s
+      end
+
+      # Wire name used when reading from a response. Only consults the
+      # attribute declaration (response field name).
+      def wire_name_for_response(ruby_key)
+        attributes.dig(ruby_key.to_sym, :wire_name) || ruby_key.to_s
+      end
+
+      # Translate a kwargs Hash from Ruby snake_case keys to wire-format keys
+      # for SENDING in a request body or query.
+      def to_wire_keys(hash)
+        hash.each_with_object({}) { |(k, v), out| out[wire_name_for_request(k)] = v }
+      end
+
+      # Unwrap a Cloudflare response envelope (`result` for V4, `data` for
+      # RealtimeKit) and return the inner payload. Returns the response
+      # unchanged when neither envelope key is present.
+      def unwrap_envelope(response)
+        return response unless response.is_a?(Hash)
+        ENVELOPE_KEYS.each do |key|
+          return response[key] if response.key?(key) && !response[key].nil?
+        end
+        response
+      end
+
+      # Declare a nested collection reachable via REST sub-path. Returns a
+      # Relation scoped to this parent. Convention: `participants` →
+      # `Participant` (singularize + classify) in the same product namespace.
+      # Override with `class_name: "Cloudflare::Other::Klass"`.
+      def has_many(name, class_name: nil)
+        define_method(name) do
+          @relations ||= {}
+          @relations[name.to_sym] ||= Relation.new(parent: self, model: resolve_class(name, class_name: class_name, singularize: true))
+        end
+      end
+
+      # Declare a nested singleton sub-resource (no id, fixed sub-path).
+      # Returns an unloaded stub scoped to this parent. Action methods on the
+      # stub (e.g., +active_session.kick_all+) work without a fetch — they
+      # only need scope. Attribute reads (e.g., +active_session.live_participants+)
+      # auto-fetch via +ensure_loaded!+ on first access and cache thereafter.
+      #
+      # The cost trade-off is HTTP-aware: action-only flows pay nothing extra,
+      # read flows pay exactly one GET on first access.
+      def has_one(name, class_name: nil)
+        define_method(name) do
+          @singletons ||= {}
+          @singletons[name.to_sym] ||= begin
+            klass = resolve_class(name, class_name: class_name, singularize: false)
+            klass.new({}, scope: child_scope_for_nested)
+          end
+        end
+      end
+
+      # CRUD defaults. Subclasses override to add explicit kwargs.
+
+      def create(**attrs)
+        scope    = extract_scope!(attrs)
+        path     = interpolate(_collection_path, scope)
+        response = Connection.instance.request(:post, path, body: to_wire_keys(attrs))
+        new(response, scope: scope)
+      end
+
+      def find(id, **scope_attrs)
+        scope    = build_scope(scope_attrs)
+        path     = interpolate(_member_path, scope.merge(id: id))
+        response = Connection.instance.request(:get, path)
+        new(response, scope: scope)
+      end
+
+      def all(**params)
+        scope    = extract_scope!(params)
+        path     = interpolate(_collection_path, scope)
+        response = Connection.instance.request(:get, path, params: to_wire_keys(params))
+        items    = unwrap_envelope(response)
+        Array(items).map { new(_1, scope: scope) }
+      end
+
+      private
+        # Pulls scope params out of the kwargs hash (mutating). Defaults
+        # account_id from global config if not provided.
+        def extract_scope!(attrs)
+          scope_params.each_with_object({}) do |key, h|
+            value = attrs.delete(key) || (key == :account_id && Cloudflare.account_id)
+            raise ArgumentError, "missing required scope param: #{key}" unless value
+            h[key] = value
+          end
+        end
+
+        def build_scope(provided)
+          scope_params.each_with_object({}) do |key, h|
+            value = provided[key] || (key == :account_id && Cloudflare.account_id)
+            raise ArgumentError, "missing required scope param: #{key}" unless value
+            h[key] = value
+          end
+        end
+
+        def interpolate(path, values)
+          path.gsub(/\{(\w+)\}/) do
+            key = $1.to_sym
+            values[key] || raise(ArgumentError, "missing path param: #{key}")
+          end
+        end
+    end
+
+    attr_reader :scope
+
+    def initialize(response, scope: {})
+      @attrs  = self.class.unwrap_envelope(response).then { |r| r.is_a?(Hash) ? r.transform_keys(&:to_s) : {} }
+      @scope  = scope
+      @loaded = !@attrs.empty?
+    end
+
+    # Note: +#id+ is intentionally not gated through +ensure_loaded!+. It's
+    # called inside +member_path+, which +reload+ itself depends on — gating
+    # would create a fetch loop. On a not-yet-loaded stub this returns nil;
+    # in practice singletons (the only path that produces stubs) don't have
+    # +{id}+ in their member_path, so the nil is harmless during the first
+    # +reload+.
+    def id          = @attrs["id"]
+    def [](key)     = (ensure_loaded!; @attrs[key.to_s])
+    def to_h        = (ensure_loaded!; @attrs)
+    def attributes  = (ensure_loaded!; @attrs)
+
+    def update(**changes)
+      response = Connection.instance.request(:patch, member_path, body: self.class.to_wire_keys(changes))
+      set_attrs_from_response(response)
+      self
+    end
+
+    def destroy
+      Connection.instance.request(:delete, member_path)
+      freeze
+    end
+
+    def reload
+      response = Connection.instance.request(:get, member_path)
+      set_attrs_from_response(response)
+      self
+    end
+
+    # Replace +@attrs+ from a freshly-received response and mark the instance
+    # loaded. Subclasses that issue their own writes (e.g., +Recording#transition+,
+    # +Summary#generate+) call this so a subsequent attribute read doesn't
+    # trigger a stale re-fetch and clobber the just-written state. Public so
+    # subclasses can use it.
+    def set_attrs_from_response(response)
+      return unless response.is_a?(Hash)
+      @attrs  = self.class.unwrap_envelope(response).transform_keys(&:to_s)
+      @loaded = true
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.id == id
+    end
+    alias_method :eql?, :==
+
+    def hash = [ self.class, id ].hash
+
+    private
+      # Auto-fetch this stub's attrs from upstream on first attribute read.
+      # No-op when already loaded. Skipped by action methods (kick, mute, etc.)
+      # which only need +@scope+, so action-only flows incur zero GETs.
+      def ensure_loaded!
+        reload unless @loaded
+      end
+
+      def member_path
+        self.class.send(:interpolate, self.class._member_path, @scope.merge(id: id))
+      end
+
+      COERCERS = {
+        Time    => ->(v) { v.is_a?(Time) ? v : Time.parse(v) },
+        Integer => ->(v) { Integer(v) },
+        Float   => ->(v) { Float(v) }
+      }.freeze
+      private_constant :COERCERS
+
+      def coerce_attribute(value, type)
+        return nil if value.nil?
+        (COERCERS[type] || ->(v) { v }).call(value)
+      end
+
+      # Resolve a nested resource class by name. `singularize: true` strips
+      # a trailing 's' (`participants` → `Participant`); `false` leaves the
+      # name as-is (`active_session` → `ActiveSession`). Override entirely
+      # via `class_name: "Cloudflare::Other::Klass"`.
+      def resolve_class(name, class_name: nil, singularize: false)
+        return Object.const_get(class_name) if class_name
+
+        product_namespace = self.class.name.split("::")[0..-2].join("::")
+        basename          = name.to_s
+        basename          = basename.sub(/s$/, "") if singularize
+        klass             = basename.split("_").map(&:capitalize).join
+        Object.const_get("#{product_namespace}::#{klass}")
+      end
+
+      # Parent's scope + parent's id mapped to its conventional key. For
+      # `Cloudflare::RealtimeKit::Meeting` (id "mtg-1") this produces
+      #   { account_id: "...", app_id: "...", meeting_id: "mtg-1" }
+      def child_scope_for_nested
+        parent_id_key = self.class.name.split("::").last.downcase + "_id"
+        @scope.merge(parent_id_key.to_sym => id)
+      end
+  end
+end

data/lib/cloudflare/version.rb

@@ -0,0 +1,3 @@
+module Cloudflare
+  VERSION = "0.1.2"
+end

data/lib/cloudflare-ruby.rb

@@ -1 +1 @@
-warn "[cloudflare-ruby] This is a placeholder release reserving the gem name. The real SDK has not yet been published. See https://github.com/tokimonki/cloudflare-ruby."
+require "cloudflare"

data/lib/cloudflare.rb

@@ -0,0 +1,34 @@
+require "faraday"
+require "faraday/retry"
+require "time"
+
+require_relative "cloudflare/version"
+
+module Cloudflare
+  autoload :Configuration, "cloudflare/configuration"
+  autoload :Connection,    "cloudflare/connection"
+  autoload :Resource,      "cloudflare/resource"
+  autoload :Relation,      "cloudflare/relation"
+  autoload :RealtimeKit,   "cloudflare/realtime_kit"
+
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = nil
+      Connection.reset!
+    end
+
+    def api_token  = configuration.api_token
+    def account_id = configuration.account_id
+    def base_url   = configuration.base_url
+  end
+end
+
+require_relative "cloudflare/errors"

data/sig/cloudflare/configuration.rbs

@@ -0,0 +1,11 @@
+module Cloudflare
+  class Configuration
+    attr_accessor api_token: String?
+    attr_accessor account_id: String?
+    attr_accessor base_url: String
+    attr_accessor timeout: Integer
+    attr_accessor user_agent: String
+
+    def initialize: () -> void
+  end
+end

data/sig/cloudflare/connection.rbs

@@ -0,0 +1,8 @@
+module Cloudflare
+  class Connection
+    def self.instance: () -> Connection
+    def self.reset!: () -> void
+
+    def request: (Symbol method, String path, ?body: Hash[Symbol | String, untyped]?, ?params: Hash[Symbol | String, untyped]?) -> untyped
+  end
+end

data/sig/cloudflare/errors.rbs

@@ -0,0 +1,25 @@
+module Cloudflare
+  class Error < StandardError
+    attr_reader status: Integer?
+    attr_reader body: untyped
+
+    def initialize: (?String? message, ?status: Integer?, ?body: untyped) -> void
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class NotFoundError < Error
+  end
+
+  class ValidationError < Error
+  end
+
+  class RateLimitError < Error
+  end
+
+  class ServerError < Error
+  end
+
+  ERROR_BY_STATUS: Hash[Integer, Class]
+end

data/sig/cloudflare/realtime_kit.rbs

@@ -0,0 +1,4 @@
+module Cloudflare
+  module RealtimeKit
+  end
+end

data/sig/cloudflare/relation.rbs

@@ -0,0 +1,9 @@
+module Cloudflare
+  class Relation
+    def initialize: (parent: Resource, model: Class) -> void
+
+    def all: (**untyped params) -> Array[Resource]
+    def create: (**untyped attrs) -> Resource
+    def find: (String id) -> Resource
+  end
+end

data/sig/cloudflare/resource.rbs

@@ -0,0 +1,40 @@
+module Cloudflare
+  class Resource
+    type scope_hash = Hash[Symbol, String]
+    type response   = Hash[String, untyped]
+
+    attr_reader scope: scope_hash
+
+    def self._collection_path: () -> String?
+    def self._member_path: () -> String?
+    def self._attributes: () -> Hash[Symbol, untyped]
+    def self.scope_params: () -> Array[Symbol]
+
+    def self.collection_path: (?String? path) -> String?
+    def self.member_path: (?String? path) -> String?
+    def self.scope_required: (*Symbol keys) -> Array[Symbol]
+    def self.attribute: (Symbol name, ?untyped type) -> Symbol
+    def self.attributes: () -> Hash[Symbol, untyped]
+    def self.has_many: (Symbol name, ?class_name: String?) -> Symbol
+    def self.has_one: (Symbol name, ?class_name: String?) -> Symbol
+
+    def self.create: (**untyped attrs) -> Resource
+    def self.find: (String id, **untyped scope_attrs) -> Resource
+    def self.all: (**untyped params) -> Array[Resource]
+
+    def initialize: (response, ?scope: scope_hash) -> void
+
+    def id: () -> String?
+    def []: (Symbol | String key) -> untyped
+    def to_h: () -> response
+    def attributes: () -> response
+
+    def update: (**untyped changes) -> self
+    def destroy: () -> self
+    def reload: () -> self
+
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+  end
+end

data/sig/cloudflare.rbs

@@ -0,0 +1,11 @@
+module Cloudflare
+  VERSION: String
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+  def self.reset_configuration!: () -> void
+
+  def self.api_token: () -> String?
+  def self.account_id: () -> String?
+  def self.base_url: () -> String
+end