listo-delivery 0.1.1

data/lib/listo_delivery/util.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "erb"
+require "uri"
+
+module ListoDelivery
+  # Argument handling shared by the generated resource methods.
+  # @api private
+  module Util
+    module_function
+
+    # A path parameter, escaped so an id can never change the route.
+    def segment(value)
+      text = value.to_s
+      raise ArgumentError, "a path parameter must not be blank" if text.strip.empty?
+
+      ERB::Util.url_encode(text)
+    end
+
+    # The request body: the positional Hash merged with keyword fields, nil
+    # when neither was given (so nothing is sent) unless `required` names
+    # the operation that needs one.
+    def body(body, fields, required: nil)
+      reject_idempotency_key(fields)
+      merged = merge(body, fields)
+      raise ArgumentError, "#{required} needs a request body" if merged.nil? && required
+
+      merged
+    end
+
+    # The query string pairs as a Hash, nil when empty.
+    def query(query, fields)
+      reject_idempotency_key(fields)
+      merged = merge(query, fields)
+      merged&.reject { |_, v| v.nil? }
+    end
+
+    # Only the operations that declare the Idempotency-Key header take
+    # `idempotency_key:`, and those methods capture it as a keyword before
+    # `fields` exists. One that reaches `fields` belongs to an operation
+    # without the header, where it would otherwise be sent as a body or
+    # query field the API drops, and the caller would think the call was
+    # protected. A body field genuinely named so goes inside the Hash.
+    def reject_idempotency_key(fields)
+      return unless fields.key?(:idempotency_key)
+
+      raise ArgumentError,
+        "this operation does not take an idempotency key; " \
+        "to send a field named idempotency_key, put it inside the Hash argument"
+    end
+
+    def merge(first, fields)
+      base = first.nil? ? nil : plain(first)
+      raise ArgumentError, "expected a Hash, got #{first.class}" unless base.nil? || base.is_a?(Hash)
+
+      extra = plain(fields)
+      return base if extra.empty?
+
+      (base || {}).merge(extra)
+    end
+
+    # Models and symbol keys become plain JSON-shaped data.
+    def plain(value)
+      case value
+      when Model then plain(value.to_h)
+      when Hash then value.each_with_object({}) { |(k, v), h| h[k.to_s] = plain(v) }
+      when Array then value.map { |v| plain(v) }
+      else value
+      end
+    end
+
+    def encode_query(pairs)
+      URI.encode_www_form(pairs)
+    end
+  end
+end

data/lib/listo_delivery/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ListoDelivery
+  # The SDK's own version. The API release it was generated from is
+  # ListoDelivery::API_VERSION (generated/api_version.rb).
+  VERSION = "0.1.1"
+end

