straddle_pay 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23aebc721853de383064f4e317d3f9a6e73705d06f2f4d0e8376873dbf05bace
-  data.tar.gz: 1996288b18fc0434b255e7638e8e75b83db350687eeca1dc93cd46f091525ac9
+  metadata.gz: bf56e36b8c5ad31abdb73a507b57e21646f5996fdbba44ba4b14f4f3509a3576
+  data.tar.gz: 0a2e227e8e70a8bed554b0372fb2d2e54ea058c96649cea773b4e983dc95aa69
 SHA512:
-  metadata.gz: 36203c68e86e4df953735bdcb7b811a7d9db9c7867a8fa10c1ace55663ce894146621983a7d56f5490e8b1dc9cd62be65a27bb314bd4aed467e63215d78e0967
-  data.tar.gz: ff082a8507a7146e55ddee23a5286834212d7b97924821ce55f7a6c4c516c9653897b480173d5e363c333d6050504cd13399450972405ff2665d31bfb3ef9b72
+  metadata.gz: ba3e1707a861e85fd772f9cb31495f0e7a0e7f6f80f50cc2c023fa9b1e64abf49114d1304a492ef970d5e0d808e947721b1f8c530b63428a56572f43fc875f65
+  data.tar.gz: bb7814818ac4e160d38b6113cf2d56fa1d834de49beb93502244720eb31f0028eddb96fcd6be5df7dcb76a71540b8cfeb0d67943ffd8fa1c5c9b57f0b0b14c98

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--no-private
+lib/**/*.rb
+- README.md
+- CHANGELOG.md
+- LICENSE.txt

data/lib/straddle_pay/client.rb

@@ -4,9 +4,23 @@ require "faraday"
 require "json"
 
 module StraddlePay
+  # HTTP client for the Straddle API. Uses Faraday under the hood.
+  #
+  # @example
+  #   client = StraddlePay::Client.new
+  #   client.charges.create(paykey: "pk_abc", amount: 10_000, ...)
   class Client
-    attr_reader :api_key, :base_url
-
+    # @return [String] API key used for authentication
+    attr_reader :api_key
+    # @return [String] base URL for API requests
+    attr_reader :base_url
+
+    # @param api_key [String, nil] override global API key
+    # @param base_url [String, nil] override global base URL
+    # @param logger [Logger, nil] override global logger
+    # @param open_timeout [Integer, nil] connection open timeout in seconds
+    # @param read_timeout [Integer, nil] response read timeout in seconds
+    # @raise [ArgumentError] if no API key is configured
     def initialize(api_key: nil, base_url: nil, logger: nil, open_timeout: nil, read_timeout: nil)
       configuration = StraddlePay.config
       @api_key      = api_key      || configuration.api_key
@@ -18,32 +32,61 @@ module StraddlePay
       raise ArgumentError, "Missing API key for StraddlePay" if @api_key.to_s.empty?
     end
 
+    # @return [Resources::Customers]
     def customers      = @customers ||= Resources::Customers.new(self)
+    # @return [Resources::Bridge]
     def bridge         = @bridge ||= Resources::Bridge.new(self)
+    # @return [Resources::Paykeys]
     def paykeys        = @paykeys ||= Resources::Paykeys.new(self)
+    # @return [Resources::Charges]
     def charges        = @charges ||= Resources::Charges.new(self)
+    # @return [Resources::Payouts]
     def payouts        = @payouts ||= Resources::Payouts.new(self)
+    # @return [Resources::Payments]
     def payments       = @payments ||= Resources::Payments.new(self)
+    # @return [Resources::FundingEvents]
     def funding_events = @funding_events ||= Resources::FundingEvents.new(self)
+    # @return [Resources::Reports]
     def reports        = @reports ||= Resources::Reports.new(self)
+    # @return [Resources::Embed]
     def embed          = @embed ||= Resources::Embed.new(self)
 
