myob_acumatica 0.1.0 → 0.1.2

data/examples/invoice.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'logger'
+require 'date'
+require 'dotenv/load'
+require 'myob_acumatica'
+
+access_token = ENV['MYOB_ACUMATICA_ACCESS_TOKEN']
+logger = Logger.new($stdout)
+
+MyobAcumatica::Api::Invoice.get_ad_hoc_schema(
+  access_token: access_token,
+  logger: logger
+)
+
+invoice1 = MyobAcumatica::Api::Invoice.put_entity(
+  access_token: access_token,
+  entity: {
+    'Customer' => { 'value' => 'JOHNGOOD1' },
+    'CustomerID' => { 'value' => 'JOHNGOOD1' },
+    'Date' => { 'value' => Date.today.strftime('%Y-%m-%d') },
+    'DueDate' => { 'value' => (Date.today + 30).strftime('%Y-%m-%d') },
+    'Terms' => { 'value' => 'NET14DAYS' },
+    'Type' => { 'value' => 'Invoice' },
+    'Hold' => { 'value' => false },
+    'BillingAddressOverride' => { 'value' => true },
+    'BillingAddress' => {
+      'AddressLine1' => { 'value' => 'Fillmore Str' },
+      'City' => { 'value' => 'San Francisco' },
+      'State' => { 'value' => 'CA' }
+    },
+    'custom' => {
+      'Document' => {
+        'DiscDate' => { 'value' => (Date.today + 10).strftime('%Y-%m-%dT00:00:00+00:00') }
+      }
+    }
+  },
+  logger: logger
+)
+
+MyobAcumatica::Api::Invoice.get_by_id(
+  access_token: access_token,
+  id: invoice1['id'],
+  logger: logger
+)
+
+MyobAcumatica::Api::Invoice.get_by_keys(
+  access_token: access_token,
+  keys: [invoice1['Type']['value'], invoice1['ReferenceNbr']['value']],
+  logger: logger
+)
+
+MyobAcumatica::Api::Invoice.get_list(
+  access_token: access_token,
+  query_params: {
+    # '$filter' => "Status eq 'Open' and "\
+    #   "LastModifiedDateTime gt datetimeoffset'2020-08-18T23:59:59.999+04:00'",
+    # '$expand' => 'Invoices',
+    '$skip' => 1,
+    '$top' => 4
+  },
+  logger: logger
+)
+
+MyobAcumatica::Api::Invoice.put_file(
+  access_token: access_token,
+  keys: [invoice1['Type']['value'], invoice1['ReferenceNbr']['value']],
+  file_path: 'examples/dummy.pdf',
+  logger: logger
+)
+
+MyobAcumatica::Api::Invoice.invoke_action(
+  access_token: access_token,
+  action_name: 'ReleaseInvoice',
+  entity: { 'id' => invoice1['id'] },
+  logger: logger
+)
+
+# MyobAcumatica::Api::Invoice.release(
+#   access_token: access_token,
+#   entity: { 'id' => invoice1['id'] },
+#   logger: logger
+# )
+
+MyobAcumatica::Api::Invoice.delete_by_keys(
+  access_token: access_token,
+  keys: [invoice1['Type']['value'], invoice1['ReferenceNbr']['value']],
+  logger: logger
+)
+
+invoice2 = MyobAcumatica::Api::Invoice.put_entity(
+  access_token: access_token,
+  entity: {
+    'Customer' => { 'value' => 'JOHNGOOD2' },
+    'CustomerID' => { 'value' => 'JOHNGOOD2' },
+    'Date' => { 'value' => Date.today.strftime('%Y-%m-%d') },
+    'DueDate' => { 'value' => (Date.today + 30).strftime('%Y-%m-%d') },
+    'Terms' => { 'value' => 'NET14DAYS' },
+    'Type' => { 'value' => 'Invoice' },
+    'Hold' => { 'value' => false },
+    'BillingAddressOverride' => { 'value' => true },
+    'BillingAddress' => {
+      'AddressLine1' => { 'value' => 'Fillmore Str' },
+      'City' => { 'value' => 'San Francisco' },
+      'State' => { 'value' => 'CA' }
+    },
+    'custom' => {
+      'Document' => {
+        'DiscDate' => { 'value' => (Date.today + 10).strftime('%Y-%m-%dT00:00:00+00:00') }
+      }
+    }
+  },
+  logger: logger
+)
+
+MyobAcumatica::Api::Invoice.delete_by_id(
+  access_token: access_token,
+  id: invoice2['id'],
+  logger: logger
+)

