fragment-dev 2.0.0 → 2.1.0

data/lib/fragment_client/typed_ledger_entry.rb

@@ -0,0 +1,281 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+class FragmentClient
+  # Base class for a typed `addLedgerEntries` payload. Abstract: one subclass per
+  # `(entry type, typeVersion)` is built by {FragmentClient::TypedEntries.load}.
+  #
+  # A subclass declares one keyword argument and one reader per Schema parameter,
+  # alongside the common `LedgerEntryInput` fields, and {#to_entry_input} reshapes
+  # them into the nested `AddLedgerEntryInput` the API takes.
+  #
+  #     entry = FragmentClient::Entries::AuthCaptureV1.new(
+  #       ik: 'ik-1', ledger_ik: 'prod', capture_amount: '100'
+  #     )
+  #     client.add_ledger_entries(entries: [entry])
+  #
+  # Section references are to `typed-batch-entries.md`; see
+  # `docs/spec-conformance.md`.
+  class TypedLedgerEntry
+    extend T::Sig
+    extend T::Helpers
+    abstract!
+
+    # The `LedgerEntryInput` fields every payload carries, whatever its entry type
+    # (spec 2.3a). Fixed by `LedgerEntryInput`, not derived from the operation,
+    # which binds only what its CLI version chose to expose.
+    #
+    # `lines` is absent deliberately: it cannot be combined with an entry that has
+    # a `type`. `type`, `typeVersion` and `parameters` are derived, never supplied.
+    COMMON_FIELDS = T.let(
+      %i[ik ledger_ik posted description tags groups conditions].freeze,
+      T::Array[Symbol]
+    )
+
+    class << self
+      extend T::Sig
+
+      # Build a payload class for one derived spec.
+      sig do
+        params(spec: FragmentClient::TypedEntries::EntrySpec, origin: T.nilable(String))
+          .returns(T.class_of(TypedLedgerEntry))
+      end
+      def build(spec, origin: nil)
+        klass = Class.new(self)
+        klass.instance_variable_set(:@spec, spec)
+        klass.instance_variable_set(:@source_path, origin)
+
+        spec.parameters.each do |parameter|
+          name = parameter.name
+          klass.send(:define_method, name) do
+            T.bind(self, TypedLedgerEntry)
+            parameter_value(name)
+          end
+        end
+
+        klass
+      end
+
+      # What this payload was derived from.
+      sig { returns(FragmentClient::TypedEntries::EntrySpec) }
+      def spec
+        @spec = T.let(@spec, T.nilable(FragmentClient::TypedEntries::EntrySpec))
+        @spec || raise(
+          NotImplementedError,
+          "#{self} has no derived spec. Typed payload classes are built by " \
+          'FragmentClient::TypedEntries.load, not subclassed by hand.'
+        )
+      end
+
+      sig { returns(String) }
+      def entry_type
+        spec.entry_type
+      end
+
+      sig { returns(Integer) }
+      def type_version
+        spec.type_version
+      end
+
+      # The Schema parameters, in source order (spec 2.4).
+      sig { returns(T::Array[FragmentClient::TypedEntries::Parameter]) }
+      def parameters
+        spec.parameters
+      end
+
+      # The `.graphql` file this came from, if it came from one.
+      sig { returns(T.nilable(String)) }
+      def source_path
+        @source_path = T.let(@source_path, T.nilable(String))
+      end
+    end
+
+    sig { returns(String) }
+    attr_reader :ik
+
+    sig { returns(String) }
+    attr_reader :ledger_ik
+
+    # The optional common fields: `nil` when unset, so `&.` and truthiness behave
+    # as usual. {#set?} is what separates "not set" from "set to nil".
+    sig { returns(T.nilable(String)) }
+    attr_reader :posted
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :description
+
+    sig { returns(T.nilable(T::Array[T.untyped])) }
+    attr_reader :tags
+
+    sig { returns(T.nilable(T::Array[T.untyped])) }
+    attr_reader :groups
+
+    sig { returns(T.nilable(T::Array[T.untyped])) }
+    attr_reader :conditions
+
+    # Optional fields default to the {FragmentClient::TypedEntries::UNSET} sentinel
+    # rather than `nil`, so an omitted keyword can be told from an explicit `nil`
+    # and left out of the payload (spec 3.2). It is converted to `nil` here and
+    # never returned.
+    #
+    # Schema parameters arrive through `**parameters` under the names this class
+    # declares. Presence and unknown names are checked here; their types come from
+    # the RBI `tapioca dsl` generates.
+    sig do
+      params(
+        ik: String,
+        ledger_ik: String,
+        posted: T.any(String, NilClass, FragmentClient::TypedEntries::Unset),
+        description: T.any(String, NilClass, FragmentClient::TypedEntries::Unset),
+        tags: T.any(T::Array[T.untyped], NilClass, FragmentClient::TypedEntries::Unset),
+        groups: T.any(T::Array[T.untyped], NilClass, FragmentClient::TypedEntries::Unset),
+        conditions: T.any(T::Array[T.untyped], NilClass, FragmentClient::TypedEntries::Unset),
+        parameters: T.untyped
+      ).void
+    end
+    # rubocop:disable Metrics/AbcSize -- one assignment per common field; `typed:
+    # strict` rules out setting them in a loop.
+    def initialize(ik:, ledger_ik:,
+                   posted: FragmentClient::TypedEntries::UNSET,
+                   description: FragmentClient::TypedEntries::UNSET,
+                   tags: FragmentClient::TypedEntries::UNSET,
+                   groups: FragmentClient::TypedEntries::UNSET,
+                   conditions: FragmentClient::TypedEntries::UNSET,
+                   **parameters)
+      @ik = ik
+      @ledger_ik = ledger_ik
+      @parameters = T.let(validate(parameters), T::Hash[Symbol, T.untyped])
+      @provided = T.let(Set.new(@parameters.keys + %i[ik ledger_ik]), T::Set[Symbol])
+      @posted = T.let(record(:posted, posted), T.nilable(String))
+      @description = T.let(record(:description, description), T.nilable(String))
+      @tags = T.let(record(:tags, tags), T.nilable(T::Array[T.untyped]))
+      @groups = T.let(record(:groups, groups), T.nilable(T::Array[T.untyped]))
+      @conditions = T.let(record(:conditions, conditions), T.nilable(T::Array[T.untyped]))
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Whether the caller set `name` -- a common field or a parameter. The readers
+    # report an omitted field and an explicit `nil` alike, so this is the only way
+    # to tell them apart.
+    sig { params(name: Symbol).returns(T::Boolean) }
+    def set?(name)
+      @provided.include?(name)
+    end
+
+    # Same class, same wire payload -- which includes agreeing on what is set.
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other)
+      other.instance_of?(self.class) && other.to_entry_input == to_entry_input
+    end
+
+    alias eql? ==
+
+    sig { returns(Integer) }
+    def hash
+      [self.class, to_entry_input].hash
+    end
+
+    # The `AddLedgerEntryInput` this payload posts (spec 3.1). Keys lexicographic
+    # at every level except `parameters`, which keeps source order (spec 3.4).
+    sig { returns(T::Hash[String, T.untyped]) }
+    def to_entry_input
+      { 'entry' => entry_input, 'ik' => @ik }
+    end
+
+    alias to_h to_entry_input
+
+    # The `parameters` payload, keyed by verbatim Schema parameter name -- so an
+    # escaped parameter still travels under its own key (spec 2.5, 3.3).
+    sig { returns(T::Hash[String, T.untyped]) }
+    def entry_parameters
+      self.class.parameters.each_with_object({}) do |parameter, out|
+        out[parameter.wire_name] = @parameters[parameter.name] if @parameters.key?(parameter.name)
+      end
+    end
+
+    sig { returns(String) }
+    def inspect
+      shown = COMMON_FIELDS.select { |name| set?(name) }
+                           .map { |name| "#{name}: #{public_send(name).inspect}" }
+      shown.concat(@parameters.map { |name, value| "#{name}: #{value.inspect}" })
+      "#<#{self.class} #{shown.join(', ')}>"
+    end
+
+    private
+
+    # Records that `name` was supplied, and unwraps the sentinel to `nil`.
+    sig { params(name: Symbol, value: T.untyped).returns(T.untyped) }
+    def record(name, value)
+      return nil if value.is_a?(FragmentClient::TypedEntries::Unset)
+
+      @provided << name
+      value
+    end
+
+    sig { params(name: Symbol).returns(T.untyped) }
+    def parameter_value(name)
+      @parameters[name]
+    end
+
+    sig { returns(T::Hash[String, T.untyped]) }
+    def entry_input
+      input = T.let({}, T::Hash[String, T.untyped])
+      input['conditions'] = @conditions if set?(:conditions)
+      input['description'] = @description if set?(:description)
+      input['groups'] = @groups if set?(:groups)
+      input['ledger'] = { 'ik' => @ledger_ik }
+      # Always present: derived rather than supplied, so it has no unset state.
+      input['parameters'] = entry_parameters
+      input['posted'] = @posted if set?(:posted)
+      input['tags'] = @tags if set?(:tags)
+      input['type'] = self.class.entry_type
+      input['typeVersion'] = self.class.type_version
+      input
+    end
+
+    sig { params(supplied: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+    def validate(supplied)
+      reject_unknown(supplied)
+      require_declared(supplied)
+      supplied
+    end
+
+    sig { params(supplied: T::Hash[Symbol, T.untyped]).void }
+    def reject_unknown(supplied)
+      known = self.class.parameters.map(&:name)
+      unknown = supplied.keys - known
+      return if unknown.empty?
+
+      raise ArgumentError,
+            "unknown keyword#{plural(unknown)}: #{list(unknown)} for #{describe}. " \
+            "Declared parameters: #{known.empty? ? '(none)' : list(known)}."
+    end
+
+    sig { params(supplied: T::Hash[Symbol, T.untyped]).void }
+    def require_declared(supplied)
+      missing = self.class.parameters
+                    .select { |parameter| parameter.required && !supplied.key?(parameter.name) }
+                    .map(&:name)
+      return if missing.empty?
+
+      raise ArgumentError, "missing keyword#{plural(missing)}: #{list(missing)} for #{describe}."
+    end
+
+    sig { returns(String) }
+    def describe
+      "#{self.class.entry_type.inspect} v#{self.class.type_version}"
+    end
+
+    sig { params(names: T::Array[Symbol]).returns(String) }
+    def plural(names)
+      names.length == 1 ? '' : 's'
+    end
+
+    sig { params(names: T::Array[Symbol]).returns(String) }
+    def list(names)
+      names.map(&:inspect).join(', ')
+    end
+  end
+end

data/lib/fragment_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FragmentSDK
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/lib/fragment_client.rb

@@ -1,15 +1,19 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
 require 'json'
 require 'graphql/client'
 require 'graphql/client/http'
+require 'logger'
 require 'sorbet-runtime'
 require 'uri'
 require 'net/http'
 require 'fragment_client/version'
+require 'fragment_client/typed_entries'
 module GraphQL
   module StaticValidation
+    # Accepts an inline object literal for the JSON-shaped scalars, which
+    # graphql-ruby otherwise rejects -- and which every `parameters: {...}` is.
     class LiteralValidator
       alias recursive_validate_old recursively_validate
       def recursively_validate(ast_value, type)
@@ -48,6 +52,7 @@ module FragmentGraphQl
 
   # Create a custom client class for Fragment-specific behavior
   class CustomClient < GraphQL::Client
+    # Keeps a memory address out of the operation name sent to the API.
     class Definition < GraphQL::Client::Definition
       def definition_name
         super.gsub(/#<Module.*>/, 'FragmentGraphQl__Dynamic')
@@ -69,6 +74,71 @@ module FragmentGraphQl
   end
 
   FragmentQueries = T.let(parse_queries("#{__dir__}/queries.graphql"), T.untyped)
+
+  # Look up one parsed operation by name.
+  #
+  # `FragmentQueries::AddLedgerEntries` reads better but does not resolve: the
+  # constants are created by `GraphQL::Client.parse` at runtime.
+  sig { params(name: Symbol).returns(T.untyped) }
+  def self.operation(name)
+    FragmentQueries.const_get(name)
+  end
+
+  # The instance method `FragmentClient` defines for an operation:
+  # `ListLedgerAccounts` -> `list_ledger_accounts`.
+  sig { params(operation_name: String).returns(String) }
+  def self.method_name_for(operation_name)
+    operation_name.gsub(/[a-z]([A-Z])/) do |m|
+      format('%<lower>s_%<upper>s', lower: m[0], upper: T.must(m[1]).downcase)
+    end.gsub(/^[A-Z]/, &:downcase)
+  end
+
+  # Method names for every operation parsed so far, in the order first seen.
+  #
+  # Read by the Tapioca compiler, which cannot otherwise see methods that
+  # `define_method_from_queries` creates per instance.
+  sig { returns(T::Array[String]) }
+  def self.operation_method_names
+    @operation_method_names ||= T.let([], T.nilable(T::Array[String]))
+  end
+
+  sig { params(queries: T.untyped).void }
+  def self.record_operations(queries)
+    queries.constants.each do |constant|
+      name = method_name_for(constant.to_s)
+      operation_method_names << name unless operation_method_names.include?(name)
+    end
+  end
+
+  # Operation ASTs by operation name, for the compilers that need a selection set
+  # rather than just a method name.
+  sig { returns(T::Hash[String, GraphQL::Language::Nodes::OperationDefinition]) }
+  def self.operations
+    @operations ||= T.let({}, T.nilable(T::Hash[String,
+                                                GraphQL::Language::Nodes::OperationDefinition]))
+  end
+
+  sig { params(source: String).void }
+  def self.record_document(source)
+    GraphQL.parse(source).definitions.each do |definition|
+      next unless definition.is_a?(GraphQL::Language::Nodes::OperationDefinition)
+
+      name = definition.name
+      operations[name] ||= definition if name
+    end
+  end
+
+  # Forget operations recorded from anything but `queries.graphql`. For tests.
+  sig { void }
+  def self.reset_operations!
+    operation_method_names.clear
+    operations.clear
+    record_operations(FragmentQueries)
+    record_document(File.read("#{__dir__}/queries.graphql"))
+  end
+
+  record_operations(FragmentQueries)
+  record_document(File.read("#{__dir__}/queries.graphql"))
 end
 
 # A client for Fragment
@@ -81,15 +151,19 @@ class FragmentClient
 
   extend T::Sig
 
+  DEFAULT_OAUTH_URL = 'https://auth.fragment.dev/oauth2/token'
+  DEFAULT_OAUTH_SCOPE = 'https://api.fragment.dev/*'
+
   sig do
     params(client_id: String, client_secret: String, extra_queries_filenames: T.nilable(T::Array[String]),
            api_url: T.nilable(String), oauth_url: T.nilable(String), oauth_scope: T.nilable(String)).void
   end
 
   def initialize(client_id, client_secret, extra_queries_filenames: nil, api_url: nil,
-                 oauth_url: 'https://auth.fragment.dev/oauth2/token', oauth_scope: 'https://api.fragment.dev/*')
-    @oauth_scope = T.let(oauth_scope, String)
-    @oauth_url = T.let(URI.parse(oauth_url), URI)
+                 oauth_url: DEFAULT_OAUTH_URL, oauth_scope: DEFAULT_OAUTH_SCOPE)
+    # Both are nilable, so nil means the default rather than an assertion failure.
+    @oauth_scope = T.let(oauth_scope || DEFAULT_OAUTH_SCOPE, String)
+    @oauth_url = T.let(parse_oauth_url(oauth_url || DEFAULT_OAUTH_URL), URI::HTTP)
     @client_id = T.let(client_id, String)
     @client_secret = T.let(client_secret, String)
 
@@ -108,10 +182,63 @@ class FragmentClient
     define_method_from_queries(FragmentGraphQl::FragmentQueries)
     return if extra_queries_filenames.nil?
 
-    extra_queries_filenames.each do |filename|
-      queries = T.let(FragmentGraphQl.parse_queries(filename), T.untyped)
-      define_method_from_queries(queries)
+    extra_queries_filenames.each { |filename| define_method_from_queries(self.class.load_queries(filename)) }
+  end
+
+  # Parse a `.graphql` document and register what can be derived from it: the
+  # operation names {FragmentClient} will answer to, and a typed payload class per
+  # Ledger Entry type it declares.
+  #
+  # Needs neither credentials nor network, so `bundle exec tapioca dsl` can see
+  # both if this runs in an initializer. {#initialize} calls it for every
+  # `extra_queries_filenames` entry, so passing the files is usually enough.
+  sig { params(paths: String).returns(T.untyped) }
+  def self.load_queries(*paths)
+    queries = paths.map do |path|
+      source = File.read(path)
+      parsed = T.let(FragmentGraphQl.parse_queries(path), T.untyped)
+      FragmentGraphQl.record_operations(parsed)
+      FragmentGraphQl.record_document(source)
+      TypedEntries.load(path)
+      parsed
     end
+    queries.length == 1 ? queries.first : queries
+  end
+
+  # Operations with a hand-written wrapper below, which the dynamic definer must
+  # not shadow -- a singleton method beats an instance method. Listed explicitly
+  # rather than tested with `method_defined?`, which would also match `clone`,
+  # `freeze` and everything else on Object.
+  WRAPPED_OPERATIONS = T.let(%w[add_ledger_entries].freeze, T::Array[String])
+
+  # Commit a batch of Ledger Entries atomically: every entry commits or none do,
+  # so there is no partial-batch state to reconcile.
+  #
+  #
+  # `entries` may mix typed payloads from {FragmentClient::TypedEntries} with raw
+  # `AddLedgerEntryInput` hashes, in any order; the API returns results in the
+  # order sent (spec 3.5). Idempotency keys are per entry, so `isIkReplay` is
+  # reported per result.
+  #
+  # The response is a union. Narrow on `__typename` before reading `results`, and
+  # read `errors` on `AddLedgerEntriesError` for the per-entry failures, each
+  # carrying the `ik` of the entry that failed (spec 4).
+  # Takes the operation's variables, like every other operation method, so
+  # `add_ledger_entries(entries: [...])` and `add_ledger_entries({ entries: [...] })`
+  # both work. Typed payloads in `entries` are converted; anything else passes
+  # through.
+  #
+  # The return type stays untyped here, unlike the generated methods: a signature in
+  # shipped source cannot name `FragmentClient::Responses::AddLedgerEntries`, which
+  # does not exist until a consumer runs `tapioca dsl`.
+  sig { params(variables: T::Hash[T.untyped, T.untyped]).returns(T.untyped) }
+  def add_ledger_entries(variables)
+    query(
+      FragmentGraphQl.operation(:AddLedgerEntries),
+      variables.to_h do |name, value|
+        [name, name.to_s == 'entries' ? TypedEntries.to_entry_inputs(value) : value]
+      end
+    )
   end
 
   # Move these error class definitions up, before the query method
@@ -130,9 +257,10 @@ class FragmentClient
 
   def define_method_from_queries(queries)
     queries.constants.each do |qry|
-      name = qry.to_s.gsub(/[a-z]([A-Z])/) do |m|
-        format('%<lower>s_%<upper>s', lower: m[0], upper: m[1].downcase)
-      end.gsub(/^[A-Z]/, &:downcase)
+      name = FragmentGraphQl.method_name_for(qry.to_s)
+
+      # Leave the hand-written wrapper in place; see WRAPPED_OPERATIONS.
+      next if WRAPPED_OPERATIONS.include?(name)
 
       # Get the original query
       original_query = queries.const_get(qry)
@@ -149,6 +277,7 @@ class FragmentClient
 
           # Define the new method that uses the stored original method
           definition_node.singleton_class.send(:define_method, :name) do
+            T.bind(self, T.untyped)
             original_name.gsub(/#<Module.*?>/, 'FragmentGraphQl__Dynamic__Custom')
           end
         end
@@ -161,17 +290,40 @@ class FragmentClient
     end
   end
 
-  sig { returns(Token) }
-  def create_token
-    uri = URI.parse(@oauth_url.to_s)
-    post = Net::HTTP::Post.new(uri.request_uri)
+  # Reject an unusable `oauth_url` here rather than in {create_token}, which fails
+  # on `request_uri` for a non-HTTP URL and says nothing about the argument.
+  sig { params(oauth_url: String).returns(URI::HTTP) }
+  def parse_oauth_url(oauth_url)
+    parsed = begin
+      URI.parse(oauth_url)
+    rescue URI::InvalidURIError => e
+      raise ArgumentError, "oauth_url is not a valid URL (#{e.message}), got #{oauth_url.inspect}"
+    end
+    # URI::HTTPS subclasses URI::HTTP, so this accepts both.
+    return parsed if parsed.is_a?(URI::HTTP)
+
+    raise ArgumentError, "oauth_url must be an http or https URL, got #{oauth_url.inspect}"
+  end
+
+  # RFC 6749 §4.4.2 and §2.3.1: client_credentials over
+  # application/x-www-form-urlencoded, with the client id and secret as HTTP Basic.
+  sig { returns(Net::HTTP::Post) }
+  def token_request
+    post = Net::HTTP::Post.new(@oauth_url.request_uri)
     post.basic_auth(@client_id, @client_secret)
-    post.content_type = "application/x-www-form-urlencoded"
+    post.content_type = 'application/x-www-form-urlencoded'
     post.body = URI.encode_www_form(
       grant_type: 'client_credentials',
       scope: @oauth_scope,
       client_id: @client_id
     )
+    post
+  end
+
+  sig { returns(Token) }
+  def create_token
+    uri = @oauth_url
+    post = token_request
 
     begin
       http = Net::HTTP.new(uri.host, uri.port)
@@ -197,6 +349,7 @@ class FragmentClient
     end
   end
 
+  # Process-wide settings, set with {FragmentClient.configure}.
   class Configuration
     extend T::Sig
 
@@ -223,7 +376,7 @@ class FragmentClient
 
     sig { params(blk: T.proc.params(config: Configuration).void).void }
     def configure(&blk)
-      yield(configuration)
+      blk.call(configuration)
     end
   end
 

data/lib/queries.graphql

@@ -94,6 +94,52 @@ mutation DeleteLedger($ledger: LedgerMatchInput!) {
   }
 }
 
+mutation AddLedgerEntries($entries: [AddLedgerEntryInput!]!) {
+  addLedgerEntries(entries: $entries) {
+    __typename
+    ... on AddLedgerEntriesResult {
+      results {
+        isIkReplay
+        entry {
+          type
+          id
+          ik
+          posted
+          created
+        }
+        lines {
+          id
+          amount
+          account {
+            path
+          }
+        }
+      }
+    }
+    ... on AddLedgerEntriesError {
+      code
+      message
+      retryable
+      errors {
+        ik
+        code
+        message
+        retryable
+      }
+    }
+    ... on BadRequestError {
+      code
+      message
+      retryable
+    }
+    ... on InternalError {
+      code
+      message
+      retryable
+    }
+  }
+}
+
 mutation AddLedgerEntry(
   $ik: SafeString!
   $ledgerIk: SafeString!

data/lib/tapioca/dsl/compilers/fragment_query_methods.rb

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+return unless defined?(Tapioca::Dsl::Compilers)
+
+require 'fragment_client'
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Declares the query and mutation methods {FragmentClient} answers to.
+      #
+      # `define_method_from_queries` creates one singleton method per operation on
+      # each client instance, so without this Sorbet reports `Method
+      # 'create_ledger' does not exist` for every one of them and a consumer has to
+      # write `T.unsafe(client)`.
+      #
+      # Covers the operations shipped in `queries.graphql`, plus any document
+      # passed to `FragmentClient.load_queries`. Operations in
+      # {FragmentClient::WRAPPED_OPERATIONS} are skipped: those have hand-written
+      # methods with real signatures already.
+      #
+      # `variables` is the operation's variables hash and stays untyped. Its keys
+      # are the GraphQL variable names verbatim, as the rest of this SDK passes
+      # them. The return type comes from `FragmentResponseTypes`.
+      class FragmentQueryMethods < Compiler
+        extend T::Sig
+
+        ConstantType = type_member { { fixed: T.class_of(FragmentClient) } }
+
+        class << self
+          extend T::Sig
+
+          sig { override.returns(T::Enumerable[Module]) }
+          def gather_constants
+            [FragmentClient]
+          end
+        end
+
+        sig { override.void }
+        def decorate
+          methods = FragmentGraphQl.operations.keys.to_h do |operation|
+            [FragmentGraphQl.method_name_for(operation), operation]
+          end
+          methods.reject! { |name, _| FragmentClient::WRAPPED_OPERATIONS.include?(name) }
+          return if methods.empty?
+
+          root.create_path(constant) do |klass|
+            methods.keys.sort.each do |name|
+              klass.create_method(
+                name,
+                parameters: [create_param('variables', type: 'T::Hash[Symbol, T.untyped]')],
+                return_type: "::FragmentClient::Responses::#{methods.fetch(name)}"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end