manza 0.3.0

data/lib/manza/errors.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Manza
+  # Base class for every Manza SDK error.
+  #
+  # Carries the HTTP status, the API request id (header `X-Request-Id`),
+  # the parsed error type from the API (`error.type`), and the raw
+  # response body so callers can introspect anything the SDK didn't
+  # explicitly model.
+  class Error < StandardError
+    attr_reader :status, :request_id, :type, :param, :body
+
+    def initialize(message = nil, status: nil, request_id: nil, type: nil, param: nil, body: nil)
+      super(message)
+      @status = status
+      @request_id = request_id
+      @type = type
+      @param = param
+      @body = body
+    end
+
+    def to_h
+      {
+        error: self.class.name.split("::").last,
+        message:,
+        status:,
+        request_id:,
+        type:,
+        param:
+      }.compact
+    end
+  end
+
+  # 401 — bearer token missing, malformed, or revoked.
+  class AuthenticationError < Error; end
+
+  # 403 — token valid but lacks the required scope, OR the entity is
+  # not yet active, OR the API feature flag is off for this entity.
+  class ForbiddenError < Error; end
+
+  # 404 — the requested resource does not exist (or this entity cannot
+  # see it).
+  class NotFoundError < Error; end
+
+  # 400 / 422 — request body or query params failed validation (400 for
+  # a malformed request such as a bad `limit`/`cursor`, 422 for a
+  # well-formed one the API rejects). `#param` carries the offending
+  # field name when the API supplies it.
+  class ValidationError < Error; end
+
+  # 409 — the request conflicts with an existing resource. For a
+  # duplicate `client_reference` on a transfer draft (`type`
+  # "duplicate_client_reference"), `#payment_id` names the draft that
+  # already holds it.
+  class ConflictError < Error
+    attr_reader :payment_id
+
+    def initialize(message = nil, payment_id: nil, **)
+      super(message, **)
+      @payment_id = payment_id
+    end
+
+    def to_h
+      super.merge(payment_id:).compact
+    end
+  end
+
+  # 429 — rate limited. Retry after the `Retry-After` header (seconds).
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **)
+      super(message, **)
+      @retry_after = retry_after
+    end
+  end
+
+  # 5xx — server error. Worth retrying once with backoff.
+  class ServerError < Error; end
+
+  # Network timeout, connection refused, DNS failure — anything that
+  # prevents the SDK from hearing back from the API.
+  class ConnectionError < Error; end
+
+  # The SDK was misconfigured (no API key, invalid base URL, etc.).
+  # Raised before any HTTP request is attempted.
+  class ConfigurationError < Error; end
+
+  # Caller passed a value the SDK refuses to send (e.g. `limit > 100`).
+  # Distinct from `ValidationError`, which represents server-side
+  # validation rejection.
+  class ArgumentError < Error; end
+end

data/lib/manza/page.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Manza
+  # A single page of a list endpoint's response.
+  #
+  # The Manza API uses cursor pagination. Every list endpoint returns
+  # `{data: [...], has_more: bool, next_cursor: string|null}`. This
+  # class wraps that shape and exposes a cursor-walking helper.
+  #
+  # Pages are intentionally not auto-paginating. The SDK refuses to
+  # let callers iterate every record across many pages with a single
+  # call — that's the failure mode that caused unbounded fetches in
+  # the CLI's `--all` flag. Callers walk pages explicitly:
+  #
+  #   page = client.invoices.list(limit: 100)
+  #   while page
+  #     page.data.each { |inv| ... }
+  #     page = page.next
+  #   end
+  #
+  # Or with a max-items cap that the caller can reason about:
+  #
+  #   client.invoices.each_page(max_items: 500) { |inv| ... }
+  class Page
+    # Hard ceiling on per-page size. Server enforces this too; we
+    # refuse to send a larger value rather than silently get clamped.
+    MAX_PER_PAGE = 100
+
+    attr_reader :response, :data, :has_more, :next_cursor
+
+    def initialize(response, fetcher:)
+      @response = response
+      @fetcher = fetcher
+
+      body = response.body
+      unless body.is_a?(Hash) && body["data"].is_a?(Array)
+        raise Manza::Error.new("List response missing 'data' array",
+                               body:)
+      end
+
+      @data = body["data"]
+      @has_more = body.fetch("has_more", false)
+      @next_cursor = body["next_cursor"]
+    end
+
+    def request_id
+      response.request_id
+    end
+
+    # Fetches the next page. Returns nil when there are no more pages.
+    def next
+      return nil unless has_more && next_cursor
+
+      @fetcher.call(next_cursor)
+    end
+
+    def each(&)
+      data.each(&)
+    end
+
+    include Enumerable
+
+    def inspect
+      "#<#{self.class.name} count=#{data.size} has_more=#{has_more} next_cursor=#{next_cursor.inspect}>"
+    end
+  end
+end

