Class: X402::DiscoveryExtension

Inherits:
Object
  • Object
show all
Defined in:
lib/x402/discovery_extension.rb

Overview

Builds the x402 Bazaar discovery extension for a route, matching the wire shape of the official @x402/extensions declareDiscoveryExtension helper.

Facilitators index a resource only when the paying client echoes this extension back in its PaymentPayload and info validates against schema. A mismatch is skipped silently, so example inputs must satisfy the declared input schema.

X402::DiscoveryExtension.declare(
body_type: "json",
input: { "city" => "San Francisco" },
input_schema: {
  "type" => "object",
  "properties" => { "city" => { "type" => "string" } },
  "required" => ["city"],
},
output: { example: { "weather" => "foggy" } },
)

body_type selects the body form (POST/PUT/PATCH); without it the query form (GET/HEAD/DELETE) is used and input describes query params. The actual request method is stamped at render time via with_method.

Constant Summary collapse

JSON_SCHEMA_DIALECT = 
"https://json-schema.org/draft/2020-12/schema"
QUERY_METHODS = 
%w[GET HEAD DELETE].freeze
BODY_METHODS = 
%w[POST PUT PATCH].freeze
BODY_TYPES = 
%w[json form-data text].freeze

Class Method Summary collapse

Class Method Details

.declare(method: nil, body_type: nil, input: {}, input_schema: { "properties" => {} }, output: nil) ⇒ Object 



35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/x402/discovery_extension.rb', line 35

def declare(method: nil, body_type: nil, input: {}, input_schema: { "properties" => {} },
            output: nil)
  info, schema =
    if body_type
      body_form(method: method, body_type: body_type, input: input, input_schema: input_schema)
    else
      query_form(method: method, input: input, input_schema: input_schema)
    end

  attach_output(info, schema, output)
  { "bazaar" => { "info" => info, "schema" => schema } }
end

.with_method(extension, http_method) ⇒ Object

Stamps the actual HTTP method into the declaration at request time, overwriting any declared method — mirroring the reference server extension's enrichment, which always reports the live request verb.



51
52
53
54
55
56
57
58
59
60
 
# File 'lib/x402/discovery_extension.rb', line 51

def with_method(extension, http_method)
  input = extension.dig("bazaar", "info", "input")
  return extension if input.nil?

  extension.deep_dup.tap do |enriched|
    enriched["bazaar"]["info"]["input"]["method"] = http_method
    method_schema = enriched.dig("bazaar", "schema", "properties", "input", "properties")
    method_schema["method"] = { "type" => "string", "enum" => [http_method] } if method_schema
  end
end