+    # @param path [String] API endpoint path
+    # @param params [Hash, nil] query parameters
+    # @param headers [Hash] additional HTTP headers
+    # @return [Hash] parsed response data
     def get(path, params: nil, headers: {})
       request(:get, path, params: params, headers: headers)
     end
 
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] request body (JSON-encoded)
+    # @param headers [Hash] additional HTTP headers
+    # @return [Hash] parsed response data
     def post(path, body = nil, headers: {})
       request(:post, path, body: body, headers: headers)
     end
 
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] request body (JSON-encoded)
+    # @param headers [Hash] additional HTTP headers
+    # @return [Hash] parsed response data
     def put(path, body = nil, headers: {})
       request(:put, path, body: body, headers: headers)
     end
 
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] request body (JSON-encoded)
+    # @param headers [Hash] additional HTTP headers
+    # @return [Hash] parsed response data
     def patch(path, body = nil, headers: {})
       request(:patch, path, body: body, headers: headers)
     end
 
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] request body (JSON-encoded)
+    # @param headers [Hash] additional HTTP headers
+    # @return [Hash] parsed response data
     def delete(path, body = nil, headers: {})
       request(:delete, path, body: body, headers: headers)
     end

data/lib/straddle_pay/config.rb

@@ -3,11 +3,29 @@
 require "logger"
 
 module StraddlePay
+  # Configuration for the StraddlePay client.
+  #
+  # @example
+  #   StraddlePay.configure do |config|
+  #     config.api_key  = "sk_test_..."
+  #     config.base_url = StraddlePay::Config::PRODUCTION_URL
+  #     config.logger   = Rails.logger
+  #   end
   class Config
+    # @return [String] Sandbox API base URL
     SANDBOX_URL = "https://sandbox.straddle.io"
+    # @return [String] Production API base URL
     PRODUCTION_URL = "https://production.straddle.io"
 
-    attr_accessor :api_key, :base_url, :open_timeout, :read_timeout
+    # @return [String, nil] API key for authentication
+    attr_accessor :api_key
+    # @return [String] Base URL for API requests (default: sandbox)
+    attr_accessor :base_url
+    # @return [Integer] Connection open timeout in seconds (default: 5)
+    attr_accessor :open_timeout
+    # @return [Integer] Response read timeout in seconds (default: 30)
+    attr_accessor :read_timeout
+    # @return [Logger] Logger instance
     attr_writer :logger
 
     def initialize
@@ -17,6 +35,7 @@ module StraddlePay
       @read_timeout = integer_or_default("STRADDLE_READ_TIMEOUT", 30)
     end
 
+    # @return [Logger] configured logger, falls back to Rails.logger or $stderr
     def logger
       @logger ||= (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) || Logger.new($stderr)
     end

data/lib/straddle_pay/engine.rb

@@ -2,6 +2,7 @@
 
 module StraddlePay
   if defined?(Rails)
+    # Rails engine for StraddlePay gem integration.
     class Engine < ::Rails::Engine
       isolate_namespace StraddlePay
     end

data/lib/straddle_pay/errors.rb

@@ -1,9 +1,26 @@
 # frozen_string_literal: true
 
 module StraddlePay
+  # Base error for all Straddle API errors.
+  #
+  # @example
+  #   rescue StraddlePay::Error => e
+  #     e.status      # => 422
+  #     e.error_type  # => "validation_error"
+  #     e.error_items # => [{"reference" => "email", "detail" => "is invalid"}]
   class Error < StandardError
-    attr_reader :status, :body, :error_type, :error_items
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status
+    # @return [Hash, nil] full response body
+    attr_reader :body
+    # @return [String, nil] Straddle error type (e.g. "validation_error")
+    attr_reader :error_type
+    # @return [Array<Hash>] Straddle error items with reference and detail
+    attr_reader :error_items
 
+    # @param message [String, nil] error message
+    # @param status [Integer, nil] HTTP status code
+    # @param body [Hash, nil] parsed response body
     def initialize(message = nil, status: nil, body: nil)
       error_hash = body.is_a?(Hash) ? (body["error"] || {}) : {}
       @error_type = error_hash["type"] if error_hash.is_a?(Hash)
@@ -14,9 +31,18 @@ module StraddlePay
     end
   end
 
+  # Raised on 401/403 responses.
   class AuthenticationError < Error; end
+
+  # Raised on 400, 404, 409, 422 responses.
   class ClientError < Error; end
+
+  # Raised on 429 responses. Retry with backoff.
   class RateLimitError < Error; end
+
+  # Raised on 500+ responses.
   class ServerError < Error; end