data/lib/manza/resources/accounts.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # Accounts and their transactions.
+    class Accounts < Base
+      # GET /api/accounts
+      #
+      # @param status [String, nil] filter by account status
+      # @param currency_code [String, nil] e.g. "MAD" or "ZAR"
+      # @param limit [Integer] page size (max 100)
+      # @param cursor [String, nil] pagination cursor
+      # @return [Manza::Page]
+      def list(status: nil, currency_code: nil, limit: MAX_PER_PAGE, cursor: nil)
+        list_page(
+          "api/accounts",
+          status: status,
+          currency_code: currency_code,
+          limit: limit,
+          cursor: cursor
+        )
+      end
+
+      # GET /api/accounts/:id
+      def get(id)
+        http_get(encode_path("api/accounts", id))
+      end
+
+      # GET /api/accounts/:account_id/transactions
+      #
+      # @param operation [String, nil] filter by movement operation
+      # @param posted_after [String, Time, nil] ISO-8601 timestamp lower bound
+      # @param posted_before [String, Time, nil] ISO-8601 timestamp upper bound
+      def list_transactions(account_id, operation: nil, posted_after: nil, posted_before: nil, limit: MAX_PER_PAGE,
+                            cursor: nil)
+        list_page(
+          encode_path("api/accounts", account_id, "transactions"),
+          operation: operation,
+          posted_after: serialize_time(posted_after),
+          posted_before: serialize_time(posted_before),
+          limit: limit,
+          cursor: cursor
+        )
+      end
+
+      # GET /api/accounts/:account_id/transactions/:id
+      def get_transaction(account_id, transaction_id)
+        http_get(encode_path("api/accounts", account_id, "transactions", transaction_id))
+      end
+
+      private
+
+      def serialize_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(String)
+
+        value.iso8601
+      end
+    end
+  end
+end

