straddle 0.5.0 → 1.0.0

data/lib/straddle/resources/customers.rb

@@ -2,80 +2,101 @@
 
 module Straddle
   module Resources
-    # Customers represent the end users who send or receive payments through your
-    # integration. Each customer undergoes automatic identity verification and fraud
-    # screening upon creation. Use customers to track payment history, manage bank
-    # account connections, and maintain a secure record of all transactions associated
-    # with a user. Customers can be either individuals or businesses with appropriate
-    # compliance checks for each type.
+    # Customers are individuals or businesses that send or receive payments through
+    # your integration.
     class Customers
-      # Customers represent the end users who send or receive payments through your
-      # integration. Each customer undergoes automatic identity verification and fraud
-      # screening upon creation. Use customers to track payment history, manage bank
-      # account connections, and maintain a secure record of all transactions associated
-      # with a user. Customers can be either individuals or businesses with appropriate
-      # compliance checks for each type.
+      # Customers are individuals or businesses that send or receive payments through
+      # your integration.
       # @return [Straddle::Resources::Customers::Review]
       attr_reader :review
 
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::CustomerCreateParams} for more details.
       #
-      # Creates a new customer record and automatically initiates identity, fraud, and
-      # risk assessment scores. This endpoint allows you to create a customer profile
-      # and associate it with paykeys and payments.
+      # Creates a customer and starts identity, fraud, and risk assessments.
       #
       # @overload create(device:, email:, name:, phone:, type:, address: nil, compliance_profile: nil, config: nil, external_id: nil, metadata: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param device [Straddle::Models::DeviceUnmaskedV1] Body param
+      # @param device [Straddle::Models::CustomerDevice] Body param
       #
-      # @param email [String] Body param: The customer's email address.
+      # @param email [String] Body param: Customer email address.
       #
-      # @param name [String] Body param: Full name of the individual or business name.
+      # @param name [String] Body param: Full name for an individual customer or business name for a business
       #
-      # @param phone [String] Body param: The customer's phone number in E.164 format. Mobile number is prefer
+      # @param phone [String] Body param: Customer phone number in E.164 format. A mobile number is preferred.
       #
-      # @param type [Symbol, Straddle::Models::CustomerCreateParams::Type] Body param
+      # @param type [Symbol, Straddle::Models::CustomerType] Body param
       #
-      # @param address [Straddle::Models::CustomerAddressV1, nil] Body param: An object containing the customer's address. **This is optional.** I
+      # @param address [Straddle::Models::CustomerAddress, nil] Body param: Customer postal address. When provided, the object must include all
       #
-      # @param compliance_profile [Straddle::Models::CustomerCreateParams::ComplianceProfile::IndividualComplianceProfile, Straddle::Models::CustomerCreateParams::ComplianceProfile::BusinessComplianceProfile, nil] Body param: An object containing the customer's compliance profile. \*\*This is
-      # op
+      # @param compliance_profile [Straddle::Models::UnmaskedComplianceProfile::IndividualComplianceProfile, Straddle::Models::UnmaskedComplianceProfile::BusinessComplianceProfile, nil] Body param: Customer compliance profile. When provided, the object must include
       #
-      # @param config [Straddle::Models::CustomerCreateParams::Config] Body param
+      # @param config [Straddle::Models::CustomerConfiguration] Body param
       #
-      # @param external_id [String, nil] Body param: Unique identifier for the customer in your database, used for cross-
+      # @param external_id [String, nil] Body param: Unique identifier for the customer in your system.
       #
-      # @param metadata [Hash{Symbol=>String}, nil] Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
+      # @param metadata [Hash{Symbol=>String}, nil] Body param: Up to 20 user-defined key-value pairs associated with the customer.
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::CustomerV1]
+      # @return [Straddle::Models::CustomerResponse]
       #
       # @see Straddle::Models::CustomerCreateParams
       def create(params)
         parsed, options = Straddle::CustomerCreateParams.dump_request(params)
-        header_params =
-          {
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          }
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
           method: :post,
           path: "v1/customers",
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Straddle::CustomerV1,
+          model: Straddle::CustomerResponse,
+          options: options
+        )
+      end
+
+      # Returns a customer by `id`.
+      #
+      # @overload retrieve(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Unique identifier for the customer.
+      #
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
+      #
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
+      #
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::CustomerResponse]
+      #
+      # @see Straddle::Models::CustomerRetrieveParams
+      def retrieve(id, params = {})
+        parsed, options = Straddle::CustomerRetrieveParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["v1/customers/%1$s", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::CustomerResponse,
           options: options
         )
       end
@@ -83,59 +104,57 @@ module Straddle
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::CustomerUpdateParams} for more details.
       #
-      # Updates an existing customer's information. This endpoint allows you to modify
-      # the customer's contact details, PII, and metadata.
+      # Updates an existing customer's profile, status, and metadata.
       #
       # @overload update(id, device:, email:, name:, phone:, status:, address: nil, compliance_profile: nil, external_id: nil, metadata: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String] Path param
