plaid 4.1.0 → 5.0.0

data/lib/plaid/products/item.rb

@@ -1,21 +1,27 @@
 module Plaid
   # Public: Class used to call the AccessToken sub-product.
-  class AccessToken
-    def initialize(client)
-      @client = client
-    end
-
+  class AccessToken < BaseProduct
     # Public: Rotate your access_token, keeping it attached to the item
     #
-    # Does a POST /item/access_token/invalidate call which will give you a new access_token
-    # allowing you to rotate access_tokens
+    # Does a POST /item/access_token/invalidate call which will give you a new
+    # access_token allowing you to rotate access_tokens.
     #
-    # access_token - access_token to invalidate and rotate
+    # access_token - The String access_token to invalidate and rotate.
     #
-    # Returns a parsed JSON with the new access_token and request id
+    # Returns an InvalidateResponse object with the new access_token and
+    # request id.
     def invalidate(access_token)
-      payload = { access_token: access_token }
-      @client.post_with_auth('item/access_token/invalidate', payload)
+      post_with_auth 'item/access_token/invalidate',
+                     InvalidateResponse,
+                     access_token: access_token
+    end
+
+    # Public: Response for /item/access_token/invalidate.
+    class InvalidateResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The String new access token.
+      property :new_access_token
     end
 
     # Public: Generate a new API access_token for a legacy access_token
@@ -25,136 +31,188 @@ module Plaid
     #
     # access_token_v1 - legacy access_token
     #
-    # Returns a parsed JSON with the new access_token and request id
+    # Returns an UpdateVersionResponse object with new access_token and item
+    # ID.
     def update_version(access_token_v1)
-      payload = { access_token_v1: access_token_v1 }
-      @client.post_with_auth('item/access_token/update_version', payload)
+      post_with_auth 'item/access_token/update_version',
+                     UpdateVersionResponse,
+                     access_token_v1: access_token_v1
     end
-  end
 
-  # Public: Class used to call the Credentials sub-product.
-  class Credentials
-    def initialize(client)
-      @client = client
+    # Public: Response for /item/access_token/update_version.
+    class UpdateVersionResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The String new access token for use.
+      property :access_token
+
+      ##
+      # :attr_reader:
+      # Public: The String item ID.
+      property :item_id
     end
+  end
 
+  # Public: Class used to call the Credentials sub-product.
+  class Credentials < BaseProduct
     # Public: Update credentials for an access_token.
     #
-    # Does a POST /item/credentials/update call which is used to update credentials
-    # if the credentials become no longer valid
+    # Does a POST /item/credentials/update call which is used to update
+    # credentials if the credentials become no longer valid.
     #
     # access_token - access_token who's item to update credentials for
     # credentials  - New credentials
     #
-    # Returns a parsed JSON of either an ItemStatus or MFA response
+    # Returns an UpdateResponse object with either an ItemStatus or MFA
+    # response.
     def update(access_token, credentials)
-      payload = { access_token: access_token,
-                  credentials: credentials }
-      @client.post_with_auth('item/credentials/update', payload)
+      post_with_auth 'item/credentials/update',
+                     UpdateResponse,
+                     access_token: access_token,
+                     credentials: credentials
     end
-  end
 
-  # Public: Class used to call the PublicToken sub-product
-  class PublicToken
-    def initialize(client)
-      @client = client
+    # Public: Response for /item/credentials/update.
+    class UpdateResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The item: Plaid::Models::Item.
+      property :item, coerce: Models::Item
     end
+  end
 
+  # Public: Class used to call the PublicToken sub-product
+  class PublicToken < BaseProduct
     # Public: Creates a public token from an access_token.
     #
-    # Does a POST /item/public_token/create call which can be used to initialize Link
-    # in update mode
+    # Does a POST /item/public_token/create call which can be used to
+    # initialize Link in update mode.
     #
     # access_token - access_token to create a public token for
     #
