wefunder 0.1.0.beta1

data/lib/wefunder/oauth.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "digest"
+require "faraday"
+require "json"
+require "securerandom"
+require "uri"
+
+module Wefunder
+  # OAuth 2.0 helpers: authorization_code + PKCE (user flows) and client_credentials
+  # (server-to-server, read:public). Refresh tokens ROTATE — every refresh returns a NEW
+  # refresh token that must be persisted (the client / TokenManager does this for you).
+  #
+  # HOST SPLIT: /token (+ refresh) is on the API gateway, which routes test/live by the
+  # credential's mode, so ONE token host serves both modes. /authorize is the browser consent
+  # redirect: wefunder.com for live, oauth.wefunder-sandbox.com for pk_test_ client ids.
+  # Overrides: specific (authorize_base_url / token_base_url) > oauth_base_url alias > default.
+  module OAuth
+    DEFAULT_AUTHORIZE_BASE_URL = "https://wefunder.com/oauth"
+    SANDBOX_AUTHORIZE_BASE_URL = "https://oauth.wefunder-sandbox.com/oauth"
+    DEFAULT_TOKEN_BASE_URL = "https://api.wefunder.com/oauth"
+    SANDBOX_CLIENT_ID_PREFIX = "pk_test_"
+
+    # The token endpoint answered non-2xx.
+    class TokenError < StandardError
+      attr_reader :status, :body
+
+      def initialize(status, body)
+        super("OAuth token request failed (#{status}): #{body}")
+        @status = status
+        @body = body
+      end
+    end
+
+    # A token set. +expires_at+ is unix seconds (Float) or nil.
+    TokenSet = Struct.new(:access_token, :refresh_token, :expires_at, :scope, :token_type, keyword_init: true) do
+      def self.from_token_response(raw, now)
+        expires_in = raw["expires_in"] || raw[:expires_in]
+        new(
+          access_token: (raw["access_token"] || raw[:access_token]).to_s,
+          refresh_token: raw["refresh_token"] || raw[:refresh_token],
+          expires_at: expires_in ? now + expires_in.to_f : nil,
+          scope: raw["scope"] || raw[:scope],
+          token_type: raw["token_type"] || raw[:token_type]
+        )
+      end
+    end
+
+    Pkce = Struct.new(:code_verifier, :code_challenge, :code_challenge_method, keyword_init: true)
+
+    module_function
+
+    def resolve_token_base(token_base_url: nil, oauth_base_url: nil, **)
+      token_base_url || oauth_base_url || DEFAULT_TOKEN_BASE_URL
+    end
+
+    # Sandbox consent host for pk_test_ client ids, live otherwise.
+    def default_authorize_base(client_id)
+      client_id.start_with?(SANDBOX_CLIENT_ID_PREFIX) ? SANDBOX_AUTHORIZE_BASE_URL : DEFAULT_AUTHORIZE_BASE_URL
+    end
+
+    # base64url without padding (no +base64+ gem dependency — it leaves the default gems in Ruby 3.4).
+    def base64url(bytes)
+      [bytes].pack("m0").tr("+/", "-_").delete("=")
+    end
+
+    # RFC 7636 S256: base64url(sha256(ascii(verifier))) without padding.
+    def pkce_challenge(code_verifier)
+      base64url(Digest::SHA256.digest(code_verifier))
+    end
+
+    # A fresh PKCE verifier/challenge pair (RFC 7636, S256).
+    def generate_pkce
+      verifier = base64url(SecureRandom.random_bytes(32))
+      Pkce.new(code_verifier: verifier, code_challenge: pkce_challenge(verifier), code_challenge_method: "S256")
+    end
+
+    # The URL to redirect a user to for the authorization_code + PKCE flow. +state+ is an
+    # opaque CSRF token you generate and verify on the callback.
+    def create_authorization_url(client_id:, redirect_uri:, scopes:, state:, pkce: nil, code_challenge: nil,
+                                 authorize_base_url: nil, oauth_base_url: nil, token_base_url: nil)
+      _ = token_base_url # accepted for symmetry with the token helpers; never affects /authorize
+      challenge = code_challenge || pkce&.code_challenge
+      raise ArgumentError, "create_authorization_url: provide pkce: or code_challenge:" unless challenge
+
+      base = authorize_base_url || oauth_base_url || default_authorize_base(client_id)
+      query = URI.encode_www_form(
+        response_type: "code", client_id: client_id, redirect_uri: redirect_uri, scope: Array(scopes).join(" "),
+        state: state, code_challenge: challenge, code_challenge_method: "S256"
+      )
+      "#{base}/authorize?#{query}"
+    end
+
+    # Exchange an authorization code (+ PKCE verifier) for a token set. Public (PKCE) clients
+    # omit +client_secret+; confidential clients pass it.
+    def exchange_code(client_id:, code:, redirect_uri:, code_verifier:, client_secret: nil, faraday: nil, now: nil, **hosts)
+      params = { grant_type: "authorization_code", client_id: client_id, code: code, redirect_uri: redirect_uri,
+                 code_verifier: code_verifier }
+      params[:client_secret] = client_secret if client_secret
+      post_token(resolve_token_base(**hosts), params, faraday, now)
+    end
+
+    # Mint an application token (server-to-server). cc tokens carry no refresh token.
+    def client_credentials_grant(client_id:, client_secret:, scopes: nil, faraday: nil, now: nil, **hosts)
+      params = { grant_type: "client_credentials", client_id: client_id, client_secret: client_secret }
+      params[:scope] = Array(scopes).join(" ") if scopes && !Array(scopes).empty?
+      post_token(resolve_token_base(**hosts), params, faraday, now)
+    end
+
+    # Refresh an access token. CRITICAL: the result carries a NEW refresh token (rotation) —
+    # persist it. Reusing the old one after rotation is a permanent 401.
+    def refresh_token(client_id:, refresh_token:, client_secret: nil, faraday: nil, now: nil, **hosts)
+      params = { grant_type: "refresh_token", client_id: client_id, refresh_token: refresh_token }
+      params[:client_secret] = client_secret if client_secret
+      post_token(resolve_token_base(**hosts), params, faraday, now)
+    end
+
+    # +faraday+ is an optional callable that configures the connection (tests inject an
+    # adapter: +->(conn) { conn.adapter :test, stubs }+).
+    def post_token(base, params, faraday, now)
+      conn = Faraday.new do |c|
+        faraday&.call(c)
+        c.adapter Faraday.default_adapter unless faraday
+      end
+      response = conn.post("#{base}/token", URI.encode_www_form(params),
+                           "Content-Type" => "application/x-www-form-urlencoded")
+      raise TokenError.new(response.status, response.body.to_s) unless (200..299).cover?(response.status)
+
+      TokenSet.from_token_response(JSON.parse(response.body.to_s), (now || -> { Time.now.to_f }).call)
+    end
+  end
+
+  TokenSet = OAuth::TokenSet
+  Pkce = OAuth::Pkce
+end

