myob_acumatica 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 678933f096d8f4456493114fee9b10c7a441dbaff1240f3446a805e8cc477780
-  data.tar.gz: 255125625f54ddce79e8d8498cb8bd19c44ae42fc33d75b383d9cb252c689798
+  metadata.gz: 13fbce76da83c644f946012fe508838d0b8a08eb2425202d6138c0dc389cbd4a
+  data.tar.gz: 7841a0ce98ce34f0ab35f71781a00e3e78000578f16c756d4cf90323355f2150
 SHA512:
-  metadata.gz: ebb16230ea6a77228861d9ffa4ebf3d8f9a69134f428c370dff21bb37c4690fe2aafd118b0a445ae54b5012a599503ce9451f014df1d4444f4acf4aef3c59b55
-  data.tar.gz: c004a8448658a209e54c42608d6759047218f4a62acfef1b26ba9803b1ef76447d354f069f9eecec8df590d070c9080026f09ca45cd8fd55e6ce5f3f596a938a
+  metadata.gz: 4f95a2575dbf194e812c0c6aa82d6058dbdce2cde3f8baafae8a5de5c00c87414e46d015901ba41f4d899776849977832dee6a27401eaa14b09360e801b83010
+  data.tar.gz: ac46af5f83b581a64f55edf70aeb4a7887962cbebd880ead202ea5e2361ce4a2dfd3de95ed2e5e255a2dc8a8f52dfeef24c6cc283c250e13c5b9a8d499adb49e

data/.rubocop.yml

@@ -24,3 +24,30 @@ Layout/FirstHashElementIndentation:
 
 Layout/HashAlignment:
   EnforcedStyle: key
+
+Style/NegatedIf:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/AbcSize:
+  Max: 50
+
+Metrics/CyclomaticComplexity:
+  Max: 50
+
+Metrics/PerceivedComplexity:
+  Max: 50
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false

data/Gemfile.lock

@@ -89,6 +89,7 @@ GEM
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
+    yard (0.9.37)
 
 PLATFORMS
   arm64-darwin-24
@@ -105,6 +106,7 @@ DEPENDENCIES
   rspec (~> 3.0)
   rubocop (~> 1.21)
   sinatra (~> 4.1)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.3.27

data/README.md

@@ -1,100 +1,237 @@
-# Myob Acumatica
+# Ruby library for the MYOB Acumatica API
 
-Access the MYOB Acumatica HTTP API via Ruby
+A lightweight Ruby client for accessing the MYOB Acumatica REST API via OAuth2.
+
+---
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Using Bundler:
+
+```bash
+bundle add myob_acumatica
+```
+
+Without Bundler:
 
-    $ bundle add myob_acumatica
+```bash
+gem install myob_acumatica
+```
+
+---
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Setup
 
-    $ gem install myob_acumatica
+Set the following environment variables in your host application:
 
-## Usage
+```bash
+MYOB_ACUMATICA_INSTANCE_NAME=your-instance.myob.com
+MYOB_ACUMATICA_CLIENT_ID=your-client-id
+MYOB_ACUMATICA_CLIENT_SECRET=your-client-secret
+MYOB_ACUMATICA_REDIRECT_URI=http://localhost:4567/oauth2/callback
+MYOB_ACUMATICA_SCOPE=api offline_access
+MYOB_ACUMATICA_ENDPOINT_NAME=Default
+MYOB_ACUMATICA_ENDPOINT_VERSION=22.200.001
+```
 
-## 1. Get an access token using the OAuth2 Authorization Code Grant Flow
+---
 
-### i. Generate Authorization URL
+## OAuth2 Flow
 
-To initiate the OAuth2 flow, generate an authorization URL:
+Get the authorization URL to initiate login:
 
 ```ruby
-MyobAcumatica::OAuth2.authorize_url(
-  instance_url: ...,
-  client_id: ...,
-  redirect_uri: ...,
-  scope: 'api offline'
-)
+MyobAcumatica::OAuth2::Token.authorize_url
+```
+
+Exchange the code for an access token and a refresh token
+
+```ruby
+token = MyobAcumatica::OAuth2::Token.authorize(code: params[:code])
+```
+
+```ruby
+{
+  "access_token" => "...",
+  "expires_in" => 3600,
+  "token_type" => "Bearer",
+  "refresh_token" => "...",
+  "scope" => "api offline_access"
+}
+```
 
