intacct-rest 1.0.0

data/lib/intacct_rest/model/invoice_line.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # An AR invoice line's data and validations only — no config, no token
+    # provider, no HTTP. Build and inspect one freely; IntacctRest::Post
+    # (via IntacctRest::Endpoints::CreateInvoiceLine) is what actually
+    # sends it.
+    #
+    # This is a standalone-creatable object (POST
+    # /objects/accounts-receivable/invoice-line) distinct from the raw
+    # line-item Hashes accepted by Model::Invoice#lines — Intacct allows
+    # both: send lines inline with the invoice, or create them separately
+    # against an existing invoice via `invoice: { "key" => "..." }`.
+    #
+    # Nested objects (glAccount, dimensions, allocation, ...) are NOT
+    # individually modeled — pass them as raw Hashes using Intacct's
+    # native (camelCase) nested key names.
+    class InvoiceLine < IntacctRest::Model::Base
+      INTACCT_OBJECT = '/objects/accounts-receivable/invoice-line'.freeze
+
+      WRITABLE_ATTRIBUTES = IntacctRest::Configuration::DEFAULT_INVOICE_LINE_WRITABLE_ATTRIBUTES
+
+      # Set by IntacctRest::Post after a successful create — writable here
+      # even though Intacct itself treats them as read-only. `href` is
+      # appended even though the schema omits it — the actual 201
+      # response includes it, same as Invoice/Vendor/Customer.
+      READONLY_ATTRIBUTES = %i[
+        key id base_amount currency payment_information line_number is_subtotal base_location
+        created_date is_summarized retainage project_contract project_contract_line audit href
+      ].freeze
+
+      attr_accessor(*WRITABLE_ATTRIBUTES.keys)
+      attr_accessor(*READONLY_ATTRIBUTES)
+      attr_reader :custom_fields
+
+      validate :presence, %i[invoice txn_amount gl_account]
+      validate :kind_of, :string, %i[txn_amount memo]
+      validate :kind_of, :hash, %i[gl_account override_offset_gl_account allocation account_label dimensions invoice]
+      validate :kind_of, :array, %i[tax_entries]
+
+      def initialize(source = nil, custom_fields: [], **attributes)
+        self.custom_fields = custom_fields
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      def custom_fields=(value)
+        @custom_fields = normalize_custom_fields(value)
+      end
+
+      def intacct_object
+        self.class::INTACCT_OBJECT
+      end
+
+      def attributes
+        WRITABLE_ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      def payload
+        WRITABLE_ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end.merge(custom_fields_payload)
+      end
+
+      # Called by IntacctRest::Post after a successful create.
+      def apply_result(result)
+        data = result.result
+        self.key = data['key'] if data['key']
+        self.href = data['href'] if data['href']
+        self.id = data['id'] if data['id'] && id.nil?
+      end
+
+      private
+
+      def attributes_from(source)
+        (WRITABLE_ATTRIBUTES.keys + READONLY_ATTRIBUTES).each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+
+      def normalize_custom_fields(value)
+        case value
+        when Array
+          value.map { |v| v.is_a?(IntacctRest::CustomField) ? v : IntacctRest::CustomField.new(**v) }
+        when Hash
+          value.map { |name, val| IntacctRest::CustomField.new(name: name.to_s, value: val) }
+        when nil
+          []
+        else
+          raise ArgumentError, "Unsupported custom_fields value: #{value.class}"
+        end
+      end
+
+      def custom_fields_payload
+        custom_fields.each_with_object({}) { |field, hash| hash[field.key] = field.value }
+      end
+    end
+  end
+end

