weft-sdk 0.24.0 → 0.32.2

data/lib/weft/client.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'error'
+require_relative 'generated'
+
+module Weft
+  # Buyer façade over the generated API client.
+  class Client
+    def initialize(api_key: nil, access_token: nil, base_url: 'https://weft.network')
+      if !api_key.nil? && !access_token.nil?
+        raise ArgumentError, 'api_key and access_token are mutually exclusive'
+      end
+
+      raw = api_key.nil? ? access_token : api_key
+      credential = raw.is_a?(String) ? raw.strip : ''
+      if credential.empty?
+        raise ArgumentError, credential_error(api_key, access_token)
+      end
+
+      configuration = Configuration.new
+      apply_base_url(configuration, base_url)
+      configuration.access_token = credential
+      @api_client = ApiClient.new(configuration)
+      @account = AccountApi.new(@api_client)
+      @balance = BalanceApi.new(@api_client)
+      @search = SearchApi.new(@api_client)
+      @fetch = FetchApi.new(@api_client)
+      @purchases = PurchasesApi.new(@api_client)
+    end
+
+    def me
+      call { @account.get_me }
+    end
+
+    def balance
+      call { @balance.get_balance }
+    end
+
+    def search(query:, max_results: nil, filters: nil)
+      request = SearchRequest.new(query: query)
+      if max_results.nil?
+        request.remove_instance_variable(:@max_results)
+      else
+        request.max_results = max_results
+      end
+      request.filters = search_filters(filters) unless filters.nil?
+      call { @search.search(request) }
+    end
+
+    def fetch(url:, max_cost_usd:, idempotency_key:, method: nil, body: nil, headers: nil,
+              search_id: nil, operation_id: nil, access_method_id: nil)
+      raise ArgumentError, 'max_cost_usd is required' if max_cost_usd.to_s.strip.empty?
+      raise ArgumentError, 'idempotency_key is required' if idempotency_key.to_s.strip.empty?
+      # Weft's limit. Checked here so a bad key never looks like a paid failure.
+      unless idempotency_key.to_s.match?(/\A[!-~]{1,255}\z/)
+        raise ArgumentError, 'idempotency_key must be 1-255 visible ASCII characters without spaces'
+      end
+
+      fields = {
+        url: url,
+        max_cost_usd: max_cost_usd,
+        method: method.nil? ? nil : method.to_s.upcase
+      }
+      fields[:body] = fetch_body(body) unless body.nil?
+      fields[:headers] = headers.transform_keys(&:to_s) unless headers.nil?
+      fields[:search_id] = search_id unless search_id.nil?
+      fields[:operation_id] = operation_id unless operation_id.nil?
+      fields[:access_method_id] = access_method_id unless access_method_id.nil?
+      request = FetchRequest.new(fields)
+      response = call(paid: true) { @fetch.fetch(request, idempotency_key: idempotency_key) }
+      # A 2xx without a fetch result body: the fetch most likely paid.
+      raise decode_error if response.nil?
+
+      response
+    end
+
+    def purchases(page: nil, per_page: nil)
+      call { @purchases.list_purchases(page: page, per_page: per_page) }
+    end
+
+    def purchase(id)
+      call { @purchases.get_purchase(id) }
+    end
+
+    private
+
+    def call(paid: false)
+      yield
+    rescue ApiError => e
+      raise normalize_api_error(e, paid: paid)
+    rescue StandardError => e
+      raise if !paid || e.is_a?(RequestError)
+
+      # Weft answered 2xx, so the fetch most likely paid, but the body did not decode.
+      raise decode_error
+    end
+
+    # A replay returns the same body; reconcile instead of retrying.
+    def decode_error
+      RequestError.new(
+        status: 0,
+        code: 'RESPONSE_DECODE_ERROR',
+        message: 'Weft API returned a fetch response that could not be decoded',
+        retryable: false,
+        charge: 'possible'
+      )
+    end
+
+    def credential_error(api_key, access_token)
+      return 'api_key is required' unless api_key.nil?
+      return 'access_token is required' unless access_token.nil?
+
+      'api_key or access_token is required'
+    end
+
+    def apply_base_url(configuration, base_url)
+      stripped = trim_trailing_slashes(base_url.to_s)
+      uri = URI.parse(stripped)
+      configuration.scheme = uri.scheme || 'https'
+      configuration.host = uri.host || trim_trailing_slashes(stripped)
+      path = collapse_slashes(uri.path.to_s)
+      path = trim_trailing_slashes(path)
+      path = strip_leading_slashes(path)
+      configuration.base_path = path
+    end
+
+    def trim_trailing_slashes(value)
+      text = value.dup
+      text.chomp!('/') while text.end_with?('/')
+      text
+    end
+
+    def strip_leading_slashes(value)
+      index = 0
+      index += 1 while index < value.length && value[index] == '/'
+      index.zero? ? value : value[index..]
+    end
+
+    def collapse_slashes(value)
+      out = +''
+      previous_slash = false
+      value.each_char do |char|
+        if char == '/'
+          out << '/' unless previous_slash
+          previous_slash = true
+        else
+          out << char
+          previous_slash = false
+        end
+      end
+      out
+    end
+
+    def search_filters(value)
+      mapped = map_filters(value)
+      spec = SearchFilterSpec.new(mapped)
+      spec.include_unknown_prices = nil unless mapped.key?(:include_unknown_prices)
+      spec
+    end
+
+    def map_filters(value)
+      table = {
+        'price' => :price,
+        'priceAtomic' => :price_atomic,
+        'type' => :type,
+        'protocol' => :protocol,
+        'category' => :category,
+        'method' => :method,
+        'executionMode' => :execution_mode,
+        'weftFetchCompatible' => :weft_fetch_compatible,
+        'includeUnknownPrices' => :include_unknown_prices
+      }
+      nested = %i[price price_atomic type protocol category method execution_mode]
+      operators = {
+        'lte' => :lte,
+        'gte' => :gte,
+        'eq' => :eq,
+        'in' => :in,
+        'rangeGte' => :range_gte,
+        'rangeLte' => :range_lte
+      }
+      mapped = map_keys(value, table)
+      nested.each do |name|
+        child = mapped[name]
+        next unless child.is_a?(Hash)
+
+        mapped[name] = map_keys(child, operators)
+      end
+      mapped
+    end
+
+    def map_keys(source, table)
+      source.each_with_object({}) do |(key, item), out|
+        mapped = table[key.to_s] || table[key.to_sym]
+        raise ArgumentError, "unmapped field #{key}" if mapped.nil?
+
+        out[mapped] = item
+      end
+    end
+
+    def fetch_body(value)
+      return value if value.is_a?(String)
+
+      JSON.generate(json_null_non_finite(value))
+    end
+
+    def json_null_non_finite(value)
+      case value
+      when Float
+        value.finite? ? value : nil
+      when Hash
+        value.each_with_object({}) { |(key, item), out| out[key] = json_null_non_finite(item) }
+      when Array
+        value.map { |item| json_null_non_finite(item) }
+      else
+        value
+      end
+    end
+
+    def normalize_api_error(error, paid:)
+      if error.code.to_i.zero? && !error.response_body
+        cause = error.instance_variable_get(:@message).to_s
+        cause = 'connection reset' if cause.empty?
+        return RequestError.new(
+          status: 0,
+          code: 'NETWORK_ERROR',
+          message: "Network failure before a Weft API response: #{cause}",
+          request_id: nil,
+          retryable: true,
+          details: nil,
+          charge: paid ? 'possible' : 'none'
+        )
+      end
+
+      details = parse_details(error.response_body)
+      body = details.is_a?(Hash) ? details : nil
+      nested = body && body['error'].is_a?(Hash) ? body['error'] : nil
+      status = error.code.to_i
+      code = nested&.[]('code') || body&.[]('code') || (body && body['error'].is_a?(String) ? body['error'] : "HTTP_#{status}")
+      RequestError.new(
+        status: status,
+        code: code,
+        message: nested&.[]('message') || body&.[]('message') || "Weft API returned HTTP #{status}",
+        request_id: nested&.[]('request_id') || body&.[]('request_id') || header_request_id(error),
+        retryable: status == 429 || status >= 500,
+        details: details,
+        charge: paid ? RequestError.fetch_charge(status, code) : 'none'
+      )
+    end
+
+    def parse_details(body)
+      return nil if body.nil? || body.empty?
+
+      parsed = JSON.parse(body)
+      parsed.is_a?(Hash) || parsed.is_a?(Array) ? parsed : nil
+    rescue JSON::ParserError
+      nil
+    end
+
+    def header_request_id(error)
+      headers = error.response_headers
+      return nil unless headers.respond_to?(:each)
+
+      pair = headers.find { |name, _| name.to_s.casecmp?('x-request-id') }
+      value = pair&.last
+      value.is_a?(Array) ? value.first : value
+    end
+  end
+end