data/lib/wefunder/pagination.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Wefunder
+  # Lazy auto-pagination over an OPAQUE cursor. Different endpoints back the cursor with an
+  # int id, an ISO timestamp, or an offset, so it is never inspected — +meta.next_cursor+ is
+  # fed back verbatim. Stop when +meta.has_more+ is false, +next_cursor+ is nil/absent, or a
+  # cursor repeats (loop guard). The Investment Delta API always sends +next_cursor+, even on
+  # the last page, so +has_more+ terminates there.
+  module Pagination
+    module_function
+
+    # +(items, has_more, next_cursor)+ from a Hash page (string or symbol keys) or a generated
+    # +*ListEnvelope+ object.
+    def page_parts(page)
+      data = read(page, :data) || []
+      meta = read(page, :meta)
+      has_more = read(meta, :has_more)
+      [Array(data), [true, false].include?(has_more) ? has_more : nil, read(meta, :next_cursor)]
+    end
+
+    def read(obj, key)
+      return nil if obj.nil?
+      return (obj.key?(key.to_s) ? obj[key.to_s] : obj[key]) if obj.is_a?(Hash)
+
+      obj.respond_to?(key) ? obj.public_send(key) : nil
+    end
+
+    # Yields every item across all pages, lazily. +fetch_page.call(nil)+ is the first page.
+    def paginate(fetch_page = nil, &block)
+      fetch = fetch_page || block
+      Enumerator.new do |y|
+        cursor = nil
+        seen = {}
+        loop do
+          items, has_more, next_cursor = page_parts(fetch.call(cursor))
+          items.each { |item| y << item }
+          break if has_more == false || next_cursor.nil? || seen.key?(next_cursor)
+
+          seen[next_cursor] = true
+          cursor = next_cursor
+        end
+      end
+    end
+
+    def collect(fetch_page = nil, &)
+      paginate(fetch_page, &).to_a
+    end
+  end
+
+  def self.paginate(fetch_page = nil, &) = Pagination.paginate(fetch_page, &)
+  def self.collect(fetch_page = nil, &) = Pagination.collect(fetch_page, &)
+end