+
+  # Raised on timeout or connection failure.
   class NetworkError < Error; end
 end

data/lib/straddle_pay/resources/base.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
 module StraddlePay
+  # Namespace for all API resource classes.
   module Resources
+    # Base class for API resources. Provides header extraction for
+    # Straddle-specific headers (account scoping, request tracking, idempotency).
     class Base
+      # @api private
       HEADER_KEYS = {
         straddle_account_id: "Straddle-Account-Id",
         request_id: "Request-Id",
@@ -10,6 +14,7 @@ module StraddlePay
         idempotency_key: "Idempotency-Key"
       }.freeze
 
+      # @param client [Client] the HTTP client instance
       def initialize(client)
         @client = client
       end

data/lib/straddle_pay/resources/bridge.rb

@@ -2,9 +2,15 @@
 
 module StraddlePay
   module Resources
+    # Bank account linking via Bridge.
     class Bridge < Base
+      # @return [BridgeLinks] bank account link sub-resource
       def links = @links ||= BridgeLinks.new(@client)
 
+      # Initialize a Bridge session for a customer.
+      #
+      # @param customer_id [String] customer ID
+      # @return [Hash] session details
       def initialize_session(customer_id:, **options)
         payload = { customer_id: customer_id, **options }.compact
         headers = extract_headers(payload)

data/lib/straddle_pay/resources/bridge_links.rb

@@ -2,7 +2,16 @@
 
 module StraddlePay
   module Resources
+    # Link bank accounts via direct details, Plaid, Quiltt, or TAN.
+    # Accessed via {Bridge#links}.
     class BridgeLinks < Base