+      # @param id [String] Path param: Unique identifier for the customer.
       #
-      # @param device [Straddle::Models::DeviceUnmaskedV1] Body param
+      # @param device [Straddle::Models::CustomerDevice] Body param
       #
-      # @param email [String] Body param: The customer's email address.
+      # @param email [String] Body param: Customer email address.
       #
-      # @param name [String] Body param: The customer's full name or business name.
+      # @param name [String] Body param: Full name for an individual customer or business name for a business
       #
-      # @param phone [String] Body param: The customer's phone number in E.164 format.
+      # @param phone [String] Body param: Customer phone number in E.164 format.
       #
-      # @param status [Symbol, Straddle::Models::CustomerUpdateParams::Status] Body param
+      # @param status [Symbol, Straddle::Models::CustomerStatus] Body param
       #
-      # @param address [Straddle::Models::CustomerAddressV1, nil] Body param: An object containing the customer's address. This is optional, but i
+      # @param address [Straddle::Models::CustomerAddress, nil] Body param: Customer postal address. When provided, the object must include all
       #
-      # @param compliance_profile [Straddle::Models::CustomerUpdateParams::ComplianceProfile::IndividualComplianceProfile, Straddle::Models::CustomerUpdateParams::ComplianceProfile::BusinessComplianceProfile, nil] Body param: Individual PII data required to trigger Patriot Act compliant KYC ve
+      # @param compliance_profile [Straddle::Models::UnmaskedComplianceProfile::IndividualComplianceProfile, Straddle::Models::UnmaskedComplianceProfile::BusinessComplianceProfile, nil] Body param
       #
-      # @param external_id [String, nil] Body param: Unique identifier for the customer in your database, used for cross-
+      # @param external_id [String, nil] Body param: Unique identifier for the customer in your system.
       #
-      # @param metadata [Hash{Symbol=>String}, nil] Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
+      # @param metadata [Hash{Symbol=>String}, nil] Body param: Up to 20 user-defined key-value pairs associated with the customer.
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param idempotency_key [String] Header param: Optional client generated value to use for idempotent requests.
+      # @param idempotency_key [String] Header param: Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an account id and set scope of a r
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::CustomerV1]
+      # @return [Straddle::Models::CustomerResponse]
       #
       # @see Straddle::Models::CustomerUpdateParams
       def update(id, params)
         parsed, options = Straddle::CustomerUpdateParams.dump_request(params)
-        header_params =
-          {
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          }
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id",
+          straddle_account_id: "straddle-account-id"
+        }
         @client.request(
           method: :put,
           path: ["v1/customers/%1$s", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Straddle::CustomerV1,
+          model: Straddle::CustomerResponse,
           options: options
         )
       end
@@ -143,10 +162,8 @@ module Straddle
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::CustomerListParams} for more details.
       #
-      # Lists or searches customers connected to your account. All supported query
-      # parameters are optional. If none are provided, the response will include all
-      # customers connected to your account. This endpoint supports advanced sorting and
-      # filtering options.
+      # Returns a paginated list of customers for the account. Optional query parameters
+      # filter, search, and sort the results.
       #
       # @overload list(created_from: nil, created_to: nil, email: nil, external_id: nil, name: nil, page_number: nil, page_size: nil, search_text: nil, sort_by: nil, sort_order: nil, status: nil, types: nil, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
@@ -166,77 +183,75 @@ module Straddle
       #
       # @param search_text [String] Query param: General search term to filter customers.
       #
-      # @param sort_by [Symbol, Straddle::Models::CustomerListParams::SortBy] Query param
+      # @param sort_by [Symbol, Straddle::Models::CustomerListParams::SortBy] Query param: Field used to sort the results.
       #
-      # @param sort_order [Symbol, Straddle::Models::CustomerListParams::SortOrder] Query param
+      # @param sort_order [Symbol, Straddle::Models::SortOrder] Query param: Order in which to sort the results.
       #
-      # @param status [Array<Symbol, Straddle::Models::CustomerListParams::Status>] Query param: Filter customers by their current `status`.
+      # @param status [Array<Symbol, Straddle::Models::CustomerStatus>] Query param: Filter customers by their current `status`.
       #
-      # @param types [Array<Symbol, Straddle::Models::CustomerListParams::Type>] Query param: Filter by customer type `individual` or `business`.
+      # @param types [Array<Symbol, Straddle::Models::CustomerType>] Query param: Filter by customer type `individual` or `business`.
       #
-      # @param correlation_id [String] Header param: Optional client generated identifier to trace and debug a series o
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @param request_id [String] Header param: Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] Header param: For use by platforms to specify an `account_id` to set the scope o
+      # @param straddle_account_id [String] Header param: For platform requests, the embedded account UUID that sets the req
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Internal::PageNumberSchema<Straddle::Models::CustomerSummaryPagedV1::Data>]
+      # @return [Straddle::Models::CustomerSummaryList]
       #
       # @see Straddle::Models::CustomerListParams
       def list(params = {})
