nombaone 0.1.0

data/lib/nombaone/object.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Nombaone
+  # A response object from the API. Every field is readable two ways:
+  #
+  #   customer.amount_in_kobo   # snake_case reader, derived from "amountInKobo"
+  #   customer[:amount_in_kobo] # or bracket access (String/Symbol, snake or wire)
+  #
+  # Nested objects and arrays of objects are wrapped recursively, so
+  # `subscription.items.first.price_id` just works. `metadata` (and any
+  # free-form JSON) keeps its keys verbatim. Reach the raw wire Hash any time
+  # with {#to_h}.
+  #
+  # The object also carries the {#request_id} for the call that produced it and
+  # the raw {#last_response} (status + headers), for support and rate-limit
+  # introspection.
+  #
+  # @example
+  #   sub = nombaone.subscriptions.retrieve("nbo000000000001sub")
+  #   sub.status                 # => "active"
+  #   sub.current_period_end     # => "2026-08-05T00:00:00.000Z"
+  #   sub.items.first.price_id   # => "nbo000000000001prc"
+  #   sub[:latestInvoiceId]      # => "nbo000000000001inv"
+  #   sub.request_id             # => "req_…"
+  class NombaObject
+    # @return [String, nil] the `meta.requestId` of the call that produced this.
+    attr_reader :request_id
+    # @return [Nombaone::Internal::Response, nil] the raw HTTP response.
+    attr_reader :last_response
+
+    # @param values [Hash] the parsed wire object (camelCase string keys).
+    # @param request_id [String, nil]
+    # @param response [Nombaone::Internal::Response, nil]
+    # @api private
+    def initialize(values, request_id: nil, response: nil)
+      @values = values.is_a?(Hash) ? values : {}
+      @converted = {}
+      @request_id = request_id
+      @last_response = response
+    end
+
+    # Read a field by snake_case or wire name (String or Symbol). Returns nil
+    # when the field is absent — the lenient counterpart to a reader method
+    # (which raises `NoMethodError` on an unknown field).
+    #
+    # @param key [String, Symbol]
+    # @return [Object, nil]
+    def [](key)
+      wire = resolve_key(key)
+      wire.nil? ? nil : converted(wire)
+    end
+
+    # Walk nested objects safely: `invoice.dig(:line_items, 0, :amount_in_kobo)`.
+    #
+    # @param keys [Array<String, Symbol, Integer>]
+    # @return [Object, nil]
+    def dig(*keys)
+      keys.reduce(self) do |node, key|
+        break nil if node.nil?
+        break nil unless node.is_a?(NombaObject) || node.is_a?(Array) || node.is_a?(Hash)
+
+        node[key]
+      end
+    end
+
+    # @param key [String, Symbol]
+    # @return [Boolean] whether the field is present.
+    def key?(key)
+      !resolve_key(key).nil?
+    end
+    alias has_key? key?
+    alias member? key?
+
+    # @return [Array<String>] the wire field names present on this object.
+    def keys
+      @values.keys
+    end
+
+    # The raw wire Hash, exactly as received (camelCase string keys, nested
+    # Hashes/Arrays). Use this to serialize the object back or inspect the
+    # untouched payload.
+    #
+    # @return [Hash]
+    def to_h
+      @values
+    end
+    alias to_hash to_h
+
+    # Two objects are equal when their underlying wire Hashes are equal.
+    # `request_id`/response metadata do not participate.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(NombaObject) && other.to_h == @values
+    end
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      @values.hash
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{@values.inspect}>"
+    end
+
+    # @api private
+    def respond_to_missing?(name, include_private = false)
+      name = name.to_s
+      return false if name.end_with?("=", "?", "!")
+
+      !resolve_key(name).nil? || super
+    end
+
+    # @api private
+    def method_missing(name, *args)
+      wire = args.empty? ? resolve_key(name) : nil
+      return converted(wire) unless wire.nil?
+
+      super
+    end
+
+    private
+
+    # Resolve a caller-supplied key to the underlying wire key, matching either
+    # the exact wire name (a camelCase field, or a verbatim `metadata` key) or
+    # its snake_case form.
+    def resolve_key(key)
+      name = key.to_s
+      return name if @values.key?(name)
+
+      camel = Internal::Util.camelize(name)
+      @values.key?(camel) ? camel : nil
+    end
+
+    def converted(wire_key)
+      return @converted[wire_key] if @converted.key?(wire_key)
+
+      @converted[wire_key] = wrap(@values[wire_key])
+    end
+
+    def wrap(value)
+      case value
+      when Hash then NombaObject.new(value)
+      when Array then value.map { |item| wrap(item) }
+      else value
+      end
+    end
+  end
+end