+      # Link a bank account directly.
+      #
+      # @param customer_id [String] customer ID
+      # @param account_number [String] bank account number
+      # @param routing_number [String] bank routing number
+      # @param account_type [String] "checking" or "savings"
+      # @return [Hash] linked bank account
       def bank_account(customer_id:, account_number:, routing_number:, account_type:, **options)
         payload = {
           customer_id: customer_id, account_number: account_number,
@@ -12,18 +21,35 @@ module StraddlePay
         @client.post("v1/bridge/bank_account", payload, headers: headers)
       end
 
+      # Link a bank account via Plaid.
+      #
+      # @param customer_id [String] customer ID
+      # @param plaid_token [String] Plaid processor token
+      # @return [Hash] linked bank account
       def plaid(customer_id:, plaid_token:, **options)
         payload = { customer_id: customer_id, plaid_token: plaid_token, **options }.compact
         headers = extract_headers(payload)
         @client.post("v1/bridge/plaid", payload, headers: headers)
       end
 
+      # Link a bank account via Quiltt.
+      #
+      # @param customer_id [String] customer ID
+      # @param quiltt_token [String] Quiltt session token
+      # @return [Hash] linked bank account
       def quiltt(customer_id:, quiltt_token:, **options)
         payload = { customer_id: customer_id, quiltt_token: quiltt_token, **options }.compact
         headers = extract_headers(payload)
         @client.post("v1/bridge/quiltt", payload, headers: headers)
       end
 
+      # Link a bank account via TAN (Tokenized Account Number).
+      #
+      # @param customer_id [String] customer ID
+      # @param routing_number [String] bank routing number
+      # @param account_type [String] "checking" or "savings"
+      # @param tan [String] tokenized account number
+      # @return [Hash] linked bank account
       def tan(customer_id:, routing_number:, account_type:, tan:, **options)
         payload = {
           customer_id: customer_id, routing_number: routing_number,

data/lib/straddle_pay/resources/charges.rb

@@ -2,7 +2,22 @@
 
 module StraddlePay
   module Resources
+    # Manage ACH charge (debit) transactions.
+    #
+    # @see https://straddle.dev/api-reference Straddle API Reference
     class Charges < Base
+      # Create a new charge.
+      #
+      # @param paykey [String] paykey identifier
+      # @param amount [Integer] amount in cents
+      # @param currency [String] three-letter currency code (e.g. "usd")
+      # @param description [String] charge description
+      # @param payment_date [String] date in YYYY-MM-DD format
+      # @param consent_type [String] consent type (e.g. "internet")
+      # @param device [Hash] device info (must include :ip_address)
+      # @param external_id [String] your external reference ID
+      # @param options [Hash] additional fields or header params
+      # @return [Hash] created charge
       def create(paykey:, amount:, currency:, description:, payment_date:, consent_type:, device:, external_id:,
                  **options)
         payload = {
@@ -14,31 +29,55 @@ module StraddlePay
         @client.post("v1/charges", payload, headers: headers)
       end
 
+      # Retrieve a charge by ID.
+      #
+      # @param id [String] charge ID
+      # @return [Hash] charge details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/charges/#{id}", headers: headers)
       end
 
+      # Update a charge.
+      #
+      # @param id [String] charge ID
+      # @return [Hash] updated charge
       def update(id, **options)
         headers = extract_headers(options)
         @client.put("v1/charges/#{id}", options, headers: headers)
       end
 
+      # Cancel a charge.
+      #
+      # @param id [String] charge ID
+      # @return [Hash] cancelled charge
       def cancel(id, **options)
         headers = extract_headers(options)
         @client.put("v1/charges/#{id}/cancel", options, headers: headers)
       end
 
+      # Place a charge on hold.
+      #
+      # @param id [String] charge ID
+      # @return [Hash] held charge
       def hold(id, **options)
         headers = extract_headers(options)
         @client.put("v1/charges/#{id}/hold", options, headers: headers)
       end
 
+      # Release a held charge.
+      #
+      # @param id [String] charge ID
+      # @return [Hash] released charge
       def release(id, **options)
         headers = extract_headers(options)
         @client.put("v1/charges/#{id}/release", options, headers: headers)
       end
 
+      # Retrieve unmasked charge details.
+      #
+      # @param id [String] charge ID
+      # @return [Hash] unmasked charge details
       def unmask(id, **options)
         headers = extract_headers(options)
         @client.get("v1/charges/#{id}/unmask", headers: headers)

data/lib/straddle_pay/resources/customer_reviews.rb

@@ -2,18 +2,33 @@
 
 module StraddlePay
   module Resources
+    # Manage customer identity reviews.
+    # Accessed via {Customers#reviews}.
     class CustomerReviews < Base
+      # Get the identity review for a customer.
+      #
+      # @param customer_id [String] customer ID
+      # @return [Hash] review details
       def get(customer_id, **options)
         headers = extract_headers(options)
         @client.get("v1/customers/#{customer_id}/review", headers: headers)
       end
 
+      # Submit a review decision.
+      #
+      # @param customer_id [String] customer ID
+      # @param status [String] decision status (e.g. "approved", "rejected")
+      # @return [Hash] updated review
       def decision(customer_id, status:, **options)
         payload = { status: status, **options }.compact
         headers = extract_headers(payload)
         @client.patch("v1/customers/#{customer_id}/review", payload, headers: headers)
       end
 
+      # Refresh a customer's identity review.
+      #
+      # @param customer_id [String] customer ID
+      # @return [Hash] refreshed review
       def refresh(customer_id, **options)
         headers = extract_headers(options)
         @client.put("v1/customers/#{customer_id}/refresh_review", options, headers: headers)

data/lib/straddle_pay/resources/customers.rb

@@ -2,35 +2,65 @@
 
 module StraddlePay
   module Resources
+    # Manage customers and their identity reviews.
     class Customers < Base
+      # @return [CustomerReviews] customer identity review sub-resource
       def reviews = @reviews ||= CustomerReviews.new(@client)
 
+      # Create a new customer.
+      #
+      # @param name [String] customer full name
+      # @param type [String] "individual" or "business"
+      # @param email [String] customer email
+      # @param phone [String] phone in E.164 format (e.g. "+15551234567")
+      # @param device [Hash] device info (must include :ip_address)
+      # @return [Hash] created customer
       def create(name:, type:, email:, phone:, device:, **options)
         payload = { name: name, type: type, email: email, phone: phone, device: device, **options }.compact
         headers = extract_headers(payload)
         @client.post("v1/customers", payload, headers: headers)
       end
 
+      # Retrieve a customer by ID.
+      #
+      # @param id [String] customer ID
+      # @return [Hash] customer details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/customers/#{id}", headers: headers)
       end
 
+      # List customers with optional pagination.
+      #
+      # @param options [Hash] filter/pagination params (page_number, page_size, etc.)
+      # @return [Hash] paginated customer list
       def list(**options)
         headers = extract_headers(options)
         @client.get("v1/customers", params: options, headers: headers)
       end
 
+      # Update a customer.
+      #
+      # @param id [String] customer ID
+      # @return [Hash] updated customer
       def update(id, **options)
         headers = extract_headers(options)
         @client.put("v1/customers/#{id}", options, headers: headers)
       end
 
+      # Delete a customer.
+      #
+      # @param id [String] customer ID
+      # @return [Hash] deletion confirmation
       def delete(id, **options)
         headers = extract_headers(options)
         @client.delete("v1/customers/#{id}", headers: headers)
       end
 
+      # Retrieve unmasked customer details.
+      #
+      # @param id [String] customer ID
+      # @return [Hash] unmasked customer details
       def unmasked(id, **options)
         headers = extract_headers(options)
         @client.get("v1/customers/#{id}/unmasked", headers: headers)

data/lib/straddle_pay/resources/embed.rb

@@ -2,10 +2,16 @@
 
 module StraddlePay
   module Resources
+    # Namespace for embedded account management (multi-tenant/platform use).
+    # Access sub-resources via +client.embed.accounts+, +client.embed.organizations+, etc.
     class Embed < Base
+      # @return [EmbedAccounts]
       def accounts              = @accounts ||= EmbedAccounts.new(@client)
+      # @return [EmbedOrganizations]
       def organizations         = @organizations ||= EmbedOrganizations.new(@client)
+      # @return [EmbedRepresentatives]
       def representatives       = @representatives ||= EmbedRepresentatives.new(@client)
+      # @return [EmbedLinkedBankAccounts]
       def linked_bank_accounts  = @linked_bank_accounts ||= EmbedLinkedBankAccounts.new(@client)
     end
   end

data/lib/straddle_pay/resources/embed_accounts.rb

@@ -2,7 +2,16 @@
 
 module StraddlePay
   module Resources
+    # Manage embedded accounts for platform/marketplace use.
+    # Accessed via {Embed#accounts}.
     class EmbedAccounts < Base
+      # Create an embedded account.
+      #
+      # @param organization_id [String] parent organization ID
+      # @param account_type [String] account type (e.g. "standard")
+      # @param business_profile [Hash] business details (must include :name)
+      # @param access_level [String] access level (e.g. "standard")
+      # @return [Hash] created account
       def create(organization_id:, account_type:, business_profile:, access_level:, **options)
         payload = {
           organization_id: organization_id, account_type: account_type,
@@ -12,27 +21,48 @@ module StraddlePay
         @client.post("v1/accounts", payload, headers: headers)
       end
 
+      # Retrieve an account by ID.
+      #
+      # @param id [String] account ID
+      # @return [Hash] account details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/accounts/#{id}", headers: headers)
       end
 
+      # List accounts with optional filters.
+      #
+      # @return [Hash] paginated account list
       def list(**options)
         headers = extract_headers(options)
         @client.get("v1/accounts", params: options, headers: headers)
       end
 
+      # Update an account.
+      #
+      # @param id [String] account ID
+      # @return [Hash] updated account
       def update(id, **options)
         headers = extract_headers(options)
         @client.put("v1/accounts/#{id}", options, headers: headers)
       end
 
+      # Onboard an account (accept terms of service).
+      #
+      # @param id [String] account ID
+      # @param terms_of_service [Hash] ToS acceptance (must include accepted: true)
+      # @return [Hash] onboarded account
       def onboard(id, terms_of_service:, **options)
         payload = { terms_of_service: terms_of_service, **options }.compact
         headers = extract_headers(payload)
         @client.post("v1/accounts/#{id}/onboard", payload, headers: headers)
       end
 
+      # Simulate account status change (sandbox only).
+      #
+      # @param id [String] account ID
+      # @param final_status [String] target status to simulate
+      # @return [Hash] simulated account
       def simulate(id, final_status:, **options)
         payload = { final_status: final_status, **options }.compact
         headers = extract_headers(payload)

data/lib/straddle_pay/resources/embed_linked_bank_accounts.rb

@@ -2,7 +2,15 @@
 
 module StraddlePay
   module Resources
+    # Manage linked bank accounts for embedded accounts.
+    # Accessed via {Embed#linked_bank_accounts}.
     class EmbedLinkedBankAccounts < Base
+      # Link a bank account to an embedded account.
+      #
+      # @param account_id [String] parent account ID
+      # @param bank_account [Hash] bank details (account_number, routing_number)
+      # @param description [String] account description
+      # @return [Hash] created linked bank account
       def create(account_id:, bank_account:, description:, **options)
         payload = {
           account_id: account_id, bank_account: bank_account,
@@ -12,26 +20,45 @@ module StraddlePay
         @client.post("v1/linked_bank_accounts", payload, headers: headers)
       end
 
+      # Retrieve a linked bank account by ID.
+      #
+      # @param id [String] linked bank account ID
+      # @return [Hash] linked bank account details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/linked_bank_accounts/#{id}", headers: headers)
       end
 
+      # List linked bank accounts with optional filters.
+      #
+      # @return [Hash] paginated linked bank account list
       def list(**options)
         headers = extract_headers(options)
         @client.get("v1/linked_bank_accounts", params: options, headers: headers)
       end
 
+      # Update a linked bank account.
+      #
+      # @param id [String] linked bank account ID
+      # @return [Hash] updated linked bank account
       def update(id, **options)
         headers = extract_headers(options)
         @client.put("v1/linked_bank_accounts/#{id}", options, headers: headers)
       end
 
+      # Cancel a linked bank account.
+      #
+      # @param id [String] linked bank account ID
+      # @return [Hash] cancelled linked bank account
       def cancel(id, **options)
         headers = extract_headers(options)
         @client.patch("v1/linked_bank_accounts/#{id}/cancel", options.empty? ? nil : options, headers: headers)
       end
 
+      # Retrieve unmasked linked bank account details.
+      #
+      # @param id [String] linked bank account ID
+      # @return [Hash] unmasked linked bank account details
       def unmask(id, **options)
         headers = extract_headers(options)
         @client.get("v1/linked_bank_accounts/#{id}/unmask", headers: headers)

data/lib/straddle_pay/resources/embed_organizations.rb

@@ -2,18 +2,31 @@
 
 module StraddlePay
   module Resources
+    # Manage organizations for embedded accounts.
+    # Accessed via {Embed#organizations}.
     class EmbedOrganizations < Base
+      # Create an organization.
+      #
+      # @param name [String] organization name
+      # @return [Hash] created organization
       def create(name:, **options)
         payload = { name: name, **options }.compact
         headers = extract_headers(payload)
         @client.post("v1/organizations", payload, headers: headers)
       end
 
+      # Retrieve an organization by ID.
+      #
+      # @param id [String] organization ID
+      # @return [Hash] organization details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/organizations/#{id}", headers: headers)
       end
 
+      # List organizations with optional filters.
+      #
+      # @return [Hash] paginated organization list
       def list(**options)
         headers = extract_headers(options)
         @client.get("v1/organizations", params: options, headers: headers)

data/lib/straddle_pay/resources/embed_representatives.rb

@@ -2,7 +2,20 @@
 
 module StraddlePay
   module Resources
+    # Manage representatives for embedded accounts.
+    # Accessed via {Embed#representatives}.
     class EmbedRepresentatives < Base
+      # Create a representative.
+      #
+      # @param account_id [String] parent account ID
+      # @param first_name [String] first name
+      # @param last_name [String] last name
+      # @param email [String] email address
+      # @param dob [String] date of birth (YYYY-MM-DD)
+      # @param mobile_number [String] phone in E.164 format
+      # @param relationship [String] relationship to business (e.g. "owner")
+      # @param ssn_last4 [String] last 4 digits of SSN
+      # @return [Hash] created representative
       def create(account_id:, first_name:, last_name:, email:, dob:, mobile_number:, relationship:, ssn_last4:,
                  **options)
         payload = {
@@ -14,21 +27,36 @@ module StraddlePay
         @client.post("v1/representatives", payload, headers: headers)
       end
 
+      # Retrieve a representative by ID.
+      #
+      # @param id [String] representative ID
+      # @return [Hash] representative details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/representatives/#{id}", headers: headers)
       end
 
+      # List representatives with optional filters.
+      #
+      # @return [Hash] paginated representative list
       def list(**options)
         headers = extract_headers(options)
         @client.get("v1/representatives", params: options, headers: headers)
       end
 
+      # Update a representative.
+      #
+      # @param id [String] representative ID
+      # @return [Hash] updated representative
       def update(id, **options)
         headers = extract_headers(options)
         @client.put("v1/representatives/#{id}", options, headers: headers)
       end
 
+      # Retrieve unmasked representative details.
+      #
+      # @param id [String] representative ID
+      # @return [Hash] unmasked representative details
       def unmask(id, **options)
         headers = extract_headers(options)
         @client.get("v1/representatives/#{id}/unmask", headers: headers)

data/lib/straddle_pay/resources/funding_events.rb

@@ -2,12 +2,21 @@
 
 module StraddlePay
   module Resources
+    # Query funding events (bank settlement records).
     class FundingEvents < Base
+      # List funding events with optional filters.
+      #
+      # @param options [Hash] filter/pagination params
+      # @return [Hash] paginated funding event list
       def list(**options)
         headers = extract_headers(options)
         @client.get("v1/funding-events", params: options, headers: headers)
       end
 
+      # Retrieve a funding event by ID.
+      #
+      # @param id [String] funding event ID
+      # @return [Hash] funding event details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/funding-events/#{id}", headers: headers)

data/lib/straddle_pay/resources/paykeys.rb

@@ -2,32 +2,56 @@
 
 module StraddlePay
   module Resources
+    # Manage paykeys (tokenized bank account references).
     class Paykeys < Base
+      # Retrieve a paykey by ID.
+      #
+      # @param id [String] paykey ID
+      # @return [Hash] paykey details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/paykeys/#{id}", headers: headers)
       end
 
+      # List paykeys with optional filters.
+      #
+      # @return [Hash] paginated paykey list
       def list(**options)
         headers = extract_headers(options)
         @client.get("v1/paykeys", params: options, headers: headers)
       end
 
+      # Retrieve unmasked paykey details.
+      #
+      # @param id [String] paykey ID
+      # @return [Hash] unmasked paykey details
       def unmasked(id, **options)
         headers = extract_headers(options)
         @client.get("v1/paykeys/#{id}/unmasked", headers: headers)
       end
 
+      # Reveal full paykey details (sensitive).
+      #
+      # @param id [String] paykey ID
+      # @return [Hash] revealed paykey
       def reveal(id, **options)
         headers = extract_headers(options)
         @client.get("v1/paykeys/#{id}/reveal", headers: headers)
       end
 
+      # Cancel a paykey.
+      #
+      # @param id [String] paykey ID
+      # @return [Hash] cancelled paykey
       def cancel(id, **options)
         headers = extract_headers(options)
         @client.put("v1/paykeys/#{id}/cancel", options, headers: headers)
       end
 
+      # Submit a paykey for review.
+      #
+      # @param id [String] paykey ID
+      # @return [Hash] review result
       def review(id, **options)
         headers = extract_headers(options)
         @client.patch("v1/paykeys/#{id}/review", options, headers: headers)

data/lib/straddle_pay/resources/payments.rb

@@ -2,7 +2,12 @@
 
 module StraddlePay
   module Resources
+    # Query unified payment records (charges and payouts).
     class Payments < Base
+      # List payments with optional filters.
+      #
+      # @param options [Hash] filter/pagination params
+      # @return [Hash] paginated payment list
       def list(**options)
         headers = extract_headers(options)
         @client.get("v1/payments", params: options, headers: headers)

data/lib/straddle_pay/resources/payouts.rb

@@ -2,7 +2,20 @@
 
 module StraddlePay
   module Resources
+    # Manage ACH payout (credit) transactions.
+    #
+    # @see https://straddle.dev/api-reference Straddle API Reference
     class Payouts < Base
+      # Create a new payout.
+      #
+      # @param paykey [String] paykey identifier
+      # @param amount [Integer] amount in cents
+      # @param currency [String] three-letter currency code
+      # @param description [String] payout description
+      # @param payment_date [String] date in YYYY-MM-DD format
+      # @param device [Hash] device info (must include :ip_address)
+      # @param external_id [String] your external reference ID
+      # @return [Hash] created payout
       def create(paykey:, amount:, currency:, description:, payment_date:, device:, external_id:, **options)
         payload = {
           paykey: paykey, amount: amount, currency: currency, description: description,
@@ -12,34 +25,61 @@ module StraddlePay
         @client.post("v1/payouts", payload, headers: headers)
       end
 
+      # Retrieve a payout by ID.
+      #
+      # @param id [String] payout ID
+      # @return [Hash] payout details
       def get(id, **options)
         headers = extract_headers(options)
         @client.get("v1/payouts/#{id}", headers: headers)
       end
 
+      # Update a payout.
+      #
+      # @param id [String] payout ID
+      # @return [Hash] updated payout
       def update(id, **options)
         headers = extract_headers(options)
         @client.put("v1/payouts/#{id}", options, headers: headers)
       end
 
+      # Cancel a payout.
+      #
+      # @param id [String] payout ID
+      # @param reason [String] cancellation reason (required)
+      # @return [Hash] cancelled payout
       def cancel(id, reason:, **options)
         payload = { reason: reason, **options }.compact
         headers = extract_headers(payload)
         @client.put("v1/payouts/#{id}/cancel", payload, headers: headers)
       end
 
+      # Place a payout on hold.
+      #
+      # @param id [String] payout ID
+      # @param reason [String] hold reason (required)
+      # @return [Hash] held payout
       def hold(id, reason:, **options)
         payload = { reason: reason, **options }.compact
         headers = extract_headers(payload)
         @client.put("v1/payouts/#{id}/hold", payload, headers: headers)
       end
 
+      # Release a held payout.
+      #
+      # @param id [String] payout ID
+      # @param reason [String] release reason (required)
+      # @return [Hash] released payout
       def release(id, reason:, **options)
         payload = { reason: reason, **options }.compact
         headers = extract_headers(payload)
         @client.put("v1/payouts/#{id}/release", payload, headers: headers)
       end
 
+      # Retrieve unmasked payout details.
+      #
+      # @param id [String] payout ID
+      # @return [Hash] unmasked payout details
       def unmask(id, **options)
         headers = extract_headers(options)
         @client.get("v1/payouts/#{id}/unmask", headers: headers)

data/lib/straddle_pay/resources/reports.rb

@@ -2,7 +2,12 @@
 
 module StraddlePay
   module Resources
+    # Generate reports from the Straddle API.
     class Reports < Base
+      # Get total customers grouped by status.
+      #
+      # @param options [Hash] optional filters
+      # @return [Hash] report data
       def total_customers_by_status(**options)
         headers = extract_headers(options)
         @client.post("v1/reports/total_customers_by_status", options.empty? ? nil : options, headers: headers)

data/lib/straddle_pay/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module StraddlePay
-  VERSION = "0.1.0"
+  # @return [String] current gem version
+  VERSION = "0.1.2"
 end

data/lib/straddle_pay.rb

@@ -2,6 +2,18 @@
 
 require_relative "straddle_pay/version"
 
+# Ruby client for the Straddle payment infrastructure API.
+#
+# @example Global configuration
+#   StraddlePay.configure do |config|
+#     config.api_key  = ENV.fetch("STRADDLE_API_KEY")
+#     config.base_url = StraddlePay::Config::PRODUCTION_URL
+#   end
+#
+# @example Per-instance client
+#   client = StraddlePay::Client.new(api_key: "sk_test_...")
+#
+# @see https://straddle.dev/api-reference Straddle API Reference
 module StraddlePay
   autoload :Config, "straddle_pay/config"
   autoload :Client, "straddle_pay/client"
@@ -32,14 +44,20 @@ module StraddlePay
   end
 
   class << self
+    # @return [Config] current configuration instance
     def config
       @config ||= Config.new
     end
 
+    # Yields the global configuration for modification.
+    #
+    # @yieldparam config [Config] the configuration instance
     def configure
       yield(config)
     end
 
+    # Reset configuration to defaults.
+    # @return [void]
     def reset_configuration!
       @config = nil
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: straddle_pay
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - dpaluy
@@ -35,6 +35,7 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -77,14 +78,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client for the Straddle payment infrastructure API.
 test_files: []