data/lib/manza/resources/base.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # Shared scaffolding for every resource module. Carries a back-
+    # reference to the client and exposes thin HTTP helpers that
+    # delegate to {Manza::Client#request}.
+    #
+    # Note on naming: the helpers are `http_get`, `http_post`, etc.
+    # rather than `get`/`post` so they do not shadow the public
+    # methods on resource subclasses. Public resources commonly
+    # define a `get(id)` method, and a same-named private helper on
+    # the base class would let `Base#list_page` accidentally dispatch
+    # to the subclass version when a list endpoint is hit.
+    #
+    # Pagination:
+    #
+    #   Every resource that has a list endpoint exposes `#list` which
+    #   returns a {Manza::Page}. Callers can walk pages explicitly via
+    #   `page.next` or use `each_page_record` for capped iteration.
+    class Base
+      MAX_PER_PAGE = Page::MAX_PER_PAGE
+
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def http_get(path, params: nil)
+        client.request(:get, path, params: params)
+      end
+
+      def http_post(path, body: nil)
+        client.request(:post, path, body: body)
+      end
+
+      def http_patch(path, body: nil)
+        client.request(:patch, path, body: body)
+      end
+
+      def http_delete(path)
+        client.request(:delete, path)
+      end
+
+      # Builds a paginated list. `path` is the collection endpoint;
+      # `params` is everything else (filters, etc.). `limit` is enforced
+      # at MAX_PER_PAGE; the caller can pass `cursor:` to fetch a
+      # specific page.
+      def list_page(path, limit: MAX_PER_PAGE, cursor: nil, **params)
+        validated_limit = validate_limit!(limit)
+
+        fetcher = lambda { |next_cursor|
+          query = params.merge(limit: validated_limit, cursor: next_cursor).compact
+          response = http_get(path, params: query)
+          Page.new(response, fetcher: fetcher)
+        }
+
+        initial_query = params.merge(limit: validated_limit, cursor: cursor).compact
+        response = http_get(path, params: initial_query)
+        Page.new(response, fetcher: fetcher)
+      end
+
+      # Iterates list-endpoint records up to `max_items`, fetching
+      # additional pages on demand. Caps ensure callers never
+      # accidentally pull a full table.
+      #
+      # Pass either a block or get an Enumerator back.
+      def each_page_record(path, max_items:, **params, &block)
+        return enum_for(:each_page_record, path, max_items: max_items, **params) unless block
+
+        unless max_items.is_a?(Integer) && max_items.positive?
+          raise ArgumentError,
+                "max_items must be a positive integer"
+        end
+
+        seen = 0
+        page = list_page(path, **params)
+
+        loop do
+          page.data.each do |record|
+            return seen if seen >= max_items
+
+            yield record
+            seen += 1
+          end
+
+          break unless page.has_more && seen < max_items
+
+          page = page.next
+          break if page.nil?
+        end
+
+        seen
+      end
+
+      def validate_limit!(limit)
+        return MAX_PER_PAGE if limit.nil?
+
+        raise Manza::ArgumentError, "limit must be a positive integer (got #{limit.inspect})" unless limit.is_a?(Integer) && limit.positive?
+
+        raise Manza::ArgumentError, "limit cannot exceed #{MAX_PER_PAGE} (got #{limit})" if limit > MAX_PER_PAGE
+
+        limit
+      end
+
+      # Builds a request path by joining a literal base path with one
+      # or more dynamic segments. The base is appended verbatim; each
+      # dynamic segment is percent-encoded so an ID containing `/` or
+      # other special characters cannot escape the intended path.
+      #
+      #   encode_path('api/accounts', 'acc_xyz')
+      #     # => "api/accounts/acc_xyz"
+      #
+      #   encode_path('api/accounts', 'acc 1', 'transactions', 'tx 1')
+      #     # => "api/accounts/acc%201/transactions/tx%201"
+      def encode_path(base, *segments)
+        encoded_segments = segments.map do |s|
+          str = s.to_s
+          # An empty segment would silently turn `/things/:id` into
+          # `/things/`, which on most APIs redispatches to the list
+          # endpoint and returns a Page-shaped body. Surface it loudly.
+          raise Manza::ArgumentError, "path segment cannot be blank" if str.empty?
+
+          # CGI.escape replaces ' ' with '+', which is wrong for path
+          # segments. Use a manual escape that targets only characters
+          # that would change path semantics.
+          str.gsub(/[^A-Za-z0-9._~-]/) { |c| format("%%%02X", c.ord) }
+        end
+        ([base] + encoded_segments).join("/")
+      end
+    end
+  end
+end

data/lib/manza/resources/beneficiaries.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # Saved transfer recipients. Each beneficiary embeds its bank
+    # accounts; the one flagged `default` is used when a transfer names
+    # only the beneficiary_id. There is no update or delete via the API.
+    class Beneficiaries < Base
+      # GET /api/beneficiaries
+      def list(limit: MAX_PER_PAGE, cursor: nil)
+        list_page("api/beneficiaries", limit: limit, cursor: cursor)
+      end
+
+      # GET /api/beneficiaries/:id
+      def get(id)
+        http_get(encode_path("api/beneficiaries", id))
+      end
+
+      # POST /api/beneficiaries
+      #
+      # Keys: beneficiary_type ("individual" | "business"; inferred from
+      # person_name / company_name when omitted), person_name, company_name, email,
+      # phone_number. Values must be strings. Shares a 10/minute limit
+      # with {#create_external_account}.
+      def create(**attributes)
+        http_post("api/beneficiaries", body: attributes)
+      end
+
+      # GET /api/beneficiaries/:beneficiary_id/external_accounts
+      def list_external_accounts(beneficiary_id, limit: MAX_PER_PAGE, cursor: nil)
+        list_page(encode_path("api/beneficiaries", beneficiary_id, "external_accounts"), limit: limit, cursor: cursor)
+      end
+
+      # GET /api/beneficiaries/:beneficiary_id/external_accounts/:id
+      def get_external_account(beneficiary_id, id)
+        http_get(encode_path("api/beneficiaries", beneficiary_id, "external_accounts", id))
+      end
+
+      # POST /api/beneficiaries/:beneficiary_id/external_accounts
+      #
+      # Required: account_number. Optional: name, country_code,
+      # currency_code, account_type ("bank" only), bank_identifier
+      # (required in ZA, rejected in MA, where it is derived from the RIB).
+      def create_external_account(beneficiary_id, **attributes)
+        http_post(encode_path("api/beneficiaries", beneficiary_id, "external_accounts"), body: attributes)
+      end
+    end
+  end
+end