data/lib/wefunder/token_manager.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Wefunder
+  # Holds the live token state and owns recovery + persistence. Two strategies, picked
+  # automatically: refresh_token ROTATION (a refresh token + client_id present) or
+  # client_credentials RE-MINT (built from cc grant inputs; cc tokens carry no refresh token).
+  # Concurrent callers coalesce: the transport passes the token it just used, and if the
+  # manager already holds a different one, another caller recovered in the meantime and the
+  # current set is returned without a round-trip. The rotated set is persisted (store +
+  # callback) BEFORE the retried request can use it. Thread-safe (Mutex).
+  class TokenManager
+    DEFAULT_EXPIRY_LEEWAY_SECONDS = 30.0
+
+    attr_reader :current
+
+    def initialize(tokens, client_id: nil, client_secret: nil, re_mint: nil, on_token_refresh: nil, store: nil,
+                   faraday: nil, now: nil, expiry_leeway_seconds: DEFAULT_EXPIRY_LEEWAY_SECONDS,
+                   token_base_url: nil, oauth_base_url: nil)
+      @current = tokens
+      @client_id = client_id
+      @client_secret = client_secret
+      @re_mint = re_mint
+      @on_token_refresh = on_token_refresh
+      @store = store
+      @faraday = faraday
+      @now = now || -> { Time.now.to_f }
+      @leeway = expiry_leeway_seconds
+      @token_base_url = OAuth.resolve_token_base(token_base_url: token_base_url, oauth_base_url: oauth_base_url)
+      @lock = Mutex.new
+    end
+
+    # True if an expired token can be recovered (rotate a refresh token or re-mint).
+    def can_refresh?
+      can_rotate? || !@re_mint.nil?
+    end
+
+    # A valid access token, refreshing proactively if expired / within the leeway.
+    def access_token
+      refresh(stale_token: @current.access_token) if near_expiry? && can_refresh?
+      @current.access_token
+    end
+
+    # Recover the token (after a 401 or proactively). If +stale_token+ is no longer the current
+    # token, someone else already recovered and the current set is returned.
+    def refresh(stale_token: nil)
+      @lock.synchronize do
+        return @current if stale_token && @current.access_token != stale_token
+
+        previous_refresh = @current.refresh_token
+        nxt =
+          if can_rotate?
+            set = OAuth.refresh_token(client_id: @client_id, client_secret: @client_secret, refresh_token: previous_refresh,
+                                      token_base_url: @token_base_url, faraday: @faraday, now: @now)
+            # Some servers omit a fresh refresh_token on rotation-disabled flows; keep the old one.
+            set.refresh_token ||= previous_refresh
+            set
+          elsif @re_mint
+            @re_mint.call
+          else
+            raise AuthError, "Access token expired and no refresh token / re-mint capability is configured."
+          end
+        @current = nxt
+        @store&.save(nxt)
+        @on_token_refresh&.call(nxt)
+        nxt
+      end
+    end
+
+    private
+
+    def can_rotate?
+      !@current.refresh_token.nil? && !@current.refresh_token.empty? && !@client_id.nil?
+    end
+
+    def near_expiry?
+      exp = @current.expires_at
+      !exp.nil? && @now.call >= exp - @leeway
+    end
+  end
+end