data/lib/listo_delivery/webhooks.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module ListoDelivery
+  # Checks that a webhook really came from Listo. Mirrors the server's own
+  # signing rule:
+  #
+  #   X-Listo-Signature: t=<unix seconds>,v1=<hex hmac-sha256 over "<t>.<raw body>">
+  #
+  # Pass the RAW body exactly as received, never re-serialized JSON, and
+  # every secret that is currently active (two during a rotation).
+  #
+  #   event = ListoDelivery::Webhooks.construct_event(request.body.read, request.headers["X-Listo-Signature"], secret)
+  module Webhooks
+    HEADER = "X-Listo-Signature"
+    DEFAULT_TOLERANCE = 300
+    PATTERN = /\At=(\d+),v1=(\h+)\z/
+
+    # True only when the header is a well formed signature over the body,
+    # made within `tolerance` seconds of `now` (either direction), under any
+    # of the secrets. Never raises: anything malformed is false.
+    #
+    # @param raw_body [String]
+    # @param signature_header [String, nil]
+    # @param secrets [String, Array<String>]
+    # @param tolerance [Integer] seconds
+    # @param now [Integer, Time, nil] unix seconds; defaults to the current time
+    def self.verify(raw_body, signature_header, secrets, tolerance: DEFAULT_TOLERANCE, now: nil)
+      usable = Array(secrets).map(&:to_s).reject { |s| s.strip.empty? }
+      return false if usable.empty?
+
+      match = PATTERN.match(signature_header.to_s)
+      return false if match.nil?
+
+      timestamp = match[1].to_i
+      return false if (now_seconds(now) - timestamp).abs > tolerance.to_i
+
+      given = match[2]
+      usable.any? { |secret| secure_equal?(digest(timestamp, raw_body, secret), given) }
+    rescue ArgumentError, TypeError, EncodingError
+      false
+    end
+
+    # Verifies, then parses the body into the event class its `type` names
+    # (a type this SDK does not know comes back as a plain
+    # Models::WebhookEvent).
+    #
+    # @raise [ListoDelivery::SignatureError] when the signature does not verify
+    # @return [Models::WebhookEvent]
+    def self.construct_event(raw_body, signature_header, secrets, tolerance: DEFAULT_TOLERANCE, now: nil)
+      raise SignatureError unless verify(raw_body, signature_header, secrets, tolerance: tolerance, now: now)
+
+      parsed = JSON.parse(raw_body.to_s)
+      unless parsed.is_a?(Hash)
+        raise Error.new("The webhook body is not a JSON object.", code: "invalid_payload", retryable: false)
+      end
+
+      Models::WebhookEvent.build(parsed)
+    rescue JSON::ParserError
+      raise Error.new("The webhook body is not valid JSON.", code: "invalid_payload", retryable: false)
+    end
+
+    # The signed string is "<t>.<raw body>" over the bytes as received.
+    def self.digest(timestamp, raw_body, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret.to_s.b, "#{timestamp}.".b + raw_body.to_s.b)
+    end
+
+    # The length check comes first because the constant-time comparison
+    # raises on unequal lengths, and a truncated signature is just invalid.
+    def self.secure_equal?(expected, given)
+      return false unless expected.bytesize == given.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, given)
+    end
+
+    def self.now_seconds(now)
+      (now || Time.now).to_i
+    end
+
+    private_class_method :digest, :secure_equal?, :now_seconds
+  end
+
+  module Resources
+    # The webhook operations (generated) plus the signature helpers, so
+    # `client.webhooks.verify(...)` reads like the rest of the client.
+    class Webhooks
+      def verify(...)
+        ListoDelivery::Webhooks.verify(...)
+      end
+
+      def construct_event(...)
+        ListoDelivery::Webhooks.construct_event(...)
+      end
+    end
+  end
+end

data/lib/listo_delivery.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "listo_delivery/version"
+require_relative "listo_delivery/errors"
+require_relative "listo_delivery/util"
+require_relative "listo_delivery/model"
+require_relative "listo_delivery/generated/loader"
+require_relative "listo_delivery/webhooks"
+require_relative "listo_delivery/client"
+
+# Official Ruby client for the Listo Delivery API.
+#
+#   require "listo_delivery"
+#   client = ListoDelivery::Client.new(api_key: "lst_test_...")
+module ListoDelivery
+end