data/lib/manza/resources/checkout_sessions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # One-off hosted checkout sessions. Pre-API there's no list,
+    # update, or delete — sessions are created and inspected by id.
+    # State (`open`, `processing`, `clearing`, `complete`, `expired`)
+    # transitions are read-only from the SDK's perspective. Responses
+    # carry `settled_at` and the paying `transaction`.
+    class CheckoutSessions < Base
+      # GET /api/checkout_sessions/:id
+      def get(id)
+        http_get(encode_path("api/checkout_sessions", id))
+      end
+
+      # POST /api/checkout_sessions
+      #
+      # @param attributes [Hash] checkout-session attributes — see API docs.
+      #   Required: account_id, amount, success_url.
+      #   Optional: metadata, customer_email, customer_name, cancel_url,
+      #   description, expires_at, collect_billing_address, billing_address.
+      def create(**attributes)
+        http_post("api/checkout_sessions", body: attributes)
+      end
+    end
+  end
+end

data/lib/manza/resources/customers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # Customers — individuals or businesses the entity invoices.
+    class Customers < Base
+      # GET /api/customers
+      #
+      # @param q [String, nil] search query (matches company name, person name, email)
+      def list(q: nil, limit: MAX_PER_PAGE, cursor: nil)
+        list_page("api/customers", q: q, limit: limit, cursor: cursor)
+      end
+
+      # GET /api/customers/:id
+      def get(id)
+        http_get(encode_path("api/customers", id))
+      end
+
+      # POST /api/customers
+      #
+      # @param attributes [Hash] customer attributes — see API docs.
+      #   Common keys: customer_type ("individual"|"business"),
+      #   person_name, company_name, email, phone, registration_number,
+      #   vat_number, billing_address (Hash with street/city/postal_code/
+      #   country/country_code). Morocco only: tax_id, ice_number — these
+      #   keys are absent from responses in other markets.
+      def create(**attributes)
+        http_post("api/customers", body: attributes)
+      end
+
+      # PATCH /api/customers/:id
+      def update(id, **attributes)
+        http_patch(encode_path("api/customers", id), body: attributes)
+      end
+
+      # DELETE /api/customers/:id
+      def delete(id)
+        http_delete(encode_path("api/customers", id))
+      end
+    end
+  end
+end

data/lib/manza/resources/entity.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # The current entity (the tenant the API key belongs to).
+    #
+    #   client.entity.get  # => Manza::Response
+    class Entity < Base
+      def get
+        http_get("api/entity")
+      end
+    end
+  end
+end

data/lib/manza/resources/invoices.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # Invoices and their lifecycle actions.
+    class Invoices < Base
+      # GET /api/invoices
+      def list(status: nil, customer_id: nil, limit: MAX_PER_PAGE, cursor: nil)
+        list_page(
+          "api/invoices",
+          status: status,
+          customer_id: customer_id,
+          limit: limit,
+          cursor: cursor
+        )
+      end
+
+      # GET /api/invoices/:id
+      def get(id)
+        http_get(encode_path("api/invoices", id))
+      end
+
+      # POST /api/invoices
+      def create(**attributes)
+        http_post("api/invoices", body: attributes)
+      end
+
+      # PATCH /api/invoices/:id
+      def update(id, **attributes)
+        http_patch(encode_path("api/invoices", id), body: attributes)
+      end
+
+      # POST /api/invoices/:id/send
+      def send_invoice(id)
+        http_post(encode_path("api/invoices", id, "send"))
+      end
+
+      # POST /api/invoices/:id/mark_as_paid
+      def mark_as_paid(id)
+        http_post(encode_path("api/invoices", id, "mark_as_paid"))
+      end
+
+      # POST /api/invoices/:id/cancel
+      def cancel(id)
+        http_post(encode_path("api/invoices", id, "cancel"))
+      end
+
+      # POST /api/invoices/:id/credit_note
+      def credit_note(id)
+        http_post(encode_path("api/invoices", id, "credit_note"))
+      end
+
+      # DELETE /api/invoices/:id
+      def delete(id)
+        http_delete(encode_path("api/invoices", id))
+      end
+
+      # POST /api/invoices/:invoice_id/payment_link
+      #
+      # @param account_id [String] the funding account for the link
+      def create_payment_link(invoice_id, account_id:)
+        http_post(
+          encode_path("api/invoices", invoice_id, "payment_link"),
+          body: { account_id: account_id }
+        )
+      end
+    end
+  end
+end