data/lib/wefunder/transport.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Wefunder
+  # The retry/refresh Faraday middleware. Owns the Authorization header (reads the managed
+  # token per attempt) and applies the contract-driven policy:
+  # * 401 → recover the token (rotation or re-mint) and retry ONCE, any method.
+  # * 429 → honour X-RateLimit-Reset (NOT Retry-After) and retry, bounded.
+  # * 5xx / network error → retry IDEMPOTENT methods only (GET/HEAD/OPTIONS) with jittered
+  #   exponential backoff. Writes are never auto-retried.
+  # Every attempt re-sends the same body (Faraday bodies are strings), which is what made
+  # the equivalent Node fix necessary.
+  class Transport < Faraday::Middleware
+    IDEMPOTENT_METHODS = %w[GET HEAD OPTIONS].freeze
+    RATE_LIMIT_RESET_HEADER = "x-ratelimit-reset"
+    NETWORK_ERRORS = [Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError].freeze
+
+    RetryOptions = Struct.new(:max_retries, :base_delay_ms, :max_delay_ms, keyword_init: true) do
+      def self.defaults = new(max_retries: 2, base_delay_ms: 250.0, max_delay_ms: 60_000.0)
+    end
+
+    # How long to wait for a 429. X-RateLimit-Reset may be absolute epoch SECONDS (values
+    # above ~1e9) or a delta in seconds. Absent/non-numeric → 1s; clamped to [0, max].
+    def self.rate_limit_wait_ms(reset_header, now_ms, max_delay_ms)
+      fallback = [1000.0, max_delay_ms].min
+      return fallback if reset_header.nil?
+
+      n = Float(reset_header, exception: false)
+      return fallback if n.nil?
+
+      wait = n > 1_000_000_000 ? (n * 1000) - now_ms : n * 1000
+      wait.clamp(0.0, max_delay_ms)
+    end
+
+    # min(base·2ⁿ + base·2ⁿ·0.5·random, max) for retry attempt n (1-based).
+    def self.backoff_ms(attempt, opts, random_value)
+      exp = opts.base_delay_ms * (2**attempt)
+      [exp + (exp * 0.5 * random_value), opts.max_delay_ms].min
+    end
+
+    def initialize(app, token_manager: nil, retry_options: nil, sleep: nil, now_ms: nil, random: nil)
+      super(app)
+      @token_manager = token_manager
+      @retry = retry_options || RetryOptions.defaults
+      @sleep = sleep || ->(ms) { Kernel.sleep(ms / 1000.0) }
+      @now_ms = now_ms || -> { Time.now.to_f * 1000 }
+      @random = random || -> { Kernel.rand }
+    end
+
+    def call(env)
+      idempotent = IDEMPOTENT_METHODS.include?(env.method.to_s.upcase)
+      token = @token_manager&.access_token
+      refreshed = false
+      attempt = 0
+      loop do
+        env.request_headers["Authorization"] = "Bearer #{token}" if token
+        response = nil
+        error = nil
+        begin
+          response = @app.call(env.dup)
+        rescue *NETWORK_ERRORS => e
+          error = e
+        end
+        status = response&.status
+
+        if status == 401 && !refreshed && @token_manager&.can_refresh?
+          refreshed = true
+          token = @token_manager.refresh(stale_token: token).access_token
+          next
+        end
+
+        delay = nil
+        if status == 429 && attempt < @retry.max_retries
+          delay = self.class.rate_limit_wait_ms(response.headers[RATE_LIMIT_RESET_HEADER], @now_ms.call, @retry.max_delay_ms)
+        elsif (error || (status && status >= 500)) && idempotent && attempt < @retry.max_retries
+          delay = self.class.backoff_ms(attempt + 1, @retry, @random.call)
+        end
+        if delay
+          attempt += 1
+          @sleep.call(delay)
+          next
+        end
+
+        return response if response
+
+        raise error
+      end
+    end
+  end
+
+  RetryOptions = Transport::RetryOptions
+end