data/lib/myob_acumatica/api/customer.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module MyobAcumatica
+  module Api
+    # Provides methods to interact with the Customer API endpoints.
+    module Customer
+      module_function
+
+      # Deletes a customer by ID.
+      # @example Delete a customer by ID
+      #   MyobAcumatica::Api::Customer.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 unique ID of the customer.
+      # @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 for logging the request process.
+      # @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: "Customer/#{id}",
+          logger: logger
+        )
+      end
+
+      # Deletes a customer by composite keys.
+      # @example Delete a customer by keys
+      #   MyobAcumatica::Api::Customer.delete_by_keys(
+      #     access_token: '...',
+      #     keys: ['JOHNGOOD'],
+      #     logger: Logger.new($stdout)
+      #   )
+      # @param access_token [String] The OAuth2 access token.
+      # @param keys [Array<String>] An array of keys that uniquely identify the customer.
+      # @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 for logging the request process.
+      # @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: "Customer/#{keys.join('/')}",
+          logger: logger
+        )
+      end
+
+      # Retrieves the ad-hoc schema for the customer endpoint.
+      # @example Retrieve the ad-hoc schema
+      #   MyobAcumatica::Api::Customer.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 for logging the request process.
+      # @return [Hash] The ad hoc schema
+      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: 'Customer/$adHocSchema',
+          logger: logger
+        )
+      end
+
+      # Retrieves a customer by ID.
+      # @example Retrieve a customer by ID
+      #   MyobAcumatica::Api::Customer.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 unique ID of the customer.
+      # @param query_params [Hash] Additional query parameters for the request.
+      # @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 for logging the request process.
+      # @return [Hash] The customer
+      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: "Customer/#{id}",
+          query_params: query_params,
+          logger: logger
+        )
+      end
+
+      # Retrieves a customer by keys.
+      # @example Retrieve a customer by keys
+      #   MyobAcumatica::Api::Customer.get_by_keys(
+      #     access_token: '...',
+      #     keys: ['JOHNGOOD'],
+      #     logger: Logger.new($stdout)
+      #   )
+      # @param access_token [String] The OAuth2 access token.
+      # @param keys [Array<String>] An array of keys that uniquely identify the customer.
+      # @param query_params [Hash] Additional query parameters for the request.
+      # @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 for logging the request process.
+      # @return [Hash] The customer
+      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: "Customer/#{keys.join('/')}",
+          query_params: query_params,
+          logger: logger
+        )
+      end
+
+      # Retrieves a list of customers.
+      # @example Retrieve a list of customers
+      #   MyobAcumatica::Api::Customer.get_list(
+      #     access_token: '...',
+      #     query_params: { '$top' => 10 },
+      #     logger: Logger.new($stdout)
+      #   )
+      # @param access_token [String] The OAuth2 access token.
+      # @param query_params [Hash] Additional query parameters for the request.
+      # @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 for logging the request process.
+      # @return [Array<Hash>] A list of customers.
+      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: 'Customer',
+          query_params: query_params,
+          logger: logger
+        )
+      end
+
+      # Updates or creates a customer entity.
+      #
+      # @example Update or create a customer entity with detailed information
+      #   MyobAcumatica::Api::Customer.put_entity(
+      #     access_token: '...',
+      #     instance_name: 'example.myobadvanced.com',
+      #     entity: {
+      #       'CustomerID' => { 'value' => 'JOHNGOOD' },
+      #       'CustomerName' => { 'value' => 'John Good' },
+      #       'CustomerClass' => { 'value' => 'CUSTDFT' }
+      #     }
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param entity [Hash] The customer entity.
+      # @param query_params [Hash] Optional query parameters.
+      # @param instance_name [String] The name of the instance.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger for request debugging.
+      # @return [Hash] The response from the server.
+      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: 'Customer',
+          body: entity,
+          query_params: query_params,
+          logger: logger
+        )
+      end
+
+      # Uploads a file to a specific customer record by resolving the `files:put` link.
+      #
+      # @example Upload a PDF to a customer record
+      #   MyobAcumatica::Api::Customer.put_file(
+      #     access_token: '...',
+      #     instance_name: 'example.myobadvanced.com',
+      #     keys: ['JOHNGOOD'],
+      #     file_path: 'examples/sample.pdf'
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param keys [Array<String>] Key(s) identifying the customer record.
+      # @param file_path [String] Full path to the file to be uploaded.
+      # @param instance_name [String] The name of the instance.
+      # @param endpoint_name [String] The endpoint name.
+      # @param endpoint_version [String] The endpoint version.
+      # @param logger [Logger, nil] Optional logger for HTTP debugging.
+      # @return [nil] Returns nil if successful.
+      # @raise [MyobAcumatica::Error] If the upload fails.
+      def put_file(access_token:, keys:, file_path:,
+                   instance_name: INSTANCE_NAME,
+                   endpoint_name: ENDPOINT_NAME,
+                   endpoint_version: ENDPOINT_VERSION,
+                   logger: nil)
+        customer = get_by_keys(
+          access_token: access_token,
+          instance_name: instance_name,
+          keys: keys,
+          logger: logger
+        )
+
+        put_url_template = customer.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 Customer entity.
+      #
+      # @example Invoke the 'CreateContactFromCustomer' action
+      #   MyobAcumatica::Api::Customer.invoke_action(
+      #     access_token: '...',
+      #     action_name: 'CreateContactFromCustomer',
+      #     entity: { 'CustomerID' => { 'value' => 'JOHNGOOD' } },
+      #     parameters: {
+      #       'FirstName' => { 'value' => 'John' },
+      #       'LastName' => { 'value' => 'Smith' }
+      #     },
+      #     logger: Logger.new($stdout)
+      #   )
+      #
+      # @param access_token [String] The OAuth2 access token.
+      # @param action_name [String] The name of the action to invoke (e.g., 'CreateContactFromCustomer').
+      # @param entity [Hash] The entity payload 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 for HTTP debugging.
+      # @return [Hash, nil] The response from the action, 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: "Customer/#{action_name}",
+          body: { 'entity' => entity, 'parameters' => parameters },
+          logger: logger
+        )
+      end
+    end
+  end
+end