data/lib/intacct_rest/model/term.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # An AR term's data and validations only — no config, no token
+    # provider, no HTTP. Build and inspect one freely; IntacctRest::Post
+    # (via IntacctRest::Endpoints::CreateTerm) is what actually sends it.
+    #
+    # Nested objects (due, discount, penalty) are NOT individually
+    # modeled — pass them as raw Hashes using Intacct's native (camelCase)
+    # nested key names, e.g. due: { "days" => 30, "from" => "fromInvoiceDate" }.
+    class Term < IntacctRest::Model::Base
+      INTACCT_OBJECT = '/objects/accounts-receivable/term'.freeze
+
+      WRITABLE_ATTRIBUTES = IntacctRest::Configuration::DEFAULT_TERM_WRITABLE_ATTRIBUTES
+
+      READONLY_ATTRIBUTES = %i[key href audit].freeze
+
+      attr_accessor(*WRITABLE_ATTRIBUTES.keys)
+      attr_accessor(*READONLY_ATTRIBUTES)
+      attr_reader :custom_fields
+
+      validate :presence, %i[id description]
+      validate :kind_of, :string, %i[id status description]
+      validate :kind_of, :hash, %i[due discount penalty]
+
+      # source: an arbitrary domain object to pull matching attributes off
+      # of via duck-typing. Explicit keyword attributes always win.
+      def initialize(source = nil, custom_fields: [], **attributes)
+        self.custom_fields = custom_fields
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      def custom_fields=(value)
+        @custom_fields = normalize_custom_fields(value)
+      end
+
+      def intacct_object
+        self.class::INTACCT_OBJECT
+      end
+
+      def attributes
+        WRITABLE_ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      def payload
+        WRITABLE_ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end.merge(custom_fields_payload)
+      end
+
+      # Called by IntacctRest::Post after a successful create.
+      def apply_result(result)
+        data = result.result
+        self.key = data['key'] if data['key']
+        self.href = data['href'] if data['href']
+        self.id = data['id'] if data['id'] && id.nil?
+      end
+
+      private
+
+      def attributes_from(source)
+        (WRITABLE_ATTRIBUTES.keys + READONLY_ATTRIBUTES).each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+
+      def normalize_custom_fields(value)
+        case value
+        when Array
+          value.map { |v| v.is_a?(IntacctRest::CustomField) ? v : IntacctRest::CustomField.new(**v) }
+        when Hash
+          value.map { |name, val| IntacctRest::CustomField.new(name: name.to_s, value: val) }
+        when nil
+          []
+        else
+          raise ArgumentError, "Unsupported custom_fields value: #{value.class}"
+        end
+      end
+
+      def custom_fields_payload
+        custom_fields.each_with_object({}) { |field, hash| hash[field.key] = field.value }
+      end
+    end
+  end
+end