-    # Returns a parsed JSON containing a public token and token info
+    # Returns a CreateResponse object with a public token and expiration info.
     def create(access_token)
-      payload = { access_token: access_token }
-      @client.post_with_auth('item/public_token/create', payload)
+      post_with_auth 'item/public_token/create',
+                     CreateResponse,
+                     access_token: access_token
+    end
+
+    # Public: Response for /item/public_token/create.
+    class CreateResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The String token.
+      property :public_token
+
+      ##
+      # :attr_reader:
+      # Public: The String token expiration time.
+      property :expiration
     end
 
     # Public: Exchange a public token for an access_token
     #
-    # Does a POST /item/public_token/exchange call helps you exchange a public token
-    # (possibly from Plaid Link) for an access_token you can use in the rest of your app
+    # Does a POST /item/public_token/exchange call helps you exchange a public
+    # token (possibly from Plaid Link) for an access_token you can use in the
+    # rest of your app.
     #
-    # public_token - Public token to get an access_token from
+    # public_token - The Public token to get an access_token from.
     #
-    # Returns a parsed JSON with an access_token and request id
+    # Returns an ExchangeResponse object with an access_token and request id.
     def exchange(public_token)
-      payload = { public_token: public_token }
-      @client.post_with_auth('item/public_token/exchange', payload)
+      post_with_auth 'item/public_token/exchange',
+                     ExchangeResponse,
+                     public_token: public_token
     end
-  end
 
-  # Public: Class used to call the Webhook sub-product
-  class Webhook
-    def initialize(client)
-      @client = client
+    # Public: Response for /item/public_token/exchange.
+    class ExchangeResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The String access token for use with API.
+      property :access_token
+
+      ##
+      # :attr_reader:
+      # Public: The String item ID.
+      property :item_id
     end
+  end
 
-    # Public: Update webhook for an access_token
+  # Public: Class used to call the Webhook sub-product
+  class Webhook < BaseProduct
+    # Public: Update webhook for an access_token.
     #
     # Does a POST /item/webhook/update call which is used to update webhook
-    # for a particular access_token, webhooks are used to be notified when
-    # transactions for an item are updated and ready
+    # for a particular access_token. Webhooks are used to be notified when
+    # transactions for an item are updated and ready.
     #
-    # access_token - access_token who's item to update webhood for
-    # webhook      - a new webhook link
+    # access_token - The access_token of an item to update webhook for.
+    # webhook      - The new webhook link.
     #
-    # Returns a parsed JSON of either an ItemStatus or MFA response
+    # Returns an UpdateResponse object with either an ItemStatus or MFA
+    # response.
     def update(access_token, webhook)
-      payload = { access_token: access_token,
-                  webhook: webhook }
-      @client.post_with_auth('item/webhook/update', payload)
+      post_with_auth 'item/webhook/update',
+                     UpdateResponse,
+                     access_token: access_token,
+                     webhook: webhook
+    end
+
+    # Public: Response for /item/webhook/update.
+    class UpdateResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The item: Plaid::Models::Item.
+      property :item, coerce: Models::Item
     end
   end
 
   # Public: Class used to call the Item product.
-  class Item
-    # Public: Memoized class instance to make requests from Plaid::AccessToken
-    def access_token
-      @access_token ||= Plaid::AccessToken.new(@client)
-    end
+  class Item < BaseProduct
+    ##
+    # :attr_reader:
+    # Public: The Plaid::AccessToken product accessor.
+    subproduct :access_token
 
-    # Public: Memoized class instance to make requests from Plaid::Credentials
-    def credentials
-      @credentials ||= Plaid::Credentials.new(@client)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Credentials product accessor.
+    subproduct :credentials
 
-    # Public: Memoized class instance to make requests from Plaid::PublicToken
-    def public_token
-      @public_token ||= Plaid::PublicToken.new(@client)
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::PublicToken product accessor.
+    subproduct :public_token
 