data/lib/wefunder/version.rb

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

data/lib/wefunder/webhooks.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Wefunder
+  # Webhook verification + parsing for Wefunder platform events. The scheme is a single
+  # Stripe-style header:
+  #   Wefunder-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]
+  #   v1 = HMAC-SHA256(secret, "<t>.<raw_body>")
+  # During a secret rotation the header carries one +v1+ per active secret; a delivery is
+  # valid if ANY matches. Consumers enforce a replay tolerance on +t+ (documented: 5 min).
+  # Every delivery body is the envelope +{id: "evt_…", event, created_at, mode, data}+ —
+  # +id+ is the dedup key. The retired attribution scheme (+X-Wefunder-Signature: sha256=…+
+  # + +X-Wefunder-Timestamp+) is still accepted by +construct_event+ when the new header is
+  # absent, so an attribution subscriber isn't stranded.
+  module Webhooks
+    SIGNATURE_HEADER = "wefunder-signature"
+    DEFAULT_TOLERANCE_SECONDS = 300
+    LEGACY_SIGNATURE_HEADER = "x-wefunder-signature"
+    LEGACY_TIMESTAMP_HEADER = "x-wefunder-timestamp"
+    LEGACY_EVENT_HEADER = "x-wefunder-event"
+    LEGACY_DELIVERY_ID_HEADER = "x-wefunder-delivery-id"
+
+    FAILURE_REASONS = %w[missing_header malformed_header timestamp_out_of_tolerance signature_mismatch
+                         invalid_payload].freeze
+    FAILURE_MESSAGES = {
+      "missing_header" => "Missing Wefunder-Signature header",
+      "malformed_header" => "Wefunder-Signature header is malformed (expected t=<unix>,v1=<hex>)",
+      "timestamp_out_of_tolerance" => "Webhook timestamp is outside the replay tolerance",
+      "signature_mismatch" => "Webhook signature verification failed",
+      "invalid_payload" => "Webhook body is not a JSON object"
+    }.freeze
+
+    # Every event name in the catalog. Kept in step with the spec's +events+ enum by
+    # spec/webhooks_spec.rb, which fails when the two diverge.
+    EVENT_NAMES = %w[
+      investment.created investment.reinstated investment.canceled investment.converted
+      investment.amount_changed investment.executed investment.changed
+      offering.opened offering.closing offering.closed offering.canceled
+      investment_session.created investment_session.started investment_session.completed
+      investment_session.expired investment_session.canceled
+      syndicate_member.invited syndicate_member.reinvited syndicate_member.applied
+      syndicate_member.approved syndicate_member.joined
+    ].freeze
+
+    # Raised by +construct_event+. Respond 400 and don't process.
+    class SignatureError < StandardError
+      attr_reader :reason
+
+      def initialize(reason)
+        super(FAILURE_MESSAGES.fetch(reason))
+        @reason = reason
+      end
+    end
+
+    # A verified, parsed delivery. +timestamp+ is the signed +t+ (unix seconds).
+    Event = Struct.new(:id, :event, :created_at, :mode, :data, :timestamp, keyword_init: true) do
+      def known? = EVENT_NAMES.include?(event)
+    end
+
+    ParsedHeader = Struct.new(:timestamp, :signatures, keyword_init: true)
+
+    module_function
+
+    # HMAC-SHA256(secret, "<timestamp>.<raw body>") as lowercase hex.
+    def compute_signature(secret, timestamp, payload)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.".b + payload.to_s.b)
+    end
+
+    # Parse +t=<unix>,v1=<hex>[,v1=<hex>]+. nil when the shape is wrong. Unknown keys (a
+    # future +v2+) are ignored on purpose.
+    def parse_signature_header(header)
+      timestamp = nil
+      signatures = []
+      header.to_s.split(",").each do |part|
+        key, eq, value = part.partition("=")
+        next if eq.empty?
+
+        key = key.strip
+        value = value.strip
+        if key == "t"
+          return nil unless value.match?(/\A\d+\z/)
+
+          timestamp = value.to_i
+        elsif key == "v1" && !value.empty?
+          signatures << value
+        end
+      end
+      return nil if timestamp.nil? || signatures.empty?
+
+      ParsedHeader.new(timestamp: timestamp, signatures: signatures)
+    end
+
+    # Build a +Wefunder-Signature+ header value for +payload+ (for your own tests — the API
+    # signs real deliveries). +additional_secrets+ adds one +v1+ per secret (rotation window).
+    def sign(payload, secret, timestamp: nil, additional_secrets: [])
+      t = timestamp || Time.now.to_i
+      entries = [secret, *additional_secrets].map { |s| "v1=#{compute_signature(s, t, payload)}" }
+      ["t=#{t}", *entries].join(",")
+    end
+
+    # The reason a delivery is NOT valid, or nil when it is. Constant-time compare against
+    # every +v1+; enforces the timestamp tolerance (0 disables it).
+    def check_signature(payload, header, secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+      parsed = parse_signature_header(header)
+      return "malformed_header" unless parsed
+      if tolerance_seconds.positive? && (now_f(now) - parsed.timestamp).abs > tolerance_seconds
+        return "timestamp_out_of_tolerance"
+      end
+
+      expected = compute_signature(secret, parsed.timestamp, payload)
+      parsed.signatures.any? { |sig| secure_equal?(sig, expected) } ? nil : "signature_mismatch"
+    end
+
+    # Legacy attribution scheme: +X-Wefunder-Signature: sha256=<hex>+ + +X-Wefunder-Timestamp+.
+    def verify_legacy(payload, signature, timestamp, secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+      ts = Integer(timestamp.to_s, exception: false)
+      return false if ts.nil?
+      return false if tolerance_seconds.positive? && (now_f(now) - ts).abs > tolerance_seconds
+
+      secure_equal?(signature.to_s, "sha256=#{compute_signature(secret, timestamp, payload)}")
+    end
+
+    # true iff the signature is valid and (when tolerance > 0) the timestamp is within
+    # tolerance. Never raises. Pass +header:+ (the Wefunder-Signature value) or, for a legacy
+    # attribution subscription, +signature:+ + +timestamp:+.
+    def verify(payload, secret, header: nil, signature: nil, timestamp: nil,
+               tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+      return check_signature(payload, header, secret, tolerance_seconds: tolerance_seconds, now: now).nil? if header
+      return false if signature.nil? || timestamp.nil?
+
+      verify_legacy(payload, signature, timestamp, secret, tolerance_seconds: tolerance_seconds, now: now)
+    end
+
+    # Verify a delivery and parse its envelope in one step. Raises SignatureError (with
+    # +reason+) on any failure. +payload+ is the RAW request body; +headers+ is any
+    # case-insensitive mapping (Rack env style keys are accepted too), or the header value itself.
+    def construct_event(payload, headers, secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+      get = header_getter(headers)
+      header = get.call(SIGNATURE_HEADER)
+      unless header
+        legacy_sig = get.call(LEGACY_SIGNATURE_HEADER)
+        legacy_ts = get.call(LEGACY_TIMESTAMP_HEADER)
+        if legacy_sig && legacy_ts
+          return construct_legacy_event(payload, get, legacy_sig, legacy_ts, secret, tolerance_seconds, now)
+        end
+
+        raise SignatureError, "missing_header"
+      end
+      failure = check_signature(payload, header, secret, tolerance_seconds: tolerance_seconds, now: now)
+      raise SignatureError, failure if failure
+
+      parsed = parse_signature_header(header)
+      env = parse_envelope(payload)
+      Event.new(id: env["id"].to_s, event: env["event"].to_s, created_at: env["created_at"].to_s,
+                mode: mode_of(env["mode"]), data: env["data"], timestamp: parsed.timestamp)
+    end
+
+    # Call the handler registered for +event.event+, falling back to "default". Returns true
+    # if a handler ran. Handlers are callables (procs/lambdas/method objects).
+    def dispatch(event, handlers)
+      handler = pick_handler(event, handlers)
+      return false unless handler
+
+      handler.call(event)
+      true
+    end
+
+    # --- internals -----------------------------------------------------------------------
+
+    def now_f(now) = (now || -> { Time.now.to_f }).call
+
+    def secure_equal?(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    def header_getter(headers)
+      return ->(name) { name == SIGNATURE_HEADER ? headers : nil } if headers.is_a?(String)
+
+      lowered = {}
+      headers.each do |k, v|
+        key = k.to_s.downcase
+        key = key.delete_prefix("http_").tr("_", "-") if key.start_with?("http_") # Rack env style
+        lowered[key] = v
+      end
+      lambda do |name|
+        value = lowered[name]
+        value = value.first if value.is_a?(Array)
+        value&.to_s
+      end
+    end
+
+    def parse_envelope(payload)
+      parsed = JSON.parse(payload.to_s)
+      raise SignatureError, "invalid_payload" unless parsed.is_a?(Hash)
+
+      parsed
+    rescue JSON::ParserError
+      raise SignatureError, "invalid_payload"
+    end
+
+    def mode_of(value) = value == "test" ? "test" : "live"
+
+    def construct_legacy_event(payload, get, signature, timestamp, secret, tolerance_seconds, now)
+      unless verify_legacy(payload, signature, timestamp, secret, tolerance_seconds: tolerance_seconds, now: now)
+        raise SignatureError, "signature_mismatch"
+      end
+
+      env = parse_envelope(payload)
+      Event.new(id: (env["id"] || get.call(LEGACY_DELIVERY_ID_HEADER)).to_s,
+                event: (env["event"] || get.call(LEGACY_EVENT_HEADER)).to_s,
+                created_at: env["created_at"].to_s, mode: mode_of(env["mode"]),
+                data: env.key?("data") ? env["data"] : env, timestamp: timestamp.to_i)
+    end
+
+    def pick_handler(event, handlers)
+      specific = event.event == "default" ? nil : (handlers[event.event] || handlers[event.event.to_sym])
+      specific || handlers["default"] || handlers[:default]
+    end
+  end
+
+  WebhookEvent = Webhooks::Event
+  WebhookSignatureError = Webhooks::SignatureError
+  WEBHOOK_EVENT_NAMES = Webhooks::EVENT_NAMES
+
+  class << self
+    def construct_event(...) = Webhooks.construct_event(...)
+    def verify_webhook(...) = Webhooks.verify(...)
+    def check_webhook_signature(...) = Webhooks.check_signature(...)
+    def sign_webhook(...) = Webhooks.sign(...)
+    def compute_webhook_signature(...) = Webhooks.compute_signature(...)
+    def parse_signature_header(...) = Webhooks.parse_signature_header(...)
+    def dispatch_webhook(...) = Webhooks.dispatch(...)
+  end
+end

data/lib/wefunder.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Official Ruby SDK for the Wefunder API (beta).
+#
+#   wf = Wefunder::Client.from_client_credentials(client_id: ..., client_secret: ..., scopes: ["read:public"])
+#   wf.offerings.all(sort: "newest").each { |offering| puts offering.id }
+require "wefunder_generated"
+require_relative "wefunder/version"
+require_relative "wefunder/errors"
+require_relative "wefunder/oauth"
+require_relative "wefunder/token_manager"
+require_relative "wefunder/transport"
+require_relative "wefunder/pagination"
+require_relative "wefunder/webhooks"
+require_relative "wefunder/client"
+
+module Wefunder
+  class << self
+    def generate_pkce = OAuth.generate_pkce
+    def pkce_challenge(...) = OAuth.pkce_challenge(...)
+    def create_authorization_url(...) = OAuth.create_authorization_url(...)
+    def exchange_code(...) = OAuth.exchange_code(...)
+    def client_credentials_grant(...) = OAuth.client_credentials_grant(...)
+    def refresh_token(...) = OAuth.refresh_token(...)
+  end
+end