data/lib/weft/error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Weft
+  # Normalized buyer API error.
+  #
+  # The generated OpenAPI model already owns Weft::Error. This exception uses
+  # RequestError so the model and the raised error can both exist.
+  #
+  # `charge` says whether the failed call can have created a charge. 'none'
+  # covers this call only: an earlier call under the same idempotency key can
+  # still have paid. After 'possible', retry only with the same idempotency key
+  # and request.
+  class RequestError < StandardError
+    # Codes Weft raises before it signs a payment in that call. Same list as the
+    # TypeScript reference.
+    PRE_SIGN_FETCH_CODES = %w[
+      EXCEEDED_MAX_COST MERCHANT_RETURNED_NON_402 INSUFFICIENT_BALANCE
+      DENYLISTED_RECIPIENT WALLET_ENVIRONMENT_MISMATCH UNSUPPORTED_ASSET
+      INVALID_REQUEST UNKNOWN_PARAMETER INVALID_URL INVALID_MAX_COST_USD
+      UNSUPPORTED_METHOD INVALID_BODY INVALID_HEADERS INVALID_IDEMPOTENCY_KEY
+    ].freeze
+
+    attr_reader :status, :code, :request_id, :retryable, :details, :charge
+
+    # @api private
+    def self.fetch_charge(status, code)
+      pre_sign = PRE_SIGN_FETCH_CODES.include?(code) || code.to_s.start_with?('POLICY_VIOLATION_')
+      status.between?(400, 499) && pre_sign ? 'none' : 'possible'
+    end
+
+    def initialize(status:, code:, message:, request_id: nil, retryable: false, details: nil, charge: 'possible')
+      super(message)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @retryable = retryable
+      @details = details
+      @charge = charge
+    end
+  end
+end

