basecradle 0.10.2 → 0.11.0

data/lib/basecradle/webhooks.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "api_object"
+require_relative "headers"
 require_relative "items"
 require_relative "serialization"
 require_relative "user"
@@ -73,169 +74,9 @@ module BaseCradle
     end
   end
 
-  # One delivery's request headers: the wire's own spelling, looked up case-insensitively.
-  #
-  # A +Hash+ of exactly what the wire carried — one pair per header, +Content-Type+ and
-  # +Content-Length+ included — so iterating, +keys+, +to_h+, +to_json+ and +==+ all read
-  # the platform's own spelling and nothing is renamed. Only *lookup* folds case, because
-  # header names are case-insensitive by RFC and the platform does not preserve the
-  # sender's casing: it stores names canonicalized to Title-Case per segment
-  # (+X-Github-Delivery+, not +X-GitHub-Delivery+). So a vendor's published spelling finds
-  # the header it names, and so does any other casing of it:
-  #
-  #   event.content.headers["X-GitHub-Delivery"] # GitHub's own published spelling
-  #   event.content.headers["x-github-delivery"] # the lowercase form
-  #   event.content.headers["X-Github-Delivery"] # what the wire actually carried
-  #
-  # Every read that takes a header name folds: +fetch+, +dig+, +values_at+, +fetch_values+,
-  # +to_proc+ and +key?+ (with +has_key?+, +include?+ and +member?+). A header that was
-  # genuinely not delivered is *absent*, never +nil+ — +[]+ and a fallback-less +fetch+ or
-  # +fetch_values+ raise +KeyError+ naming the headers that did arrive, while +fetch+ with
-  # a fallback, +dig+ and +values_at+ answer for it the way +Hash+ does.
-  #
-  # The methods that *reshape* the hash rather than read one name — +slice+, +except+,
-  # +select+, +transform_values+ — and the mutators are left exactly as +Hash+ defines
-  # them: case-sensitive, on the platform's own spelling. This is a read of one delivery
-  # that already happened. Converting away from this type gives up the folding too
-  # (+to_h+, <tt>{**headers}</tt>, and anything else that hands back a plain +Hash+);
-  # +merge+ and +dup+ keep it.
-  #
-  # What it does *not* print is the values: +inspect+, +to_s+ and +pp+ render the header
-  # names alone, because these are the sender's headers and one of them may be the
-  # sender's credential. Every read is unaffected — and so is +to_json+, which still
-  # emits the delivery verbatim. Converting away from this type gives the redaction up
-  # exactly as it gives up the folding, and for the same reason: +slice+, +except+,
-  # +select+, +transform_values+ and +to_h+ hand back a plain +Hash+, whose +inspect+
-  # prints pairs.
-  class WebhookEventHeaders < Hash
-    # Hash's own exact-match membership, kept under a private name before the case-folding
-    # +key?+ below takes the name: a caller who wrote the wire's own spelling is answered
-    # without a scan, and it is the tiebreak if a derived copy holds two casings of one
-    # name.
-    alias_method :exact_key?, :key?
-    private :exact_key?
-
-    NO_FALLBACK = Object.new.freeze
-    private_constant :NO_FALLBACK
-
-    # +client:+ is unused — headers carry no verbs — but every wrapped model is built with
-    # it (see ApiObject.attribute's +wrap:+), so it is accepted.
-    def initialize(data, client: nil)
-      super()
-      update(data)
-    end
-
-    # The header's value, matched case-insensitively. Raises +KeyError+ when no casing of
-    # the name was delivered.
-    def [](name)
-      wire = wire_name(name)
-      wire.nil? ? raise_missing(name) : super(wire)
-    end
-
-    # Hash-like: the value, or the fallback — a default argument, or a block, which is
-    # handed the name as written — when the header was not delivered. With no fallback it
-    # behaves like +[]+.
-    def fetch(name, fallback = NO_FALLBACK, &block)
-      wire = wire_name(name)
-      return super(wire) if wire
-      return yield(name) if block
-      return fallback unless fallback.equal?(NO_FALLBACK)
-
-      raise_missing(name)
-    end
-
-    # Did this delivery carry the header, under any casing?
-    def key?(name)
-      !wire_name(name).nil?
-    end
-    alias_method :has_key?, :key?
-    alias_method :include?, :key?
-    alias_method :member?, :key?
-
-    # Ruby's nil-returning read, case folded: the value, or +nil+ for a header that was
-    # not delivered.
-    def dig(name, *rest)
-      wire = wire_name(name)
-      wire.nil? ? nil : super(wire, *rest)
-    end
-
-    # Several headers at once, folded the same way — +nil+ for one that was not delivered,
-    # as +Hash+ answers for a key it has no value for.
-    def values_at(*names)
-      names.map { |name| dig(name) }
-    end
-
-    # As +values_at+, but a header that was not delivered raises, exactly as +fetch+ does.
-    def fetch_values(*names, &block)
-      names.map { |name| block ? fetch(name, &block) : fetch(name) }
-    end
-
-    # +&headers+ — a header name to its value, folded, +nil+ for one not delivered.
-    def to_proc
-      ->(name) { dig(name) }
-    end
-
-    # The header *names* this delivery carried, and none of their values.
-    #
-    # +Hash+'s own +inspect+ prints every pair, and these headers are the *sender's*,
-    # stored verbatim by the platform: a sender that authenticates its POST to an ingest
-    # URL puts its credential in one of them, so +logger.debug(event.content.headers)+
-    # would write another party's secret into our logs. Every other renderable object in
-    # this SDK is already safe by one rule — +ApiObject#inspect+ prints field names, never
-    # values — and this is the one class that sat outside it, because +Hash+ brought its
-    # own render.
-    #
-    # Only the human-facing render changes. Every *read* is untouched and still
-    # wire-exact: lookups, +fetch+, +each+, +keys+, +to_h+, +to_json+, +==+.
-    #
-    # Names are sorted, as +ApiObject#inspect+ sorts its fields and as the +KeyError+ a
-    # missing header raises already lists the ones that did arrive.
-    def inspect
-      return "#<#{self.class}>" if empty?
-
-      "#<#{self.class} #{keys.sort_by(&:to_s).join(', ')}>"
-    end
-
-    # +Hash+ aliases +to_s+ to its *own* +inspect+ — one shared method entry — so
-    # overriding +inspect+ alone would leave <tt>"#{headers}"</tt> and +puts headers+
-    # printing every value. Late-bound rather than +alias to_s inspect+, so a subclass
-    # that redacts more is not bypassed by interpolation (as +Client#to_s+ is).
-    def to_s
-      inspect
-    end
-
-    # +pp+ reaches for +pretty_print+, and +Hash+ brings one that prints the pairs — the
-    # same leak through the one door +inspect+ does not cover. Delegating puts +pp+ back
-    # on the SDK-wide rule: +pp+ uses an object's own +inspect+ when it defines one, which
-    # is why every +ApiObject+ is already safe here and only a +Hash+ descendant was not.
-    def pretty_print(printer)
-      printer.text(inspect)
-    end
-
-    private
-
-    # The wire's own spelling of +name+, or nil if no casing of it was delivered. Anything
-    # but a String is not a header name, so it is never matched rather than being coerced
-    # into one: +headers[:host]+ finds nothing, and so misses like any other absent name.
-    # Keys are type-checked too — +merge+ hands back one of these, so a caller's derived
-    # copy can hold a key that never came off the wire.
-    def wire_name(name)
-      return nil unless name.is_a?(String)
-      return name if exact_key?(name)
-
-      each_key { |wire| return wire if wire.is_a?(String) && wire.casecmp?(name) }
-      nil
-    end
-
-    def raise_missing(name)
-      raise KeyError.new(
-        "No #{name.inspect} header on this delivery. Header names are matched " \
-        "case-insensitively, so no casing of it was delivered either. " \
-        "Headers present: #{keys.sort_by(&:to_s).inspect}",
-        receiver: self, key: name
-      )
-    end
-  end
+  # One delivery's request headers, exactly as the sender sent them — read through
+  # RequestHeaders' rules: case-insensitive lookup, a render of names and never values.
+  class WebhookEventHeaders < RequestHeaders; end
 
   # One inbound delivery: what was sent, and the two facts about the endpoint as it was at
   # the moment of receipt. Everything in the event's embedded endpoint is *current*; these

