xero-ruby 3.2.1 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcc8e88d077eb5b42f9a9c8a206ce6c7fb62589e7179932764a70cc28c3f821a
-  data.tar.gz: 8c25945749aaca49892462186f749701255022d05ea498645a3b1e59c10a5e52
+  metadata.gz: 471817aae937985bd56abe5d70a1e3d078c24e2d87971205e30c1583a05c3e37
+  data.tar.gz: 70990d160ea9bdaac183acd06eaab41e0b680525b386b2c1411cf33ec3fbef9a
 SHA512:
-  metadata.gz: 4196ec14ceaa6179bbbedb856b447e7af947ba96e4af24ab8130835af5660a8e6787fbf3261c3f6c5c605d0f81436559bd37e1e0a7252bab42feb752f4634d31
-  data.tar.gz: c99e89b1f45563b72023ad5d5ceb3632fe5661068ad5ee89d672194fca72ddccbb1967d9f9796098d12ff9b649f03dfa5b26d3eb08b3daf756bef0e3a7f3fe5f
+  metadata.gz: 5f47679440b82e924e68da60d26fbb6d7062c47ef026272be763740ad826392781d7dd260a04b5e139d09de2a54336c0602c51746df819554e2a625f8fdf7dbd
+  data.tar.gz: 353ca2bcb1d9395d5d68fdb3474ab1c86f54f9474bd8b5135616c3469173683c927d2bea4cfd5a457dae2ab1ee4caf34ff6c9adac81c7f219e8dba3e4f1298fe

data/README.md