-    # Public: Memoized class instance to make requests from Plaid::Webhook
-    def webhook
-      @webhook ||= Plaid::Webhook.new(@client)
-    end
-
-    def initialize(client)
-      @client = client
-    end
+    ##
+    # :attr_reader:
+    # Public: The Plaid::Webhook product accessor.
+    subproduct :webhook
 
     # Public: Creates an item.
     #
     # Does a POST /item/create call which attemps to create a new item for you
-    # possibly returning a success, error, or multi-factor authentication response
-    #
-    # credentials                 - Institution credentials to create item with
-    # institution_id              - Institution ID to create item with
-    # initial_products            - Initial products to create the item with i.e. ['transactions']
-    # transactions_start_date     - date at which to begin the item's initial transaction pull
-    #                              (optional)
-    # transactions_end_date       - date at which to end the item's initial transaction pull
-    #                              (optional)
-    # transactions_await_results  - if true, the initial transaction pull will be performed
-    #                              synchronously (optional)
-    # webhook                     - webhook to associate with the item (optional)
-    # options                     - Additional options to merge into API request
-    #
-    # Returns a parsed JSON of item info including access_token and ItemStatus or
-    # MFA response or error
+    # possibly returning a success, error, or multi-factor authentication
+    # response.
+    #
+    # credentials                - Institution credentials to create item with.
+    # institution_id             - Institution ID to create item with.
+    # initial_products           - Initial products to create the item with,
+    #                              i.e. [:transactions].
+    # transactions_start_date    - date at which to begin the item's initial
+    #                              transaction pull (optional).
+    # transactions_end_date      - date at which to end the item's initial
+    #                              transaction pull (optional).
+    # transactions_await_results - if true, the initial transaction pull will
+    #                              be performed synchronously (optional).
+    # webhook                    - webhook to associate with the item
+    #                              (optional).
+    # options                    - Additional options to merge into API
+    #                              request.
+    #
+    # Returns an ItemResponse object with item info including access_token and
+    # ItemStatus, or MFA response or error.
     def create(credentials:,
                institution_id:,
                initial_products:,
@@ -164,67 +222,115 @@ module Plaid
                webhook: nil,
                options: nil)
 
-      transactions_options = {}
-      unless transactions_start_date.nil?
-        transactions_options[:start_date] = Plaid.convert_to_date_string(transactions_start_date)
-      end
-      unless transactions_end_date.nil?
-        transactions_options[:end_date] = Plaid.convert_to_date_string(transactions_end_date)
-      end
-      unless transactions_await_results.nil?
-        transactions_options[:await_results] = transactions_await_results
-      end
-
       options_payload = {}
-      options_payload[:transactions] = transactions_options if transactions_options != {}
+
+      txn_options = transaction_options transactions_start_date,
+                                        transactions_end_date,
+                                        transactions_await_results
+
+      options_payload[:transactions] = txn_options if txn_options != {}
       options_payload[:webhook] = webhook unless webhook.nil?
       options_payload = options_payload.merge(options) unless options.nil?
 
