release: 0.2.0

.gitignore

@@ -1,10 +1,10 @@
 *.gem
 .idea/
+.ignore
 .prism.log
 .ruby-lsp/
 .yardoc/
-Brewfile.lock.json
 bin/tapioca
+Brewfile.lock.json
 doc/
-sorbet/*
-!/sorbet/config
+sorbet/tapioca/*

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.3"
+  ".": "0.2.0"
 }

.rubocop.yml

@@ -244,6 +244,7 @@ Style/SafeNavigation:
 Style/SignalException:
   Exclude:
     - Rakefile
+    - "**/*.rake"
 
 # We use these sparingly, where we anticipate future branches for the
 # inner conditional.

.ruby-version

@@ -0,0 +1 @@
+3.1.0

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.2.0 (2025-04-17)
+
+Full Changelog: [v0.1.3...v0.2.0](https://github.com/orbcorp/orb-ruby/compare/v0.1.3...v0.2.0)
+
+### Features
+
+* **client:** enable setting base URL from environment variable ([a472f4c](https://github.com/orbcorp/orb-ruby/commit/a472f4cdee0d969b7e240a9519acccd3877f3de6))
+
+
+### Bug Fixes
+
+* always send idempotency header when specified as a request option ([f570e93](https://github.com/orbcorp/orb-ruby/commit/f570e93e8fe1a2f6d6df495021ea1152aeaf1e58))
+
+
+### Chores
+
+* **internal:** always run post-processing when formatting when syntax_tree ([9df6d63](https://github.com/orbcorp/orb-ruby/commit/9df6d6382e67f6f28f1cedff4ee1c949ffd70237))
+* **internal:** codegen related update ([202fff4](https://github.com/orbcorp/orb-ruby/commit/202fff413ad9e9be16b67a07270dd4ac2c4f14e4))
+* **internal:** codegen related update ([2b99ae2](https://github.com/orbcorp/orb-ruby/commit/2b99ae2ea108ad4e6227bd5ab7e9a7dd064a8ded))
+* **internal:** contribute.md and contributor QoL improvements ([cb204de](https://github.com/orbcorp/orb-ruby/commit/cb204de43549ee6aa9ead2d1e071ec5df0c58cb2))
+* **internal:** loosen internal type restrictions ([9dc6b52](https://github.com/orbcorp/orb-ruby/commit/9dc6b52d1bfa57e3fab328bf8673872522ab7f25))
+* **internal:** minor touch ups on sdk internals ([9297be8](https://github.com/orbcorp/orb-ruby/commit/9297be8eaa459f14cb0b4118066ecd59877686ab))
+* **internal:** protect SSE parsing pipeline from broken UTF-8 characters ([bb2243a](https://github.com/orbcorp/orb-ruby/commit/bb2243a19fbd077687be4b2a4a001e4b7381c54d))
+* **internal:** version bump ([c664f2f](https://github.com/orbcorp/orb-ruby/commit/c664f2fb5019cabca07ce026410d6951f9412d69))
+* refine `#inspect` and `#to_s` for model classes ([86f8280](https://github.com/orbcorp/orb-ruby/commit/86f8280e1126e5bd4013f4c1e5ddd09190044fa3))
+
+
+### Documentation
+
+* update documentation links to be more uniform ([a0bfe42](https://github.com/orbcorp/orb-ruby/commit/a0bfe42c34e09819e4948069670cfdf895cb51af))
+
 ## 0.1.3 (2025-04-11)
 
 Full Changelog: [v0.1.2...v0.1.3](https://github.com/orbcorp/orb-ruby/compare/v0.1.2...v0.1.3)

CONTRIBUTING.md

@@ -0,0 +1,132 @@
+## Setting up the environment
+
+This repository contains a `.ruby-version` file, which should work with either [rbenv](https://github.com/rbenv/rbenv) or [asdf](https://github.com/asdf-vm/asdf) with the [ruby plugin](https://github.com/asdf-vm/asdf-ruby).
+
+Please follow the instructions for your preferred version manager to install the Ruby version specified in the `.ruby-version` file.
+
+To set up the repository, run:
+
+```bash
+$ ./scripts/bootstrap
+```
+
+This will install all the required dependencies.
+
+## Modifying/Adding code
+
+Most of the SDK is generated code. Modifications to code will be persisted between generations, but may result in merge conflicts between manual patches and changes from the generator. The generator will never modify the contents `examples/` directory.
+
+## Adding and running examples
+
+All files in the `examples/` directory are not modified by the generator and can be freely edited or added to.
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/orb"
+
+# ...
+```
+
+```bash
+$ chmod +x './examples/<your-example>.rb'
+
+# run the example against your api
+$ ruby './examples/<your-example>.rb'
+```
+
+## Using the repository from source
+
+If you’d like to use the repository from source, you can either install from git or reference a cloned repository:
+
+To install via git in your `Gemfile`:
+
+```ruby
+gem "orb-billing", git: "https://www.github.com/orbcorp/orb-ruby"
+```
+
+Alternatively, reference local copy of the repo:
+
+```bash
+$ git clone -- 'https://www.github.com/orbcorp/orb-ruby' '<path-to-repo>'
+```
+
+```ruby
+gem "orb-billing", path: "<path-to-repo>"
+```
+
+## Running commands
+
+Running `rake` by itself will show all runnable commands.
+
+```bash
+$ bundle exec rake
+```
+
+## Running tests
+
+Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.
+
+```bash
+$ npx prism mock path/to/your/openapi.yml
+```
+
+```bash
+$ bundle exec rake test
+```
+
+## Linting and formatting
+
+This repository uses [rubocop](https://github.com/rubocop/rubocop) for linting and formatting of `*.rb` and `*.rbi` files. [syntax_tree](https://github.com/ruby-syntax-tree/syntax_tree) is used for formatting `*.rbs` files.
+
+There are two separate type checkers supported by this library: [sorbet](https://github.com/sorbet/sorbet) and [steep](https://github.com/soutaro/steep) are used for verifying `*.rbi` and `*.rbs` files respectively.
+
+To lint and typecheck:
+
+```bash
+$ bundle exec rake lint
+```
+
+To format and fix all lint issues automatically:
+
+```bash
+$ bundle exec rake format
+```
+
+## Editor Support
+
+### Solargraph
+
+This library includes [Solargraph](https://solargraph.org) support for both auto-completion and go to definition.
+
+```ruby
+gem "solargraph", group: :development
+```
+
+Note: if you had installed the gem locally using `git: "..."` or `path: "..."`, you must update your [`.solargraph.yml`](https://solargraph.org/guides/configuration) to include the path to where the gem is located:
+
+```yaml
+include:
+  - '<path-to-repo>/lib/**/*.rb'
+```
+
+### Sorbet
+
+[Sorbet](https://sorbet.org) should mostly work out of the box when editing this library directly. However, there are a some caveats due to the colocation of `*.rb` and `*.rbi` files in the same project. These issues should not otherwise manifest when this library is used as a dependency.
+
+1. For go to definition usages, sorbet might get confused and may not always navigate to the correct location.
+
+2. For each generic type in `*.rbi` files, a spurious "Duplicate type member" error is present.
+
+### Ruby LSP
+
+The Ruby LSP has [best effort support](https://shopify.github.io/ruby-lsp/#guessed-types) for inferring type information from Ruby code, and as such it may not always be able to provide accurate type information.
+
+## Documentation Preview
+
+To preview the documentation, run:
+
+```bash
+$ bundle exec rake docs:preview [PORT=8808]
+```

Gemfile.lock

@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    orb-billing (0.1.2)
+    orb-billing (0.1.3)
       connection_pool
 
 GEM

README.md

@@ -4,9 +4,9 @@ The Orb Ruby library provides convenient access to the Orb REST API from any Rub
 
 ## Documentation
 
-Documentation for released of this gem can be found [on RubyDoc](https://gemdocs.org/gems/orb-billing).
+Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/orb-billing).
 
-The underlying REST API documentation can be found on [docs.withorb.com](https://docs.withorb.com/reference/api-reference).
+The REST API documentation can be found on [docs.withorb.com](https://docs.withorb.com/reference/api-reference).
 
 ## Installation
 
@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "orb-billing", "~> 0.1.3"
+gem "orb-billing", "~> 0.2.0"
 ```
 
 <!-- x-release-please-end -->

Rakefile

@@ -1,16 +1,30 @@
 # frozen_string_literal: true
 
+require "pathname"
 require "securerandom"
 require "shellwords"
 
 require "minitest/test_task"
 require "rake/clean"
 require "rubocop/rake_task"
 
-CLEAN.push(*%w[.idea/ .ruby-lsp/ .yardoc/])
+tapioca = "sorbet/tapioca"
+ignore_file = ".ignore"
 
-multitask(default: [:test])
+CLEAN.push(*%w[.idea/ .ruby-lsp/ .yardoc/ doc/], *FileList["*.gem"], ignore_file)
 
+CLOBBER.push(*%w[sorbet/rbi/annotations/ sorbet/rbi/gems/], tapioca)
+
+multitask(:default) do
+  sh(*%w[rake --tasks])
+end
+
+desc("Preview docs; use `PORT=<PORT>` to change the port")
+multitask(:"docs:preview") do
+  sh(*%w[yard server --bind [::] --reload --quiet --port], ENV.fetch("PORT", "8808"))
+end
+
+desc("Run test suites; use `TEST=path/to/test.rb` to run a specific test file")
 multitask(:test) do
   rb =
     FileList[ENV.fetch("TEST", "./test/**/*_test.rb")]
@@ -23,17 +37,20 @@ end
 rubo_find = %w[find ./lib ./test ./rbi -type f -and ( -name *.rb -or -name *.rbi ) -print0]
 xargs = %w[xargs --no-run-if-empty --null --max-procs=0 --max-args=300 --]
 
-multitask(:rubocop) do
+desc("Lint `*.rb(i)`")
+multitask(:"lint:rubocop") do
   lint = xargs + %w[rubocop --fail-level E] + (ENV.key?("CI") ? %w[--format github] : [])
   sh("#{rubo_find.shelljoin} | #{lint.shelljoin}")
 end
 
-multitask(:ruboformat) do
+desc("Format `*.rb(i)`")
+multitask(:"format:rubocop") do
   fmt = xargs + %w[rubocop --fail-level F --autocorrect --format simple --]
   sh("#{rubo_find.shelljoin} | #{fmt.shelljoin}")
 end
 
-multitask(:syntax_tree) do
+desc("Format `*.rbs`")
+multitask(:"format:syntax_tree") do
   find = %w[find ./sig -type f -name *.rbs -print0]
   inplace = /darwin|bsd/ =~ RUBY_PLATFORM ? %w[-i''] : %w[-i]
   uuid = SecureRandom.uuid
@@ -59,35 +76,64 @@ multitask(:syntax_tree) do
   #   2. at label `l1`, join previously annotated line with `class | module` information.
   pst = sed + [subst, "--"]
 
+  success = false
+
   # transform class aliases to type aliases, which syntax tree has no trouble with
   sh("#{find.shelljoin} | #{pre.shelljoin}")
   # run syntax tree to format `*.rbs` files
-  sh("#{find.shelljoin} | #{fmt.shelljoin}")
+  sh("#{find.shelljoin} | #{fmt.shelljoin}") do
+    success = _1
+  end
   # transform type aliases back to class aliases
   sh("#{find.shelljoin} | #{pst.shelljoin}")
+
+  # always run post-processing to remove comment marker
+  fail unless success
 end
 
-multitask(format: [:ruboformat, :syntax_tree])
+desc("Format everything")
+multitask(format: [:"format:rubocop", :"format:syntax_tree"])
 
-multitask(:steep) do
+desc("Typecheck `*.rbs`")
+multitask(:"typecheck:steep") do
   sh(*%w[steep check])
 end
 
-multitask(:sorbet) do
+desc("Typecheck `*.rbi`")
+multitask(:"typecheck:sorbet") do
   sh(*%w[srb typecheck])
 end
 
-file("sorbet/tapioca") do
+file(tapioca) do
   sh(*%w[tapioca init])
 end
 
-multitask(typecheck: [:steep, :sorbet])
-multitask(lint: [:rubocop, :typecheck])
+desc("Typecheck everything")
+multitask(typecheck: [:"typecheck:steep", :"typecheck:sorbet"])
+
+desc("Lint everything")
+multitask(lint: [:"lint:rubocop", :typecheck])
+
+desc("Build yard docs")
+multitask(:"build:docs") do
+  sh(*%w[yard])
+end
 
-multitask(:build) do
-  sh(*%w[gem build -- orb.gemspec])
+desc("Build ruby gem")
+multitask(:"build:gem") do
+  # optimizing for grepping through the gem bundle: many tools honour `.ignore` files, including VSCode
+  #
+  # both `rbi` and `sig` directories are navigable by their respective tool chains and therefore can be ignored by tools such as `rg`
+  Pathname(ignore_file).write(<<~GLOB)
+    rbi/*
+    sig/*
+  GLOB
+
+  sh(*%w[gem build -- openai.gemspec])
+  rm_rf(ignore_file)
 end
 
-multitask(release: [:build]) do
+desc("Release ruby gem")
+multitask(release: [:"build:gem"]) do
   sh(*%w[gem push], *FileList["orb-*.gem"])
 end

lib/orb/client.rb

@@ -76,7 +76,8 @@ class Client < Orb::Internal::Transport::BaseClient
     #
     # @param api_key [String, nil] Defaults to `ENV["ORB_API_KEY"]`
     #
-    # @param base_url [String, nil] Override the default base URL for the API, e.g., `"https://api.example.com/v2/"`
+    # @param base_url [String, nil] Override the default base URL for the API, e.g.,
+    # `"https://api.example.com/v2/"`. Defaults to `ENV["ORB_BASE_URL"]`
     #
     # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
     #
@@ -89,7 +90,7 @@ class Client < Orb::Internal::Transport::BaseClient
     # @param idempotency_header [String]
     def initialize(
       api_key: ENV["ORB_API_KEY"],
-      base_url: nil,
+      base_url: ENV["ORB_BASE_URL"],
       max_retries: DEFAULT_MAX_RETRIES,
       timeout: DEFAULT_TIMEOUT_IN_SECONDS,
       initial_retry_delay: DEFAULT_INITIAL_RETRY_DELAY,

lib/orb/internal.rb

@@ -3,6 +3,10 @@
 module Orb
   # @api private
   module Internal
-    OMIT = Object.new.freeze
+    OMIT =
+      Object.new.tap do
+        _1.define_singleton_method(:inspect) { "#<#{Orb::Internal}::OMIT>" }
+      end
+        .freeze
   end
 end