data/lib/myob_acumatica/api/http.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module MyobAcumatica
+  module Api
+    module Http
+      module_function
+
+      def request(instance_name:, access_token:, method:,
+                  endpoint_name:, endpoint_version:, path:,
+                  accept: 'application/json', content_type: 'application/json',
+                  query_params: {}, body: nil, logger: nil)
+        uri = URI.join("https://#{instance_name}/", 'entity/', "#{endpoint_name}/", "#{endpoint_version}/",
+                       path.to_s)
+        uri.query = URI.encode_www_form(query_params) unless query_params.empty?
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        http.set_debug_output(logger) unless logger.nil?
+
+        request_class = case method
+                        when :get then Net::HTTP::Get
+                        when :post then Net::HTTP::Post
+                        when :put then Net::HTTP::Put
+                        when :delete then Net::HTTP::Delete
+                        end
+
+        request = request_class.new(uri)
+        request['Authorization'] = "Bearer #{access_token}"
+        request['Content-Type'] = content_type
+        request['Accept'] = accept
+        request.body = content_type == 'application/json' ? body.to_json : body
+
+        response = http.request(request)
+
+        case response
+        when Net::HTTPAccepted
+          { 'location' => response['Location'] }
+        when Net::HTTPNoContent
+          nil
+        when Net::HTTPSuccess
+          response.body.empty? ? nil : JSON.parse(response.body)
+        else
+          raise MyobAcumatica::Error, "HTTP #{response.code}: #{response.body}"
+        end
+      end
+    end
+  end
+end