nombaone 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8afad05465e8552625852dc7e1f0b51622c5f22c60363a3c634a12e9d0ec9eca
+  data.tar.gz: e02ec17de6bae9637866fd224308ebe01c76b039b2c9f71cfb5397f030074257
+SHA512:
+  metadata.gz: 730e98dad92f45ba053b64c09fb9d9ad46423cad73e70b556cedb96401bf75b2ffb51693c7cf026bcc62847aba7a1bffbcd604ae4dd2c3e2bd2acc7d41c076b8
+  data.tar.gz: 694293710c28f718bd958864f3b62d045b95cb3e4fe1f8e58a68db59e2076f641e389471bb924248d6b3bb5377907147a30be8228c7c92dad308c7b244d78b4c

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+Initial release — the official Ruby SDK for the NombaOne subscription-billing
+API.
+
+### Added
+
+- `Nombaone::Client` covering the full API surface: customers, plans (with
+  nested prices), prices, subscriptions (with schedules and dunning), invoices,
+  coupons, payment methods, mandates, settlements, webhook endpoints (with
+  deliveries), events, organization (with billing policy), metrics, and the
+  sandbox toolkit.
+- Automatic, money-safe idempotency: a UUID `Idempotency-Key` is generated once
+  per POST and reused across every automatic retry, so a network blip can never
+  double-charge.
+- Automatic retries with full-jitter exponential backoff, honoring `Retry-After`,
+  for transport failures, timeouts, 408/429/5xx, and in-flight idempotency
+  conflicts.
+- Typed error hierarchy (`Nombaone::APIError` and subclasses) carrying the wire
+  `code`, `hint`, `doc_url`, per-field validation errors, and `request_id`.
+- Cursor pagination with idiomatic auto-iteration (`Enumerable`, `each`,
+  `auto_paging_each`) plus manual cursor control.
+- A keyless webhook helper (`Nombaone.webhooks`) implementing signed-delivery
+  verification, event construction, and test-header generation.
+- Zero runtime dependencies; RBS type signatures shipped in `sig/`.
+
+[Unreleased]: https://github.com/nombaone/nomba-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nombaone/nomba-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nomba One
+
+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,230 @@
+# nombaone
+
+The official Ruby SDK for the [Nomba One](https://nombaone.xyz) subscription-billing API — recurring billing for Nigeria over card, direct debit, bank transfer, and more, with dunning that recovers and a ledger that never loses a kobo.
+
+```bash
+gem install nombaone
+# or add to your Gemfile:
+gem "nombaone"
+```
+
+Requires Ruby 3.1+. Zero runtime dependencies (built on the standard library). Ships RBS type signatures.
+
+## Quickstart
+
+Grab a sandbox key (`nbo_sandbox_…`) from the [dashboard](https://app.nombaone.xyz), set it as `NOMBAONE_API_KEY`, and you are three objects away from a live subscription:
+
+```ruby
+require "nombaone"
+
+nombaone = Nombaone.new(ENV["NOMBAONE_API_KEY"])
+
+plan = nombaone.plans.create(name: "Pro")
+price = nombaone.plans.prices.create(plan.id, unit_amount_in_kobo: 250_000, interval: "month") # ₦2,500/mo
+customer = nombaone.customers.create(email: "ada@example.com", name: "Ada Lovelace")
+
+# Sandbox: mint a deterministic test card, then subscribe.
+method = nombaone.sandbox.create_payment_method(customer_id: customer.id)
+subscription = nombaone.subscriptions.create(
+  customer_id: customer.id,
+  price_id: price.id,
+  payment_method_id: method.id,
+)
+
+subscription.status # => "active"
+```
+
+The client derives the host from your key prefix — `nbo_sandbox_…` talks to `https://sandbox.api.nombaone.xyz`, `nbo_live_…` to `https://api.nombaone.xyz`. Server-side only; there is no publishable key to leak.
+
+## Sandbox first
+
+The sandbox runs the real billing engine. `nombaone.sandbox.*` gives you the levers to make a month happen in a second:
+
+```ruby
+# A card that declines like a thin balance does — "not yet", not "no".
+nombaone.sandbox.create_payment_method(
+  customer_id: customer.id,
+  behavior: "decline_insufficient_funds", # or success | requires_otp | decline_expired_card | decline_do_not_honor
+)
+
+# The test clock: force the next billing cycle through the real engine.
+cycle = nombaone.sandbox.advance_cycle(subscription.id)
+cycle.outcome # => "paid" | "past_due" | …
+
+# Fire a real, signed webhook at your registered endpoints.
+nombaone.sandbox.simulate_webhook(type: "invoice.payment_failed")
+```
+
+These methods raise locally (before any network call) if used with a live key.
+
+## Money is integer kobo
+
+Every amount in the API is an **integer in kobo**: `₦1.00 = 100`. `250_000` is ₦2,500 — not ₦250,000. No floats, no decimal strings, `currency` is always `"NGN"`. Multiply naira by 100 exactly once, at the edge of your system; every money field is suffixed `_in_kobo` so a mixup is hard to type.
+
+## Response objects
+
+Every result is a lightweight object with snake_case readers derived from the wire's camelCase, plus bracket access and a `to_h` escape hatch:
+
+```ruby
+sub = nombaone.subscriptions.retrieve(id)
+sub.status              # => "active"
+sub.current_period_end  # from "currentPeriodEnd"
+sub.items.first.price_id
+sub[:latestInvoiceId]   # bracket access (snake or wire, String or Symbol)
+sub.to_h                # the raw wire Hash
+sub.request_id          # the meta.requestId for this call
+```
+
+## Pagination
+
+Every `list` works three ways:
+
+```ruby
+# One page.
+page = nombaone.invoices.list(status: "open", limit: 50)
+page.data          # the items on this page
+page.has_more?
+page.next_cursor
+
+# Manual paging.
+page = page.next_page if page.next_page?
+
+# Or let the SDK thread the cursors — a Page is Enumerable, and iteration is
+# lazy (first(3) only fetches what it needs):
+nombaone.invoices.list(status: "open").each do |invoice|
+  # every item across every page
+end
+recent = nombaone.customers.list.first(3)
+```
+
+## Errors are a feature
+
+Failures raise typed errors carrying everything the API said — the stable `code` to branch on, a `hint` telling you exactly what to do next, a `doc_url` into the error reference, per-field details on validation failures, and the `request_id` to quote to support:
+
+```ruby
+begin
+  nombaone.subscriptions.create(customer_id: customer_id, price_id: price_id)
+rescue Nombaone::ValidationError => e
+  e.fields   # { "paymentMethodId" => [...] }
+rescue Nombaone::RateLimitError => e
+  e.retry_after # seconds
+rescue Nombaone::NotFoundError => e
+  e.code     # "CUSTOMER_NOT_FOUND"
+end
+```
+
+| Status | Class                    | Notes                                     |
+| ------ | ------------------------ | ----------------------------------------- |
+| 400    | `BadRequestError`        | malformed request                         |
+| 401    | `AuthenticationError`    | missing/invalid/wrong-environment key     |
+| 403    | `PermissionDeniedError`  | missing scope, foreign resource           |
+| 404    | `NotFoundError`          | wrong id or wrong environment             |
+| 409    | `ConflictError`          | state conflicts, idempotency reuse        |
+| 422    | `ValidationError`        | `error.fields` has the per-field messages |
+| 429    | `RateLimitError`         | `retry_after`, `limit`, `remaining`       |
+| 5xx    | `ServerError`            | safe to retry (the SDK already did)       |
+| —      | `ConnectionError` / `TimeoutError` | transport-level                 |
+
+All of them descend from `Nombaone::Error`, and webhook failures raise `Nombaone::WebhookVerificationError`. Branch on `e.code` (stable) or the class; the error codes are available as constants (`Nombaone::ErrorCode::CUSTOMER_NOT_FOUND`), and unknown future codes still parse.
+
+## Idempotency & retries
+
+The SDK auto-generates an `Idempotency-Key` for every POST and **reuses it across its automatic retries** (network failures, timeouts, 408/429/5xx — 2 retries by default, honoring `Retry-After`), so a blip can never double-charge. Pass your own key when the operation must stay idempotent across _process_ restarts:
+
+```ruby
+nombaone.settlements.create_payout(
+  amount_in_kobo: 5_000_000, bank_code: "058", account_number: "0123456789",
+  request_options: { idempotency_key: "payout-#{my_payout.id}" }, # ⚠ doubles as the payout's durable merchantTxRef
+)
+```
+
+Every method also accepts `request_options:` with `:idempotency_key`, `:headers`, `:timeout`, `:max_retries`, and `:cancel_when` (a callable checked before each attempt — a caller cancel is never retried).
+
+## Webhooks
+
+Verify before you parse, and dedupe on the event id — delivery is at-least-once, never exactly-once. Verification needs only the signing secret, never an API key, so `Nombaone.webhooks` works in a receiver that never builds a client.
+
+**Feed it the raw request body** — parsing and re-serializing JSON changes bytes and breaks the signature.
+
+```ruby
+# Rails
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    event = Nombaone.webhooks.construct_event(
+      request.raw_post,                                # the RAW body — never re-serialize
+      request.headers["X-Nombaone-Signature"],
+      ENV.fetch("NOMBAONE_WEBHOOK_SECRET"),            # shown once when you created the endpoint
+    )
+
+    return head(:ok) if already_processed?(event.event.id) # at-least-once ⇒ dedupe on event.event.id
+
+    case event.type
+    when Nombaone::WebhookEventType::INVOICE_PAID           then unlock(event.data.reference)
+    when Nombaone::WebhookEventType::INVOICE_ACTION_REQUIRED then email(event.data.checkout_link)
+    when Nombaone::WebhookEventType::INVOICE_PAYMENT_FAILED  then note(event.data.reason)
+    end
+
+    head :ok # respond 2xx fast; do heavy work async
+  rescue Nombaone::WebhookVerificationError
+    head :bad_request
+  end
+end
+```
+
+In **Sinatra/Rack**, the raw body is `request.body.read` and the header is `request.env["HTTP_X_NOMBAONE_SIGNATURE"]`. `construct_event` checks the `X-Nombaone-Signature` (`t=<unix>,v1=<hex>`, HMAC-SHA256 over `"#{t}.#{body}"`) in constant time, rejects stale timestamps (300s tolerance, configurable), and returns a typed event. `Nombaone.webhooks.generate_test_header(payload:, secret:)` lets you unit-test your handler. Manage endpoints via `nombaone.webhook_endpoints` (create/rotate return the secret **exactly once**).
+
+## The full surface
+
+`customers` (+credit, discount) · `plans` (+nested `prices`) · `prices` · `subscriptions` (pause/resume/cancel/resubscribe/change, `schedule`, `dunning`, upcoming invoice, events) · `invoices` · `coupons` · `payment_methods` (hosted-checkout cards, virtual accounts) · `mandates` (NIBSS direct debit) · `settlements` (escrow, refunds, payouts) · `webhook_endpoints` (+deliveries, replay) · `events` (+catalog) · `organization` (+billing policy) · `metrics` · `sandbox` — every operation in the [API reference](https://docs.nombaone.xyz), 1:1.
+
+Worth knowing:
+
+- **Mandates are asynchronous.** They start `consent_pending` and activate when the customer's bank confirms — listen for `payment_method.updated`, don't poll, don't charge early.
+- **Bank transfer is a push rail.** `payment_methods.create_virtual_account` issues a NUBAN; collection completes when the transfer arrives and reconciles.
+- **`past_due` is not canceled.** Read `nombaone.subscriptions.dunning.retrieve(id)` and honor `grace_access_until` before cutting anyone off. Involuntary churn is `status: "canceled"` with `cancellation_reason: "involuntary"` (and a `subscription.churned` event).
+- **Prices are immutable; plans archive, never delete.**
+
+## Configuration
+
+```ruby
+Nombaone.new(
+  api_key,                 # defaults to ENV["NOMBAONE_API_KEY"]
+  base_url: nil,           # override the derived host
+  timeout: 30,             # per-attempt seconds
+  max_retries: 2,          # automatic retry budget
+  default_headers: {},     # sent on every request
+  http: nil,               # inject a connection (tests, proxies)
+)
+```
+
+Read-only `nombaone.mode` (`"sandbox"`/`"live"`, derived from the key) and `nombaone.base_url` are exposed.
+
+## Examples & development
+
+Runnable scripts live in [`examples/`](examples) — quickstart, pagination, the subscription lifecycle, a webhook receiver, and a dunning rehearsal with the test clock:
+
+```bash
+NOMBAONE_API_KEY=nbo_sandbox_… ruby -Ilib examples/01_quickstart.rb
+```
+
+To develop the SDK itself: `bundle install && rake` (RuboCop + RBS validate + specs). The live suite is opt-in:
+
+```bash
+NOMBAONE_INTEGRATION=1 NOMBAONE_API_KEY=nbo_sandbox_… \
+  NOMBAONE_BASE_URL=https://sandbox.api.nombaone.xyz \
+  bundle exec rspec spec/integration
+```
+
+To prove the whole surface against the sandbox — every method called, with a plain per-method result and a `DEFECTS 0` verdict:
+
+```bash
+NOMBAONE_API_KEY=nbo_sandbox_… ruby -Ilib scripts/verify.rb
+```
+
+Releases are automated and merge-triggered — see [`PUBLISHING.md`](PUBLISHING.md).
+
+## Requirements & versioning
+
+Ruby ≥ 3.1. Semantic versioning; the API itself is versioned at `/v1` and additive changes never break you. MIT licensed.

data/lib/nombaone/client.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Nombaone
+  # The NombaOne API client. Construct one with your secret key; it derives the
+  # host from the key's prefix and exposes every resource as a namespace.
+  #
+  # @example
+  #   nombaone = Nombaone.new(ENV["NOMBAONE_API_KEY"])
+  #
+  #   plan = nombaone.plans.create(name: "Pro")
+  #   price = nombaone.plans.prices.create(plan.id, unit_amount_in_kobo: 250_000, interval: "month")
+  #   customer = nombaone.customers.create(email: "ada@example.com", name: "Ada Lovelace")
+  #   method = nombaone.sandbox.create_payment_method(customer_id: customer.id)
+  #   subscription = nombaone.subscriptions.create(
+  #     customer_id: customer.id, price_id: price.id, payment_method_id: method.id
+  #   )
+  #   subscription.status # => "active"
+  class Client
+    # Default host per environment. Overridable with the `base_url:` option.
+    BASE_URLS = {
+      "sandbox" => "https://sandbox.api.nombaone.xyz",
+      "live" => "https://api.nombaone.xyz",
+    }.freeze
+
+    # Per-attempt request timeout, in seconds.
+    DEFAULT_TIMEOUT = 30
+    # Automatic retries (3 attempts total). Retried POSTs reuse one idempotency key.
+    DEFAULT_MAX_RETRIES = 2
+
+    # @return [String] the environment this client talks to ("sandbox"/"live"),
+    #   derived from the key prefix.
+    attr_reader :mode
+    # @return [String] the API origin in use (no `/v1`).
+    attr_reader :base_url
+
+    # @param api_key [String, nil] your secret key (`nbo_sandbox_…` / `nbo_live_…`).
+    #   Defaults to `ENV["NOMBAONE_API_KEY"]`. Server-side only — never ship it
+    #   to a browser or mobile app.
+    # @param base_url [String, nil] override the API origin (no `/v1`). Defaults
+    #   to the host matching the key's environment; required if the key prefix
+    #   is unrecognized.
+    # @param timeout [Numeric] per-attempt timeout in seconds (default 30).
+    # @param max_retries [Integer] automatic retry budget (default 2).
+    # @param http [#execute, nil] an injectable connection for tests/proxies;
+    #   defaults to a `Net::HTTP` transport.
+    # @param default_headers [Hash{String => String}, nil] extra headers on
+    #   every request.
+    # @raise [Nombaone::Error] if the key is missing or its prefix is
+    #   unrecognized and no `base_url` was given.
+    def initialize(api_key = nil, base_url: nil, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, http: nil, default_headers: nil, sleeper: nil)
+      resolved_key = api_key || ENV.fetch("NOMBAONE_API_KEY", nil)
+      if resolved_key.nil? || resolved_key.empty?
+        raise Error,
+              "Missing API key — set the NOMBAONE_API_KEY environment variable, or pass one: " \
+              'Nombaone.new("nbo_sandbox_…"). Create keys in the dashboard under API keys.'
+      end
+
+      derived = derive_mode(resolved_key)
+      if derived.nil? && base_url.nil?
+        raise Error,
+              'Unrecognized API key format — expected a key starting with "nbo_sandbox_" or ' \
+              '"nbo_live_". Copy the key exactly as shown in the dashboard, or pass an explicit ' \
+              "base_url: if you are targeting a custom host."
+      end
+
+      @mode = derived || "sandbox"
+      @base_url = (base_url || BASE_URLS.fetch(@mode)).sub(%r{/+\z}, "")
+      @http = Internal::HTTPClient.new(
+        api_key: resolved_key,
+        base_url: @base_url,
+        timeout: timeout,
+        max_retries: max_retries,
+        connection: http || Internal::NetHTTPConnection.new,
+        default_headers: default_headers,
+        sleeper: sleeper,
+      )
+    end
+
+    # @return [Resources::Customers] the people and businesses you bill.
+    def customers = @customers ||= Resources::Customers.new(self)
+    # @return [Resources::Plans] your catalog (prices nest under `plans.prices`).
+    def plans = @plans ||= Resources::Plans.new(self)
+    # @return [Resources::Prices] immutable amounts and cadences.
+    def prices = @prices ||= Resources::Prices.new(self)
+    # @return [Resources::Subscriptions] the core billing object.
+    def subscriptions = @subscriptions ||= Resources::Subscriptions.new(self)
+    # @return [Resources::Invoices] what billing cycles produced (read + void).
+    def invoices = @invoices ||= Resources::Invoices.new(self)
+    # @return [Resources::Coupons] reusable discount rules.
+    def coupons = @coupons ||= Resources::Coupons.new(self)
+    # @return [Resources::PaymentMethods] cards, mandates, virtual accounts.
+    def payment_methods = @payment_methods ||= Resources::PaymentMethods.new(self)
+    # @return [Resources::Mandates] direct-debit mandates (async NIBSS consent).
+    def mandates = @mandates ||= Resources::Mandates.new(self)
+    # @return [Resources::Settlements] settlements, refunds, payouts, escrow.
+    def settlements = @settlements ||= Resources::Settlements.new(self)
+    # @return [Resources::WebhookEndpoints] webhook endpoint management (REST).
+    def webhook_endpoints = @webhook_endpoints ||= Resources::WebhookEndpoints.new(self)
+    # @return [Resources::Events] the domain-event log — your reconciliation backstop.
+    def events = @events ||= Resources::Events.new(self)
+    # @return [Resources::Organization] org settings + billing/dunning policy.
+    def organization = @organization ||= Resources::Organization.new(self)
+    # @return [Resources::Metrics] billing KPIs computed from the ledger.
+    def metrics = @metrics ||= Resources::Metrics.new(self)
+    # @return [Resources::Sandbox] sandbox-only simulation instruments.
+    def sandbox = @sandbox ||= Resources::Sandbox.new(self)
+
+    # A {Webhooks} helper bound to this client. Verification needs only the
+    # signing secret, so {Nombaone.webhooks} works without a client too.
+    #
+    # @return [Nombaone::Webhooks]
+    def webhooks = @webhooks ||= Webhooks.new
+
+    # Execute a single-object request and return the wrapped {NombaObject}.
+    # @api private
+    def request(method:, path:, query: nil, body: nil, options: nil)
+      result = perform(method: method, path: path, query: query, body: body, options: options)
+      wrap_data(result)
+    end
+
+    # Execute a list request and return a {Page} that auto-paginates.
+    # @api private
+    def request_page(method:, path:, query: nil, options: nil)
+      raw_query = query || {}
+      fetcher = lambda do |query_for_page|
+        perform(method: method, path: path, query: query_for_page, options: options)
+      end
+      Page.new(fetcher: fetcher, query: raw_query, result: fetcher.call(raw_query))
+    end
+
+    private
+
+    def perform(method:, path:, query: nil, body: nil, options: nil)
+      @http.request(
+        method: method,
+        path: path,
+        query: query.nil? ? nil : Internal::Util.serialize_query(query),
+        body: body.nil? ? nil : Internal::Util.serialize_body(body),
+        options: options,
+      )
+    end
+
+    def wrap_data(result)
+      data = result.data
+      return data unless data.is_a?(Hash)
+
+      NombaObject.new(data, request_id: result.request_id, response: result.response)
+    end
+
+    def derive_mode(api_key)
+      return "sandbox" if api_key.start_with?("nbo_sandbox_")
+      return "live" if api_key.start_with?("nbo_live_")
+
+      nil
+    end
+  end
+end