-        query_params =
-          [
-            :created_from,
-            :created_to,
-            :email,
-            :external_id,
-            :name,
-            :page_number,
-            :page_size,
-            :search_text,
-            :sort_by,
-            :sort_order,
-            :status,
-            :types
-          ]
+        query_params = %i[
+          created_from
+          created_to
+          email
+          external_id
+          name
+          page_number
+          page_size
+          search_text
+          sort_by
+          sort_order
+          status
+          types
+        ]
         parsed, options = Straddle::CustomerListParams.dump_request(params)
         query = Straddle::Internal::Util.encode_query_params(parsed.slice(*query_params))
         @client.request(
           method: :get,
           path: "v1/customers",
           query: query,
-          headers: parsed.except(*query_params).transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          page: Straddle::Internal::PageNumberSchema,
-          model: Straddle::CustomerSummaryPagedV1::Data,
+          headers:
+            parsed.except(*query_params).transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::CustomerSummaryList,
           options: options
         )
       end
 
-      # Permanently removes a customer record from Straddle. This action cannot be
-      # undone and should only be used to satisfy regulatory requirements or for privacy
-      # compliance.
+      # Permanently deletes a customer record. The deletion cannot be undone. Use this
+      # endpoint only to meet regulatory or privacy requirements.
       #
       # @overload delete(id, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String]
+      # @param id [String] Unique identifier for the customer.
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      # @param idempotency_key [String] Optional client generated value to use for idempotent requests.
+      # @param idempotency_key [String] Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::CustomerV1]
+      # @return [Straddle::Models::CustomerResponse]
       #
       # @see Straddle::Models::CustomerDeleteParams
       def delete(id, params = {})
@@ -244,83 +259,86 @@ module Straddle
         @client.request(
           method: :delete,
           path: ["v1/customers/%1$s", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            idempotency_key: "idempotency-key",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::CustomerV1,
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              idempotency_key: "idempotency-key",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::CustomerResponse,
           options: options
         )
       end
 
-      # Retrieves the details of an existing customer. Supply the unique customer ID
-      # that was returned from your 'create customer' request, and Straddle will return
-      # the corresponding customer information.
+      # Returns unmasked details for a customer, including personally identifiable
+      # information. Straddle must enable this endpoint for your account. Use this
+      # endpoint only when unmasked data is necessary.
       #
-      # @overload get(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @overload list_unmasked(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param id [String]
+      # @param id [String] Unique identifier for the customer.
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::CustomerV1]
+      # @return [Straddle::Models::UnmaskedCustomerResponse]
       #
-      # @see Straddle::Models::CustomerGetParams
-      def get(id, params = {})
-        parsed, options = Straddle::CustomerGetParams.dump_request(params)
+      # @see Straddle::Models::CustomerListUnmaskedParams
+      def list_unmasked(id, params = {})
+        parsed, options = Straddle::CustomerListUnmaskedParams.dump_request(params)
         @client.request(
           method: :get,
-          path: ["v1/customers/%1$s", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::CustomerV1,
+          path: ["v1/customers/%1$s/unmasked", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::UnmaskedCustomerResponse,
           options: options
         )
       end
 
-      # Retrieves the unmasked details, including PII, of an existing customer. Supply
-      # the unique customer ID that was returned from your 'create customer' request,
-      # and Straddle will return the corresponding customer information. This endpoint
-      # needs to be enabled by Straddle and should only be used when absolutely
-      # necessary.
+      # Starts a new identity review for a customer. The review runs asynchronously.
+      # Webhooks and the customer review endpoint return updated results.
+      #
+      # @overload refresh_review(id, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @overload unmasked(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # @param id [String] Unique identifier for the customer.
       #
-      # @param id [String]
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param idempotency_key [String] Optional client-generated key for an idempotent request.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param straddle_account_id [String] For platform requests, the embedded account UUID that sets the request scope.
       #
       # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Straddle::Models::CustomerUnmaskedV1]
+      # @return [Straddle::Models::CustomerResponse]
       #
-      # @see Straddle::Models::CustomerUnmaskedParams
-      def unmasked(id, params = {})
-        parsed, options = Straddle::CustomerUnmaskedParams.dump_request(params)
+      # @see Straddle::Models::CustomerRefreshReviewParams
+      def refresh_review(id, params = {})
+        parsed, options = Straddle::CustomerRefreshReviewParams.dump_request(params)
         @client.request(
-          method: :get,
-          path: ["v1/customers/%1$s/unmasked", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::CustomerUnmaskedV1,
+          method: :put,
+          path: ["v1/customers/%1$s/refresh_review", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              idempotency_key: "idempotency-key",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::CustomerResponse,
           options: options
         )
       end