data/lib/weft/facilitator/client.rb

@@ -1,88 +1,225 @@
-require 'net/http'
+# frozen_string_literal: true
+
 require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'handshake'
+require_relative 'json_wire'
+require_relative 'settlement'
 
 module Weft
   module Facilitator
-    DEFAULT_URL = 'https://x402.weft.network'.freeze
-    DEFAULT_ENV = 'X402_FACILITATOR_URL'.freeze
+    DEFAULT_URL = 'https://x402.weft.network'
+    DEFAULT_ENV = 'X402_FACILITATOR_URL'
+    PATH_KEYS = %w[verify settle supported bazaar].freeze
+    SUPPORTED_RETRIES = 3
+    DEFAULT_TIMEOUT_MS = 30_000
+
+    module_function
+
+    def resolve_url(config = nil)
+      url = config_url(config)
+      return url unless url.nil? || url.empty?
+
+      env = ENV.fetch(DEFAULT_ENV, nil)
+      return env unless env.nil? || env.empty?
+
+      DEFAULT_URL
+    end
+
+    def validate_url(url)
+      if url.nil? || url.strip.empty?
+        raise ArgumentError, 'Invalid URL: URL cannot be empty'
+      end
+      return if url.start_with?('http://') || url.start_with?('https://')
+
+      raise ArgumentError,
+            "Invalid URL format: URL must start with http:// or https://, got: #{url}"
+    end
+
+    def config_url(config)
+      return nil unless config.is_a?(Hash)
+      return config['url'] if config.key?('url')
+      return config[:url] if config.key?(:url)
+
+      nil
+    end
+
+    def merge_seller_wins(derived, seller)
+      merged = derived.dup
+      (seller || {}).each do |name, value|
+        merged.delete_if { |existing, _| existing.to_s.casecmp?(name.to_s) }
+        merged[name.to_s] = value
+      end
+      merged
+    end
+
+    def assert_path_keyed_auth_headers(headers)
+      return unless headers.is_a?(Hash)
+
+      header_object = lambda do |value|
+        value.is_a?(Hash)
+      end
+      has_path_key = PATH_KEYS.any? { |key| header_object.call(headers[key] || headers[key.to_sym]) }
+      looks_flat = !has_path_key && headers.values.any? { |value| !header_object.call(value) }
+      return unless looks_flat
+
+      raise ArgumentError,
+            'createAuthHeaders must return an object keyed by facilitator path, ' \
+            'e.g. { verify: { Authorization: "..." }, settle: { ... }, ' \
+            'supported: { ... } }, but received a flat headers object.'
+    end
 
     class Client