data/listo_delivery.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "lib/listo_delivery/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "listo-delivery"
+  spec.version = ListoDelivery::VERSION
+  spec.summary = "Official Ruby client for the Listo Delivery API"
+  spec.description = "Quote and book deliveries, manage stores and money, and verify webhooks with the Listo Delivery API. Standard library only."
+  spec.authors = ["Listo"]
+  spec.homepage = "https://docs.listo.delivery"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+  spec.metadata = {
+    "homepage_uri" => "https://docs.listo.delivery",
+    "documentation_uri" => "https://docs.listo.delivery/en/quickstart",
+    "changelog_uri" => "https://docs.listo.delivery/en/changelog",
+    "source_code_uri" => "https://github.com/listo-delivery/listo-ruby",
+    "bug_tracker_uri" => "https://github.com/listo-delivery/listo-ruby/issues",
+    "rubygems_mfa_required" => "true"
+  }
+
+  # Listed from the directory, never from git, so the gem builds the same
+  # from a tarball or a worktree.
+  spec.files = Dir.chdir(__dir__) { Dir["lib/**/*.rb"] + ["README.md", "LICENSE", "listo_delivery.gemspec"] }.sort
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: listo-delivery
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Listo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Quote and book deliveries, manage stores and money, and verify webhooks
+  with the Listo Delivery API. Standard library only.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/listo_delivery.rb
+- lib/listo_delivery/client.rb
+- lib/listo_delivery/errors.rb
+- lib/listo_delivery/generated/api_version.rb
+- lib/listo_delivery/generated/client_operations.rb
+- lib/listo_delivery/generated/loader.rb
+- lib/listo_delivery/generated/models/balance.rb
+- lib/listo_delivery/generated/models/cancel_delivery_request.rb
+- lib/listo_delivery/generated/models/card_onboarding_link.rb
+- lib/listo_delivery/generated/models/card_status.rb
+- lib/listo_delivery/generated/models/connect_request.rb
+- lib/listo_delivery/generated/models/courier_ping.rb
+- lib/listo_delivery/generated/models/create_connect_request_request.rb
+- lib/listo_delivery/generated/models/create_connection_request.rb
+- lib/listo_delivery/generated/models/create_delivery_request.rb
+- lib/listo_delivery/generated/models/create_quote_request.rb
+- lib/listo_delivery/generated/models/create_store_owner_request.rb
+- lib/listo_delivery/generated/models/create_store_request.rb
+- lib/listo_delivery/generated/models/create_withdrawal_request.rb
+- lib/listo_delivery/generated/models/delivery.rb
+- lib/listo_delivery/generated/models/delivery_courier_location_event.rb
+- lib/listo_delivery/generated/models/delivery_list.rb
+- lib/listo_delivery/generated/models/delivery_message_skipped.rb
+- lib/listo_delivery/generated/models/delivery_message_skipped_event.rb
+- lib/listo_delivery/generated/models/delivery_status_changed_event.rb
+- lib/listo_delivery/generated/models/delivery_updated_event.rb
+- lib/listo_delivery/generated/models/error.rb
+- lib/listo_delivery/generated/models/error_response.rb
+- lib/listo_delivery/generated/models/event_list.rb
+- lib/listo_delivery/generated/models/ledger_entry.rb
+- lib/listo_delivery/generated/models/ledger_entry_list.rb
+- lib/listo_delivery/generated/models/manifest.rb
+- lib/listo_delivery/generated/models/manifest_item.rb
+- lib/listo_delivery/generated/models/owner_invitation.rb
+- lib/listo_delivery/generated/models/ping.rb
+- lib/listo_delivery/generated/models/quote.rb
+- lib/listo_delivery/generated/models/refund_delivery_request.rb
+- lib/listo_delivery/generated/models/request_log.rb
+- lib/listo_delivery/generated/models/request_log_detail.rb
+- lib/listo_delivery/generated/models/request_log_list.rb
+- lib/listo_delivery/generated/models/reschedule_delivery_request.rb
+- lib/listo_delivery/generated/models/same_day_terms.rb
+- lib/listo_delivery/generated/models/send_test_webhook_request.rb
+- lib/listo_delivery/generated/models/store.rb
+- lib/listo_delivery/generated/models/store_balance.rb
+- lib/listo_delivery/generated/models/store_connected_event.rb
+- lib/listo_delivery/generated/models/store_list.rb
+- lib/listo_delivery/generated/models/store_updated_event.rb
+- lib/listo_delivery/generated/models/update_store_request.rb
+- lib/listo_delivery/generated/models/webhook_delivery.rb
+- lib/listo_delivery/generated/models/webhook_delivery_list.rb
+- lib/listo_delivery/generated/models/webhook_event.rb
+- lib/listo_delivery/generated/models/webhook_event_envelope.rb
+- lib/listo_delivery/generated/models/withdrawal.rb
+- lib/listo_delivery/generated/models/withdrawal_list.rb
+- lib/listo_delivery/generated/models/withdrawal_updated_event.rb
+- lib/listo_delivery/generated/resources/balance.rb
+- lib/listo_delivery/generated/resources/card_onboarding.rb
+- lib/listo_delivery/generated/resources/connect_requests.rb
+- lib/listo_delivery/generated/resources/connections.rb
+- lib/listo_delivery/generated/resources/deliveries.rb
+- lib/listo_delivery/generated/resources/events.rb
+- lib/listo_delivery/generated/resources/ledger.rb
+- lib/listo_delivery/generated/resources/quotes.rb
+- lib/listo_delivery/generated/resources/request_logs.rb
+- lib/listo_delivery/generated/resources/stores.rb
+- lib/listo_delivery/generated/resources/webhooks.rb
+- lib/listo_delivery/generated/resources/withdrawals.rb
+- lib/listo_delivery/model.rb
+- lib/listo_delivery/util.rb
+- lib/listo_delivery/version.rb
+- lib/listo_delivery/webhooks.rb
+- listo_delivery.gemspec
+homepage: https://docs.listo.delivery
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.listo.delivery
+  documentation_uri: https://docs.listo.delivery/en/quickstart
+  changelog_uri: https://docs.listo.delivery/en/changelog
+  source_code_uri: https://github.com/listo-delivery/listo-ruby
+  bug_tracker_uri: https://github.com/listo-delivery/listo-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.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby client for the Listo Delivery API
+test_files: []