data/lib/intacct_rest/model/vendor.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Model
+    # The vendor's data and validations only — no config, no token
+    # provider, no HTTP. Build and inspect one freely; IntacctRest::Post
+    # (via IntacctRest::Endpoints::CreateVendor) and IntacctRest::Patch
+    # (via IntacctRest::Endpoints::UpdateVendor) are what actually send it.
+    # Create requires id/name; update requires key and sends only the
+    # fields that are set (see #update_payload).
+    #
+    # Nested objects (bank_files, contacts, term, bill_payment, ...) are
+    # not individually modeled: pass them as raw Hashes using Intacct's
+    # native (camelCase) nested key names, e.g. term: { "id" => "Net 30" },
+    # or a helper's #payload, e.g. contacts: contact.payload.
+    class Vendor < IntacctRest::Model::Base
+      INTACCT_OBJECT = '/objects/accounts-payable/vendor'.freeze
+
+      WRITABLE_ATTRIBUTES = IntacctRest::Configuration::DEFAULT_VENDOR_WRITABLE_ATTRIBUTES
+
+      # Set by IntacctRest::Post (via #apply_result) after a successful
+      # create — writable here even though Intacct itself treats them as
+      # read-only, since this is the only place that result gets recorded.
+      READONLY_ATTRIBUTES = %i[
+        key href is_system_generated customer employee total_due last_bill_created_date
+        last_payment_made_date web_url audit entity
+      ].freeze
+
+      # Writable on create but readOnly on PATCH — left out of
+      # #update_payload.
+      UPDATE_READONLY_ATTRIBUTES = %i[id].freeze
+
+      # The exact enum from the OpenAPI bankFiles.paymentCountryCode /
+      # country-code schema (nil is separately allowed by the :inclusion
+      # validator below — not listed here).
+      BANK_FILE_COUNTRY_CODES = %w[
+        us af ax al dz as ad ao ai aq ag ar am aw au at az bs bh bd bb by be bz bj bm bt bo bq ba
+        bw bv br io bn bg bf bi kh cm ca ic cv ky cf td cl cn cx cc co km cg cd ck cr ci hr cu cw
+        cy cz dk dj dm do ec eg sv gq er ee sz et fk fo fj fi fr gf pf tf ga gm ge de gh gi gr gl
+        gd gp gu gt gg gn gw gy ht hm hn hk hu is in id ir iq ie im il it jm jp je jo kz ke ki kr
+        kp xk kw kg la lv lb ls lr ly li lt lu mo mk mg mw my mv ml mt mh mq mr mu yt mx fm md mc
+        mn me ms ma mz mm na nr np nl an nc nz ni ne ng nu nf mp no om pk pw ps pa pg py pe ph pn
+        pl pt pr qa re ro ru rw bl sh kn lc mf pm vc ws sm st sa sn rs sc sl sg sx sk si sb so za
+        gs es lk sd ss sr sj se ch sy tw tj tz th tl tg tk to tt tn tr tm tc tv ug ua ae gb um uy
+        uz vu va ve vn vg vi wf eh ye zm zw
+      ].freeze
+
+      attr_accessor(*WRITABLE_ATTRIBUTES.keys)
+      attr_accessor(*READONLY_ATTRIBUTES)
+      attr_reader :custom_fields
+
+      validate :presence, %i[id name], on: :create
+      validate :presence, %i[key], on: :update
+      validate :kind_of, :string, %i[key], on: :update
+
+      validate :kind_of, :string, %i[
+        id name status state file_payment_service tax_id notes preferred_payment_method
+        billing_type payment_priority currency vendor_account_number vendor_restriction
+      ]
+      validate :kind_of, :boolean, %i[
+        is_one_time_use is_on_hold do_not_pay always_create_bill is_individual_person
+        merge_payment_requests send_payment_notification display_term_discount_on_check_stub
+        display_vendor_account_on_check_stub
+      ]
+      validate :kind_of, :integer, %i[default_lead_time]
+      validate :kind_of, :numeric, %i[credit_limit retainage_percentage discount_percent]
+      validate :kind_of, :hash, %i[
+        vendor_type parent account_group account_label bank_files tpar t5018 form1099 attachment
+        price_list price_schedule override_offset_gl_account default_expense_gl_account contacts
+        term bill_payment ach
+      ]
+      validate :kind_of, :array, %i[
+        contact_list vendor_email_templates vendor_payment_providers vendor_bank_file_setup
+        vendor_account_number_list restricted_locations restricted_departments
+      ]
+
+      validate :inclusion, BANK_FILE_COUNTRY_CODES, %i[bank_files_payment_country_code]
+
+      # source: an arbitrary domain object (ActiveRecord record, OpenStruct,
+      # another Model::Vendor, ...) to pull matching attributes off of via
+      # duck-typing — any WRITABLE_ATTRIBUTES/READONLY_ATTRIBUTES key it
+      # responds to is copied over. Explicit keyword attributes always win
+      # over whatever the source provided.
+      def initialize(source = nil, custom_fields: [], **attributes)
+        self.custom_fields = custom_fields
+        merged = source ? attributes_from(source).merge(attributes) : attributes
+        merged.each { |key, value| public_send(:"#{key}=", value) if respond_to?(:"#{key}=") }
+      end
+
+      def custom_fields=(value)
+        @custom_fields = normalize_custom_fields(value)
+      end
+
+      def intacct_object
+        self.class::INTACCT_OBJECT
+      end
+
+      # Ruby-side attributes (unmapped, no custom fields) — useful for
+      # logging/introspection without the camelCase JSON translation.
+      def attributes
+        WRITABLE_ATTRIBUTES.keys.each_with_object({}) { |attr, hash| hash[attr] = public_send(attr) }
+      end
+
+      def payload
+        WRITABLE_ATTRIBUTES.each_with_object({}) do |(attr, json_key), hash|
+          value = public_send(attr)
+          hash[json_key] = value unless value.nil?
+        end.merge(custom_fields_payload)
+      end
+
+      # The PATCH body: #payload minus fields Intacct treats as readOnly on
+      # update. nil fields are already left out, so only what was set gets
+      # sent — Intacct leaves everything else unchanged.
+      def update_payload
+        payload.except(*UPDATE_READONLY_ATTRIBUTES.map { |attr| WRITABLE_ATTRIBUTES.fetch(attr) })
+      end
+
+      # Called by IntacctRest::Post/IntacctRest::Patch after a successful
+      # create/update.
+      def apply_result(result)
+        data = result.result
+        self.key = data['key'] if data['key']
+        self.href = data['href'] if data['href']
+        self.id = data['id'] if data['id'] && id.nil?
+      end
+
+      # Virtual attribute so the generic :inclusion validator can point at
+      # a nested field — bank_files itself stays a raw Hash (see above), so
+      # this just digs the one field out of it, tolerating string or
+      # symbol keys.
+      def bank_files_payment_country_code
+        return nil unless bank_files
+
+        bank_files['paymentCountryCode'] || bank_files[:paymentCountryCode]
+      end
+
+      private
+
+      def attributes_from(source)
+        (WRITABLE_ATTRIBUTES.keys + READONLY_ATTRIBUTES).each_with_object({}) do |attr, hash|
+          hash[attr] = source.public_send(attr) if source.respond_to?(attr)
+        end
+      end
+
+      def normalize_custom_fields(value)
+        case value
+        when Array
+          value.map { |v| v.is_a?(IntacctRest::CustomField) ? v : IntacctRest::CustomField.new(**v) }
+        when Hash
+          value.map { |name, val| IntacctRest::CustomField.new(name: name.to_s, value: val) }
+        when nil
+          []
+        else
+          raise ArgumentError, "Unsupported custom_fields value: #{value.class}"
+        end
+      end
+
+      def custom_fields_payload
+        custom_fields.each_with_object({}) { |field, hash| hash[field.key] = field.value }
+      end
+    end
+  end
+end