-=> https://{instance_url}/identity/connect/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=api+offline_access
+Refresh the access token when expired:
+
+```ruby
+token = MyobAcumatica::OAuth2::Token.refresh(refresh_token: token["refresh_token"])
 ```
 
-Then redirect users to this URL to start the authorization process.
+---
+
+## Customer Examples
+
+Create or update a customer:
+
+```ruby
+MyobAcumatica::Api::Customer.put_entity(
+  access_token: token["access_token"],
+  entity: {
+    'CustomerID' => { 'value' => 'JOHNGOOD' },
+    'CustomerName' => { 'value' => 'John Good' },
+    'CustomerClass' => { 'value' => 'CUSTDFT' }
+  }
+)
+```
 
-### ii. Exchange the authorization code for an access token
+List customers:
 
-After the user has authorized the application, they will be redirected back to your application with an authorization code.
+```ruby
+MyobAcumatica::Api::Customer.get_list(
+  access_token: token["access_token"],
+  query_params: { '$filter' => "Status eq 'Active'" }
+)
+```
 
-Use this code to request an access token:
+Get customer by keys:
 
 ```ruby
-MyobAcumatica::OAuth2.authorize_token(
-  instance_url: ...,
-  client_id: ...,
-  client_secret: ...,
-  code: params['code'],
-  redirect_uri: ...,
+MyobAcumatica::Api::Customer.get_by_keys(
+  access_token: token["access_token"],
+  keys: ['JOHNGOOD']
 )
+```
 
