zazu-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb2684661a728ba3f69777037fa66bbc8c9a0ed50b168709b3be159dabb9d5d4
+  data.tar.gz: 8ff94850c110055ea939adc202010df5f8f2622f64d4935e79b67e848a48e986
+SHA512:
+  metadata.gz: fef8dcde5e3433ece2c550573fc717a5bd172ebaf9d13284eb3e77b44503793d10859fa7324669551189ce4230e059c9ba436b173e5a90d8c5cec90cab2270d0
+  data.tar.gz: ad848283fcb72e9c17d385fba58f19588370db028f673963a49ac682d9c7aefc718969586867e67e542da966df0e2038ac78a1398c533b3dbf70471011092ca9

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `zazu-ruby` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+
+- `Zazu::Client` — Faraday + HTTPX adapter, JSON request/response, retry middleware.
+- Resource modules: `Accounts`, `Customers`, `Entity`, `Invoices`, `PaymentLinks`, `WebhookEndpoints`.
+- Cursor-based pagination via `Zazu::Page` (max 100 records per page; no auto-pagination).
+- Error hierarchy: `AuthenticationError`, `ForbiddenError`, `NotFoundError`,
+  `ValidationError`, `RateLimitError`, `ServerError`, `ConnectionError`,
+  `ConfigurationError`, `ArgumentError` — all under `Zazu::Error`.
+- VCR-backed RSpec suite covering every public method.
+- Cassette tarball published as a release asset for cross-language SDK reuse.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zazu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,178 @@
+# Zazu Ruby SDK
+
+Ruby SDK for the [Zazu API](https://zazu.ma). Faraday + HTTPX adapter for HTTP/2 + persistent connections.
+
+```ruby
+gem "zazu-ruby"
+```
+
+The gem is published as `zazu-ruby` on RubyGems but loaded as `zazu` in code (the `zazu` name was already taken by an unrelated 2014-era gem).
+
+## Quick start
+
+```ruby
+require "zazu"
+
+zazu = Zazu.new(api_key: ENV["ZAZU_API_KEY"])
+# Or with explicit base URL (defaults to https://zazu.ma):
+zazu = Zazu.new(api_key: ENV["ZAZU_API_KEY"], base_url: "https://zazu.africa")
+
+entity = zazu.entity.get
+# => #<Zazu::Response status=200 ...>
+entity.body["name"]
+# => "Acme Corp"
+```
+
+Environment variables `ZAZU_API_KEY`, `ZAZU_BASE_URL`, `ZAZU_API_VERSION`, and `ZAZU_TIMEOUT` are read by default.
+
+## Resources
+
+```ruby
+zazu.entity.get
+
+zazu.accounts.list(currency_code: "MAD", limit: 50)
+zazu.accounts.get("019dde7d-...")
+zazu.accounts.list_transactions("019dde7d-...", operation: "credit")
+zazu.accounts.get_transaction("019dde7d-...", "01a0e1...")
+
+zazu.customers.list(q: "acme")
+zazu.customers.get("01a0...")
+zazu.customers.create(
+  customer_type: "business",
+  company_name: "Acme Corp",
+  email: "billing@acme.com",
+  ice_number: "000000000000000"
+)
+zazu.customers.update("01a0...", email: "new@example.com")
+zazu.customers.delete("01a0...")
+
+zazu.invoices.list(status: "sent", limit: 50)
+zazu.invoices.create(
+  customer_id: "01a0...",
+  currency_code: "MAD",
+  issue_date: "2026-05-03",
+  due_date: "2026-06-03",
+  items: [{ description: "Consulting", quantity: 10, unit_price: "150.00" }]
+)
+zazu.invoices.send_invoice("01a0...")
+zazu.invoices.mark_as_paid("01a0...")
+zazu.invoices.cancel("01a0...")
+zazu.invoices.credit_note("01a0...")
+zazu.invoices.create_payment_link("01a0...", account_id: "019dde7d-...")
+
+zazu.payment_links.list(status: "active")
+zazu.payment_links.create(
+  account_id: "019dde7d-...",
+  amount: "1500.00",
+  description: "March consulting",
+  link_type: "single"
+)
+zazu.payment_links.cancel("01a0...")
+
+zazu.webhook_endpoints.list
+zazu.webhook_endpoints.create(
+  url: "https://example.com/webhooks/zazu",
+  events: ["invoice.sent", "payment_link.paid"]
+)
+zazu.webhook_endpoints.test_endpoint("01a0...")
+zazu.webhook_endpoints.regenerate_secret("01a0...")
+zazu.webhook_endpoints.enable("01a0...")
+zazu.webhook_endpoints.disable("01a0...")
+```
+
+## Pagination
+
+Every list endpoint returns a `Zazu::Page`. The SDK enforces a hard cap of **100 records per page** — there is no auto-pagination across pages.
+
+```ruby
+page = zazu.invoices.list(limit: 100)
+page.data         # => Array of invoice hashes
+page.has_more     # => true / false
+page.next_cursor  # => string or nil
+
+# Walk pages explicitly:
+while page
+  page.data.each { |inv| process(inv) }
+  page = page.next  # returns nil when has_more is false
+end
+```
+
+For capped iteration, use the underlying `each_page_record` helper on a resource (private; access via `send` if you need it). The deliberate restriction is a guardrail — accidentally pulling 50,000 records in a single SDK call should be impossible without explicit per-page consent.
+
+## Errors
+
+Every non-2xx response raises a subclass of `Zazu::Error`:
+
+| Status | Class |
+|---|---|
+| 401 | `Zazu::AuthenticationError` |
+| 403 | `Zazu::ForbiddenError` |
+| 404 | `Zazu::NotFoundError` |
+| 422 | `Zazu::ValidationError` |
+| 429 | `Zazu::RateLimitError` (carries `#retry_after`) |
+| 5xx | `Zazu::ServerError` |
+| network | `Zazu::ConnectionError` |
+
+Each error exposes `#status`, `#request_id`, `#type`, `#param`, and the raw `#body`.
+
+```ruby
+begin
+  zazu.invoices.get("does-not-exist")
+rescue Zazu::NotFoundError => e
+  e.status      # => 404
+  e.request_id  # => "req_..."
+  e.type        # => "not_found_error"
+end
+```
+
+## Versioning the API contract
+
+```ruby
+zazu = Zazu.new(api_key: "...", api_version: "2026-03-27")
+```
+
+Or via env: `ZAZU_API_VERSION=2026-03-27`. The header is sent on every request; the API echoes it back in `Zazu-Version`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+The spec suite is VCR-backed — cassettes live in `spec/fixtures/cassettes/` and are committed to the repo.
+
+To re-record cassettes against staging:
+
+```bash
+cp .env.example .env
+# fill in ZAZU_STAGING_API_KEY and the ZAZU_FIXTURE_*_ID values
+bundle exec rake fixtures:record
+```
+
+Cassettes are scrubbed before write — bearer tokens and request IDs are rewritten to placeholders. Even if a real key is in `.env`, the committed cassette never contains it.
+
+## Cassettes for other-language SDKs
+
+Each release of `zazu-ruby` publishes the cassette directory as a tarball release asset:
+
+```
+https://github.com/getzazu/zazu-ruby/releases/download/v0.1.0/cassettes-v0.1.0.tar.gz
+```
+
+`zazu-go`, `zazu-python`, etc. pin a specific version in their `.zazu-fixtures` file and download the tarball during CI. This guarantees every SDK is tested against the same recorded API interactions, surfacing cross-SDK inconsistencies immediately.
+
+VCR's YAML format is supported natively by:
+
+- Ruby — VCR (this gem)
+- Go — go-vcr
+- Python — VCR.py
+- PHP — PHP-VCR
+- Crystal — vcr-crystal / hi8.cr
+- Rust — http_replayer (or a small custom YAML reader)
+- JavaScript / TypeScript — Talkback or polly.js (slight format adapter needed)
+
+## License
+
+MIT

data/lib/zazu/client.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "httpx/adapters/faraday"
+require "json"
+require "securerandom"
+
+module Zazu
+  # The main SDK entry point.
+  #
+  #   zazu = Zazu::Client.new(api_key: "sk_live_...")
+  #   zazu.entity.get
+  #   zazu.accounts.list(limit: 50)
+  #
+  # All public state is set at construction time. The client is
+  # thread-safe in the sense that the underlying Faraday connection
+  # uses a connection pool via the HTTPX adapter — multiple threads
+  # can share one client.
+  class Client
+    DEFAULT_BASE_URL = "https://zazu.ma"
+    DEFAULT_TIMEOUT = 30
+    USER_AGENT = "zazu-ruby/#{VERSION}".freeze
+
+    attr_reader :api_key, :base_url, :api_version, :timeout, :logger
+
+    def initialize(
+      api_key: ENV.fetch("ZAZU_API_KEY", nil),
+      base_url: ENV.fetch("ZAZU_BASE_URL", DEFAULT_BASE_URL),
+      api_version: ENV.fetch("ZAZU_API_VERSION", nil),
+      timeout: Integer(ENV.fetch("ZAZU_TIMEOUT", DEFAULT_TIMEOUT)),
+      logger: nil
+    )
+      raise ConfigurationError, "Missing api_key. Pass api_key: or set ZAZU_API_KEY." if api_key.to_s.empty?
+
+      @api_key = api_key
+      @base_url = base_url.to_s.chomp("/")
+      @api_version = api_version
+      @timeout = timeout
+      @logger = logger
+    end
+
+    # Resource accessors — each returns a memoized resource module.
+    def accounts
+      @accounts ||= Resources::Accounts.new(self)
+    end
+
+    def customers
+      @customers ||= Resources::Customers.new(self)
+    end
+
+    def entity
+      @entity ||= Resources::Entity.new(self)
+    end
+
+    def invoices
+      @invoices ||= Resources::Invoices.new(self)
+    end
+
+    def payment_links
+      @payment_links ||= Resources::PaymentLinks.new(self)
+    end
+
+    def webhook_endpoints
+      @webhook_endpoints ||= Resources::WebhookEndpoints.new(self)
+    end
+
+    # Performs an HTTP request and returns a {Zazu::Response} on
+    # success. Translates non-2xx responses into the matching
+    # {Zazu::Error} subclass.
+    def request(method, path, params: nil, body: nil, headers: {})
+      raw = connection.send(method) do |req|
+        req.url(path)
+        req.params.update(params) if params
+        req.body = body unless body.nil?
+        headers.each { |k, v| req.headers[k] = v }
+      end
+
+      response = Response.new(raw)
+      return response if response.success?
+
+      raise build_error(response)
+    rescue Faraday::TimeoutError => e
+      raise ConnectionError, "Request timed out after #{timeout}s: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |f|
+        f.headers["Authorization"] = "Bearer #{api_key}"
+        f.headers["User-Agent"] = USER_AGENT
+        f.headers["Accept"] = "application/json"
+        f.headers["Zazu-Version"] = api_version if api_version
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.options.timeout = timeout
+        f.options.open_timeout = [timeout, 10].min
+        f.response :logger, logger if logger
+        f.adapter(*adapter_args)
+      end
+    end
+
+    # The HTTPX adapter ships its own WebMock plugin that wraps every
+    # connection. When VCR's WebMock library hook is also active and
+    # net-connect is allowed (recording mode), the two interceptors
+    # layer in a way that deadlocks on the first real request. For
+    # cassette recording we drop down to Net::HTTP, which has rock-
+    # solid WebMock + VCR integration. Cassettes are adapter-agnostic
+    # so replay continues to use the production HTTPX adapter.
+    def adapter_args
+      ENV["VCR_RECORD"] ? [:net_http] : [:httpx]
+    end
+
+    # Lookup table for status → (error class, default message). 5xx
+    # is matched separately because Range keys don't work in Hash
+    # lookup the way exact integers do.
+    ERROR_BY_STATUS = {
+      401 => [AuthenticationError, "Authentication failed"],
+      403 => [ForbiddenError, "Forbidden"],
+      404 => [NotFoundError, "Not found"],
+      422 => [ValidationError, "Validation failed"]
+    }.freeze
+    private_constant :ERROR_BY_STATUS
+
+    def build_error(response)
+      payload = error_payload(response.body)
+      message = payload["message"]
+      kwargs = error_kwargs(response, payload)
+
+      if (mapping = ERROR_BY_STATUS[response.status])
+        klass, default_message = mapping
+        return klass.new(message || default_message, **kwargs)
+      end
+
+      build_special_error(response, message, kwargs)
+    end
+
+    def error_payload(body)
+      return {} unless body.is_a?(Hash) && body["error"].is_a?(Hash)
+
+      body["error"]
+    end
+
+    def error_kwargs(response, payload)
+      {
+        status: response.status,
+        request_id: response.request_id,
+        type: payload["type"],
+        param: payload["param"],
+        body: response.body
+      }
+    end
+
+    def build_special_error(response, message, kwargs)
+      case response.status
+      when 429
+        retry_after = response.headers["retry-after"]&.to_i
+        RateLimitError.new(message || "Rate limited", retry_after: retry_after, **kwargs)
+      when 500..599
+        ServerError.new(message || "Server error (#{response.status})", **kwargs)
+      else
+        Error.new(message || "Unexpected status #{response.status}", **kwargs)
+      end
+    end
+  end
+end

data/lib/zazu/errors.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Zazu
+  # Base class for every Zazu 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
+
+  # 422 — request body or query params failed validation. `#param`
+  # carries the offending field name when the API supplies it.
+  class ValidationError < Error; 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/zazu/page.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Zazu
+  # A single page of a list endpoint's response.
+  #
+  # The Zazu 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 Zazu::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/zazu/resources/accounts.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Zazu
+  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 [Zazu::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/zazu/resources/base.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Zazu
+  module Resources
+    # Shared scaffolding for every resource module. Carries a back-
+    # reference to the client and exposes thin HTTP helpers that
+    # delegate to {Zazu::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 {Zazu::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 Zazu::ArgumentError, "limit must be a positive integer (got #{limit.inspect})" unless limit.is_a?(Integer) && limit.positive?
+
+        raise Zazu::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 Zazu::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/zazu/resources/customers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Zazu
+  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, tax_id, ice_number,
+      #   billing_address (Hash with street/city/postal_code/country/country_code).
+      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/zazu/resources/entity.rb

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

data/lib/zazu/resources/invoices.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Zazu
+  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/zazu/resources/payment_links.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Zazu
+  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
+      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/zazu/resources/webhook_endpoints.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Zazu
+  module Resources
+    # Webhook endpoint configuration.
+    class WebhookEndpoints < Base
+      # GET /api/webhook_endpoints
+      def list(limit: MAX_PER_PAGE, cursor: nil)
+        list_page("api/webhook_endpoints", limit: limit, cursor: cursor)
+      end
+
+      # GET /api/webhook_endpoints/:id
+      def get(id)
+        http_get(encode_path("api/webhook_endpoints", id))
+      end
+
+      # POST /api/webhook_endpoints
+      #
+      # @param url [String] the URL to deliver events to
+      # @param events [Array<String>] event names to subscribe to
+      # @param description [String, nil]
+      def create(url:, events:, description: nil)
+        http_post(
+          "api/webhook_endpoints",
+          body: { url: url, events: events, description: description }.compact
+        )
+      end
+
+      # PATCH /api/webhook_endpoints/:id
+      def update(id, **attributes)
+        http_patch(encode_path("api/webhook_endpoints", id), body: attributes)
+      end
+
+      # DELETE /api/webhook_endpoints/:id
+      def delete(id)
+        http_delete(encode_path("api/webhook_endpoints", id))
+      end
+
+      # POST /api/webhook_endpoints/:id/test
+      def test_endpoint(id)
+        http_post(encode_path("api/webhook_endpoints", id, "test"))
+      end
+
+      # POST /api/webhook_endpoints/:id/regenerate_secret
+      def regenerate_secret(id)
+        http_post(encode_path("api/webhook_endpoints", id, "regenerate_secret"))
+      end
+
+      # POST /api/webhook_endpoints/:id/enable
+      def enable(id)
+        http_post(encode_path("api/webhook_endpoints", id, "enable"))
+      end
+
+      # POST /api/webhook_endpoints/:id/disable
+      def disable(id)
+        http_post(encode_path("api/webhook_endpoints", id, "disable"))
+      end
+    end
+  end
+end

data/lib/zazu/response.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Zazu
+  # Wraps a Faraday response with the few helpers callers actually
+  # want. Cheap value object — no parsing or normalization is done
+  # eagerly; `body`, `data`, `headers` all read straight through.
+  #
+  # The SDK's resource methods return one of these directly when the
+  # endpoint is a single-record fetch. List endpoints return a
+  # {Zazu::Page} instead, which composes a Response.
+  class Response
+    attr_reader :raw, :request_id
+
+    def initialize(raw, request_id: nil)
+      @raw = raw
+      @request_id = request_id || raw.headers["x-request-id"]
+    end
+
+    def status
+      raw.status
+    end
+
+    def headers
+      raw.headers
+    end
+
+    def body
+      raw.body
+    end
+
+    def success?
+      status.between?(200, 299)
+    end
+
+    # Returns the response body without the `data` envelope when one
+    # is present. List endpoints wrap their items in `{"data": [...]}`
+    # — this returns the array. Single-record endpoints return the
+    # body as-is.
+    def data
+      return body unless body.is_a?(Hash)
+
+      body.key?("data") ? body["data"] : body
+    end
+
+    # The Zazu-Version header echoed by the server. Useful for
+    # debugging migration mismatches.
+    def api_version
+      headers["zazu-version"]
+    end
+
+    def to_h
+      {
+        status:,
+        request_id:,
+        api_version:,
+        body:
+      }.compact
+    end
+
+    def inspect
+      "#<#{self.class.name} status=#{status} request_id=#{request_id.inspect}>"
+    end
+  end
+end

data/lib/zazu/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Zazu
+  VERSION = "0.1.0"
+end

data/lib/zazu.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Ruby SDK for the Zazu API.
+#
+# Usage:
+#
+#   zazu = Zazu.new(api_key: ENV["ZAZU_API_KEY"])
+#   zazu.entity.get
+#   zazu.accounts.list(limit: 50)
+#
+# See README.md for full documentation.
+module Zazu
+  # Module-level shortcut. Equivalent to Zazu::Client.new(...).
+  def self.new(**)
+    Client.new(**)
+  end
+end
+
+require_relative "zazu/version"
+require_relative "zazu/errors"
+require_relative "zazu/response"
+require_relative "zazu/page"
+require_relative "zazu/resources/base"
+require_relative "zazu/resources/accounts"
+require_relative "zazu/resources/customers"
+require_relative "zazu/resources/entity"
+require_relative "zazu/resources/invoices"
+require_relative "zazu/resources/payment_links"
+require_relative "zazu/resources/webhook_endpoints"
+require_relative "zazu/client"

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: zazu-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zazu
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: httpx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Faraday-based Ruby SDK for the Zazu payment platform API. Wraps accounts,
+  customers, invoices, payment links, transactions, and webhook endpoints. HTTPX adapter
+  for HTTP/2 + persistent connections.
+email:
+- hello@get-zazu.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/zazu.rb
+- lib/zazu/client.rb
+- lib/zazu/errors.rb
+- lib/zazu/page.rb
+- lib/zazu/resources/accounts.rb
+- lib/zazu/resources/base.rb
+- lib/zazu/resources/customers.rb
+- lib/zazu/resources/entity.rb
+- lib/zazu/resources/invoices.rb
+- lib/zazu/resources/payment_links.rb
+- lib/zazu/resources/webhook_endpoints.rb
+- lib/zazu/response.rb
+- lib/zazu/version.rb
+homepage: https://github.com/getzazu/zazu-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/getzazu/zazu-ruby/tree/main
+  changelog_uri: https://github.com/getzazu/zazu-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/getzazu/zazu-ruby/issues
+  documentation_uri: https://github.com/getzazu/zazu-ruby#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby SDK for the Zazu API
+test_files: []