data/lib/intacct_rest/oauth_client.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  # OAuth2 token handling against Intacct's v1 token endpoint: client_credentials
+  # and refresh_token grants, with pluggable token storage (see Configuration#token_store).
+  class OauthClient
+    include ErrorReporting
+
+    TOKEN_EXPIRY_BUFFER = 60 # seconds
+
+    def initialize(config: IntacctRest.configuration)
+      @config = config
+    end
+
+    def access_token
+      token_store.read(access_token_key) || fetch_token
+    end
+
+    def refresh_access_token
+      refresh = token_store.read(refresh_token_key)
+      refresh ? exchange_refresh_token(refresh) : fetch_token
+    end
+
+    private
+
+    attr_reader :config
+
+    # Token errors are reported here, not in post_token: a failed
+    # refresh_token exchange is recovered by falling back to this method, so
+    # only errors leaving fetch_token actually reach the caller.
+    def fetch_token
+      store_tokens(post_token(grant_type: 'client_credentials'))
+    rescue IntacctRest::Error => e
+      raise_reported e, operation: :token_request, path: config.token_path, grant_type: 'client_credentials'
+    end
+
+    def exchange_refresh_token(refresh)
+      store_tokens(post_token(grant_type: 'refresh_token', refresh_token: refresh))
+    rescue IntacctRest::Error
+      fetch_token
+    end
+
+    def post_token(params)
+      client = IntacctRest::Client.new(token_url, :post)
+      client.body = params.merge(
+        client_id:     config.client_id,
+        client_secret: config.client_secret,
+        username:      config.username
+      )
+
+      response = client.request
+      unless response.is_a?(Net::HTTPSuccess)
+        raise IntacctRest::AuthenticationError,
+              "OAuth token request failed: HTTP #{response.code} — #{response.body}"
+      end
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError => e
+      raise IntacctRest::ResponseParseError.new(e.message, raw_body: response&.body)
+    end
+
+    def store_tokens(parsed)
+      ttl = [parsed['expires_in'].to_i - TOKEN_EXPIRY_BUFFER, 1].max
+      token_store.write(access_token_key, parsed['access_token'], ttl: ttl)
+      token_store.write(refresh_token_key, parsed['refresh_token']) if parsed['refresh_token']
+      parsed['access_token']
+    end
+
+    def token_store
+      config.token_store
+    end
+
+    def token_url
+      "#{config.base_url}#{config.token_path}"
+    end
+
+    def access_token_key
+      "#{config.token_key_prefix}:access_token"
+    end
+
+    def refresh_token_key
+      "#{config.token_key_prefix}:refresh_token"
+    end
+  end
+end