-=> {"access_token":"abc",expires_in":3600,"token_type":"Bearer","refresh_token":"def","scope":"api offline_access"}
+Delete a customer:
+
+```ruby
+MyobAcumatica::Api::Customer.delete_by_keys(
+  access_token: token["access_token"],
+  keys: ['JOHNGOOD']
+)
 ```
 
+---
+
+## Invoice Examples
 
-### iii. Refresh the access token using the refresh token
+Create an invoice:
 
-If the access token expires, you can use the refresh token received during the token exchange to obtain a new access token:
+```ruby
+MyobAcumatica::Api::Invoice.put_entity(
+  access_token: token["access_token"],
+  entity: {
+    'CustomerID' => { 'value' => 'JOHNGOOD' },
+    'Date' => { 'value' => '2025-06-06' },
+    'Details' => [
+      {
+        'InventoryID' => { 'value' => 'CONSULTING' },
+        'Quantity' => { 'value' => 2 },
+        'UnitPrice' => { 'value' => 150.0 }
+      }
+    ]
+  }
+)
+```
+
+List invoices:
 
 ```ruby
-MyobAcumatica::OAuth2.refresh_token(
-  instance_url: ENV['INSTANCE_URL'],
-  client_id: ENV['CLIENT_ID'],
-  client_secret: ENV['CLIENT_SECRET'],
-  refresh_token: params[:refresh_token],
-  logger: Logger.new($stdout)
+MyobAcumatica::Api::Invoice.get_list(
+  access_token: token["access_token"],
+  query_params: {
+    '$filter' => "Status eq 'Open'",
+    '$top' => 10,
+    '$select' => 'InvoiceNbr,CustomerID,Status,Date'
+  }
 )
+```
+
+Get invoice by ID:
 
-=> {"access_token":"ghi",expires_in":3600,"token_type":"Bearer","refresh_token":"jkl","scope":"api offline_access"}
+```ruby
+MyobAcumatica::Api::Invoice.get_by_id(
+  access_token: token["access_token"],
+  id: '00000000-0000-0000-0000-000000000000'
+)
 ```
 
-## 2. Hit the MYOB Accumatica API
+Delete an invoice:
 
 ```ruby
-customers = MyobAcumatica::Customer.list(
-  instance_url: ...,
-  endpoint_name: 'Default',
-  endpoint_version: ...,
-  access_token: token['access_token'],
-  query_params: { filter: 'IsActive eq true' },
-  logger: Logger.new($stdout)
+MyobAcumatica::Api::Invoice.delete_by_id(
+  access_token: token["access_token"],
+  id: '00000000-0000-0000-0000-000000000000'
 )
 ```
 
+---
+
+## Documentation
+
+See full API reference and usage examples: [rubydoc.info/gems/myob_acumatica](https://www.rubydoc.info/gems/myob_acumatica)
+
+---
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### 1. Clone the repo
+
+```bash
+git clone https://github.com/fast-programmer/myob_acumatica.git
+cd myob_acumatica
+bundle install
+```
+
+### 2. Create a `.env` file
+
+```env
+MYOB_ACUMATICA_INSTANCE_NAME=your-instance.myob.com
+MYOB_ACUMATICA_CLIENT_ID=your-client-id
+MYOB_ACUMATICA_CLIENT_SECRET=your-client-secret
+MYOB_ACUMATICA_REDIRECT_URI=http://localhost:4567/oauth2/callback
+MYOB_ACUMATICA_SCOPE=api offline_access
+MYOB_ACUMATICA_ENDPOINT_NAME=Default
+MYOB_ACUMATICA_ENDPOINT_VERSION=22.200.001
+```
+
+### 3. Run the Sinatra example app
+
+This test app helps acquire an OAuth token and inspect customer data.
+
+```bash
+bundle exec ruby examples/app.rb
+```
+
+Visit in your browser:
+
+- http://localhost:4567/oauth2/authorize — start login
+- http://localhost:4567/oauth2/callback — receive tokens and fetch customer list
+
+### 4. Open an interactive shell
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+bin/console
+```
+
+Try this command with your token:
+
+```ruby
+MyobAcumatica::Api::Customer.get_list(access_token: token["access_token"])
+```
+
+---
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/fast-programmer/myob_acumatica. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/fast-programmer/myob_acumatica/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome at:
+https://github.com/fast-programmer/myob_acumatica
 
-## License
+Please follow the code of conduct:
+https://github.com/fast-programmer/myob_acumatica/blob/master/CODE_OF_CONDUCT.md
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+---
 
-## Code of Conduct
+## License
 
-Everyone interacting in the MyobAcumatica project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fast-programmer/myob_acumatica/blob/master/CODE_OF_CONDUCT.md).
+MIT — see the LICENSE
+https://opensource.org/licenses/MIT

data/examples/app.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'myob_acumatica'
-
 require 'sinatra/base'
 require 'dotenv'
 
+require 'myob_acumatica'
+
 Dotenv.load
 
 module MyobAcumaticIntegration
@@ -16,32 +16,31 @@ module MyobAcumaticIntegration
     end
 
     get '/oauth2/authorize' do
-      authorize_url = MyobAcumatica::OAuth2.authorize_url(
-        instance_url: ENV['INSTANCE_URL'],
-        client_id: ENV['CLIENT_ID'],
-        redirect_uri: ENV['REDIRECT_URI'],
-        scope: ENV['SCOPE']
+      authorize_url = MyobAcumatica::OAuth2::Token.authorize_url(
+        instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
+        client_id: ENV['MYOB_ACUMATICA_CLIENT_ID'],
+        redirect_uri: ENV['MYOB_ACUMATICA_REDIRECT_URI'],
+        scope: ENV['MYOB_ACUMATICA_SCOPE']
       )
 
       redirect authorize_url
     end
 
     get '/oauth2/callback' do
-      response = MyobAcumatica::OAuth2.authorize_token(
-        instance_url: ENV['INSTANCE_URL'],
-        client_id: ENV['CLIENT_ID'],
-        client_secret: ENV['CLIENT_SECRET'],
+      response = MyobAcumatica::OAuth2::Token.authorize(
+        instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
+        client_id: ENV['MYOB_ACUMATICA_CLIENT_ID'],
+        client_secret: ENV['MYOB_ACUMATICA_CLIENT_SECRET'],
         code: params[:code],
-        redirect_uri: ENV['REDIRECT_URI'],
+        redirect_uri: ENV['MYOB_ACUMATICA_REDIRECT_URI'],
         logger: logger
       )
 
-      customers = MyobAcumatica::Customer.list(
-        instance_url: ENV['INSTANCE_URL'],
-        endpoint_name: ENV['ENDPOINT_NAME'],
-        endpoint_version: ENV['ENDPOINT_VERSION'],
+      customers = MyobAcumatica::Api::Customer.get_list(
+        instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
         access_token: response['access_token'],
-        query_params: { filter: 'IsActive eq true' },
+        endpoint_name: ENV['MYOB_ACUMATICA_ENDPOINT_NAME'],
+        endpoint_version: ENV['MYOB_ACUMATICA_ENDPOINT_VERSION'],
         logger: Logger.new($stdout)
       )
 
@@ -54,8 +53,8 @@ module MyobAcumaticIntegration
     end
 
     get '/oauth2/refresh' do
-      response = MyobAcumatica::OAuth2.refresh_token(
-        instance_url: ENV['INSTANCE_URL'],
+      response = MyobAcumatica::OAuth2::Token.refresh(
+        instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
         client_id: ENV['CLIENT_ID'],
         client_secret: ENV['CLIENT_SECRET'],
         refresh_token: params[:refresh_token],
@@ -70,6 +69,102 @@ module MyobAcumaticIntegration
       }.to_json
     end
 
+    # get '/customers' do
+    #   timestamp = (Time.now - 1 * 3600).utc.strftime('%Y-%m-%dT%H:%M:%S.%L+00:00')
+    #   filter = "Status eq 'Active' and LastModifiedDateTime gt datetimeoffset'#{timestamp}'"
+
+    #   customers = MyobAcumatica::Api::Customer.get_list(
+    #     instance_name: ENV['MYOB_ACUMATICA_INSTANCE_NAME'],
+    #     access_token: params['access_token'],
+    #     query_params: {
+    #       '$select' => 'CustomerID, CustomerName, LastModifiedDateTime',
+    #       '$filter' => filter,
+    #       '$expand' => 'Contacts',
+    #       '$skip' => 0,
+    #       '$top' => 2
+    #     },
+    #     endpoint_name: ENV['MYOB_ACUMATICA_ENDPOINT_NAME'],
+    #     endpoint_version: ENV['MYOB_ACUMATICA_ENDPOINT_VERSION'],
+    #     logger: Logger.new($stdout)
+    #   )
+
+    #   content_type :json
+
+    #   {
+    #     customers: customers
+    #   }.to_json
+    # 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)
+
+      content_type :json
+
+      { customers: customers }.to_json
+    end
+
+    get '/sales_invoices' do
+      sales_invoices = MyobAcumatica::Api::SalesInvoice.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'],
+        logger: Logger.new($stdout)
+      )
+
+      content_type :json
+
+      {
+        sales_invoices: sales_invoices
+      }.to_json
+    end
+
+    get '/invoices' do
+      invoices = MyobAcumatica::Api::Invoice.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'],
+        logger: Logger.new($stdout)
+      )
+
+      content_type :json
+
+      {
+        invoices: invoices
+      }.to_json
+    end
+
     run! if app_file == $PROGRAM_NAME
   end
 end

data/examples/customer.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'logger'
+require 'byebug'
+require 'dotenv/load'
+require 'cgi'
+
+require 'myob_acumatica'
+
+access_token = ENV['MYOB_ACUMATICA_ACCESS_TOKEN']
+logger = Logger.new($stdout)
+
+MyobAcumatica::Api::Customer.get_ad_hoc_schema(
+  access_token: access_token,
+  logger: logger
+)
+
+customer1 = MyobAcumatica::Api::Customer.put_entity(
+  access_token: access_token,
+  entity: {
+    'CustomerID' => { 'value' => 'JOHNGOOD' },
+    'CustomerName' => { 'value' => 'John Good' },
+    'CustomerClass' => { 'value' => 'CUSTDFT' },
+    'MainContact' => {
+      'Email' => { 'value' => 'demo@gmail.com' },
+      'Address' => {
+        'AddressLine1' => { 'value' => '4030 Lake Washington Blvd NE' },
+        'AddressLine2' => { 'value' => 'Suite 100' },
+        'City' => { 'value' => 'Kirkland' },
+        'State' => { 'value' => 'WA' },
+        'PostalCode' => { 'value' => '98033' },
+        'Country' => { 'value' => 'US' }
+      }
+    }
+  },
+  logger: logger
+)
+
+customer1 = MyobAcumatica::Api::Customer.put_entity(
+  access_token: access_token,
+  entity: {
+    'CustomerID' => { 'value' => customer1['CustomerID']['value'] },
+    'CustomerName' => { 'value' => 'John Good Updated' }
+  },
+  logger: logger
+)
+
+customer1 = MyobAcumatica::Api::Customer.get_by_keys(
+  access_token: access_token,
+  keys: [customer1['CustomerID']['value']],
+  logger: logger
+)
+
+# MyobAcumatica::Api::Customer.invoke_action(
+#   access_token: access_token,
+#   action_name: 'CreateContactFromCustomer',
+#   entity: {
+#     'CustomerID' => { 'value' => 'JOHNGOOD' }
+#   },
+#   parameters: {
+#     'FirstName' => { 'value' => 'John' },
+#     'LastName' => { 'value' => 'Smith' },
+#     'JobTitle' => { 'value' => 'Director' },
+#     'Email' => { 'value' => 'john.smith@example.com' },
+#     'ContactClass' => { 'value' => 'DEFAULT' }
+#   },
+#   logger: logger
+# )
+
+MyobAcumatica::Api::Customer.put_file(
+  access_token: access_token,
+  keys: [customer1['CustomerID']['value']],
+  file_path: 'examples/dummy.pdf',
+  logger: logger
+)
+
+MyobAcumatica::Api::Customer.get_by_id(
+  access_token: access_token,
+  id: customer1['id'],
+  logger: logger
+)
+
+MyobAcumatica::Api::Customer.get_list(
+  access_token: access_token,
+  query_params: {
+    '$select' => 'CustomerID, CustomerName, LastModifiedDateTime',
+    '$filter' => "Status eq 'Active' and "\
+      "LastModifiedDateTime gt datetimeoffset'2020-08-18T23:59:59.999+04:00'",
+    '$expand' => 'Contacts',
+    '$skip' => 2,
+    '$top' => 3
+  },
+  logger: logger
+)
+
+MyobAcumatica::Api::Customer.delete_by_id(
+  access_token: access_token,
+  id: customer1['id'],
+  logger: logger
+)
+
+customer2 = MyobAcumatica::Api::Customer.put_entity(
+  access_token: access_token,
+  entity: {
+    'CustomerID' => { 'value' => 'STEVEYELLOW' },
+    'CustomerName' => { 'value' => 'Steve Yellow' },
+    'CustomerClass' => { 'value' => 'CUSTDFT' },
+    'MainContact' => {
+      'Email' => { 'value' => 'demo@gmail.com' },
+      'Address' => {
+        'AddressLine1' => { 'value' => '2030 Lake Washington Blvd NE' },
+        'AddressLine2' => { 'value' => 'Suite 100' },
+        'City' => { 'value' => 'Kirkland' },
+        'State' => { 'value' => 'WA' },
+        'PostalCode' => { 'value' => '98033' },
+        'Country' => { 'value' => 'US' }
+      }
+    }
+  },
+  logger: logger
+)
+
+MyobAcumatica::Api::Customer.delete_by_keys(
+  access_token: access_token,
+  keys: [customer2['CustomerID']['value']],
+  logger: logger
+)