data/lib/nombaone/pagination.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Nombaone
+  # One page of a list result, plus everything needed to keep going. A `Page`
+  # is {Enumerable}: iterating it (`each`, `map`, `select`, `first(n)`, …)
+  # walks **every item across every following page**, fetching each next page
+  # lazily as you go — so `list.first(3)` stops after one page.
+  #
+  # For a single page, read {#data}; for page-by-page control, use {#next_page}
+  # / {#next_page?} or {#each_page}.
+  #
+  # @example Every item, cursors handled for you
+  #   nombaone.customers.list.each { |customer| puts customer.email }
+  #
+  # @example Just this page
+  #   page = nombaone.invoices.list(status: "open", limit: 50)
+  #   page.data              # => [<Invoice>, …]
+  #   page.next_cursor       # => "…" or nil
+  #
+  # @example Manual paging
+  #   page = page.next_page if page.next_page?
+  class Page
+    include Enumerable
+
+    # @return [Array<NombaObject>] the items on this page.
+    attr_reader :data
+    # @return [String, nil] the request id of the fetch that produced this page.
+    attr_reader :request_id
+
+    # @api private
+    def initialize(fetcher:, query:, result:)
+      @fetcher = fetcher
+      @query = query || {}
+      @data = Array(result.data).map { |item| item.is_a?(Hash) ? NombaObject.new(item) : item }
+      @page = result.pagination || { limit: @data.length, has_more: false, next_cursor: nil }
+      @request_id = result.request_id
+      @response = result.response
+    end
+
+    # The applied page size (1–100; the API default is 20).
+    # @return [Integer]
+    def limit = @page[:limit]
+
+    # Whether more items exist beyond this page.
+    # @return [Boolean]
+    def has_more? = @page[:has_more]
+
+    # The opaque cursor for the next page, or nil when there is none.
+    # @return [String, nil]
+    def next_cursor = @page[:next_cursor]
+
+    # @return [Boolean] whether {#next_page} will return another page.
+    def next_page?
+      has_more? && !next_cursor.nil?
+    end
+    alias has_next_page? next_page?
+
+    # The cursor block as an object: `pagination.limit`, `pagination.has_more`,
+    # `pagination.next_cursor`.
+    # @return [NombaObject]
+    def pagination
+      @pagination ||= NombaObject.new(
+        { "limit" => limit, "hasMore" => has_more?, "nextCursor" => next_cursor },
+      )
+    end
+
+    # Fetch the next page (same filters, next cursor).
+    # @return [Page]
+    # @raise [Nombaone::Error] if there is no next page — check {#next_page?}.
+    def next_page
+      unless next_page?
+        raise Error, "No next page available — check next_page? before calling next_page."
+      end
+
+      paged_query = @query.merge(cursor: next_cursor)
+      Page.new(fetcher: @fetcher, query: paged_query, result: @fetcher.call(paged_query))
+    end
+
+    # Iterate every item across this and all following pages. Without a block,
+    # returns an {Enumerator} (so the whole {Enumerable} toolbox works and stays
+    # lazy — `each` only fetches the next page when the current one is drained).
+    #
+    # @yieldparam item [NombaObject]
+    # @return [Enumerator, self]
+    def each(&block)
+      return to_enum(:each) unless block
+
+      page = self
+      loop do
+        page.data.each(&block)
+        break unless page.next_page?
+
+        page = page.next_page
+      end
+      self
+    end
+    alias auto_paging_each each
+
+    # Iterate page-by-page (this page first), fetching each next page lazily.
+    #
+    # @yieldparam page [Page]
+    # @return [Enumerator, self]
+    def each_page
+      return to_enum(:each_page) unless block_given?
+
+      page = self
+      loop do
+        yield page
+        break unless page.next_page?
+
+        page = page.next_page
+      end
+      self
+    end
+  end
+end