@@ -4,7 +4,7 @@
 [![Github stars](https://img.shields.io/github/stars/XeroAPI/xero-ruby.svg)](https://github.com/XeroAPI/xero-ruby/stargazers)
 ![total downloads](https://ruby-gem-downloads-badge.herokuapp.com/xero-ruby?type=total)
 
-The xero-ruby SDK makes it easy for developers to access Xero's APIs in their Ruby code, and build robust applications and software using small business & general ledget accounting data.
+The xero-ruby SDK makes it easy for developers to access Xero's APIs in their Ruby code, and build robust applications and software using small business & general ledger accounting data.
 # Table of Contents
 - [API Client documentation](#api-client-documentation)
 - [Sample Applications](#sample-applications)
@@ -13,6 +13,7 @@ The xero-ruby SDK makes it easy for developers to access Xero's APIs in their Ru
 - [Configuration](#configuration)
 - [Authentication](#authentication)
 - [Custom Connections](#custom-connections)
+- [App Store Subscriptions](#app-store-subscriptions)
 - [API Clients](#api-clients)
 - [Helper Methods](#helper-methods)
 - [Usage Examples](#usage-examples)
@@ -46,6 +47,7 @@ Sample apps can get you started quickly with simple auth flows to advanced usage
 | [`xero-ruby-oauth2-starter`](https://github.com/XeroAPI/Xero-ruby-oauth2-starter) | A Sinatra application showing the basic getting started code to work with the sdk | <img src="https://i.imgur.com/9H4F98M.png" alt="drawing" width="300"/>
 | [`xero-ruby-oauth2-app`](https://github.com/XeroAPI/Xero-ruby-oauth2-app) | Complete rails app with +95% of api set examples, complex filters, pagination, and user/token management in postgres | <img src="https://i.imgur.com/XsAp9Ww.png" alt="drawing" width="500"/>
 | [`xero-ruby-custom-connections-starter`](https://github.com/XeroAPI/xero-ruby-custom-connections-starter) | A getting started Sinatra app showing Custom Connections - a Xero [premium option](https://developer.xero.com/documentation/oauth2/custom-connections) for building M2M integrations to a single org | <img src="https://i.imgur.com/YEkScui.png" alt="drawing" width="300"/>
+| [`xero-ruby-sso-form`](https://github.com/XeroAPI/xero-ruby-sso-form) | A basic Sinatra app showing how to implement SSU to Lead | <img src="https://i.imgur.com/Nf95GVd.png" alt="drawing" width="300"/>
 
 <hr>
 
@@ -155,6 +157,73 @@ Because Custom Connections are only valid for a single organisation you don't ne
 However - due to the nature of how our SDK's are generated from our OpenAPI spec, the parameter remains which requires you to pass an empty string for now to use the SDK with a Custom Connection.
 
 ---
+
+## App Store Subscriptions
+
+If you are implementing subscriptions to participate in Xero's App Store you will need to setup [App Store subscriptions](https://developer.xero.com/documentation/guides/how-to-guides/xero-app-store-referrals/) endpoints.
+
+When a plan is successfully purchased, the user is redirected back to the URL specified in the setup process. The Xero App Store appends the subscription Id to this URL so you can immediately determine what plan the user has subscribed to through the subscriptions API.
+
+With your app credentials you can create a client via `client_credentials` grant_type with the `marketplace.billing` scope. This unique access_token will allow you to query any functions in `appStoreApi`. Client Credentials tokens to query app store endpoints will only work for apps that have completed the App Store on-boarding process.
+
+```ruby
+// => /post-purchase-url?subscriptionId=03bc74f2-1237-4477-b782-2dfb1a6d8b21
+
+subscription_id = params[:subscriptionId]
+
+xero_app_store_client ||= XeroRuby::ApiClient.new(credentials: {
+  client_id: ENV['CLIENT_ID'],
+  client_secret: ENV['CLIENT_SECRET'],
+  grant_type: 'client_credentials'
+  scopes: ['marketplace.billing']
+})
+
+xero_app_store_client.get_client_credentials_token
+
+@subscription = xero_app_store_client.app_store_api.get_subscription(subscription_id)
+
+puts @subscription.to_attributes
+{
+  :current_period_end => Thu, 02 Sep 2021 14:08:58 +0000,
+  :id => "03bc74f2-1237-4477-b782-2dfb1a6d8b21",
+  :organisation_id => "79e8b2e5-c63d-4dce-888f-e0f3e9eac647",
+  :plans => [
+    {
+      :id => "6abc26f3-9390-4194-8b25-ce8b9942fda9",
+      :name => "Small",
+      :status => "ACTIVE",
+      :subscription_items => [
+        {
+          :id => "834cff4c-b753-4de2-9e7a-3451e14fa17a",
+          :price => {
+            :amount => 0.1e0,
+            :currency => "NZD",
+            :id => "2310de92-c7c0-4bcb-b972-fb7612177bc7"
+          },
+          :product => {
+            :id => "9586421f-7325-4493-bac9-d93be06a6a38",
+            :name => "",
+            :type => "FIXED"
+          },
+          :start_date => Mon, 02 Aug 2021 14:08:58 +0000,
+          :test_mode => true
+        }
+      ]
+    }
+  ],
+  :start_date => Mon, 02 Aug 2021 14:08:58 +0000,
+  :status => "ACTIVE",
+  :test_mode => true
+}
+```
+You should use this subscription data to provision user access/permissions to your application.
+### App Store Subscription Webhooks
+
+In additon to a subscription Id being passed through the URL, when a purchase or an upgrade takes place you will be notified via a webhook. You can then use the subscription Id in the webhook payload to query the AppStore endpoints and determine what plan the user purchased, upgraded, downgraded or cancelled.
+
+Refer to Xero's documenation to learn more about setting up and receiving webhooks.
+> https://developer.xero.com/documentation/guides/webhooks/overview/
+
 ## API Clients
 You can access the different API sets and their available methods through the following:
 

data/lib/xero-ruby/api/accounting_api.rb

@@ -7018,20 +7018,24 @@ module XeroRuby
       return data, status_code, headers
     end
 
-    # Retrieves a specific budgets, which includes budget lines
+    # Retrieves a specific budget, which includes budget lines
     # @param xero_tenant_id [String] Xero identifier for Tenant
     # @param budget_id [String] Unique identifier for Budgets
     # @param [Hash] opts the optional parameters
+    # @option opts [Date] :date_to Filter by start date
+    # @option opts [Date] :date_from Filter by end date
     # @return [Budgets]
     def get_budget(xero_tenant_id, budget_id, opts = {})
       data, _status_code, _headers = get_budget_with_http_info(xero_tenant_id, budget_id, opts)
       data
     end
 
-    # Retrieves a specific budgets, which includes budget lines
+    # Retrieves a specific budget, which includes budget lines
     # @param xero_tenant_id [String] Xero identifier for Tenant
     # @param budget_id [String] Unique identifier for Budgets
     # @param [Hash] opts the optional parameters
+    # @option opts [Date] :date_to Filter by start date
+    # @option opts [Date] :date_from Filter by end date
     # @return [Array<(Budgets, Integer, Hash)>] Budgets data, response status code and response headers
     def get_budget_with_http_info(xero_tenant_id, budget_id, options = {})
       opts = options.dup
@@ -7054,6 +7058,8 @@ module XeroRuby
 
       # query parameters
       query_params = opts[:query_params] || {}
+      query_params[:'DateTo'] = opts[:'date_to'] if !opts[:'date_to'].nil?
+      query_params[:'DateFrom'] = opts[:'date_from'] if !opts[:'date_from'].nil?
       
       # XeroAPI's `IDs` convention openapi-generator does not snake_case properly.. manual over-riding `i_ds` malformations:
       query_params[:'IDs'] = @api_client.build_collection_param(opts[:'ids'], :csv) if !opts[:'ids'].nil?
@@ -7882,6 +7888,7 @@ module XeroRuby
     # @option opts [Integer] :page e.g. page&#x3D;1 - Up to 100 contacts will be returned in a single API call.
     # @option opts [Boolean] :include_archived e.g. includeArchived&#x3D;true - Contacts with a status of ARCHIVED will be included in the response
     # @option opts [Boolean] :summary_only Use summaryOnly&#x3D;true in GET Contacts and Invoices endpoint to retrieve a smaller version of the response object. This returns only lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient. (default to false)
+    # @option opts [String] :search_term Search parameter that performs a case-insensitive text search across the Name, FirstName, LastName, ContactNumber and EmailAddress fields.
     # @return [Contacts]
     def get_contacts(xero_tenant_id, opts = {})
       data, _status_code, _headers = get_contacts_with_http_info(xero_tenant_id, opts)
@@ -7898,6 +7905,7 @@ module XeroRuby
     # @option opts [Integer] :page e.g. page&#x3D;1 - Up to 100 contacts will be returned in a single API call.
     # @option opts [Boolean] :include_archived e.g. includeArchived&#x3D;true - Contacts with a status of ARCHIVED will be included in the response
     # @option opts [Boolean] :summary_only Use summaryOnly&#x3D;true in GET Contacts and Invoices endpoint to retrieve a smaller version of the response object. This returns only lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient.
+    # @option opts [String] :search_term Search parameter that performs a case-insensitive text search across the Name, FirstName, LastName, ContactNumber and EmailAddress fields.
     # @return [Array<(Contacts, Integer, Hash)>] Contacts data, response status code and response headers
     def get_contacts_with_http_info(xero_tenant_id, options = {})
       opts = options.dup
@@ -7922,6 +7930,7 @@ module XeroRuby
       query_params[:'page'] = opts[:'page'] if !opts[:'page'].nil?
       query_params[:'includeArchived'] = opts[:'include_archived'] if !opts[:'include_archived'].nil?
       query_params[:'summaryOnly'] = opts[:'summary_only'] if !opts[:'summary_only'].nil?
+      query_params[:'searchTerm'] = opts[:'search_term'] if !opts[:'search_term'].nil?
       
       # XeroAPI's `IDs` convention openapi-generator does not snake_case properly.. manual over-riding `i_ds` malformations:
       query_params[:'IDs'] = @api_client.build_collection_param(opts[:'ids'], :csv) if !opts[:'ids'].nil?

data/lib/xero-ruby/api/app_store_api.rb

@@ -0,0 +1,87 @@
+=begin
+#Xero AppStore API
+
+#These endpoints are for Xero Partners to interact with the App Store Billing platform
+
+Contact: api@xero.com
+Generated by: https://openapi-generator.tech
+OpenAPI Generator version: 4.3.1
+
+=end
+
+module XeroRuby
+  class AppStoreApi
+    attr_accessor :api_client
+
+    def initialize(api_client = ApiClient.new)
+      @api_client = api_client
+    end
+    # Retrieves a subscription for a given subscriptionId
+    # @param subscription_id [String] Unique identifier for Subscription object
+    # @param [Hash] opts the optional parameters
+    # @return [Subscription]
+    def get_subscription(subscription_id, opts = {})
+      data, _status_code, _headers = get_subscription_with_http_info(subscription_id, opts)
+      data
+    end
+
+    # Retrieves a subscription for a given subscriptionId
+    # @param subscription_id [String] Unique identifier for Subscription object
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(Subscription, Integer, Hash)>] Subscription data, response status code and response headers
+    def get_subscription_with_http_info(subscription_id, options = {})
+      opts = options.dup
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: AppStoreApi.get_subscription ...'
+      end
+      # verify the required parameter 'subscription_id' is set
+      if @api_client.config.client_side_validation && subscription_id.nil?
+        fail ArgumentError, "Missing the required parameter 'subscription_id' when calling AppStoreApi.get_subscription"
+      end
+      # resource path
+      local_var_path = '/subscriptions/{subscriptionId}'.sub('{' + 'subscriptionId' + '}', subscription_id.to_s)
+
+      # camelize keys of incoming `where` opts
+      opts[:'where'] = @api_client.parameterize_where(opts[:'where']) if !opts[:'where'].nil?
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      
+      # XeroAPI's `IDs` convention openapi-generator does not snake_case properly.. manual over-riding `i_ds` malformations:
+      query_params[:'IDs'] = @api_client.build_collection_param(opts[:'ids'], :csv) if !opts[:'ids'].nil?
+      query_params[:'ContactIDs'] = @api_client.build_collection_param(opts[:'contact_ids'], :csv) if !opts[:'contact_ids'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:body] 
+
+      # return_type
+      return_type = opts[:return_type] || 'Subscription' 
+
+      # auth_names
+      auth_names = opts[:auth_names] || ['OAuth2']
+
+      new_options = opts.merge(
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, "AppStoreApi", new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: AppStoreApi#get_subscription\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end