-      payload = { credentials: credentials,
-                  institution_id: institution_id,
-                  initial_products: initial_products,
-                  options: options_payload }
-      @client.post_with_auth('item/create', payload)
+      post_with_auth 'item/create',
+                     ItemResponse,
+                     credentials: credentials,
+                     institution_id: institution_id,
+                     initial_products: initial_products,
+                     options: options_payload
+    end
+
+    private def transaction_options(start_date, end_date, await_results)
+      {}.tap do |options|
+        options[:start_date] = Plaid.convert_to_date_string(start_date) \
+          if start_date
+
+        options[:end_date] = Plaid.convert_to_date_string(end_date) \
+          if end_date
+
+        options[:await_results] = await_results if await_results
+      end
+    end
+
+    # Public: Response for /item/create and /item/mfa endpoints.
+    class ItemResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The String access_token to use with API.
+      property :access_token
+
+      ##
+      # :attr_reader:
+      # Public: The Plaid::Models::Item object, returned if item has been
+      # successfully created.
+      property :item, coerce: Models::Item
+
+      ##
+      # :attr_reader:
+      # Public: The MFA/OTP device information: Plaid::Models::MFA::Device.
+      property :device, coerce: Models::MFA::Device
+
+      ##
+      # :attr_reader:
+      # Public: The list of devices to send the OTP to:
+      # Array of Plaid::Models::MFA::DeviceListElement.
+      property :device_list, coerce: Array[Models::MFA::DeviceListElement]
+
+      ##
+      # :attr_reader:
+      # Public: The String MFA type. E.g. "device_list", "device", "questions",
+      # "selections".
+      property :mfa_type
+
+      ##
+      # :attr_reader:
+      # Public: The Array of String MFA questions.
+      property :questions
+
+      ##
+      # :attr_reader:
+      # Public: The Array of MFA selections: Plaid::Models::MFA::Selection.
+      property :selections, coerce: Array[Models::MFA::Selection]
     end
 
     # Public: Submit an MFA step.
     #
-    # Does a POST /item/mfa call which gives you the ability to response to an MFA
+    # Does a POST /item/mfa call which gives you the ability to respond to an
+    # MFA.
     #
-    # access_token - To submit MFA step for
-    # mfa_type     - The MFA type indicated in the MFA response
-    # responses    - List of answers/responses to MFA
+    # access_token - To submit MFA step for.
+    # mfa_type     - The MFA type indicated in the MFA response.
+    # responses    - List of answers/responses to MFA.
     #
-    # Returns a parsed JSON of ItemStatus or another MFA step
+    # Returns an ItemResponse instance.
     def mfa(access_token, mfa_type, responses)
-      payload = { access_token: access_token,
-                  mfa_type: mfa_type,
-                  responses: responses }
-      @client.post_with_auth('item/mfa', payload)
+      post_with_auth 'item/mfa',
+                     ItemResponse,
+                     access_token: access_token,
+                     mfa_type: mfa_type,
+                     responses: responses
     end
 
-    # Public: Get information about an item
+    # Public: Get information about an item.
     #
-    # Does a POST /item/get call which returns information about an item or ItemStatus
+    # Does a POST /item/get call which returns information about an item or
+    # ItemStatus.
     #
     # access_token - access_token who's item to fetch status for
     #
-    # Returns a parsed JSON of item information
+    # Returns a GetResponse object with item information.
     def get(access_token)
-      payload = { access_token: access_token }
-      @client.post_with_auth('item/get', payload)
+      post_with_auth 'item/get',
+                     GetResponse,
+                     access_token: access_token
     end
 
-    # Public: Deletes an item
-    #
-    # Does a POST /item/delete call which is used to delete an item
-    #
-    # access_token - access_token who's item to delete
-    #
-    # Returns a parsed JSON of delete result
-    def delete(access_token)
-      payload = { access_token: access_token }
-      @client.post_with_auth('item/delete', payload)
+    # Public: Response for /item/get.
+    class GetResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The item: Plaid::Models::Item.
+      property :item, coerce: Models::Item
     end
 
     # Public: Removes an item
@@ -233,10 +339,19 @@ module Plaid
     #
     # access_token - access_token who's item to remove
     #
-    # Returns a parsed JSON of remove result
+    # Returns a RemoveResponse object with remove result.
     def remove(access_token)
-      payload = { access_token: access_token }
-      @client.post_with_auth('item/remove', payload)
+      post_with_auth 'item/remove',
+                     RemoveResponse,
+                     access_token: access_token
+    end
+
+    # Public: Response for /item/remove.
+    class RemoveResponse < Models::BaseResponse
+      ##
+      # :attr_reader:
+      # Public: The Boolean flag meaning successful removal.
+      property :removed
     end
   end
 end