myob_acumatica 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f55ce7017ae2648ed83e6342d1067b97529db7dfac0437d45602f748e0ac402d
-  data.tar.gz: 3b3e9c12b1ca74f6b9214b1e97ffe8c086a16dc79af3dd475d371e127e676f2f
+  metadata.gz: ce19eee3aaa8648a6b035713bec45d0b194c5086b36005a7d8a2ca96890715be
+  data.tar.gz: a4d92210b0cc27dc599567afeea1e3e16a82a707fcbf3c5098366ef31efe9a9c
 SHA512:
-  metadata.gz: 8ea6da5df7be16a1dcb9f62ad4db478683b8d60ea2c735dfd852cc510d5f84ff3437accfd1ab9747d0efa28ee97665611ff9c66fe4d8e9267a42487cbb2e5733
-  data.tar.gz: 5aed30d5a8da8d83f60ab217629f7327f876c87268cf86c0a4c3b1c93ef96cb6a41f6e14a6ca491e1ed09bad0d502f07cbe0a75396418795d3872aa76826e955
+  metadata.gz: 375e4ada85b85912fbbda2d7475b5ca6519633993bea2c8a77b6b95dad5cff04f54b65611620d88c66774359fb40565ab60fed8344706b89180d73bf387c33ee
+  data.tar.gz: adca33c562c5c152268714889324920267a67273287548d65886d668e7d3f1c104e39bda2a155c531772b3fe9eea11b59d0255b641a21eb6459043c24d88022b

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.1.6] - 2025-09-17
+### Added
+- **Ledger API** support:
+  - `delete_by_id`
+  - `delete_by_keys`
+  - `get_ad_hoc_schema`
+  - `get_by_id`
+  - `get_by_keys`
+  - `get_list`
+  - `put_entity`
+  - `put_file`
+  - `invoke_action`
+
 ## [0.1.5] - 2025-08-13
 ### Added
 - **Currency API** support:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    myob_acumatica (0.1.5)
+    myob_acumatica (0.1.6)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -18,9 +18,7 @@ gem install myob_acumatica
 
 ## Configuration
 
-Provide configuration via **environment variables** and **explicitly per call**.
-
-**Note**: explicit parameters always override environment variables.
+Provide via **environment variables** or **explicit arguments**.
 
 ### Environment variables
 
