straddle 0.5.0 → 1.0.0

data/lib/straddle/resources/funding_events.rb

@@ -2,125 +2,226 @@
 
 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
+      # Returns a funding event by its unique identifier, including its current status,
+      # status history, and linked bank account details when available.
+      #
+      # @overload retrieve(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param id [String] Unique identifier for the funding event.
+      #
+      # @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::FundingEventResponse]
+      #
+      # @see Straddle::Models::FundingEventRetrieveParams
+      def retrieve(id, params = {})
+        parsed, options = Straddle::FundingEventRetrieveParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["v1/funding_events/%1$s", id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::FundingEventResponse,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {Straddle::Models::FundingEventListParams} for more details.
       #
-      # Retrieves a list of funding events for your account. This endpoint supports
-      # advanced sorting and filtering options.
+      # Returns a paginated list of funding events that match the specified filters.
       #
       # @overload list(created_from: nil, created_to: nil, direction: nil, event_type: nil, page_number: nil, page_size: nil, search_text: nil, sort_by: nil, sort_order: nil, status: nil, status_reason: nil, status_source: nil, trace_id: nil, trace_number: nil, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param created_from [Date, nil] Query param: The start date of the range to filter by using the `YYYY-MM-DD` for
+      # @param created_from [Date, nil] Query param: Filter to funding events created on or after this date.
       #
-      # @param created_to [Date, nil] Query param: The end date of the range to filter by using the `YYYY-MM-DD` forma
+      # @param created_to [Date, nil] Query param: Filter to funding events created on or before this date.
       #
-      # @param direction [Symbol, Straddle::Models::FundingEventListParams::Direction] Query param: Describes the direction of the funding event from the perspective o
+      # @param direction [Symbol, Straddle::Models::TransferDirection] Query param: Filter by transfer direction relative to the linked bank account.
       #
-      # @param event_type [Symbol, Straddle::Models::FundingEventListParams::EventType] Query param: The funding event types describes the direction and reason for the
+      # @param event_type [Symbol, Straddle::Models::FundingEventType] Query param: Filter by funding event type.
       #
       # @param page_number [Integer] Query param: Results page number. Starts at page 1.
       #
-      # @param page_size [Integer] Query param: Results page size. Max value: 1000
+      # @param page_size [Integer] Query param: Results page size. Max value: 1000.
       #
-      # @param search_text [String, nil] Query param: Search text.
+      # @param search_text [String, nil] Query param: Free-text search across funding event fields.
       #
-      # @param sort_by [Symbol, Straddle::Models::FundingEventListParams::SortBy] Query param: The field to sort the results by.
+      # @param sort_by [Symbol, Straddle::Models::FundingEventListParams::SortBy] Query param: Field used to sort the results.
       #
-      # @param sort_order [Symbol, Straddle::Models::FundingEventListParams::SortOrder] Query param: The order in which to sort the results.
+      # @param sort_order [Symbol, Straddle::Models::SortOrder] Query param: Order in which to sort the results.
       #
-      # @param status [Array<Symbol, Straddle::Models::FundingEventListParams::Status>, nil] Query param: Funding Event status.
+      # @param status [Array<Symbol, Straddle::Models::PaymentStatus>, nil] Query param: Filter by funding event status.
       #
-      # @param status_reason [Array<Symbol, Straddle::Models::FundingEventListParams::StatusReason>, nil] Query param: Reason for latest payment status change.
+      # @param status_reason [Array<Symbol, Straddle::Models::PaymentStatusReason>, nil] Query param: Filter by the reason for the most recent status change.
       #
-      # @param status_source [Array<Symbol, Straddle::Models::FundingEventListParams::StatusSource>, nil] Query param: Source of latest payment status change.
+      # @param status_source [Array<Symbol, Straddle::Models::PaymentStatusSource>, nil] Query param: Filter by the source of the most recent status change.
       #
-      # @param trace_id [String, nil] Query param: Trace Id.
+      # @param trace_id [String, nil] Query param: Filter by a network-level trace identifier assigned during processi
       #
-      # @param trace_number [String, nil] Query param: Trace number.
+      # @param trace_number [String, nil] Query param: Filter by a network trace number assigned during processing.
       #
-      # @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 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::Internal::PageNumberSchema<Straddle::Models::FundingEventSummaryPagedV1::Data>]
+      # @return [Straddle::Models::FundingEventSummaryList]
       #
       # @see Straddle::Models::FundingEventListParams
       def list(params = {})
-        query_params =
-          [
-            :created_from,
-            :created_to,
-            :direction,
-            :event_type,
-            :page_number,
-            :page_size,
-            :search_text,
-            :sort_by,
-            :sort_order,
-            :status,
-            :status_reason,
-            :status_source,
-            :trace_id,
-            :trace_number
-          ]
+        query_params = %i[
+          created_from
+          created_to
+          direction
+          event_type
+          page_number
+          page_size
+          search_text
+          sort_by
+          sort_order
+          status
+          status_reason
+          status_source
+          trace_id
+          trace_number
+        ]
         parsed, options = Straddle::FundingEventListParams.dump_request(params)
         query = Straddle::Internal::Util.encode_query_params(parsed.slice(*query_params))
         @client.request(
           method: :get,
           path: "v1/funding_events",
           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::FundingEventSummaryPagedV1::Data,
+          headers:
+            parsed.except(*query_params).transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::FundingEventSummaryList,
           options: 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.
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::FundingEventListPaymentsParams} for more details.
       #
-      # @overload get(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      # Returns a paginated list of payments included in the funding event.
       #
-      # @param id [String]
+      # @overload list_payments(id, default_page_size: nil, default_sort: nil, default_sort_order: nil, include_metadata: nil, page_number: nil, page_size: nil, sort_by: nil, sort_order: nil, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {})
       #
-      # @param correlation_id [String] Optional client generated identifier to trace and debug a series of requests.
+      # @param id [String] Path param: Unique identifier for the funding event.
       #
-      # @param request_id [String] Optional client generated identifier to trace and debug a request.
+      # @param default_page_size [Integer] Query param: Default number of results returned per page.
       #
-      # @param straddle_account_id [String] For use by platforms to specify an account id and set scope of a request.
+      # @param default_sort [Symbol, Straddle::Models::FundingEventListPaymentsParams::DefaultSort] Query param: Default field used to sort the results.
       #
-      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      # @param default_sort_order [Symbol, Straddle::Models::SortOrder] Query param: Default order in which to sort the results.
+      #
+      # @param include_metadata [Boolean] Query param: When `true`, includes each payment's metadata. Defaults to `false`.
+      #
+      # @param page_number [Integer] Query param: Results page number. Starts at 1. Defaults to 1.
+      #
+      # @param page_size [Integer] Query param: Number of results per page. Maximum 1,000. Defaults to 100.
+      #
+      # @param sort_by [Symbol, Straddle::Models::FundingEventListPaymentsParams::SortBy] Query param: Field used to sort the results.
+      #
+      # @param sort_order [Symbol, Straddle::Models::SortOrder] Query param: Order in which to sort the results.
+      #
+      # @param correlation_id [String] Header param: Optional client-generated identifier for tracing a series of relat
       #
-      # @return [Straddle::Models::FundingEventSummaryItemV1]
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
       #
-      # @see Straddle::Models::FundingEventGetParams
-      def get(id, params = {})
-        parsed, options = Straddle::FundingEventGetParams.dump_request(params)
+      # @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::FundingEventPaymentList]
+      #
+      # @see Straddle::Models::FundingEventListPaymentsParams
+      def list_payments(id, params = {})
+        query_params = %i[
+          default_page_size
+          default_sort
+          default_sort_order
+          include_metadata
+          page_number
+          page_size
+          sort_by
+          sort_order
+        ]
+        parsed, options = Straddle::FundingEventListPaymentsParams.dump_request(params)
+        query = Straddle::Internal::Util.encode_query_params(parsed.slice(*query_params))
         @client.request(
           method: :get,
-          path: ["v1/funding_events/%1$s", id],
-          headers: parsed.transform_keys(
-            correlation_id: "correlation-id",
-            request_id: "request-id",
-            straddle_account_id: "straddle-account-id"
-          ),
-          model: Straddle::FundingEventSummaryItemV1,
+          path: ["v1/funding_event_payments/%1$s", id],
+          query: query,
+          headers:
+            parsed.except(*query_params).transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id",
+              straddle_account_id: "straddle-account-id"
+            ),
+          model: Straddle::FundingEventPaymentList,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::FundingEventSimulateParams} for more details.
+      #
+      # Creates a funding event for unfunded charge or payout activity in the sandbox
+      # and returns its ID. This endpoint is unavailable in production.
+      #
+      # @overload simulate(funding_event_job_type:, sandbox_outcome: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {})
+      #
+      # @param funding_event_job_type [Symbol, Straddle::Models::FundingEventSimulateParams::FundingEventJobType] Body param: Required. Selects charge or payout activity for the simulated fundin
+      #
+      # @param sandbox_outcome [Symbol, Straddle::Models::SimulatedPaymentOutcome] Body param: Optional. Sets the processing outcome for the simulated funding even
+      #
+      # @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 key for an idempotent request.
+      #
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
+      #
+      # @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::FundingEventSimulation]
+      #
+      # @see Straddle::Models::FundingEventSimulateParams
+      def simulate(params)
+        parsed, options = Straddle::FundingEventSimulateParams.dump_request(params)
+        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/funding_events/simulate",
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: Straddle::FundingEventSimulation,
           options: options
         )
       end