data/lib/intacct_rest/objects.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  # Wraps Intacct's Objects API (GET /objects/{resource} and
+  # GET /objects/{resource}/{key}) — distinct from the Query API (Query).
+  # No pagination handling: callers needing more than "list" or "fetch one"
+  # should use Query against the same resource instead.
+  class Objects
+    include AuthenticatedRequest
+
+    attr_reader :token_provider
+
+    def initialize(config: IntacctRest.configuration, token_provider: nil)
+      @config = config
+      @token_provider = token_provider || IntacctRest::OauthClient.new(config: config)
+    end
+
+    def list(resource)
+      authenticated_request(:get, "/objects/#{resource}")['ia::result'] || []
+    end
+
+    def find(resource, key)
+      authenticated_request(:get, "/objects/#{resource}/#{key}")['ia::result']
+    end
+
+    private
+
+    attr_reader :config
+  end
+end

data/lib/intacct_rest/page.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  Page = Struct.new(:items, :next_cursor, :raw, keyword_init: true)
+end

data/lib/intacct_rest/patch.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  # Generic operation for PATCH-ing (updating) any model that responds to
+  # #intacct_object (the collection path), #key (the record appended to
+  # it), #update_payload (the outgoing JSON hash — only the fields to
+  # change), and #valid?/#errors with an :update context. Raises
+  # IntacctRest::ValidationError if the model is invalid for update,
+  # before sending anything. Otherwise always returns an
+  # IntacctRest::Result (Success or Error) — never raises for the HTTP
+  # outcome itself. On success, calls model.apply_result(result) so the
+  # model can absorb whatever it cares about from the response.
+  class Patch
+    include AuthenticatedRequest
+
+    def self.call(model, config: IntacctRest.configuration, token_provider: nil)
+      new(config: config, token_provider: token_provider).send(:perform, model)
+    end
+
+    def initialize(config: IntacctRest.configuration, token_provider: nil)
+      @config = config
+      @token_provider = token_provider || IntacctRest::OauthClient.new(config: config)
+    end
+
+    private
+
+    attr_reader :config, :token_provider
+
+    def perform(model)
+      errors = model.errors(:update)
+      raise IntacctRest::ValidationError.new(errors.join('; '), attributes: errors) unless errors.empty?
+
+      path = "#{model.intacct_object}/#{model.key}"
+      response = authenticated_response(:patch, path, body: model.update_payload)
+      parsed = parse_json(response.body, path)
+      result = build_result(model, response, parsed)
+      model.apply_result(result) if result.success?
+      result
+    end
+
+    def build_result(model, response, parsed)
+      klass = response.is_a?(Net::HTTPSuccess) ? IntacctRest::Result::Success : IntacctRest::Result::Error
+      klass.new(model: model, code: response.code, body: parsed, headers: response.to_hash)
+    end
+  end
+end