data/lib/basecradle.rb

@@ -9,6 +9,8 @@ require_relative "basecradle/pagination"
 require_relative "basecradle/items"
 require_relative "basecradle/webhooks"
 require_relative "basecradle/sessions"
+require_relative "basecradle/headers"
+require_relative "basecradle/contact_messages"
 require_relative "basecradle/timeline"
 require_relative "basecradle/timelines"
 require_relative "basecradle/client"
@@ -18,8 +20,9 @@ require_relative "basecradle/client"
 # same API (https://basecradle.com).
 #
 # Start with a client: +BaseCradle::Client.new+ (token from BASECRADLE_TOKEN) or
-# +BaseCradle::Client.login(email_address:, password:)+. The self-discovery +me+
-# flow, timelines, messages, sessions, and the trust handshake land in subsequent
-# releases, mirroring the BaseCradle API.
+# +BaseCradle::Client.login(email_address:, password:)+. From there, +bc.me+ answers
+# "who am I?", and every other surface of the BaseCradle API hangs off the client:
+# timelines and their messages, assets, tasks and webhooks, your own sessions, and the
+# users directory with its trust handshake.
 module BaseCradle
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: basecradle
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Drawk Kwast
@@ -22,10 +22,13 @@ files:
 - lib/basecradle.rb
 - lib/basecradle/api_object.rb
 - lib/basecradle/client.rb
+- lib/basecradle/contact_messages.rb
 - lib/basecradle/dashboard.rb
 - lib/basecradle/errors.rb
+- lib/basecradle/headers.rb
 - lib/basecradle/items.rb
 - lib/basecradle/pagination.rb
+- lib/basecradle/rendering.rb
 - lib/basecradle/serialization.rb
 - lib/basecradle/sessions.rb
 - lib/basecradle/timeline.rb