data/lib/straddle/resources/linked_bank_accounts.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Straddle
+  module Resources
+    # Linked bank accounts connect external bank accounts to an account or platform
+    # for charges, payouts, or billing.
+    class LinkedBankAccounts
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::LinkedBankAccountCreateParams} for more details.
+      #
+      # Creates a linked bank account for an account or platform, assigns its payment
+      # purposes, and returns the linked bank account.
+      #
+      # @overload create(bank_account:, account_id: nil, description: nil, metadata: nil, platform_id: nil, purposes: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, request_options: {})
+      #
+      # @param bank_account [Straddle::Models::LinkedBankAccountCreateParams::BankAccount] Body param
+      #
+      # @param account_id [String, nil] Body param: ID of the account that will own the linked bank account. Omit this f
+      #
+      # @param description [String, nil] Body param: Your description for the linked bank account.
+      #
+      # @param metadata [Hash{Symbol=>String, nil}, nil] Body param: Up to 20 user-defined key-value pairs.
+      #
+      # @param platform_id [String, nil] Body param: ID of the platform to associate with the linked bank account.
+      #
+      # @param purposes [Array<Symbol, Straddle::Models::LinkedBankAccountCreateParams::Purpose>, nil] Body param: Payment purposes for the linked bank account. Defaults to `charges`,
+      #
+      # @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 key for an idempotent request.
+      #
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::LinkedBankAccountResponse]
+      #
+      # @see Straddle::Models::LinkedBankAccountCreateParams
+      def create(params)
+        parsed, options = Straddle::LinkedBankAccountCreateParams.dump_request(params)
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id"
+        }
+        @client.request(
+          method: :post,
+          path: "v1/linked_bank_accounts",
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: Straddle::LinkedBankAccountResponse,
+          options: options
+        )
+      end
+
+      # Returns the linked bank account with the specified ID. The response masks the
+      # account number.
+      #
+      # @overload retrieve(linked_bank_account_id, correlation_id: nil, request_id: nil, request_options: {})
+      #
+      # @param linked_bank_account_id [String] The ID of the linked bank account.
+      #
+      # @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 request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::LinkedBankAccountResponse]
+      #
+      # @see Straddle::Models::LinkedBankAccountRetrieveParams
+      def retrieve(linked_bank_account_id, params = {})
+        parsed, options = Straddle::LinkedBankAccountRetrieveParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["v1/linked_bank_accounts/%1$s", linked_bank_account_id],
+          headers: parsed.transform_keys(correlation_id: "correlation-id", request_id: "request-id"),
+          model: Straddle::LinkedBankAccountResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::LinkedBankAccountUpdateParams} for more details.
+      #
+      # Updates bank account details and metadata, then returns the linked bank account.
+      # The linked bank account must have status `created`, or status `onboarding` with
+      # `status_detail.reason` set to `stuck`.
+      #
+      # @overload update(linked_bank_account_id, bank_account:, metadata: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, request_options: {})
+      #
+      # @param linked_bank_account_id [String] Path param: The ID of the linked bank account.
+      #
+      # @param bank_account [Straddle::Models::LinkedBankAccountUpdateParams::BankAccount] Body param
+      #
+      # @param metadata [Hash{Symbol=>String, nil}, nil] Body param: Up to 20 user-defined key-value pairs.
+      #
+      # @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 key for an idempotent request.
+      #
+      # @param request_id [String] Header param: Optional client-generated identifier for tracing one request.
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::LinkedBankAccountResponse]
+      #
+      # @see Straddle::Models::LinkedBankAccountUpdateParams
+      def update(linked_bank_account_id, params)
+        parsed, options = Straddle::LinkedBankAccountUpdateParams.dump_request(params)
+        header_params = {
+          correlation_id: "correlation-id",
+          idempotency_key: "idempotency-key",
+          request_id: "request-id"
+        }
+        @client.request(
+          method: :put,
+          path: ["v1/linked_bank_accounts/%1$s", linked_bank_account_id],
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: Straddle::LinkedBankAccountResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Straddle::Models::LinkedBankAccountListParams} for more details.
+      #
+      # Returns a paginated list of linked bank accounts. Filter the list by account,
+      # scope, purpose, or status.
+      #
+      # @overload list(account_id: nil, level: nil, page_number: nil, page_size: nil, purpose: nil, sort_by: nil, sort_order: nil, status: nil, correlation_id: nil, request_id: nil, request_options: {})
+      #
+      # @param account_id [String] Query param: Account ID used to filter the results.
+      #
+      # @param level [Symbol, Straddle::Models::LinkedBankAccountListParams::Level] Query param: Scope of linked bank accounts to return.
+      #
+      # @param page_number [Integer] Query param: Page number. Defaults to `1`.
+      #
+      # @param page_size [Integer] Query param: Number of results per page. Defaults to `100`. Maximum `1000`.
+      #
+      # @param purpose [Symbol, Straddle::Models::LinkedBankAccountListParams::Purpose] Query param: Linked bank account purpose. Accepted values are `charges`, `payout
+      #
+      # @param sort_by [String] Query param: Field used to sort results. Defaults to `id`.
+      #
+      # @param sort_order [Symbol, Straddle::Models::LinkedBankAccountListParams::SortOrder] Query param: Sort direction. Defaults to `asc`.
+      #
+      # @param status [Symbol, Straddle::Models::LinkedBankAccountListParams::Status] Query param: Linked bank account status. Accepted values are `created`, `onboard
+      #
+      # @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 for tracing one request.
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::LinkedBankAccountList]
+      #
+      # @see Straddle::Models::LinkedBankAccountListParams
+      def list(params = {})
+        query_params = %i[account_id level page_number page_size purpose sort_by sort_order status]
+        parsed, options = Straddle::LinkedBankAccountListParams.dump_request(params)
+        query = Straddle::Internal::Util.encode_query_params(parsed.slice(*query_params))
+        @client.request(
+          method: :get,
+          path: "v1/linked_bank_accounts",
+          query: query,
+          headers:
+            parsed.except(*query_params).transform_keys(
+              correlation_id: "correlation-id",
+              request_id: "request-id"
+            ),
+          model: Straddle::LinkedBankAccountList,
+          options: options
+        )
+      end
+
+      # Cancels a linked bank account and returns it with status `canceled`. The linked
+      # bank account must have status `created`.
+      #
+      # @overload cancel(linked_bank_account_id, correlation_id: nil, idempotency_key: nil, request_id: nil, request_options: {})
+      #
+      # @param linked_bank_account_id [String] The ID of the linked bank account.
+      #
+      # @param correlation_id [String] Optional client-generated identifier for tracing a series of related requests.
+      #
+      # @param idempotency_key [String] Optional client-generated key for an idempotent request.
+      #
+      # @param request_id [String] Optional client-generated identifier for tracing one request.
+      #
+      # @param request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::LinkedBankAccountResponse]
+      #
+      # @see Straddle::Models::LinkedBankAccountCancelParams
+      def cancel(linked_bank_account_id, params = {})
+        parsed, options = Straddle::LinkedBankAccountCancelParams.dump_request(params)
+        @client.request(
+          method: :patch,
+          path: ["v1/linked_bank_accounts/%1$s/cancel", linked_bank_account_id],
+          headers:
+            parsed.transform_keys(
+              correlation_id: "correlation-id",
+              idempotency_key: "idempotency-key",
+              request_id: "request-id"
+            ),
+          model: Straddle::LinkedBankAccountResponse,
+          options: options
+        )
+      end
+
+      # Returns the linked bank account with the specified ID without masking its
+      # account number. This endpoint is available only when Straddle enables data
+      # unmasking for the account.
+      #
+      # @overload list_unmasked(linked_bank_account_id, correlation_id: nil, request_id: nil, request_options: {})
+      #
+      # @param linked_bank_account_id [String] The ID of the linked bank account.
+      #
+      # @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 request_options [Straddle::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Straddle::Models::UnmaskedLinkedBankAccountResponse]
+      #
+      # @see Straddle::Models::LinkedBankAccountListUnmaskedParams
+      def list_unmasked(linked_bank_account_id, params = {})
+        parsed, options = Straddle::LinkedBankAccountListUnmaskedParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["v1/linked_bank_accounts/%1$s/unmask", linked_bank_account_id],
+          headers: parsed.transform_keys(correlation_id: "correlation-id", request_id: "request-id"),
+          model: Straddle::UnmaskedLinkedBankAccountResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Straddle::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end