data/lib/manza/resources/payee_trust_requests.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # Requests to trust payees for machine-authorized transfers. The API
+    # key can only ask: a member holding payment-authorize permission
+    # approves the request in the Manza app. Status: pending → approved /
+    # declined / cancelled. There is no list, update, or delete.
+    class PayeeTrustRequests < Base
+      # POST /api/payee_trust_requests
+      #
+      # @param external_account_ids [Array<String>] at most 100 bank accounts.
+      def create(external_account_ids:)
+        http_post("api/payee_trust_requests", body: { external_account_ids: external_account_ids })
+      end
+
+      # GET /api/payee_trust_requests/:id
+      def get(id)
+        http_get(encode_path("api/payee_trust_requests", id))
+      end
+    end
+  end
+end

data/lib/manza/resources/payment_links.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # Standalone payment links (not attached to an invoice).
+    class PaymentLinks < Base
+      # GET /api/payment_links
+      def list(status: nil, link_type: nil, limit: MAX_PER_PAGE, cursor: nil)
+        list_page(
+          "api/payment_links",
+          status: status,
+          link_type: link_type,
+          limit: limit,
+          cursor: cursor
+        )
+      end
+
+      # GET /api/payment_links/:id
+      def get(id)
+        http_get(encode_path("api/payment_links", id))
+      end
+
+      # POST /api/payment_links
+      #
+      # Optional billing keys: collect_billing_address, billing_address.
+      # Responses carry `settled_at`; status includes `clearing`.
+      def create(**attributes)
+        http_post("api/payment_links", body: attributes)
+      end
+
+      # POST /api/payment_links/:id/cancel
+      def cancel(id)
+        http_post(encode_path("api/payment_links", id, "cancel"))
+      end
+    end
+  end
+end

data/lib/manza/resources/transfer_drafts.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Manza
+  module Resources
+    # API-initiated transfers. Creating a draft never executes a
+    # transfer by itself. A draft inside the entity's machine-
+    # authorization envelope (trusted payee, within limits) is sent to
+    # the enrolled transfer authorizer as a `payment.authorization_requested`
+    # webhook; answer it with {#authorize} or {#decline}, using an API
+    # key other than the one that created the draft. Every other draft
+    # goes to the in-app approval flow, where a manager or legal
+    # representative approves it. Poll {#get} (status: requested →
+    # processing → completed / failed) or subscribe to the
+    # `transfer.executed` webhook to follow execution.
+    class TransferDrafts < Base
+      # POST /api/transfer_drafts
+      #
+      # Required: account_id, amount, and exactly one of beneficiary_id
+      # (external transfer) or destination_account_id (own-account move).
+      # Optional: external_account_id, currency_code, payment_reference,
+      # internal_notes, client_reference (unique per entity, at most 128
+      # characters; a duplicate raises {Manza::ConflictError} whose
+      # `payment_id` names the existing draft).
+      def create(**attributes)
+        http_post("api/transfer_drafts", body: attributes)
+      end
+
+      # GET /api/transfer_drafts/:id
+      def get(id)
+        http_get(encode_path("api/transfer_drafts", id))
+      end
+
+      # POST /api/transfer_drafts/:id/authorize
+      #
+      # Executes the draft. `authorization_id` comes from the
+      # `payment.authorization_requested` webhook; build `signature` with
+      # {Manza::TransferAuthorization}. Requires the `transfers:authorize`
+      # scope on a key other than the draft's creator (otherwise 403
+      # `same_key_forbidden`). A blank signature is refused locally: the
+      # API counts it as a failed attempt, and five fail the challenge.
+      def authorize(id, authorization_id:, signature:)
+        raise Manza::ArgumentError, "signature cannot be blank" if signature.to_s.strip.empty?
+
+        http_post(
+          encode_path("api/transfer_drafts", id, "authorize"),
+          body: { authorization_id: authorization_id, signature: signature }
+        )
+      end
+
+      # POST /api/transfer_drafts/:id/decline
+      #
+      # Declines the challenge and deletes the draft. Returns the
+      # authorization (`status: "declined"`).
+      def decline(id, authorization_id:, reason: nil)
+        http_post(
+          encode_path("api/transfer_drafts", id, "decline"),
+          body: { authorization_id: authorization_id, reason: reason }.compact
+        )
+      end
+    end
+  end
+end