@@ -41,7 +39,7 @@ MyobAcumatica::Api::Customer.get_list(
 )
 ```
 
-### Explicit parameters
+### Explicit arguments
 
 ```ruby
 MyobAcumatica::Api::Customer.get_list(
@@ -53,6 +51,8 @@ MyobAcumatica::Api::Customer.get_list(
 )
 ```
 
+**Note**: explicit arguments override environment variables.
+
 ## Authorization
 
 Allow a client application to obtain an access token on behalf of a user, using an authorization code granted by the user after consent.
@@ -296,9 +296,6 @@ MyobAcumatica::Api::Customer.get_list(access_token: token["access_token"])
 Bug reports and pull requests are welcome at:
 https://github.com/fast-programmer/myob_acumatica
 
-Please follow the code of conduct:
-https://github.com/fast-programmer/myob_acumatica/blob/master/CODE_OF_CONDUCT.md
-
 ## License
 
 MIT — see the LICENSE

data/examples/app.rb

@@ -41,6 +41,7 @@ module MyobAcumaticIntegration
         access_token: response['access_token'],
         endpoint_name: ENV['MYOB_ACUMATICA_ENDPOINT_NAME'],
         endpoint_version: ENV['MYOB_ACUMATICA_ENDPOINT_VERSION'],
+        query_params: { '$top' => 100, '$skip' => 0 },
         logger: Logger.new($stdout)
       )
 
@@ -96,40 +97,49 @@ module MyobAcumaticIntegration
     # end
 
     get '/customers' do
-      page_size = 1
-      skip = 0
-
-      customer_enum = Enumerator.new do |yielder|
-        customers = MyobAcumatica::Api::Customer.get_list(
-          instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
-          access_token: params['access_token'],
-          query_params: {
-            '$top' => page_size,
-            '$skip' => skip
-          }
-        )
-
-        while customers.size == page_size
-          yielder << customers
-          skip += page_size
-
-          customers = MyobAcumatica::Api::Customer.get_list(
-            instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
-            access_token: params['access_token'],
-            query_params: {
-              '$top' => page_size,
-              '$skip' => skip
-            }
-          )
-        end
-
-        yielder << customers if customers.any?
-      end
-
-      customers = customer_enum.flat_map(&:itself)
+      # page_size = 1
+      # skip = 0
+
+      # customer_enum = Enumerator.new do |yielder|
+      #   customers = MyobAcumatica::Api::Customer.get_list(
+      #     instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
+      #     access_token: params['access_token'],
+      #     query_params: {
+      #       '$top' => page_size,
+      #       '$skip' => skip
+      #     }
+      #   )
+
+      #   while customers.size == page_size
+      #     yielder << customers
+      #     skip += page_size
+
+      #     customers = MyobAcumatica::Api::Customer.get_list(
+      #       instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
+      #       access_token: params['access_token'],
+      #       query_params: {
+      #         '$top' => page_size,
+      #         '$skip' => skip
+      #       }
+      #     )
+      #   end
+
+      #   yielder << customers if customers.any?
 
       content_type :json
 
+      customers = MyobAcumatica::Api::Customer.get_list(
+        instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
+        access_token: params['access_token'],
+        endpoint_name: ENV['MYOB_ACUMATICA_ENDPOINT_NAME'],
+        endpoint_version: ENV['MYOB_ACUMATICA_ENDPOINT_VERSION'],
+        query_params: {
+          '$top' => 100,
+          '$skip' => 0
+        },
+        logger: Logger.new($stdout)
+      )
+
       { customers: customers }.to_json
     end
 

data/examples/ledger.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'logger'
+require 'dotenv/load'
+
+require 'myob_acumatica'
+
+access_token = ENV['MYOB_ACUMATICA_ACCESS_TOKEN']
+logger = Logger.new($stdout)
+
+MyobAcumatica::Api::Ledger.get_ad_hoc_schema(
+  access_token: access_token,
+  logger: logger
+)
+
+ledger1 = MyobAcumatica::Api::Ledger.put_entity(
+  access_token: access_token,
+  entity: {
+    'LedgerID' => { 'value' => 'LEDGER-ACTUAL' },
+    'Description' => { 'value' => 'Actuals Ledger' },
+    'Active' => { 'value' => true }
+  },
+  logger: logger
+)
+
+ledger1 = MyobAcumatica::Api::Ledger.put_entity(
+  access_token: access_token,
+  entity: {
+    'LedgerID' => { 'value' => ledger1['LedgerID']['value'] },
+    'Description' => { 'value' => 'Actuals Ledger (Updated)' }
+  },
+  logger: logger
+)
+
+ledger1 = MyobAcumatica::Api::Ledger.get_by_keys(
+  access_token: access_token,
+  keys: [ledger1['LedgerID']['value']],
+  logger: logger
+)
+
+MyobAcumatica::Api::Ledger.put_file(
+  access_token: access_token,
+  keys: [ledger1['LedgerID']['value']],
+  file_path: 'examples/dummy.pdf',
+  logger: logger
+)
+
+MyobAcumatica::Api::Ledger.get_by_id(
+  access_token: access_token,
+  id: ledger1['id'],
+  logger: logger
+)
+
+MyobAcumatica::Api::Ledger.get_list(
+  access_token: access_token,
+  logger: logger
+)
+
+MyobAcumatica::Api::Ledger.delete_by_id(
+  access_token: access_token,
+  id: ledger1['id'],
+  logger: logger
+)
+
+ledger2 = MyobAcumatica::Api::Ledger.put_entity(
+  access_token: access_token,
+  entity: {
+    'LedgerID' => { 'value' => 'LEDGER-BUDGET' },
+    'Description' => { 'value' => 'Budget Ledger' },
+    'Active' => { 'value' => false }
+  },
+  logger: logger
+)
+
+MyobAcumatica::Api::Ledger.delete_by_keys(
+  access_token: access_token,
+  keys: [ledger2['LedgerID']['value']],
+  logger: logger
+)
+
+# MyobAcumatica::Api::Ledger.invoke_action(
+#   access_token: access_token,
+#   action_name: 'RebuildBalances',
+#   entity: { 'LedgerID' => { 'value' => 'LEDGER-ACTUAL' } },
+#   parameters: { 'FromPeriod' => { 'value' => '2024-01' } },
+#   logger: logger
+# )

data/lib/myob_acumatica/api/ledger.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module MyobAcumatica
+  module Api
+    # Provides methods to interact with the Ledger API endpoints.
+    #
+    # All methods follow the same conventions as other entities in this gem:
+    # - Paths, query params, and headers are set via Http.request
+    # - Keys are joined with "/" when addressing composite primary keys
+    # - Binary uploads use 'application/octet-stream'
+    module Ledger
+      module_function
+
+      # Deletes a ledger by session identifier (GUID).
+      #
+      # @example Delete a ledger by ID
+      #   MyobAcumatica::Api::Ledger.delete_by_id(
+      #     access_token: '...',
+      #     id: '00000000-0000-4000-8000-000000000000',
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param id [String] The session GUID of the record.
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [nil] Always nil.
+      def delete_by_id(access_token:, id:,
+                       instance_name: INSTANCE_NAME,
+                       endpoint_name: ENDPOINT_NAME,
+                       endpoint_version: ENDPOINT_VERSION,
+                       logger: nil)
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :delete,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: "Ledger/#{id}",
+          logger: logger
+        )
+      end
+
+      # Deletes a ledger by composite keys.
+      #
+      # @example Delete a ledger by keys
+      #   MyobAcumatica::Api::Ledger.delete_by_keys(
+      #     access_token: '...',
+      #     keys: ['LEDGER-ACTUAL'],
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param keys [Array<String>] The key values identifying the record.
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [nil] Always nil.
+      def delete_by_keys(access_token:, keys:,
+                         instance_name: INSTANCE_NAME,
+                         endpoint_name: ENDPOINT_NAME,
+                         endpoint_version: ENDPOINT_VERSION,
+                         logger: nil)
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :delete,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: "Ledger/#{keys.join('/')}",
+          logger: logger
+        )
+      end
+
+      # Retrieves the ad-hoc schema (custom fields) for Ledger.
+      #
+      # @example Retrieve the ad-hoc schema
+      #   MyobAcumatica::Api::Ledger.get_ad_hoc_schema(
+      #     access_token: '...',
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [Hash] The ad-hoc schema document.
+      def get_ad_hoc_schema(access_token:,
+                            instance_name: INSTANCE_NAME,
+                            endpoint_name: ENDPOINT_NAME,
+                            endpoint_version: ENDPOINT_VERSION,
+                            logger: nil)
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :get,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: 'Ledger/$adHocSchema',
+          logger: logger
+        )
+      end
+
+      # Retrieves a ledger by session identifier (GUID).
+      #
+      # @example Retrieve a ledger by ID
+      #   MyobAcumatica::Api::Ledger.get_by_id(
+      #     access_token: '...',
+      #     id: '00000000-0000-4000-8000-000000000000',
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param id [String] The session GUID of the record.
+      # @param query_params [Hash] Optional query params ($select, $filter, etc.).
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [Hash] The ledger record.
+      def get_by_id(access_token:, id:, query_params: {},
+                    instance_name: INSTANCE_NAME,
+                    endpoint_name: ENDPOINT_NAME,
+                    endpoint_version: ENDPOINT_VERSION,
+                    logger: nil)
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :get,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: "Ledger/#{id}",
+          query_params: query_params,
+          logger: logger
+        )
+      end
+
+      # Retrieves a ledger by its key values.
+      #
+      # @example Retrieve a ledger by keys
+      #   MyobAcumatica::Api::Ledger.get_by_keys(
+      #     access_token: '...',
+      #     keys: ['LEDGER-ACTUAL'],
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param keys [Array<String>] The key values identifying the record.
+      # @param query_params [Hash] Optional query params ($select, $filter, etc.).
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [Hash] The ledger record.
+      def get_by_keys(access_token:, keys:, query_params: {},
+                      instance_name: INSTANCE_NAME,
+                      endpoint_name: ENDPOINT_NAME,
+                      endpoint_version: ENDPOINT_VERSION,
+                      logger: nil)
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :get,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: "Ledger/#{keys.join('/')}",
+          query_params: query_params,
+          logger: logger
+        )
+      end
+
+      # Retrieves a list of ledgers matching optional filters.
+      #
+      # @example Retrieve a list of ledgers
+      #   MyobAcumatica::Api::Ledger.get_list(
+      #     access_token: '...',
+      #     query_params: { '$top' => 10 },
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param query_params [Hash] Optional query params ($select, $top, etc.).
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [Array<Hash>] A list of ledger records.
+      def get_list(access_token:, query_params: {},
+                   instance_name: INSTANCE_NAME,
+                   endpoint_name: ENDPOINT_NAME,
+                   endpoint_version: ENDPOINT_VERSION,
+                   logger: nil)
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :get,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: 'Ledger',
+          query_params: query_params,
+          logger: logger
+        )
+      end
+
+      # Creates or updates a ledger record.
+      #
+      # @example Upsert a ledger
+      #   MyobAcumatica::Api::Ledger.put_entity(
+      #     access_token: '...',
+      #     entity: {
+      #       'LedgerID' => { 'value' => 'LEDGER-ACTUAL' },
+      #       'Description' => { 'value' => 'Actuals' }
+      #     },
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param entity [Hash] The ledger entity payload.
+      # @param query_params [Hash] Optional query params ($select, $custom, etc.).
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [Hash] The created or updated record.
+      def put_entity(access_token:, entity:, query_params: {},
+                     instance_name: INSTANCE_NAME,
+                     endpoint_name: ENDPOINT_NAME,
+                     endpoint_version: ENDPOINT_VERSION,
+                     logger: nil)
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :put,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: 'Ledger',
+          body: entity,
+          query_params: query_params,
+          logger: logger
+        )
+      end
+
+      # Attaches a file to a specific ledger record by resolving the 'files:put' link.
+      #
+      # @example Upload a PDF to a ledger record
+      #   MyobAcumatica::Api::Ledger.put_file(
+      #     access_token: '...',
+      #     keys: ['LEDGER-ACTUAL'],
+      #     file_path: 'examples/sample.pdf',
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param keys [Array<String>] Key(s) identifying the record.
+      # @param file_path [String] Full path to the file to upload.
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [nil] Returns nil if successful.
+      # @raise [MyobAcumatica::Error] If the upload link is missing or request fails.
+      def put_file(access_token:, keys:, file_path:,
+                   instance_name: INSTANCE_NAME,
+                   endpoint_name: ENDPOINT_NAME,
+                   endpoint_version: ENDPOINT_VERSION,
+                   logger: nil)
+        ledger = get_by_keys(
+          access_token: access_token,
+          instance_name: instance_name,
+          keys: keys,
+          logger: logger
+        )
+
+        put_url_template = ledger.dig('_links', 'files:put')
+        raise MyobAcumatica::Error, 'files:put link not found' unless put_url_template
+
+        filename = File.basename(file_path)
+        path = put_url_template.gsub('{filename}', filename)
+
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :put,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: path,
+          body: File.binread(file_path),
+          content_type: 'application/octet-stream',
+          logger: logger
+        )
+      end
+
+      # Invokes a custom action on the Ledger entity.
+      #
+      # The API may respond with 202 (accepted, in progress) or 204 (completed).
+      #
+      # @example Invoke a custom action
+      #   MyobAcumatica::Api::Ledger.invoke_action(
+      #     access_token: '...',
+      #     action_name: 'RebuildBalances',
+      #     entity: { 'LedgerID' => { 'value' => 'LEDGER-ACTUAL' } },
+      #     parameters: { 'FromPeriod' => { 'value' => '2024-01' } },
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param action_name [String] The action name (e.g., 'RebuildBalances').
+      # @param entity [Hash] The entity on which to invoke the action.
+      # @param parameters [Hash] Optional parameters for the action.
+      # @param instance_name [String] The instance name.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger.
+      # @return [Hash, nil] The action response, if any.
+      def invoke_action(access_token:, action_name:, entity:, parameters: {},
+                        instance_name: INSTANCE_NAME,
+                        endpoint_name: ENDPOINT_NAME,
+                        endpoint_version: ENDPOINT_VERSION,
+                        logger: nil)
+        Http.request(
+          instance_name: instance_name,
+          access_token: access_token,
+          method: :post,
+          endpoint_name: endpoint_name,
+          endpoint_version: endpoint_version,
+          path: "Ledger/#{action_name}",
+          body: { 'entity' => entity, 'parameters' => parameters },
+          logger: logger
+        )
+      end
+    end
+  end
+end

data/lib/myob_acumatica/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MyobAcumatica
-  VERSION = '0.1.5'
+  VERSION = '0.1.6'
 end

data/lib/myob_acumatica.rb

@@ -30,3 +30,4 @@ require_relative 'myob_acumatica/api/invoice'
 require_relative 'myob_acumatica/api/payment'
 require_relative 'myob_acumatica/api/tax'
 require_relative 'myob_acumatica/api/currency'
+require_relative 'myob_acumatica/api/ledger'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: myob_acumatica
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Adam Mikulasev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-13 00:00:00.000000000 Z
+date: 2025-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -157,6 +157,7 @@ files:
 - examples/customer.rb
 - examples/dummy.pdf
 - examples/invoice.rb
+- examples/ledger.rb
 - examples/payment.rb
 - examples/tax.rb
 - lib/myob_acumatica.rb
@@ -165,6 +166,7 @@ files:
 - lib/myob_acumatica/api/customer.rb
 - lib/myob_acumatica/api/http.rb
 - lib/myob_acumatica/api/invoice.rb
+- lib/myob_acumatica/api/ledger.rb
 - lib/myob_acumatica/api/payment.rb
 - lib/myob_acumatica/api/tax.rb
 - lib/myob_acumatica/o_auth_2/http.rb