billrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef5dd94f1b7c90b5ad0ebf63d71c6e3361c8ea015d20e43f4eff34fe5e7592ab
+  data.tar.gz: d2f1213dae7ab2f5e116d247833f6daa9697da5c2647cb9bb1a3845772aca102
+SHA512:
+  metadata.gz: 8218de5263247cade5a381591c554fd35855200b33dd5303995d1002d5b5f0b56aa4bbb0971ea7fbcf77d70c9dec9b9418b9cd94fe0f62e1eae485fb7607cabc
+  data.tar.gz: c74ffc5f2eaf9a5d1505c3f134c40a473edbd9748aff52da54ff5c00f7429897e79e0d08638141c2193f1aaf07d8c95555ca6603373dc930eb512dfe0ca1ee5f

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [Unreleased]
+
+- Initial architecture: configuration, Faraday-based client with BILL v3
+  session authentication (lazy login, automatic re-login on session expiry),
+  typed error hierarchy, pagination, and a small resource layer.
+- Automatic retries with exponential backoff for transient failures (429 for
+  all methods, 5xx/network for idempotent methods only), honoring `Retry-After`.
+  Configurable via `max_retries` / `retry_backoff`.
+- Thread-safe session handling: mutex-guarded login with double-checked
+  re-authentication, so a shared client is safe across threads.
+- Nested API objects are wrapped as resources, enabling dot-access at any depth
+  (e.g. `invoice.billing_address.city`); `to_h` still returns raw attributes.
+- Pluggable Faraday: `config.adapter` and a `config.faraday` middleware hook.
+- `Configuration#inspect` and `Client#inspect` redact credentials and session id.
+- Credential-gated integration specs (`spec/integration`) that exercise the
+  AR resources end-to-end against the BILL sandbox; loaded from a gitignored
+  `.env` (see `.env.example`) and skipped when credentials are absent.
+- Tooling: RuboCop (lint) + rufo (format) wired up as pre-commit hooks.
+- Accounts Receivable resources: `Billrb::Customer` (with charge
+  authorization), `Billrb::CustomerBankAccount`, `Billrb::Invoice` (with
+  email, payment link, and offline payment recording), `Billrb::CreditMemo`,
+  `Billrb::RecurringInvoice`, and `Billrb::ReceivablePayment` (charging).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Carlos Aguilar
+
+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,214 @@
+# billrb
+
+A lightweight Ruby client for the [BILL (bill.com) v3 API](https://developer.bill.com/), focused on the Accounts Receivable modules: customers (including bank accounts and charge authorization), invoices, recurring invoices, credit memos, and received payments.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "billrb"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install billrb
+
+## Configuration
+
+```ruby
+Billrb.configure do |config|
+  config.username        = ENV["BILL_USERNAME"]
+  config.password        = ENV["BILL_PASSWORD"]
+  config.organization_id = ENV["BILL_ORGANIZATION_ID"]
+  config.dev_key         = ENV["BILL_DEV_KEY"]
+  config.environment     = :production # defaults to :sandbox
+end
+```
+
+The client logs in lazily on the first request and transparently re-authenticates when the API session expires (BILL sessions expire after 35 minutes of inactivity).
+
+### All configuration options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `username`, `password`, `organization_id`, `dev_key` | — | BILL credentials (required) |
+| `environment` | `:sandbox` | `:sandbox` or `:production` |
+| `timeout`, `open_timeout` | `30`, `5` | Faraday request/connect timeouts (seconds) |
+| `logger` | `nil` | A `Logger`; request lines are logged with headers/bodies excluded |
+| `max_retries` | `2` | Retry attempts for transient failures (see below) |
+| `retry_backoff` | `0.5` | Base seconds for exponential backoff |
+| `adapter` | Faraday default | Faraday adapter, e.g. `:net_http_persistent` |
+| `faraday` | `nil` | A proc given the Faraday builder to add custom middleware |
+
+### Resilience
+
+Transient failures are retried automatically with exponential backoff, honoring a `Retry-After` header when present. Rate-limit responses (429) are retried for every method since the request was rejected before processing; `5xx` and network errors are retried only for idempotent methods (GET/HEAD/PUT/DELETE), so a `POST` create is never silently repeated. After `max_retries` the mapped error (e.g. `RateLimitError`, `ServerError`) is raised.
+
+### Thread safety
+
+A client may be shared across threads. Sign-in is mutex-guarded, so concurrent requests trigger at most one login, and an expired session is refreshed only once even when many requests race on it.
+
+### Custom Faraday middleware
+
+```ruby
+Billrb.configure do |config|
+  config.adapter = :net_http_persistent
+  config.faraday = ->(builder) { builder.use MyInstrumentationMiddleware }
+end
+```
+
+For multi-tenant applications, build clients explicitly instead of using the global configuration:
+
+```ruby
+client = Billrb::Client.new(
+  username: "...", password: "...", organization_id: "...", dev_key: "..."
+)
+Billrb::Customer.list({ max: 50 }, client: client)
+Billrb::Customer.retrieve("customer_id", client: client)
+```
+
+## Usage
+
+```ruby
+# List with filters and pagination (BILL's native filter syntax)
+page = Billrb::Customer.list(max: 50, filters: "archived:eq:false")
+page.each { |customer| puts customer.name }
+page = page.fetch_next_page if page.next_page?
+
+# Or iterate across all pages
+Billrb::Invoice.list(max: 100).auto_paging_each do |invoice|
+  puts "#{invoice.invoice_number}: #{invoice.due_date}"
+end
+
+# CRUD — params are written snake_case and converted to the API's camelCase
+customer = Billrb::Customer.create(name: "Acme Inc.", email: "billing@acme.test")
+customer = Billrb::Customer.update(customer.id, name: "Acme Incorporated")
+Billrb::Customer.archive(customer.id)
+
+invoice = Billrb::Invoice.retrieve("inv_id")
+invoice.due_date              # reads "dueDate" from the API response
+invoice.billing_address.city  # nested objects are wrapped too
+invoice.line_items.first.amount
+invoice.to_h                  # raw API attributes (nested values stay hashes)
+```
+
+### Invoicing actions
+
+```ruby
+# Email the invoice (PDF attached) to the customer
+Billrb::Invoice.send_email(invoice.id, recipient: { to: ["billing@acme.test"] })
+
+# Or get a payment link to deliver yourself
+link = Billrb::Invoice.payment_link(invoice.id, customer_id: customer.id, email: "billing@acme.test")
+link.payment_link
+
+# Record a payment received outside BILL (cash, check, ...)
+Billrb::Invoice.record_payment(
+  amount: 50.0, payment_date: "2026-06-12", payment_type: "CASH",
+  invoices: [{ invoice_id: invoice.id, amount: 50.0 }]
+)
+
+# Recurring invoices and credit memos follow the same CRUD shape
+Billrb::RecurringInvoice.create(customer_id: customer.id, ...)
+Billrb::CreditMemo.create(customer_id: customer.id, ...)
+```
+
+### Charging customers
+
+Charging requires a one-time authorization and a customer bank account:
+
+```ruby
+Billrb::Customer.authorize_charge(customer.id)
+Billrb::CustomerBankAccount.create(customer.id, routing_number: "...", account_number: "...")
+
+payment = Billrb::ReceivablePayment.charge(
+  customer_id: customer.id,
+  invoices: [{ invoice_id: invoice.id, amount: 100.0 }]
+)
+
+# Received payments are queryable like any other resource
+Billrb::ReceivablePayment.list(max: 50)
+Billrb::ReceivablePayment.retrieve(payment.id)
+```
+
+### Errors
+
+All errors inherit from `Billrb::Error`:
+
+| Error | Raised on |
+| --- | --- |
+| `Billrb::ConfigurationError` | missing/invalid configuration |
+| `Billrb::ConnectionError` | network failures and timeouts |
+| `Billrb::AuthenticationError` | 401 (after one automatic re-login attempt) |
+| `Billrb::BadRequestError` / `ForbiddenError` / `NotFoundError` | 400 / 403 / 404 |
+| `Billrb::RateLimitError` | 429 |
+| `Billrb::ServerError` | 5xx |
+
+API errors expose `error.status` and `error.body` (the parsed response) for access to BILL error codes.
+
+## Architecture & extending
+
+The gem is intentionally small and layered so new BILL modules can be added without touching existing code:
+
+- `Billrb::Client` — transport only: session auth, JSON, error mapping. Knows nothing about resources.
+- `Billrb::Resource` — wraps API JSON, exposing camelCase attributes as snake_case readers.
+- `Billrb::Operations` — CRUD mixins (`List`, `Retrieve`, `Create`, `Update`, `Replace`, `Archive`).
+
+A new resource is one file declaring its path and supported operations:
+
+```ruby
+module Billrb
+  class CreditMemo < Resource
+    self.resource_path = "/credit-memos"
+
+    extend Operations::List
+    extend Operations::Retrieve
+    extend Operations::Create
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Linting & formatting
+
+Formatting is handled by [rufo](https://github.com/ruby-formatter/rufo) and linting by [RuboCop](https://rubocop.org); rufo owns formatting, so RuboCop's layout cops are disabled to keep the two from fighting. They are wired up as [pre-commit](https://pre-commit.com) hooks:
+
+```sh
+pre-commit run --all-files   # run on the whole repo
+pre-commit install           # optional: run automatically on every commit
+```
+
+You can also run them directly: `bundle exec rufo .` and `bundle exec rubocop`.
+
+### Integration specs
+
+`spec/integration` runs end-to-end against the real BILL sandbox. It needs all four credentials; copy the template and fill it in:
+
+```sh
+cp .env.example .env   # .env is gitignored
+bundle exec rspec spec/integration
+```
+
+Without the credentials these specs are skipped automatically, so `rake spec` stays green for everyone else. In CI they run when the matching repository secrets are configured.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/TECMANIC/billrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/TECMANIC/billrb/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Billrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/TECMANIC/billrb/blob/main/CODE_OF_CONDUCT.md).

data/lib/billrb/client.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Billrb
+  # Thin HTTP layer over the BILL v3 API: session auth, retries, JSON, and
+  # error mapping. Knows nothing about individual resources.
+  #
+  # A client may be shared across threads: sign-in is guarded by a mutex, so
+  # concurrent requests trigger at most one login and an expired session is
+  # refreshed only once even when many requests race on it.
+  class Client
+    BASE_PATH = "/connect/v3"
+
+    # HTTP methods with no side effects, so they are safe to retry on a 5xx or
+    # network error. 429 (rate limited) is retried for every method since the
+    # request was rejected before processing.
+    IDEMPOTENT_METHODS = %i[get head options put delete].freeze
+
+    attr_reader :config
+
+    # Accepts an explicit Configuration, inline options
+    # (Client.new(dev_key: "...", ...)), or falls back to Billrb.configuration.
+    def initialize(config = nil, **options)
+      @config = if config
+          config
+        elsif options.any?
+          Configuration.new(**options)
+        else
+          Billrb.configuration
+        end
+      @login_mutex = Mutex.new
+    end
+
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body = nil)
+      request(:post, path, body: body)
+    end
+
+    def put(path, body = nil)
+      request(:put, path, body: body)
+    end
+
+    def patch(path, body = nil)
+      request(:patch, path, body: body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    # Forces a fresh sign-in. Normally unnecessary — requests sign in lazily.
+    def login!
+      @login_mutex.synchronize { do_login! }
+      true
+    end
+
+    def logout!
+      @login_mutex.synchronize do
+        return false unless @session_id
+
+        parse!(perform(:post, "/logout"))
+        @session_id = nil
+      end
+      true
+    end
+
+    def inspect
+      "#<#{self.class.name} environment=#{config.environment.inspect} " \
+      "authenticated=#{!@session_id.nil?}>"
+    end
+
+    private
+
+    def request(method, path, params: nil, body: nil)
+      parse!(send_with_retries(method, path, params: params, body: body))
+    end
+
+    # Refreshes an expired session once, then retries transient failures (429
+    # always; 5xx and network errors only for idempotent methods) with
+    # exponential backoff, honoring a Retry-After header when present.
+    def send_with_retries(method, path, **opts)
+      attempt = 0
+      loop do
+        begin
+          response = perform_with_reauth(method, path, **opts)
+        rescue ConnectionError
+          raise unless retry?(method, attempt, nil)
+
+          pause(backoff(attempt += 1))
+          next
+        end
+
+        return response unless retry?(method, attempt, response.status)
+
+        pause(backoff(attempt += 1, response))
+      end
+    end
+
+    def perform_with_reauth(method, path, **opts)
+      ensure_session!
+      stale = @session_id
+      response = perform(method, path, **opts)
+      if response.status == 401
+        reauthenticate!(stale)
+        response = perform(method, path, **opts)
+      end
+      response
+    end
+
+    def ensure_session!
+      return if @session_id
+
+      @login_mutex.synchronize { do_login! unless @session_id }
+    end
+
+    # Only sign in again if another thread has not already refreshed the
+    # session out from under us.
+    def reauthenticate!(stale)
+      @login_mutex.synchronize { do_login! if @session_id == stale }
+    end
+
+    def do_login!
+      config.validate!
+      response = perform(:post, "/login", body: {
+                                            "devKey" => config.dev_key,
+                                            "username" => config.username,
+                                            "password" => config.password,
+                                            "organizationId" => config.organization_id,
+                                          })
+      data = parse!(response)
+      @session_id = data.is_a?(Hash) ? data["sessionId"] : nil
+      return if @session_id
+
+      raise AuthenticationError.new("login response did not include a sessionId",
+                                    status: response.status, body: data)
+    end
+
+    def perform(method, path, params: nil, body: nil)
+      connection.run_request(method, BASE_PATH + path, nil, nil) do |req|
+        req.headers["sessionId"] = @session_id if @session_id
+        req.params.update(params) if params && !params.empty?
+        req.body = body if body
+      end
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise ConnectionError, e.message
+    end
+
+    def parse!(response)
+      return response.body if response.status.between?(200, 299)
+
+      raise ApiError.from_response(status: response.status, body: response.body)
+    end
+
+    # status is nil for a network error.
+    def retry?(method, attempt, status)
+      return false if attempt >= config.max_retries
+      return true if status == 429
+
+      (status.nil? || (500..599).cover?(status)) && IDEMPOTENT_METHODS.include?(method)
+    end
+
+    def backoff(attempt, response = nil)
+      retry_after = response&.headers&.[]("Retry-After").to_i
+      return retry_after if retry_after.positive?
+
+      config.retry_backoff * (2 ** (attempt - 1))
+    end
+
+    def pause(seconds)
+      sleep(seconds)
+    end
+
+    def connection # rubocop:disable Metrics/AbcSize -- cohesive Faraday builder
+      @connection ||= Faraday.new(url: config.base_url) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.options.timeout = config.timeout
+        f.options.open_timeout = config.open_timeout
+        f.headers["devKey"] = config.dev_key if config.dev_key
+        f.headers["Accept"] = "application/json"
+        # headers/bodies excluded: they carry credentials and customer data
+        f.response :logger, config.logger, headers: false, bodies: false if config.logger
+        config.faraday&.call(f)
+        f.adapter(*Array(config.adapter || Faraday.default_adapter))
+      end
+    end
+  end
+end

data/lib/billrb/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Billrb
+  class Configuration
+    ENVIRONMENTS = {
+      production: "https://gateway.prod.bill.com",
+      sandbox: "https://gateway.stage.bill.com",
+    }.freeze
+
+    SECRET_ATTRS = %i[password dev_key].freeze
+
+    attr_accessor :username, :password, :organization_id, :dev_key,
+                  :timeout, :open_timeout, :logger,
+                  :max_retries, :retry_backoff, :adapter, :faraday
+    attr_reader :environment
+
+    def initialize(username: nil, password: nil, organization_id: nil, dev_key: nil,
+                   environment: :sandbox, timeout: 30, open_timeout: 5, logger: nil,
+                   max_retries: 2, retry_backoff: 0.5, adapter: nil, faraday: nil)
+      self.environment = environment
+      @username = username
+      @password = password
+      @organization_id = organization_id
+      @dev_key = dev_key
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @logger = logger
+      @max_retries = max_retries
+      @retry_backoff = retry_backoff
+      @adapter = adapter
+      @faraday = faraday
+    end
+
+    def environment=(value)
+      value = value.to_sym
+      unless ENVIRONMENTS.key?(value)
+        raise ConfigurationError,
+              "unknown environment #{value.inspect} (valid: #{ENVIRONMENTS.keys.join(", ")})"
+      end
+      @environment = value
+    end
+
+    def base_url
+      ENVIRONMENTS.fetch(environment)
+    end
+
+    def validate!
+      missing = %i[username password organization_id dev_key].select do |key|
+        public_send(key).to_s.empty?
+      end
+      return if missing.empty?
+
+      raise ConfigurationError, "missing required configuration: #{missing.join(", ")}"
+    end
+
+    # Redact credentials so they never leak into logs or error dumps.
+    def inspect
+      "#<#{self.class.name} environment=#{environment.inspect} " \
+      "username=#{username.inspect} organization_id=#{organization_id.inspect} " \
+      "password=#{redacted(password)} dev_key=#{redacted(dev_key)}>"
+    end
+
+    private
+
+    def redacted(value)
+      value.nil? ? "nil" : "[REDACTED]"
+    end
+  end
+end

data/lib/billrb/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Billrb
+  class Error < StandardError; end
+
+  # Raised when required configuration (credentials, environment) is missing
+  # or invalid before a request is attempted.
+  class ConfigurationError < Error; end
+
+  # Raised on network-level failures (DNS, refused connection, timeout).
+  class ConnectionError < Error; end
+
+  # Raised when the API responds with a non-2xx status. Subclasses map common
+  # statuses; `status` and `body` carry the raw response for callers that need
+  # the BILL error code or details.
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+
+    def self.from_response(status:, body:)
+      klass = case status
+        when 400 then BadRequestError
+        when 401 then AuthenticationError
+        when 403 then ForbiddenError
+        when 404 then NotFoundError
+        when 429 then RateLimitError
+        when 500..599 then ServerError
+        else ApiError
+        end
+      klass.new(message_from(body) || "HTTP #{status}", status: status, body: body)
+    end
+
+    def self.message_from(body)
+      return unless body.is_a?(Hash)
+
+      body["message"] ||
+        body.dig("error", "message") ||
+        (body["errors"].is_a?(Array) &&
+         body["errors"].filter_map { |e| e["message"] if e.is_a?(Hash) }.first) ||
+        nil
+    end
+    private_class_method :message_from
+  end
+
+  class BadRequestError < ApiError; end
+  class AuthenticationError < ApiError; end
+  class ForbiddenError < ApiError; end
+  class NotFoundError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ServerError < ApiError; end
+end

data/lib/billrb/list_page.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Billrb
+  # One page of a list endpoint response. BILL paginates with `max`/`page`
+  # query params and returns `results` plus `nextPage`/`prevPage` tokens.
+  class ListPage
+    include Enumerable
+
+    attr_reader :results, :next_page, :prev_page
+
+    # list_args carries leading positional arguments for nested resources
+    # (e.g. the customer id for CustomerBankAccount.list) so pagination can
+    # replay the same list call.
+    def initialize(resource_class, data, params: {}, client: Billrb.client, list_args: [])
+      @resource_class = resource_class
+      @client = client
+      @params = params
+      @list_args = list_args
+      data = {} unless data.is_a?(Hash)
+      @results = Array(data["results"]).map { |attrs| resource_class.new(attrs) }
+      @next_page = data["nextPage"]
+      @prev_page = data["prevPage"]
+    end
+
+    def each(&)
+      results.each(&)
+    end
+
+    def next_page?
+      !next_page.nil?
+    end
+
+    def fetch_next_page
+      raise Error, "there is no next page" unless next_page?
+
+      @resource_class.list(*@list_args, @params.merge(page: next_page), { client: @client })
+    end
+
+    # Iterates over every result, fetching subsequent pages as needed.
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block
+
+      page = self
+      loop do
+        page.results.each(&block)
+        break unless page.next_page?
+
+        page = page.fetch_next_page
+      end
+    end
+  end
+end

data/lib/billrb/operations.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Billrb
+  # CRUD mixins for resource classes. Each resource `extend`s only the
+  # operations its endpoint supports, so adding a new BILL module is a new
+  # file declaring its path and operations — no existing code changes.
+  #
+  # Every method takes a trailing options hash; pass `client:` there to use a
+  # client other than the default (e.g. Customer.retrieve(id, client: other)).
+  module Operations
+    def self.client_from(options)
+      options[:client] || Billrb.client
+    end
+
+    module List
+      def list(params = {}, options = {})
+        client = Operations.client_from(options)
+        data = client.get(resource_path, Util.camelize_keys(params))
+        ListPage.new(self, data, params: params, client: client)
+      end
+    end
+
+    module Retrieve
+      def retrieve(id, options = {})
+        new(Operations.client_from(options).get("#{resource_path}/#{id}"))
+      end
+    end
+
+    module Create
+      def create(params, options = {})
+        new(Operations.client_from(options).post(resource_path, Util.camelize_keys(params)))
+      end
+    end
+
+    module Update
+      def update(id, params, options = {})
+        new(Operations.client_from(options).patch("#{resource_path}/#{id}",
+                                                  Util.camelize_keys(params)))
+      end
+    end
+
+    # PUT — full replacement of the resource, including its line items
+    # (omitted line item ids are removed), unlike PATCH-based Update.
+    module Replace
+      def replace(id, params, options = {})
+        new(Operations.client_from(options).put("#{resource_path}/#{id}",
+                                                Util.camelize_keys(params)))
+      end
+    end
+
+    module Archive
+      def archive(id, options = {})
+        new(Operations.client_from(options).post("#{resource_path}/#{id}/archive"))
+      end
+
+      def restore(id, options = {})
+        new(Operations.client_from(options).post("#{resource_path}/#{id}/restore"))
+      end
+    end
+  end
+end

data/lib/billrb/resource.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Billrb
+  # Base class for API resources. Wraps the raw JSON attributes (camelCase
+  # string keys, as returned by the API) and exposes them as snake_case
+  # readers: resource.payment_term_id reads attributes["paymentTermId"].
+  class Resource
+    class << self
+      attr_accessor :resource_path
+    end
+
+    attr_reader :attributes
+
+    def initialize(attributes = {})
+      @attributes = attributes.is_a?(Hash) ? attributes : {}
+    end
+
+    def [](key)
+      wrap(attributes[Util.camelize(key)])
+    end
+
+    def id
+      attributes["id"]
+    end
+
+    # Raw attributes exactly as returned by the API (nested values stay hashes).
+    def to_h
+      attributes
+    end
+
+    def method_missing(name, *args)
+      key = Util.camelize(name)
+      return wrap(attributes[key]) if args.empty? && attributes.key?(key)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      attributes.key?(Util.camelize(name)) || super
+    end
+
+    def inspect
+      "#<#{self.class.name} #{attributes.inspect}>"
+    end
+
+    private
+
+    # Expose nested objects as Resources so dot-access works at any depth
+    # (e.g. invoice.billing_address.city), while to_h stays raw.
+    def wrap(value)
+      case value
+      when Hash then Resource.new(value)
+      when Array then value.map { |item| wrap(item) }
+      else value
+      end
+    end
+  end
+end

data/lib/billrb/resources/credit_memo.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Billrb
+  class CreditMemo < Resource
+    self.resource_path = "/credit-memos"
+
+    extend Operations::List
+    extend Operations::Retrieve
+    extend Operations::Create
+    extend Operations::Update
+    extend Operations::Replace
+    extend Operations::Archive
+  end
+end

data/lib/billrb/resources/customer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Billrb
+  class Customer < Resource
+    self.resource_path = "/customers"
+
+    extend Operations::List
+    extend Operations::Retrieve
+    extend Operations::Create
+    extend Operations::Update
+    extend Operations::Archive
+
+    # POST /v3/customers/{id}/charge-authorization — required before charging
+    # a customer with ReceivablePayment.charge.
+    def self.authorize_charge(id, params = {}, options = {})
+      new(Operations.client_from(options).post("#{resource_path}/#{id}/charge-authorization",
+                                               Util.camelize_keys(params)))
+    end
+  end
+end

data/lib/billrb/resources/customer_bank_account.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Billrb
+  # Bank account on file for a customer, required for charging them.
+  # Nested under a customer, so every operation takes the customer id first.
+  class CustomerBankAccount < Resource
+    def self.resource_path(customer_id)
+      "/customers/#{customer_id}/bank-accounts"
+    end
+
+    def self.list(customer_id, params = {}, options = {})
+      client = Operations.client_from(options)
+      data = client.get(resource_path(customer_id), Util.camelize_keys(params))
+      ListPage.new(self, data, params: params, client: client, list_args: [customer_id])
+    end
+
+    def self.retrieve(customer_id, id, options = {})
+      new(Operations.client_from(options).get("#{resource_path(customer_id)}/#{id}"))
+    end
+
+    def self.create(customer_id, params, options = {})
+      new(Operations.client_from(options).post(resource_path(customer_id),
+                                               Util.camelize_keys(params)))
+    end
+
+    # Only `nickname` and `ownerType` can change; for anything else, create a
+    # new bank account.
+    def self.update(customer_id, id, params, options = {})
+      new(Operations.client_from(options).patch("#{resource_path(customer_id)}/#{id}",
+                                                Util.camelize_keys(params)))
+    end
+
+    # Archived customer bank accounts cannot be restored.
+    def self.archive(customer_id, id, options = {})
+      new(Operations.client_from(options).post("#{resource_path(customer_id)}/#{id}/archive"))
+    end
+  end
+end

data/lib/billrb/resources/invoice.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Billrb
+  class Invoice < Resource
+    self.resource_path = "/invoices"
+
+    extend Operations::List
+    extend Operations::Retrieve
+    extend Operations::Create
+    extend Operations::Update
+    extend Operations::Replace
+    extend Operations::Archive
+
+    # POST /v3/invoices/{id}/email — emails the invoice (with PDF attached)
+    # to the customer, e.g. send_email(id, recipient: { to: ["a@b.test"] }).
+    def self.send_email(id, params = {}, options = {})
+      Resource.new(Operations.client_from(options).post("#{resource_path}/#{id}/email",
+                                                        Util.camelize_keys(params)))
+    end
+
+    # POST /v3/invoices/{id}/payment-link — returns a payment link the
+    # customer can use to pay the invoice.
+    def self.payment_link(id, params = {}, options = {})
+      Resource.new(Operations.client_from(options).post("#{resource_path}/#{id}/payment-link",
+                                                        Util.camelize_keys(params)))
+    end
+
+    # POST /v3/invoices/record-payment — records a payment received outside
+    # BILL (cash, check, ...) and applies it to one or more invoices.
+    def self.record_payment(params, options = {})
+      ReceivablePayment.new(Operations.client_from(options).post(
+        "#{resource_path}/record-payment", Util.camelize_keys(params),
+      ))
+    end
+  end
+end

data/lib/billrb/resources/receivable_payment.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Billrb
+  # A payment received from a customer. Creating one charges the customer for
+  # one or more invoices — the customer must have `authorizedToCharge` set
+  # (Customer.authorize_charge) and a bank account (CustomerBankAccount).
+  class ReceivablePayment < Resource
+    self.resource_path = "/receivable-payments"
+
+    extend Operations::List
+    extend Operations::Retrieve
+    extend Operations::Create
+
+    class << self
+      alias charge create
+    end
+  end
+end

data/lib/billrb/resources/recurring_invoice.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Billrb
+  # Template for creating identical invoices on a schedule. Modifying a
+  # recurring invoice changes all future invoices generated from it.
+  class RecurringInvoice < Resource
+    self.resource_path = "/recurring-invoices"
+
+    extend Operations::List
+    extend Operations::Retrieve
+    extend Operations::Create
+    extend Operations::Update
+    extend Operations::Replace
+    extend Operations::Archive
+  end
+end

data/lib/billrb/util.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Billrb
+  module Util
+    module_function
+
+    # "organization_id" -> "organizationId". Keys without underscores pass
+    # through unchanged, so callers may also use the API's native camelCase.
+    def camelize(key)
+      parts = key.to_s.split("_")
+      parts.first.to_s + parts.drop(1).map(&:capitalize).join
+    end
+
+    def camelize_keys(value)
+      case value
+      when Hash
+        value.to_h { |k, v| [camelize(k), camelize_keys(v)] }
+      when Array
+        value.map { |v| camelize_keys(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/billrb/version.rb

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

data/lib/billrb.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "billrb/version"
+require_relative "billrb/util"
+require_relative "billrb/errors"
+require_relative "billrb/configuration"
+require_relative "billrb/client"
+require_relative "billrb/list_page"
+require_relative "billrb/resource"
+require_relative "billrb/operations"
+require_relative "billrb/resources/customer"
+require_relative "billrb/resources/customer_bank_account"
+require_relative "billrb/resources/invoice"
+require_relative "billrb/resources/credit_memo"
+require_relative "billrb/resources/recurring_invoice"
+require_relative "billrb/resources/receivable_payment"
+
+module Billrb
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      @client = nil
+      configuration
+    end
+
+    # Default client built from the module-level configuration. For
+    # multi-tenant apps, build clients directly: Billrb::Client.new(dev_key: ...)
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: billrb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carlos Aguilar
+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'
+description: Lightweight, extensible Ruby client for the BILL (bill.com) v3 REST API.
+  Covers Accounts Receivable resources such as customers and invoices, with a small
+  resource layer that makes new endpoints easy to add.
+email:
+- carlos.aguilar@tecmanic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/billrb.rb
+- lib/billrb/client.rb
+- lib/billrb/configuration.rb
+- lib/billrb/errors.rb
+- lib/billrb/list_page.rb
+- lib/billrb/operations.rb
+- lib/billrb/resource.rb
+- lib/billrb/resources/credit_memo.rb
+- lib/billrb/resources/customer.rb
+- lib/billrb/resources/customer_bank_account.rb
+- lib/billrb/resources/invoice.rb
+- lib/billrb/resources/receivable_payment.rb
+- lib/billrb/resources/recurring_invoice.rb
+- lib/billrb/util.rb
+- lib/billrb/version.rb
+homepage: https://github.com/TECMANIC/billrb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/TECMANIC/billrb
+  source_code_uri: https://github.com/TECMANIC/billrb
+  changelog_uri: https://github.com/TECMANIC/billrb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Ruby client for the BILL (bill.com) v3 API, focused on Accounts Receivable.
+test_files: []