data/lib/intacct_rest/post.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  # Generic operation for POST-ing any model that responds to
+  # #intacct_object (the endpoint path), #payload (the outgoing JSON
+  # hash), and #valid?/#errors. Raises IntacctRest::ValidationError if the
+  # model is invalid, before sending anything. Otherwise always returns an
+  # IntacctRest::Result (Success or Error) — never raises for the HTTP
+  # outcome itself. On success, calls model.apply_result(result) so the
+  # model can absorb whatever it cares about from the response.
+  class Post
+    include AuthenticatedRequest
+
+    def self.call(model, config: IntacctRest.configuration, token_provider: nil)
+      new(config: config, token_provider: token_provider).send(:perform, model)
+    end
+
+    def initialize(config: IntacctRest.configuration, token_provider: nil)
+      @config = config
+      @token_provider = token_provider || IntacctRest::OauthClient.new(config: config)
+    end
+
+    private
+
+    attr_reader :config, :token_provider
+
+    def perform(model)
+      errors = model.errors(:create)
+      raise IntacctRest::ValidationError.new(errors.join('; '), attributes: errors) unless errors.empty?
+
+      response = authenticated_response(:post, model.intacct_object, body: model.payload)
+      parsed = parse_json(response.body, model.intacct_object)
+      result = build_result(model, response, parsed)
+      model.apply_result(result) if result.success?
+      result
+    end
+
+    def build_result(model, response, parsed)
+      klass = response.is_a?(Net::HTTPSuccess) ? IntacctRest::Result::Success : IntacctRest::Result::Error
+      klass.new(model: model, code: response.code, body: parsed, headers: response.to_hash)
+    end
+  end
+end

data/lib/intacct_rest/query.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  # Wraps Intacct's POST /services/core/query endpoint for any object type
+  # (not just invoices), with pagination support.
+  #
+  #   query = IntacctRest::Query.new(
+  #     resource: "accounts-receivable/invoice",
+  #     schema:   %w[key state],
+  #     filters:  [IntacctRest::Filter.eq("state", "paid")]
+  #   )
+  #   query.each_page { |items, next_cursor| ... }
+  class Query
+    include AuthenticatedRequest
+
+    attr_reader :resource, :schema, :filters, :order_by, :size, :start, :token_provider
+
+    def initialize(resource:, schema: [], filters: [], order_by: nil, size: nil, start: nil,
+                   config: IntacctRest.configuration, token_provider: nil)
+      @resource = resource
+      @schema = schema
+      @filters = filters
+      @order_by = order_by
+      @config = config
+      @size = size || config.page_size
+      @start = start
+      @token_provider = token_provider || IntacctRest::OauthClient.new(config: config)
+    end
+
+    def url
+      "#{config.base_url}#{config.query_path}"
+    end
+
+    def payload
+      {
+        'object'  => resource,
+        'fields'  => schema,
+        'filters' => filters,
+        'orderBy' => order_by,
+        'size'    => size,
+        'start'   => start
+      }.compact
+    end
+
+    def call
+      parsed = authenticated_request(:post, config.query_path, body: payload)
+
+      IntacctRest::Page.new(
+        items:       parsed['ia::result'] || [],
+        next_cursor: parsed.dig('ia::meta', 'next'),
+        raw:         parsed
+      )
+    end
+
+    def each_page(max_pages: config.max_pages)
+      cursor = start
+      pages_fetched = 0
+
+      loop do
+        pages_fetched += 1
+        if pages_fetched > max_pages
+          raise IntacctRest::TooManyPagesError.new(
+            "Exceeded max pages (#{max_pages}) while querying #{resource}",
+            pages_fetched: pages_fetched - 1
+          )
+        end
+
+        page = with_start(cursor).call
+        yield page.items, page.next_cursor
+
+        break unless page.next_cursor
+
+        cursor = page.next_cursor
+      end
+    end
+
+    private
+
+    attr_reader :config
+
+    def with_start(cursor)
+      return self if cursor == start
+
+      self.class.new(resource: resource, schema: schema, filters: filters, order_by: order_by,
+                      size: size, start: cursor, config: config, token_provider: token_provider)
+    end
+  end
+end

data/lib/intacct_rest/result/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Result
+    class Base
+      attr_reader :model, :code, :body, :headers
+      alias response body
+
+      def initialize(model:, code:, body:, headers: {})
+        @model = model
+        @code = code
+        @body = body
+        @headers = headers
+      end
+    end
+  end
+end

data/lib/intacct_rest/result/error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module IntacctRest
+  module Result
+    class Error < Base
+      def success? = false
+      def failed? = true
+
+      def error
+        body.dig('ia::result', 'ia::error') || body['ia::error']
+      end
+    end
+  end
+end