-      def initialize(url: nil, create_headers: nil)
-        @url = resolve_url(url)
-        validate_url(@url)
+      def initialize(url: nil, create_headers: nil, timeout_ms: DEFAULT_TIMEOUT_MS)
+        resolved = Facilitator.resolve_url(url.nil? ? nil : { 'url' => url })
+        Facilitator.validate_url(resolved)
+        @url = trim_trailing_slashes(resolved)
         @create_headers = create_headers
+        @timeout_ms = timeout_ms
+      end
+
+      def trim_trailing_slashes(value)
+        text = value.dup
+        text.chomp!('/') while text.end_with?('/')
+        text
       end
 
       def verify(payment_payload:, payment_requirements:)
-        post_json('/verify', {
-                    x402Version: 2,
-                    paymentPayload: payment_payload,
-                    paymentRequirements: payment_requirements
+        post_json('/verify', 'verify', {
+                    'x402Version' => payment_payload['x402Version'] || payment_payload[:x402Version] || 2,
+                    'paymentPayload' => payment_payload,
+                    'paymentRequirements' => payment_requirements
                   })
       end
 
       def settle(payment_payload:, payment_requirements:)
-        post_json('/settle', {
-                    x402Version: 2,
-                    paymentPayload: payment_payload,
-                    paymentRequirements: payment_requirements
-                  })
+        settle_once(payment_payload, payment_requirements, allow_retry: true)
       end
 
       def supported
-        get_json('/supported')
+        last_error = nil
+        SUPPORTED_RETRIES.times do |attempt|
+          begin
+            return get_json('/supported', 'supported')
+          rescue RateLimited => e
+            last_error = e
+            sleep(e.retry_after) if attempt < SUPPORTED_RETRIES - 1
+          end
+        end
+        raise last_error || StandardError, 'Facilitator getSupported failed'
       end
 
       private
 
-      def resolve_url(url)
-        return url if url && !url.empty?
+      def settle_once(payment_payload, payment_requirements, allow_retry:)
+        result = post_json('/settle', 'settle', {
+                              'x402Version' => payment_payload['x402Version'] || payment_payload[:x402Version] || 2,
+                              'paymentPayload' => payment_payload,
+                              'paymentRequirements' => payment_requirements
+                            })
+        if allow_retry && pending_result?(result)
+          return settle_once(payment_payload, payment_requirements, allow_retry: false)
+        end
 
-        env = ENV.fetch(DEFAULT_ENV, nil)
-        return env if env && !env.empty?
+        result
+      rescue SettleError => e
+        if allow_retry && pending_error?(e)
+          return settle_once(payment_payload, payment_requirements, allow_retry: false)
+        end
+        raise FacilitatorUnavailableError if SettleErrors.unavailable?(e)
 
-        DEFAULT_URL
+        raise
       end
 
-      def validate_url(url)
-        return unless url.empty? || (!url.start_with?('http://') && !url.start_with?('https://'))
+      def pending_result?(result)
+        result.is_a?(Hash) && result['success'] == false &&
+          result['errorReason'] == 'settlement_pending' && !result['transaction'].to_s.empty?
+      end
 
-        raise ArgumentError, "Invalid URL: #{url}"
+      def pending_error?(error)
+        error.error_reason == 'settlement_pending' && !error.transaction.to_s.empty?
       end
 
-      def build_headers(scope)
+      def headers_for(scope)
         headers = { 'Content-Type' => 'application/json' }
         return headers unless @create_headers
 
         custom = @create_headers.call
-        scope_headers = custom && custom[scope]
+        Facilitator.assert_path_keyed_auth_headers(custom) if custom
+        scope_headers = custom.is_a?(Hash) ? (custom[scope] || custom[scope.to_sym]) : nil
         headers.merge(scope_headers || {})
       end
 
-      def get_json(path)
-        uri = URI.join(@url, path)
-        request = Net::HTTP::Get.new(uri, build_headers('supported'))
-        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+      def get_json(path, scope)
+        uri = URI.parse("#{@url}#{path}")
+        request = Net::HTTP::Get.new(uri)
+        headers_for(scope).each { |name, value| request[name] = value }
+        response = perform(uri, request)
+        parse_response(response, scope)
+      end
+
+      def post_json(path, scope, body)
+        uri = URI.parse("#{@url}#{path}")
+        request = Net::HTTP::Post.new(uri)
+        headers_for(scope).each { |name, value| request[name] = value }
+        request.body = JsonWire.generate(body)
+        response = perform(uri, request)
+        parse_response(response, scope)
+      end
+
+      def perform(uri, request)
+        Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == 'https',
+          open_timeout: @timeout_ms / 1000.0,
+          read_timeout: @timeout_ms / 1000.0
+        ) do |http|
           http.request(request)
         end
-        parse_response(response)
       end
 
-      def post_json(path, body)
-        uri = URI.join(@url, path)
-        scope = path.include?('verify') ? 'verify' : 'settle'
-        request = Net::HTTP::Post.new(uri, build_headers(scope))
-        request.body = JSON.generate(body)
-        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
-          http.request(request)
+      def parse_response(response, scope)
+        return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
+
+        text = response.body.to_s
+        data = begin
+          JSON.parse(text)
+        rescue JSON::ParserError
+          nil
         end
-        parse_response(response)
+        if scope == 'settle' && data.is_a?(Hash) && data.key?('success')
+          raise SettleError.new(response.code.to_i, data)
+        end
+        if scope == 'verify' && data.is_a?(Hash) && data.key?('isValid')
+          raise StandardError, verify_failure_message(response.code, data)
+        end
+        raise RateLimited.new(response['retry-after']) if response.code.to_i == 429
+
+        excerpt = text.length > 200 ? "#{text[0, 200]}..." : text
+        raise StandardError, "Facilitator #{scope_name(scope)} failed (#{response.code}): #{excerpt}"
       end
 
-      def parse_response(response)
-        raise "Facilitator request failed: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+      def scope_name(scope)
+        scope == 'supported' ? 'getSupported' : scope
+      end
+
+      def verify_failure_message(code, data)
+        reason = data['invalidReason'] || 'unknown reason'
+        message = data['invalidMessage']
+        message ? "#{reason}: #{message}" : reason.to_s
+      end
+    end
+
+    class RateLimited < StandardError
+      attr_reader :retry_after
 
-        JSON.parse(response.body)
+      def initialize(header)
+        @retry_after = header.to_i
+        @retry_after = 1 if @retry_after <= 0
+        super('Facilitator getSupported failed (429)')
       end
     end
   end

data/lib/weft/facilitator/echo.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Weft
+  module Facilitator
+    module Echo
+      ADDITIVE_ARRAY_INFO_FIELDS = { 'builder-code' => ['s'] }.freeze
+      ADDITIVE_ARRAY_MAX_LENGTHS = { 'builder-code' => { 's' => 10 } }.freeze
+
+      module_function
+
+      def validate(payment_required, payment, dynamic_fields: {})
+        return { 'valid' => true } unless payment.is_a?(Hash) && payment['x402Version'] == 2
+
+        server_extensions = payment_required['extensions']
+        return { 'valid' => true } unless server_extensions.is_a?(Hash) && !server_extensions.empty?
+
+        client_extensions = payment['extensions']
+        return { 'valid' => true } unless client_extensions.is_a?(Hash) && !client_extensions.empty?
+
+        client_extensions.each do |key, echoed|
+          next unless server_extensions.key?(key)
+
+          fields = dynamic_fields[key]
+          advertised = omit_fields(extension_info(server_extensions[key]), fields)
+          echoed_info = omit_fields(extension_info(echoed), fields)
+          additive = ADDITIVE_ARRAY_INFO_FIELDS[key]
+          limits = ADDITIVE_ARRAY_MAX_LENGTHS[key]
+          next if contains_subset?(advertised, echoed_info, additive, limits)
+
+          return { 'valid' => false, 'invalidReason' => 'extension_echo_mismatch', 'extensionKey' => key }
+        end
+        { 'valid' => true }
+      end
+
+      def extension_info(value)
+        return value['info'] if value.is_a?(Hash) && value.key?('info')
+
+        value
+      end
+
+      def omit_fields(value, fields)
+        return value if fields.nil? || fields.empty? || !value.is_a?(Hash)
+
+        copy = value.dup
+        fields.each { |field| copy.delete(field) }
+        copy
+      end
+
+      def contains_subset?(expected, actual, additive = nil, max_lengths = nil, field_key = nil)
+        if field_key && additive&.include?(field_key) && (expected.is_a?(Array) || actual.is_a?(Array))
+          expected_array = comparable_array(expected)
+          actual_array = comparable_array(actual)
+          return false unless expected_array && actual_array
+
+          max = max_lengths && max_lengths[field_key]
+          return false if max && actual_array.length > max
+
+          return expected_array.all? { |item| actual_array.any? { |other| deep_equal?(item, other) } }
+        end
+        return deep_equal?(expected, actual) if expected.nil? || !expected.is_a?(Hash)
+        return false unless actual.is_a?(Hash)
+
+        expected.all? do |key, value|
+          if actual.key?(key)
+            contains_subset?(value, actual[key], additive, max_lengths, key)
+          else
+            value.nil?
+          end
+        end
+      end
+
+      def comparable_array(value)
+        return value if value.is_a?(Array)
+        return nil if value.nil? || value.is_a?(Hash)
+
+        [value]
+      end
+
+      def deep_equal?(left, right)
+        return true if left.nil? && right.nil?
+        return false if left.nil? || right.nil?
+
+        case left
+        when Hash
+          return false unless right.is_a?(Hash)
+          return false unless left.keys.map(&:to_s).sort == right.keys.map(&:to_s).sort
+
+          left.all? { |key, value| deep_equal?(value, right[key] || right[key.to_s]) }
+        when Array
+          return false unless right.is_a?(Array) && left.length == right.length
+
+          left.zip(right).all? { |item, other| deep_equal?(item, other) }
+        else
+          left == right
+        end
+      end
+    end
+  end
+end