data/lib/nombaone/resources/base_resource.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Nombaone
+  # The API resource namespaces (`nombaone.customers`, `nombaone.subscriptions`,
+  # …). Each is a thin, fully-documented transcription of one slice of the wire
+  # contract.
+  module Resources
+    # Re-exported so resource method signatures can default optional keyword
+    # arguments to `OMIT` (dropped from the body) rather than `nil` (sent as
+    # JSON `null` to clear a nullable field). See {Nombaone::Internal::OMIT}.
+    OMIT = Internal::OMIT
+
+    # Base class every resource namespace extends. Holds the client and the
+    # small request helpers each method builds on.
+    class BaseResource
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      # Issue a single-object request; returns a {NombaObject}.
+      def request(method, path, body: nil, query: nil, options: {})
+        @client.request(method: method, path: path, body: body, query: query, options: options)
+      end
+
+      # Issue a list request; returns a {Page}.
+      def request_page(path, query: nil, options: {})
+        @client.request_page(method: :get, path: path, query: query, options: options)
+      end
+
+      # Percent-encode one id before splicing it into a path — ids come from
+      # user input and are never trusted raw.
+      def encode(value)
+        Internal::Util.encode_path_segment(value)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/coupons.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Coupons — reusable discount rules you apply via
+    # `customers.apply_discount` / `subscriptions.apply_discount`. The coupon is
+    # the rule; applying it creates a discount (one application of it).
+    #
+    # @example
+    #   coupon = nombaone.coupons.create(
+    #     code: "LAUNCH20", percent_off: 20, duration: "repeating", duration_in_cycles: 3
+    #   )
+    class Coupons < BaseResource
+      # Create a coupon. Set **exactly one** of `amount_off_in_kobo` / `percent_off`.
+      #
+      # @param code [String] the tenant-facing redemption code, e.g. `"LAUNCH20"`.
+      # @param duration [String] `"once"`, `"repeating"`, or `"forever"`.
+      # @param amount_off_in_kobo [Integer] fixed discount, **integer kobo** (₦1.00 = 100).
+      # @param percent_off [Integer] percentage discount, 1–100.
+      # @param duration_in_cycles [Integer] required when `duration` is `"repeating"`.
+      # @param redeem_by [String] ISO-8601 date-time after which it can't be applied.
+      # @param max_redemptions [Integer]
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ValidationError] 422 `COUPON_INVALID_DEFINITION` — set
+      #   exactly one of `amount_off_in_kobo` / `percent_off`.
+      def create(code:, duration:, amount_off_in_kobo: OMIT, percent_off: OMIT,
+                 duration_in_cycles: OMIT, redeem_by: OMIT, max_redemptions: OMIT,
+                 metadata: OMIT, request_options: {})
+        request(:post, "/coupons",
+                body: {
+                  code: code,
+                  duration: duration,
+                  amount_off_in_kobo: amount_off_in_kobo,
+                  percent_off: percent_off,
+                  duration_in_cycles: duration_in_cycles,
+                  redeem_by: redeem_by,
+                  max_redemptions: max_redemptions,
+                  metadata: metadata,
+                },
+                options: request_options)
+      end
+
+      # Retrieve a coupon by id.
+      #
+      # @param id [String] `nbo…cpn`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `COUPON_NOT_FOUND`
+      def retrieve(id, request_options: {})
+        request(:get, "/coupons/#{encode(id)}", options: request_options)
+      end
+
+      # Update a coupon's redeem-by, max redemptions, or metadata.
+      #
+      # @param id [String] `nbo…cpn`
+      # @param redeem_by [String]
+      # @param max_redemptions [Integer]
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def update(id, redeem_by: OMIT, max_redemptions: OMIT, metadata: OMIT, request_options: {})
+        request(:patch, "/coupons/#{encode(id)}",
+                body: {
+                  redeem_by: redeem_by,
+                  max_redemptions: max_redemptions,
+                  metadata: metadata,
+                },
+                options: request_options)
+      end
+
+      # List coupons, newest first.
+      #
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list(limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/coupons", query: { limit: limit, cursor: cursor }, options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/customers.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Customers — the people and businesses you bill.
+    #
+    # @example
+    #   customer = nombaone.customers.create(email: "ada@example.com", name: "Ada Lovelace")
+    #   customer.id # => "nbo…cus"
+    class Customers < BaseResource
+      # Create a customer.
+      #
+      # @param email [String] unique per organization + environment
+      #   (`CUSTOMER_EMAIL_TAKEN` on reuse).
+      # @param name [String]
+      # @param phone [String, nil]
+      # @param metadata [Hash] free-form annotations (keys are stored verbatim).
+      # @param request_options [Hash] per-call overrides (`:idempotency_key`,
+      #   `:headers`, `:timeout`, `:max_retries`, `:cancel_when`).
+      # @return [NombaObject] the created customer.
+      # @raise [Nombaone::ValidationError] 422 `CLIENT_VALIDATION_FAILED` — see `error.fields`.
+      # @raise [Nombaone::ConflictError] 409 `CUSTOMER_EMAIL_TAKEN` — reuse the existing customer.
+      #
+      # @example
+      #   customer = nombaone.customers.create(
+      #     email: "ada@example.com",
+      #     name: "Ada Lovelace",
+      #     metadata: { crm_id: "crm_812" },
+      #   )
+      def create(email:, name:, phone: OMIT, metadata: OMIT, request_options: {})
+        request(:post, "/customers",
+                body: { email: email, name: name, phone: phone, metadata: metadata },
+                options: request_options)
+      end
+
+      # Retrieve a customer by id.
+      #
+      # @param id [String] `nbo…cus`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `CUSTOMER_NOT_FOUND` — check the id
+      #   and that your key matches the environment the customer was created in.
+      def retrieve(id, request_options: {})
+        request(:get, "/customers/#{encode(id)}", options: request_options)
+      end
+
+      # Update a customer's mutable fields. At least one field is required.
+      #
+      # @param id [String] `nbo…cus`
+      # @param name [String]
+      # @param phone [String, nil] pass `nil` to clear the phone number.
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      #
+      # @example
+      #   nombaone.customers.update(customer.id, phone: "+2348012345678")
+      def update(id, name: OMIT, phone: OMIT, metadata: OMIT, request_options: {})
+        request(:patch, "/customers/#{encode(id)}",
+                body: { name: name, phone: phone, metadata: metadata },
+                options: request_options)
+      end
+
+      # List customers, newest first.
+      #
+      # @param email [String] exact-match filter on email.
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page's `next_cursor`.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      #
+      # @example
+      #   nombaone.customers.list.each { |customer| puts customer.email }
+      def list(email: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/customers",
+                     query: { email: email, limit: limit, cursor: cursor },
+                     options: request_options)
+      end
+
+      # Apply a coupon to a customer. The resulting discount shapes every future
+      # invoice for the customer until it ends or is removed.
+      #
+      # @param id [String] `nbo…cus`
+      # @param coupon [String] a coupon id (`nbo…cpn`) or its code (e.g. `"LAUNCH20"`).
+      # @param request_options [Hash]
+      # @return [NombaObject] the created discount.
+      # @raise [Nombaone::NotFoundError] 404 `COUPON_NOT_FOUND`
+      # @raise [Nombaone::ConflictError] 409 `COUPON_ALREADY_APPLIED`
+      #
+      # @example
+      #   nombaone.customers.apply_discount(customer.id, coupon: "LAUNCH20")
+      def apply_discount(id, coupon:, request_options: {})
+        request(:post, "/customers/#{encode(id)}/discount",
+                body: { coupon: coupon }, options: request_options)
+      end
+
+      # Remove the customer's active discount. Returns the ended discount.
+      #
+      # @param id [String] `nbo…cus`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def remove_discount(id, request_options: {})
+        request(:delete, "/customers/#{encode(id)}/discount", options: request_options)
+      end
+
+      # Grant credit to a customer. Credit is drawn down oldest-grant-first by
+      # future invoices **before** any payment rail is charged.
+      #
+      # This moves money-shaped state, so the API requires an `Idempotency-Key`;
+      # the SDK sends one automatically. Pass `request_options[:idempotency_key]`
+      # to keep the grant idempotent across process restarts.
+      #
+      # @param id [String] `nbo…cus`
+      # @param amount_in_kobo [Integer] amount to grant, **integer kobo**
+      #   (₦1.00 = 100). `250_000` is ₦2,500 — not ₦250,000. Multiply naira by
+      #   100 exactly once, at the edge of your system.
+      # @param source [String] `"manual"` or `"goodwill"` (defaults to `manual`).
+      # @param source_reference [String] your own reference (ticket, promo id, …).
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject] the created credit grant.
+      #
+      # @example
+      #   nombaone.customers.grant_credit(customer.id, amount_in_kobo: 250_000, source: "goodwill")
+      def grant_credit(id, amount_in_kobo:, source: OMIT, source_reference: OMIT,
+                       metadata: OMIT, request_options: {})
+        request(:post, "/customers/#{encode(id)}/credit",
+                body: {
+                  amount_in_kobo: amount_in_kobo,
+                  source: source,
+                  source_reference: source_reference,
+                  metadata: metadata,
+                },
+                options: request_options)
+      end
+
+      # Retrieve the customer's credit balance and the grants behind it.
+      #
+      # @param id [String] `nbo…cus`
+      # @param request_options [Hash]
+      # @return [NombaObject] with `balance_in_kobo` and `grants`.
+      def retrieve_credit_balance(id, request_options: {})
+        request(:get, "/customers/#{encode(id)}/credit", options: request_options)
+      end
+
+      # Void a credit grant — its remaining balance becomes unusable. Consumed
+      # credit is untouched.
+      #
+      # @param id [String] `nbo…cus`
+      # @param grant_id [String] `nbo…crg`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `CREDIT_GRANT_ALREADY_VOIDED`
+      def void_credit(id, grant_id, request_options: {})
+        request(:delete, "/customers/#{encode(id)}/credit/#{encode(grant_id)}",
+                options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/events.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Events — the append-only log behind every webhook. Webhook delivery is
+    # at-least-once; this log is your reconciliation backstop when a delivery
+    # was missed or you need to backfill.
+    class Events < BaseResource
+      # List events, newest first.
+      #
+      # @param type [String] filter to one catalog type, e.g. `"invoice.paid"`.
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      #
+      # @example
+      #   nombaone.events.list(type: "invoice.paid").each { |event| puts event.id }
+      def list(type: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/events",
+                     query: { type: type, limit: limit, cursor: cursor },
+                     options: request_options)
+      end
+
+      # Retrieve one event by id.
+      #
+      # @param id [String] `nbo…evt`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def retrieve(id, request_options: {})
+        request(:get, "/events/#{encode(id)}", options: request_options)
+      end
+
+      # The machine-readable event catalog — every event type the platform can
+      # emit, with a description and its `data` keys. Useful for building
+      # subscription pickers or codegen.
+      #
+      # @param request_options [Hash]
+      # @return [NombaObject] a map of `type => { when:, payload: }`; read entries
+      #   with `catalog["invoice.paid"]`.
+      def catalog(request_options: {})
+        request(:get, "/events/catalog", options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/invoices.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Invoices — read what the billing engine produced; void what should never
+    # be collected. You never create invoices — subscription cycles do; amounts
+    # are locked at finalization. All amounts are integer kobo.
+    class Invoices < BaseResource
+      # Retrieve an invoice by id.
+      #
+      # @param id [String] `nbo…inv`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `INVOICE_NOT_FOUND`
+      def retrieve(id, request_options: {})
+        request(:get, "/invoices/#{encode(id)}", options: request_options)
+      end
+
+      # List invoices, newest first.
+      #
+      # @param customer_id [String] filter to one customer (`nbo…cus`).
+      # @param subscription_id [String] filter to one subscription (`nbo…sub`).
+      # @param status [String] the list filter accepts `"draft"`, `"open"`,
+      #   `"paid"`, `"void"`, `"uncollectible"` (note: no `"partially_paid"`,
+      #   though invoice objects can carry that status).
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      #
+      # @example
+      #   nombaone.invoices.list(status: "open").each { |inv| puts inv.amount_due_in_kobo }
+      def list(customer_id: OMIT, subscription_id: OMIT, status: OMIT, limit: OMIT, cursor: OMIT,
+               request_options: {})
+        request_page("/invoices",
+                     query: {
+                       customer_id: customer_id,
+                       subscription_id: subscription_id,
+                       status: status,
+                       limit: limit,
+                       cursor: cursor,
+                     },
+                     options: request_options)
+      end
+
+      # Void an open, unpaid invoice. Paid invoices can't be voided — refund the
+      # settlement instead.
+      #
+      # @param id [String] `nbo…inv`
+      # @param comment [String]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `INVOICE_NOT_VOIDABLE`
+      # @raise [Nombaone::ConflictError] 409 `INVOICE_ALREADY_PAID`
+      def void(id, comment: OMIT, request_options: {})
+        request(:post, "/invoices/#{encode(id)}/void",
+                body: { comment: comment }, options: request_options)
+      end
+    end
+  end
+end