straddle 0.4.0 → 1.0.0

data/rbi/straddle/resources/customers.rbi

@@ -2,41 +2,31 @@
 
 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.
       sig { returns(Straddle::Resources::Customers::Review) }
       attr_reader :review
 
-      # 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.
       sig do
         params(
-          device: Straddle::DeviceUnmaskedV1::OrHash,
+          device: Straddle::CustomerDevice::OrHash,
           email: String,
           name: String,
           phone: String,
-          type: Straddle::CustomerCreateParams::Type::OrSymbol,
-          address: T.nilable(Straddle::CustomerAddressV1::OrHash),
+          type: Straddle::CustomerType::OrSymbol,
+          address: T.nilable(Straddle::CustomerAddress::OrHash),
           compliance_profile:
             T.nilable(
               T.any(
-                Straddle::CustomerCreateParams::ComplianceProfile::IndividualComplianceProfile::OrHash,
-                Straddle::CustomerCreateParams::ComplianceProfile::BusinessComplianceProfile::OrHash
+                Straddle::UnmaskedComplianceProfile::IndividualComplianceProfile::OrHash,
+                Straddle::UnmaskedComplianceProfile::BusinessComplianceProfile::OrHash
               )
             ),
-          config: Straddle::CustomerCreateParams::Config::OrHash,
+          config: Straddle::CustomerConfiguration::OrHash,
           external_id: T.nilable(String),
           metadata: T.nilable(T::Hash[Symbol, String]),
           correlation_id: String,
@@ -44,65 +34,84 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::CustomerV1)
+        ).returns(Straddle::CustomerResponse)
       end
       def create(
         # Body param
         device:,
-        # Body param: The customer's email address.
+        # Body param: Customer email address.
         email:,
-        # Body param: Full name of the individual or business name.
+        # Body param: Full name for an individual customer or business name for a business
+        # customer.
         name:,
-        # Body param: The customer's phone number in E.164 format. Mobile number is
-        # preferred.
+        # Body param: Customer phone number in E.164 format. A mobile number is preferred.
         phone:,
         # Body param
         type:,
-        # Body param: An object containing the customer's address. **This is optional.**
-        # If used, all required fields must be present.
+        # Body param: Customer postal address. When provided, the object must include all
+        # required fields.
         address: nil,
-        # Body param: An object containing the customer's compliance profile. **This is
-        # optional.** If all required fields must be present for the appropriate customer
-        # type.
+        # Body param: Customer compliance profile. When provided, the object must include
+        # all fields required for the customer type.
         compliance_profile: nil,
         # Body param
         config: nil,
-        # Body param: Unique identifier for the customer in your database, used for
-        # cross-referencing between Straddle and your systems.
+        # Body param: Unique identifier for the customer in your system.
         external_id: nil,
-        # Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
-        # additional information about the customer in a structured format.
+        # Body param: Up to 20 user-defined key-value pairs associated with the customer.
         metadata: nil,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated value to use for idempotent requests.
+        # Header param: Optional client-generated key for an idempotent request.
         idempotency_key: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Updates an existing customer's information. This endpoint allows you to modify
-      # the customer's contact details, PII, and metadata.
+      # Returns a customer by `id`.
       sig do
         params(
           id: String,
-          device: Straddle::DeviceUnmaskedV1::OrHash,
+          correlation_id: String,
+          request_id: String,
+          straddle_account_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::CustomerResponse)
+      end
+      def retrieve(
+        # Unique identifier for the customer.
+        id,
+        # Optional client-generated identifier for tracing a series of related requests.
+        correlation_id: nil,
+        # Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        # For platform requests, the embedded account UUID that sets the request scope.
+        straddle_account_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Updates an existing customer's profile, status, and metadata.
+      sig do
+        params(
+          id: String,
+          device: Straddle::CustomerDevice::OrHash,
           email: String,
           name: String,
           phone: String,
-          status: Straddle::CustomerUpdateParams::Status::OrSymbol,
-          address: T.nilable(Straddle::CustomerAddressV1::OrHash),
+          status: Straddle::CustomerStatus::OrSymbol,
+          address: T.nilable(Straddle::CustomerAddress::OrHash),
           compliance_profile:
             T.nilable(
               T.any(
-                Straddle::CustomerUpdateParams::ComplianceProfile::IndividualComplianceProfile::OrHash,
-                Straddle::CustomerUpdateParams::ComplianceProfile::BusinessComplianceProfile::OrHash
+                Straddle::UnmaskedComplianceProfile::IndividualComplianceProfile::OrHash,
+                Straddle::UnmaskedComplianceProfile::BusinessComplianceProfile::OrHash
               )
             ),
           external_id: T.nilable(String),
@@ -112,51 +121,47 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::CustomerV1)
+        ).returns(Straddle::CustomerResponse)
       end
       def update(
-        # Path param
+        # Path param: Unique identifier for the customer.
         id,
         # Body param
         device:,
-        # Body param: The customer's email address.
+        # Body param: Customer email address.
         email:,
-        # Body param: The customer's full name or business name.
+        # Body param: Full name for an individual customer or business name for a business
+        # customer.
         name:,
-        # Body param: The customer's phone number in E.164 format.
+        # Body param: Customer phone number in E.164 format.
         phone:,
         # Body param
         status:,
-        # Body param: An object containing the customer's address. This is optional, but
-        # if provided, all required fields must be present.
+        # Body param: Customer postal address. When provided, the object must include all
+        # required fields.
         address: nil,
-        # Body param: Individual PII data required to trigger Patriot Act compliant KYC
-        # verification.
+        # Body param
         compliance_profile: nil,
-        # Body param: Unique identifier for the customer in your database, used for
-        # cross-referencing between Straddle and your systems.
+        # Body param: Unique identifier for the customer in your system.
         external_id: nil,
-        # Body param: Up to 20 additional user-defined key-value pairs. Useful for storing
-        # additional information about the customer in a structured format.
+        # Body param: Up to 20 user-defined key-value pairs associated with the customer.
         metadata: nil,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated value to use for idempotent requests.
+        # Header param: Optional client-generated key for an idempotent request.
         idempotency_key: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # 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.
       sig do
         params(
           created_from: Time,
@@ -168,18 +173,14 @@ module Straddle
           page_size: Integer,
           search_text: String,
           sort_by: Straddle::CustomerListParams::SortBy::OrSymbol,
-          sort_order: Straddle::CustomerListParams::SortOrder::OrSymbol,
-          status: T::Array[Straddle::CustomerListParams::Status::OrSymbol],
-          types: T::Array[Straddle::CustomerListParams::Type::OrSymbol],
+          sort_order: Straddle::SortOrder::OrSymbol,
+          status: T::Array[Straddle::CustomerStatus::OrSymbol],
+          types: T::Array[Straddle::CustomerType::OrSymbol],
           correlation_id: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(
-          Straddle::Internal::PageNumberSchema[
-            Straddle::CustomerSummaryPagedV1::Data
-          ]
-        )
+        ).returns(Straddle::CustomerSummaryList)
       end
       def list(
         # Query param: Start date for filtering by `created_at` date.
@@ -198,29 +199,28 @@ module Straddle
         page_size: nil,
         # Query param: General search term to filter customers.
         search_text: nil,
-        # Query param
+        # Query param: Field used to sort the results.
         sort_by: nil,
-        # Query param
+        # Query param: Order in which to sort the results.
         sort_order: nil,
         # Query param: Filter customers by their current `status`.
         status: nil,
         # Query param: Filter by customer type `individual` or `business`.
         types: nil,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an `account_id` to set the scope
-        # of a request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_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.
       sig do
         params(
           id: String,
@@ -229,25 +229,26 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::CustomerV1)
+        ).returns(Straddle::CustomerResponse)
       end
       def delete(
+        # Unique identifier for the customer.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Optional client-generated identifier for tracing a series of related requests.
         correlation_id: nil,
-        # Optional client generated value to use for idempotent requests.
+        # Optional client-generated key for an idempotent request.
         idempotency_key: nil,
-        # Optional client generated identifier to trace and debug a request.
+        # Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # For use by platforms to specify an account id and set scope of a request.
+        # For platform requests, the embedded account UUID that sets the request scope.
         straddle_account_id: nil,
         request_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.
       sig do
         params(
           id: String,
@@ -255,41 +256,43 @@ module Straddle
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::CustomerV1)
+        ).returns(Straddle::UnmaskedCustomerResponse)
       end
-      def get(
+      def list_unmasked(
+        # Unique identifier for the customer.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Optional client-generated identifier for tracing a series of related requests.
         correlation_id: nil,
-        # Optional client generated identifier to trace and debug a request.
+        # Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # For use by platforms to specify an account id and set scope of a request.
+        # For platform requests, the embedded account UUID that sets the request scope.
         straddle_account_id: nil,
         request_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.
       sig do
         params(
           id: String,
           correlation_id: String,
+          idempotency_key: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::CustomerUnmaskedV1)
+        ).returns(Straddle::CustomerResponse)
       end
-      def unmasked(
+      def refresh_review(
+        # Unique identifier for the customer.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Optional client-generated identifier for tracing a series of related requests.
         correlation_id: nil,
-        # Optional client generated identifier to trace and debug a request.
+        # Optional client-generated key for an idempotent request.
+        idempotency_key: nil,
+        # Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # For use by platforms to specify an account id and set scope of a request.
+        # For platform requests, the embedded account UUID that sets the request scope.
         straddle_account_id: nil,
         request_options: {}
       )

data/rbi/straddle/resources/funding_events.rbi

@@ -2,114 +2,180 @@
 
 module Straddle
   module Resources
-    # Funding events represent all money movement between Straddle and an Account's
-    # external bank accounts. They are automatically generated when charges settle or
-    # payouts are initiated. Each event provides detailed tracking of settlement
-    # status, fee breakdowns, and reconciliation data across both incoming and
-    # outgoing transfers. Use funding events to monitor your platform's entire money
-    # movement lifecycle.
+    # Funding events group charge and payout activity into transfers between Straddle
+    # and your linked bank account.
     class FundingEvents
-      # Retrieves a list of funding events for your account. This endpoint supports
-      # advanced sorting and filtering options.
+      # Returns a funding event by its unique identifier, including its current status,
+      # status history, and linked bank account details when available.
+      sig do
+        params(
+          id: String,
+          correlation_id: String,
+          request_id: String,
+          straddle_account_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::FundingEventResponse)
+      end
+      def retrieve(
+        # Unique identifier for the funding event.
+        id,
+        # Optional client-generated identifier for tracing a series of related requests.
+        correlation_id: nil,
+        # Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        # For platform requests, the embedded account UUID that sets the request scope.
+        straddle_account_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns a paginated list of funding events that match the specified filters.
       sig do
         params(
           created_from: T.nilable(Date),
           created_to: T.nilable(Date),
-          direction: Straddle::FundingEventListParams::Direction::OrSymbol,
-          event_type: Straddle::FundingEventListParams::EventType::OrSymbol,
+          direction: Straddle::TransferDirection::OrSymbol,
+          event_type: Straddle::FundingEventType::OrSymbol,
           page_number: Integer,
           page_size: Integer,
           search_text: T.nilable(String),
           sort_by: Straddle::FundingEventListParams::SortBy::OrSymbol,
-          sort_order: Straddle::FundingEventListParams::SortOrder::OrSymbol,
-          status:
-            T.nilable(
-              T::Array[Straddle::FundingEventListParams::Status::OrSymbol]
-            ),
+          sort_order: Straddle::SortOrder::OrSymbol,
+          status: T.nilable(T::Array[Straddle::PaymentStatus::OrSymbol]),
           status_reason:
-            T.nilable(
-              T::Array[Straddle::FundingEventListParams::StatusReason::OrSymbol]
-            ),
+            T.nilable(T::Array[Straddle::PaymentStatusReason::OrSymbol]),
           status_source:
-            T.nilable(
-              T::Array[Straddle::FundingEventListParams::StatusSource::OrSymbol]
-            ),
+            T.nilable(T::Array[Straddle::PaymentStatusSource::OrSymbol]),
           trace_id: T.nilable(String),
           trace_number: T.nilable(String),
           correlation_id: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(
-          Straddle::Internal::PageNumberSchema[
-            Straddle::FundingEventSummaryPagedV1::Data
-          ]
-        )
+        ).returns(Straddle::FundingEventSummaryList)
       end
       def list(
-        # Query param: The start date of the range to filter by using the `YYYY-MM-DD`
-        # format.
+        # Query param: Filter to funding events created on or after this date.
         created_from: nil,
-        # Query param: The end date of the range to filter by using the `YYYY-MM-DD`
-        # format.
+        # Query param: Filter to funding events created on or before this date.
         created_to: nil,
-        # Query param: Describes the direction of the funding event from the perspective
-        # of the `linked_bank_account`.
+        # Query param: Filter by transfer direction relative to the linked bank account.
         direction: nil,
-        # Query param: The funding event types describes the direction and reason for the
-        # funding event.
+        # Query param: Filter by funding event type.
         event_type: nil,
         # Query param: Results page number. Starts at page 1.
         page_number: nil,
-        # Query param: Results page size. Max value: 1000
+        # Query param: Results page size. Max value: 1000.
         page_size: nil,
-        # Query param: Search text.
+        # Query param: Free-text search across funding event fields.
         search_text: nil,
-        # Query param: The field to sort the results by.
+        # Query param: Field used to sort the results.
         sort_by: nil,
-        # Query param: The order in which to sort the results.
+        # Query param: Order in which to sort the results.
         sort_order: nil,
-        # Query param: Funding Event status.
+        # Query param: Filter by funding event status.
         status: nil,
-        # Query param: Reason for latest payment status change.
+        # Query param: Filter by the reason for the most recent status change.
         status_reason: nil,
-        # Query param: Source of latest payment status change.
+        # Query param: Filter by the source of the most recent status change.
         status_source: nil,
-        # Query param: Trace Id.
+        # Query param: Filter by a network-level trace identifier assigned during
+        # processing.
         trace_id: nil,
-        # Query param: Trace number.
+        # Query param: Filter by a network trace number assigned during processing.
         trace_number: nil,
-        # Header param: Optional client generated identifier to trace and debug a series
-        # of requests.
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Header param: Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # Header param: For use by platforms to specify an account id and set scope of a
-        # request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )
       end
 
-      # Retrieves the details of an existing funding event. Supply the unique funding
-      # event `id`, and Straddle will return the individual transaction items that make
-      # up the funding event.
+      # Returns a paginated list of payments included in the funding event.
       sig do
         params(
           id: String,
+          default_page_size: Integer,
+          default_sort:
+            Straddle::FundingEventListPaymentsParams::DefaultSort::OrSymbol,
+          default_sort_order: Straddle::SortOrder::OrSymbol,
+          include_metadata: T::Boolean,
+          page_number: Integer,
+          page_size: Integer,
+          sort_by: Straddle::FundingEventListPaymentsParams::SortBy::OrSymbol,
+          sort_order: Straddle::SortOrder::OrSymbol,
           correlation_id: String,
           request_id: String,
           straddle_account_id: String,
           request_options: Straddle::RequestOptions::OrHash
-        ).returns(Straddle::FundingEventSummaryItemV1)
+        ).returns(Straddle::FundingEventPaymentList)
       end
-      def get(
+      def list_payments(
+        # Path param: Unique identifier for the funding event.
         id,
-        # Optional client generated identifier to trace and debug a series of requests.
+        # Query param: Default number of results returned per page.
+        default_page_size: nil,
+        # Query param: Default field used to sort the results.
+        default_sort: nil,
+        # Query param: Default order in which to sort the results.
+        default_sort_order: nil,
+        # Query param: When `true`, includes each payment's metadata. Defaults to `false`.
+        include_metadata: nil,
+        # Query param: Results page number. Starts at 1. Defaults to 1.
+        page_number: nil,
+        # Query param: Number of results per page. Maximum 1,000. Defaults to 100.
+        page_size: nil,
+        # Query param: Field used to sort the results.
+        sort_by: nil,
+        # Query param: Order in which to sort the results.
+        sort_order: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
+        correlation_id: nil,
+        # Header param: Optional client-generated identifier for tracing one request.
+        request_id: nil,
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
+        straddle_account_id: nil,
+        request_options: {}
+      )
+      end
+
+      # Creates a funding event for unfunded charge or payout activity in the sandbox
+      # and returns its ID. This endpoint is unavailable in production.
+      sig do
+        params(
+          funding_event_job_type:
+            Straddle::FundingEventSimulateParams::FundingEventJobType::OrSymbol,
+          sandbox_outcome: Straddle::SimulatedPaymentOutcome::OrSymbol,
+          correlation_id: String,
+          idempotency_key: String,
+          request_id: String,
+          straddle_account_id: String,
+          request_options: Straddle::RequestOptions::OrHash
+        ).returns(Straddle::FundingEventSimulation)
+      end
+      def simulate(
+        # Body param: Required. Selects charge or payout activity for the simulated
+        # funding event.
+        funding_event_job_type:,
+        # Body param: Optional. Sets the processing outcome for the simulated funding
+        # event. Defaults to `standard`.
+        sandbox_outcome: nil,
+        # Header param: Optional client-generated identifier for tracing a series of
+        # related requests.
         correlation_id: nil,
-        # Optional client generated identifier to trace and debug a request.
+        # Header param: Optional client-generated key for an idempotent request.
+        idempotency_key: nil,
+        # Header param: Optional client-generated identifier for tracing one request.
         request_id: nil,
-        # For use by platforms to specify an account id and set scope of a request.
+        # Header param: For platform requests, the embedded account UUID that sets the
+        # request scope.
         straddle_account_id: nil,
         request_options: {}
       )