paystack_sdk 0.1.0 → 0.2.0

data/lib/paystack_sdk/resources/transfer_recipients.rb

@@ -1,46 +1,154 @@
-require_relative "../validations"
+# frozen_string_literal: true
+
+# Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
+# Do not edit by hand: regenerate it with `bin/paystack-scaffold Transfer Recipient`. Hand-written extras go in lib/paystack_sdk/resources/extensions/transfer_recipients.rb.
+# scaffold-digest: 74785aa38f6edfebdeff52d47bb3b355c2ad95b2cacdd6c0d7062725415bbfaa
+
+require_relative "base"
 
 module PaystackSdk
   module Resources
-    class TransferRecipients < Base
-      # Create a transfer recipient
+    # Transfer Recipient operations.
+    class TransferRecipients < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {next_cursor: "next", per_page: "perPage"}.freeze
+
+      # List Transfer Recipients.
+      #
+      # List transfer recipients available on your integration
+      #
+      # @param use_cursor [Boolean] A flag to indicate if cursor based pagination should be used
+      # @param next_cursor [String] An alphanumeric value returned for every cursor based retrieval, used to retrieve the next set of data
+      # @param previous [String] An alphanumeric value returned for every cursor based retrieval, used to retrieve the previous set of data
+      # @param per_page [Integer] The number of records to fetch per request
+      # @param page [Integer] The offset to retrieve data from
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer-recipient/#list
+      def list(use_cursor: nil, next_cursor: nil, previous: nil, per_page: nil, page: nil)
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+
+        wire_query = to_wire({use_cursor:, next_cursor:, previous:, per_page:, page:}, WIRE_NAMES)
+
+        handle_response(@connection.get("/transferrecipient", wire_query))
+      end
+
+      # Create Transfer Recipient.
+      #
+      # Creates a new recipient. A duplicate account number will lead to the retrieval of the existing record.
+      #
+      # @param type [String] Recipient Type One of: nuban, ghipss, mobile_money, basa, authorization.
+      # @param name [String] The recipient's name according to their account registration.
+      # @param account_number [String] Recipient's bank account number
+      # @param bank_code [String] Recipient's bank code, from the List Banks endpoint.
+      # @param description [String] A description for this recipient
+      # @param currency [String] Currency for the account receiving the transfer
+      # @param authorization_code [String] An authorization code from a previous transaction
+      # @param metadata [Hash] JSON object of custom data
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer-recipient/#create
-      def create(params)
-        validate_hash!(input: params, name: "TransferRecipient params")
-        validate_required_params!(
-          payload: params,
-          required_params: %i[type name account_number bank_code],
-          operation_name: "Create Transfer Recipient"
+      def create(
+        type:,
+        name:,
+        account_number:,
+        bank_code:,
+        description: nil,
+        currency: nil,
+        authorization_code: nil,
+        metadata: nil
+      )
+        validate_presence!(value: type, name: "type")
+        validate_allowed_values!(
+          value: type,
+          allowed_values: %w[nuban ghipss mobile_money basa authorization],
+          name: "type"
+        )
+        validate_presence!(value: name, name: "name")
+        validate_presence!(value: account_number, name: "account_number")
+        validate_presence!(value: bank_code, name: "bank_code")
+
+        wire_body = to_wire(
+          {
+            type:,
+            name:,
+            account_number:,
+            bank_code:,
+            description:,
+            currency:,
+            authorization_code:,
+            metadata:
+          },
+          WIRE_NAMES
         )
-        handle_response(@connection.post("/transferrecipient", params))
+
+        handle_response(@connection.post("/transferrecipient", wire_body))
       end
 
-      # List transfer recipients
-      # @see https://paystack.com/docs/api/transfer-recipient/#list
-      def list(query = {})
-        handle_response(@connection.get("/transferrecipient", query))
+      # Bulk Create Transfer Recipient.
+      #
+      # Create multiple transfer recipients in batches. A duplicate account number will lead to the retrieval of the existing record.
+      #
+      # @param batch [Array<Hash>] A list of transfer recipient objects, each with the fields accepted by {#create}
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer-recipient/#bulk
+      def bulk_create(batch:)
+        validate_presence!(value: batch, name: "batch")
+
+        wire_body = to_wire({batch:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transferrecipient/bulk", wire_body))
       end
 
-      # Fetch a transfer recipient
+      # Fetch Transfer recipient.
+      #
+      # Fetch the details of a transfer recipient
+      #
+      # @param id_or_code [String] The recipient code (RCP_...) or numeric ID
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer-recipient/#fetch
-      def fetch(recipient_code:)
-        validate_presence!(value: recipient_code, name: "recipient_code")
-        handle_response(@connection.get("/transferrecipient/#{recipient_code}"))
+      def fetch(id_or_code:)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+
+        handle_response(@connection.get("/transferrecipient/#{escape_path(id_or_code, name: "id_or_code")}"))
       end
 
-      # Update a transfer recipient
+      # Update Transfer Recipient.
+      #
+      # Update the details of a transfer recipient
+      #
+      # @param id_or_code [String] The recipient code (RCP_...) or numeric ID
+      # @param name [String] Recipient's name
+      # @param email [String] Recipient's email address
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer-recipient/#update
-      def update(recipient_code:, params:)
-        validate_presence!(value: recipient_code, name: "recipient_code")
-        validate_hash!(input: params, name: "Update TransferRecipient params")
-        handle_response(@connection.put("/transferrecipient/#{recipient_code}", params))
+      def update(id_or_code:, name: nil, email: nil)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+        validate_email!(email: email, name: "email", allow_nil: true)
+
+        wire_body = to_wire({name:, email:}, WIRE_NAMES)
+
+        handle_response(
+          @connection.put("/transferrecipient/#{escape_path(id_or_code, name: "id_or_code")}", wire_body)
+        )
       end
 
-      # Delete a transfer recipient
+      # Delete Transfer Recipient.
+      #
+      # Delete a transfer recipient (sets the transfer recipient to inactive)
+      #
+      # @param id_or_code [String] The recipient code (RCP_...) or numeric ID
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer-recipient/#delete
-      def delete(recipient_code:)
-        validate_presence!(value: recipient_code, name: "recipient_code")
-        handle_response(@connection.delete("/transferrecipient/#{recipient_code}"))
+      def delete(id_or_code:)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+
+        handle_response(@connection.delete("/transferrecipient/#{escape_path(id_or_code, name: "id_or_code")}"))
       end
     end
   end

data/lib/paystack_sdk/resources/transfers.rb

@@ -1,46 +1,281 @@
-require_relative "../validations"
+# frozen_string_literal: true
+
+# Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d), then
+# edited by hand against Paystack's Transfers and Transfers Control docs pages (descriptions, docs
+# links and the `fetch(id_or_code:)` keyword), so the scaffold treats it as hand-written and will not regenerate it.
+# Hand-written extras go in lib/paystack_sdk/resources/extensions/transfers.rb.
+
+require_relative "base"
 
 module PaystackSdk
   module Resources
-    class Transfers < Base
-      # Create a transfer
-      # @see https://paystack.com/docs/api/transfer/#initiate
-      def create(params)
-        validate_hash!(input: params, name: "Transfer params")
-        validate_required_params!(
-          payload: params,
-          required_params: %i[source amount recipient],
-          operation_name: "Create Transfer"
-        )
-        handle_response(@connection.post("/transfer", params))
-      end
+    # Transfer operations: send money from your balance to transfer recipients, and manage the OTP
+    # requirement that guards them.
+    class Transfers < PaystackSdk::Resources::Base
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {next_cursor: "next", per_page: "perPage"}.freeze
 
-      # List transfers
+      # List Transfers.
+      #
+      # List the transfers made on your integration.
+      #
+      # @param use_cursor [Boolean] Set to true to use cursor-based pagination (the response meta then carries `next` and `previous`)
+      # @param next_cursor [String] The `next` cursor from a previous cursor-based response
+      # @param previous [String] The `previous` cursor from a previous cursor-based response
+      # @param per_page [Integer] How many records to retrieve per page (Paystack defaults to 50)
+      # @param page [Integer] The page to retrieve (Paystack defaults to 1)
+      # @param from [String, Date, Time] A timestamp from which to start listing transfers
+      # @param to [String, Date, Time] A timestamp at which to stop listing transfers
+      # @param recipient [Integer] Filter by the recipient ID
+      # @param status [String] Filter by status. One of: pending, success, failed, otp, abandoned, reversed, blocked, rejected, received.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer/#list
-      def list(query = {})
-        handle_response(@connection.get("/transfer", query))
+      def list(
+        use_cursor: nil,
+        next_cursor: nil,
+        previous: nil,
+        per_page: nil,
+        page: nil,
+        from: nil,
+        to: nil,
+        recipient: nil,
+        status: nil
+      )
+        validate_positive_integer!(value: per_page, name: "perPage")
+        validate_positive_integer!(value: page, name: "page")
+        validate_allowed_values!(
+          value: status,
+          allowed_values: %w[pending success failed otp abandoned reversed blocked rejected received],
+          name: "status"
+        )
+
+        wire_query = to_wire(
+          {
+            use_cursor:,
+            next_cursor:,
+            previous:,
+            per_page:,
+            page:,
+            from: format_datetime(from, name: "from"),
+            to: format_datetime(to, name: "to"),
+            recipient:,
+            status:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/transfer", wire_query))
       end
 
-      # Fetch a transfer
-      # @see https://paystack.com/docs/api/transfer/#fetch
-      def fetch(id:)
-        validate_presence!(value: id, name: "transfer id")
-        handle_response(@connection.get("/transfer/#{id}"))
+      # Initiate Transfer.
+      #
+      # Send money to your customers. The transfer's status is `pending` when the OTP requirement is
+      # disabled, and `otp` when an OTP is required (complete it with {#finalize}).
+      #
+      # @param amount [Integer] Amount to transfer in the currency's subunit (kobo for NGN, pesewas for GHS)
+      # @param recipient [String] Code for the transfer recipient (RCP_...)
+      # @param reference [String] A unique identifier for the transfer, so retrying it cannot create a second transfer. Paystack documents 16 to 50 characters of lowercase letters, digits, `-` and `_`.
+      # @param source [String] Where to transfer from. Only "balance" for now.
+      # @param reason [String] The reason for the transfer; it also shows up in the narration of the recipient's credit notification
+      # @param currency [String] The currency of the transfer; Paystack defaults to NGN. One of: NGN, ZAR, KES, GHS.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer/#initiate
+      def create(amount:, recipient:, reference:, source:, reason: nil, currency: nil)
+        validate_presence!(value: amount, name: "amount")
+        validate_positive_integer!(value: amount, name: "amount")
+        validate_presence!(value: recipient, name: "recipient")
+        validate_presence!(value: reference, name: "reference")
+        validate_reference_format!(reference: reference, name: "reference")
+        validate_presence!(value: source, name: "source")
+        validate_allowed_values!(
+          value: currency,
+          allowed_values: %w[NGN ZAR KES GHS],
+          name: "currency"
+        )
+
+        wire_body = to_wire(
+          {
+            amount:,
+            recipient:,
+            reference:,
+            source:,
+            reason:,
+            currency:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.post("/transfer", wire_body))
       end
 
-      # Finalize a transfer (OTP)
+      # Finalize Transfer.
+      #
+      # Finalize an initiated transfer that is waiting for an OTP.
+      #
+      # @param transfer_code [String] The transfer code you want to finalize
+      # @param otp [String] OTP sent to the business phone to verify the transfer
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer/#finalize
       def finalize(transfer_code:, otp:)
         validate_presence!(value: transfer_code, name: "transfer_code")
         validate_presence!(value: otp, name: "otp")
-        handle_response(@connection.post("/transfer/finalize_transfer", {transfer_code: transfer_code, otp: otp}))
+
+        wire_body = to_wire({transfer_code:, otp:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transfer/finalize_transfer", wire_body))
+      end
+
+      # Initiate Bulk Transfer.
+      #
+      # Batch multiple transfers in a single request. You need to disable the Transfers OTP
+      # requirement to use this endpoint.
+      #
+      # @param source [String] Where to transfer from. Only "balance" for now.
+      # @param transfers [Array<Hash>] The transfers, each with `amount`, `recipient`, `reference` and optionally `reason`, named as Paystack names them
+      # @param currency [String] The currency of the transfers. One of: NGN, ZAR, KES, GHS.
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer/#bulk
+      def bulk_create(source:, transfers:, currency: nil)
+        validate_presence!(value: source, name: "source")
+        validate_presence!(value: transfers, name: "transfers")
+        validate_allowed_values!(
+          value: currency,
+          allowed_values: %w[NGN ZAR KES GHS],
+          name: "currency"
+        )
+
+        wire_body = to_wire({source:, transfers:, currency:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transfer/bulk", wire_body))
+      end
+
+      # Fetch Transfer.
+      #
+      # Get details of a transfer on your integration.
+      #
+      # @param id_or_code [String, Integer] The transfer ID or code you want to fetch
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer/#fetch
+      def fetch(id_or_code:)
+        validate_presence!(value: id_or_code, name: "id_or_code")
+
+        handle_response(@connection.get("/transfer/#{escape_path(id_or_code, name: "id_or_code")}"))
       end
 
-      # Verify a transfer
+      # Verify Transfer.
+      #
+      # Verify the status of a transfer on your integration.
+      #
+      # @param reference [String] Transfer reference
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transfer/#verify
       def verify(reference:)
         validate_presence!(value: reference, name: "reference")
-        handle_response(@connection.get("/transfer/verify/#{reference}"))
+
+        handle_response(
+          @connection.get("/transfer/verify/#{escape_path(reference, name: "reference")}")
+        )
+      end
+
+      # Export Transfers.
+      #
+      # Export a list of transfers carried out on your integration. This operation is in Paystack's
+      # OpenAPI spec but not on its docs page; the API answers it (404 "Transfers not found" when
+      # nothing matches).
+      #
+      # @param recipient [String] Export transfers by the recipient code
+      # @param status [String] Export transfers by status. One of: pending, success, failed, otp, abandoned, reversed, blocked, rejected, received.
+      # @param from [String, Date, Time] The start date
+      # @param to [String, Date, Time] The end date
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer/
+      def export(recipient: nil, status: nil, from: nil, to: nil)
+        validate_allowed_values!(
+          value: status,
+          allowed_values: %w[pending success failed otp abandoned reversed blocked rejected received],
+          name: "status"
+        )
+
+        wire_query = to_wire(
+          {
+            recipient:,
+            status:,
+            from: format_datetime(from, name: "from"),
+            to: format_datetime(to, name: "to")
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/transfer/export", wire_query))
+      end
+
+      # Resend OTP for Transfer.
+      #
+      # Generates a new OTP and sends it to the business phone, for when it has trouble receiving one.
+      #
+      # @param transfer_code [String] The transfer code that requires an OTP validation
+      # @param reason [String] The purpose of the OTP. The docs list "resend_otp" and "transfer"; the spec also allows "disable_otp".
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer-control/#resend-otp
+      def resend_otp(transfer_code:, reason:)
+        validate_presence!(value: transfer_code, name: "transfer_code")
+        validate_presence!(value: reason, name: "reason")
+        validate_allowed_values!(
+          value: reason,
+          allowed_values: %w[disable_otp resend_otp transfer],
+          name: "reason"
+        )
+
+        wire_body = to_wire({transfer_code:, reason:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transfer/resend_otp", wire_body))
+      end
+
+      # Disable OTP for Transfers.
+      #
+      # Start turning off the OTP requirement so transfers can be completed programmatically.
+      # Paystack sends an OTP to the business phone; confirm with {#finalize_disable_otp}.
+      #
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the API request fails.
+      # @see https://paystack.com/docs/api/transfer-control/#disable-otp
+      def disable_otp
+        handle_response(@connection.post("/transfer/disable_otp"))
+      end
+
+      # Finalize Disabling OTP for Transfers.
+      #
+      # Finalize the request to disable OTP on your transfers.
+      #
+      # @param otp [String] OTP sent to the business phone to verify disabling the OTP requirement
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
+      # @see https://paystack.com/docs/api/transfer-control/#finalize-disable-otp
+      def finalize_disable_otp(otp:)
+        validate_presence!(value: otp, name: "otp")
+
+        wire_body = to_wire({otp:}, WIRE_NAMES)
+
+        handle_response(@connection.post("/transfer/disable_otp_finalize", wire_body))
+      end
+
+      # Enable OTP requirement for Transfers.
+      #
+      # Turn the OTP requirement for transfers back on.
+      #
+      # @return [PaystackSdk::Response] The response from the Paystack API.
+      # @raise [PaystackSdk::Error] If the API request fails.
+      # @see https://paystack.com/docs/api/transfer-control/#enable-otp
+      def enable_otp
+        handle_response(@connection.post("/transfer/enable_otp"))
       end
     end
   end