release: 0.3.0

.github/workflows/ci.yml

@@ -1,17 +1,19 @@
 name: CI
 on:
   push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-      - next
+    branches-ignore:
+      - 'generated'
+      - 'codegen/**'
+      - 'integrated/**'
+      - 'stl-preview-head/**'
+      - 'stl-preview-base/**'
 
 jobs:
   lint:
+    timeout-minutes: 10
     name: lint
-    runs-on: ubuntu-latest
+    runs-on: ${{ github.repository == 'stainless-sdks/orb-ruby' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+
     steps:
       - uses: actions/checkout@v4
       - name: Set up Ruby
@@ -25,8 +27,9 @@ jobs:
       - name: Run lints
         run: ./scripts/lint
   test:
+    timeout-minutes: 10
     name: test
-    runs-on: ubuntu-latest
+    runs-on: ${{ github.repository == 'stainless-sdks/orb-ruby' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@v4
       - name: Set up Ruby

.release-please-manifest.json

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

.yardopts

@@ -1,3 +1,5 @@
+--type-name-tag generic:Generic
+--default-return void
 --markup markdown
 --markup-provider redcarpet
 --exclude /rbi

CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.3.0 (2025-04-25)
+
+Full Changelog: [v0.2.0...v0.3.0](https://github.com/orbcorp/orb-ruby/compare/v0.2.0...v0.3.0)
+
+### Features
+
+* implement `#hash` for data containers ([ba49d29](https://github.com/orbcorp/orb-ruby/commit/ba49d294bfa09eca64b9a137c730c452318a56d4))
+* support specifying content-type with FilePart class ([200103f](https://github.com/orbcorp/orb-ruby/commit/200103fddf8b1d524caa1cb3a126d72b476315f4))
+* support webmock for testing ([ca1c497](https://github.com/orbcorp/orb-ruby/commit/ca1c497d57309c0bd2518070a0f8af3e0c639be4))
+
+
+### Bug Fixes
+
+* ensure gem release is unaffected by renaming ([3e0fd9e](https://github.com/orbcorp/orb-ruby/commit/3e0fd9e21bb02529c0513b7a1e2fbdfa7d80b049))
+* make a typo for `FilePart.content` ([f62d185](https://github.com/orbcorp/orb-ruby/commit/f62d18544ccd90a55bdfc520cbea03c1ea7583d1))
+
+
+### Chores
+
+* broadly detect json family of content-type headers ([d4e5904](https://github.com/orbcorp/orb-ruby/commit/d4e5904287b32db4efe997b617310670961be6b1))
+* **ci:** add timeout thresholds for CI jobs ([450f552](https://github.com/orbcorp/orb-ruby/commit/450f552e892e75242d3ec3e3e0c98605e1ac0b61))
+* **ci:** only use depot for staging repos ([fd387ce](https://github.com/orbcorp/orb-ruby/commit/fd387ce6f9dff526039887480712e8b0c35595b5))
+* **ci:** run on more branches and use depot runners ([7f5a6c3](https://github.com/orbcorp/orb-ruby/commit/7f5a6c320853a23d5ac339ea368d7cad7bbc35c5))
+* documentation improvements ([6e04e50](https://github.com/orbcorp/orb-ruby/commit/6e04e5062b468fdf1f40fe3cd491b9fbb610bc5c))
+* explicitly mark apis public under `Internal` module ([d19524a](https://github.com/orbcorp/orb-ruby/commit/d19524a2a412b98ac4529b46c02e249e8a587c34))
+* **internal:** improve response envelope unwrap functionality ([b3f0632](https://github.com/orbcorp/orb-ruby/commit/b3f0632eae23d838395933fe4a334fd23dff46fd))
+* **internal:** minor type annotation improvements ([cf871bc](https://github.com/orbcorp/orb-ruby/commit/cf871bca5feacf6e95351418a3553c774889ccee))
+* **internal:** version bump ([6b83db6](https://github.com/orbcorp/orb-ruby/commit/6b83db65c3d405b7f7c5e20a93be6428dcf7fc08))
+* make sorbet enums easier to read ([3793346](https://github.com/orbcorp/orb-ruby/commit/3793346c4a6cd6ff18aad64e4c48933a5159ebe1))
+* show truncated parameter docs in yard ([0fb86bd](https://github.com/orbcorp/orb-ruby/commit/0fb86bd1313bb300e565f873e5a181f652ce88fa))
+* simplify yard annotations by removing most `@!parse` directives ([a94843b](https://github.com/orbcorp/orb-ruby/commit/a94843be3f13ed22ae07ded47bff22e044525f0b))
+* update README with recommended editor plugins ([50771fd](https://github.com/orbcorp/orb-ruby/commit/50771fdf28dcee2856522c5c29a491873ec14a4a))
+* use `@!method` instead of `@!parse` for virtual method type definitions ([21cfdfc](https://github.com/orbcorp/orb-ruby/commit/21cfdfcc91f9dbd04831e502b990f9118f4b5eb0))
+
 ## 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)

CONTRIBUTING.md

@@ -96,20 +96,17 @@ $ bundle exec rake format
 
 ## Editor Support
 
-### Solargraph
+### Ruby LSP
 
-This library includes [Solargraph](https://solargraph.org) support for both auto-completion and go to definition.
+[Ruby LSP](https://github.com/Shopify/ruby-lsp) has quite good support for go to definition, but not auto-completion.
 
-```ruby
-gem "solargraph", group: :development
-```
+This can be installed along side Solargraph.
+
+### Solargraph
 
-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:
+[Solargraph](https://solargraph.org) has quite good support for auto-completion, but not go to definition.
 
-```yaml
-include:
-  - '<path-to-repo>/lib/**/*.rb'
-```
+This can be installed along side Ruby LSP.
 
 ### Sorbet
 
@@ -119,10 +116,6 @@ include:
 
 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:

Gemfile

@@ -23,6 +23,7 @@ group :development, :test do
   gem "minitest-hooks"
   gem "minitest-proveit"
   gem "minitest-rg"
+  gem "webmock"
 end
 
 group :development, :docs do

Gemfile.lock

@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    orb-billing (0.1.3)
+    orb-billing (0.2.0)
       connection_pool
 
 GEM
@@ -29,6 +29,8 @@ GEM
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)
     async (2.23.1)
       console (~> 1.29)
@@ -45,6 +47,9 @@ GEM
       fiber-annotation
       fiber-local (~> 1.1)
       json
+    crack (1.0.0)
+      bigdecimal
+      rexml
     csv (3.3.3)
     drb (2.2.1)
     erubi (1.13.1)
@@ -54,6 +59,7 @@ GEM
       fiber-storage
     fiber-storage (1.0.0)
     fileutils (1.7.3)
+    hashdiff (1.1.2)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     io-event (1.10.0)
@@ -82,6 +88,7 @@ GEM
       racc
     prettier_print (1.2.1)
     prism (1.4.0)
+    public_suffix (6.0.1)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.2.1)
@@ -96,6 +103,7 @@ GEM
       logger
     redcarpet (3.6.1)
     regexp_parser (2.10.0)
+    rexml (3.4.1)
     rubocop (1.75.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -165,6 +173,10 @@ GEM
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
     uri (1.0.3)
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
     webrick (1.9.1)
     yard (0.9.37)
     yard-sorbet (0.9.0)
@@ -191,6 +203,7 @@ DEPENDENCIES
   syntax_tree
   syntax_tree-rbs!
   tapioca
+  webmock
   webrick
   yard
 

README.md

@@ -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.2.0"
+gem "orb-billing", "~> 0.3.0"
 ```
 
 <!-- x-release-please-end -->
@@ -35,6 +35,16 @@ customer = orb.customers.create(email: "example-customer@withorb.com", name: "My
 puts(customer.id)
 ```
 
+## Sorbet
+
+This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+
+When using sorbet, it is recommended to use model classes as below. This provides stronger type checking and tooling integration.
+
+```ruby
+orb.customers.create(email: "example-customer@withorb.com", name: "My Customer")
+```
+
 ### Pagination
 
 List methods in the Orb API are paginated.
@@ -126,61 +136,33 @@ orb.customers.create(
 )
 ```
 
-## LSP Support
-
-### Solargraph
-
-This library includes [Solargraph](https://solargraph.org) support for both auto completion and go to definition.
-
-```ruby
-gem "solargraph", group: :development
-```
-
-After Solargraph is installed, **you must populate its index** either via the provided editor command, or by running the following in your terminal:
-
-```sh
-bundle exec solargraph gems
-```
-
-Note: if you had installed the gem either using a `git:` or `github:` URL, or had vendored the gem using bundler, you will need to set up your [`.solargraph.yml`](https://solargraph.org/guides/configuration) to include the path to the gem's `lib` directory.
-
-```yaml
-include:
-  - 'vendor/bundle/ruby/*/gems/orb-billing-*/lib/**/*.rb'
-```
-
-Otherwise Solargraph will not be able to provide type information or auto-completion for any non-indexed libraries.
-
-### Sorbet
-
-This library is written with [Sorbet type definitions](https://sorbet.org/docs/rbi). However, there is no runtime dependency on the `sorbet-runtime`.
+## Model DSL
 
-What this means is that while you can use Sorbet to type check your code statically, and benefit from the [Sorbet Language Server](https://sorbet.org/docs/lsp) in your editor, there is no runtime type checking and execution overhead from Sorbet itself.
+This library uses a simple DSL to represent request parameters and response shapes in `lib/orb/models`.
 
-Due to limitations with the Sorbet type system, where a method otherwise can take an instance of `Orb::BaseModel` class, you will need to use the `**` splat operator to pass the arguments:
+With the right [editor plugins](https://shopify.github.io/ruby-lsp), you can ctrl-click on elements of the DSL to navigate around and explore the library.
 
-Please follow Sorbet's [setup guides](https://sorbet.org/docs/adopting) for best experience.
+In all places where a `BaseModel` type is specified, vanilla Ruby `Hash` can also be used. For example, the following are interchangeable as arguments:
 
 ```ruby
+# This has tooling readability, for auto-completion, static analysis, and goto definition with supported language services
 params = Orb::Models::CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
 
-orb.customers.create(**params)
+# This also works
+params = {
+  email: "example-customer@withorb.com",
+  name: "My Customer"
+}
 ```
 
-Note: **This library emits an intentional warning under the [`tapioca` toolchain](https://github.com/Shopify/tapioca)**. This is normal, and does not impact functionality.
-
-### Ruby LSP
+## Editor support
 
-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.
+A combination of [Shopify LSP](https://shopify.github.io/ruby-lsp) and [Solargraph](https://solargraph.org/) is recommended for non-[Sorbet](https://sorbet.org) users. The former is especially good at go to definition, while the latter has much better auto-completion support.
 
-## Advanced
+## Advanced concepts
 
 ### Making custom/undocumented requests
 
-This library is typed for convenient access to the documented API.
-
-If you need to access undocumented endpoints, params, or response properties, the library can still be used.
-
 #### Undocumented request params
 
 If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a requests as seen in examples above.
@@ -191,15 +173,15 @@ To make requests to undocumented endpoints, you can make requests using `client.
 
 ```ruby
 response = client.request(
-    method: :post,
-    path: '/undocumented/endpoint',
-    query: {"dog": "woof"},
-    headers: {"useful-header": "interesting-value"},
-    body: {"he": "llo"},
-  )
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"he": "llo"},
+)
 ```
 
-### Concurrency & Connection Pooling
+### Concurrency & connection pooling
 
 The `Orb::Client` instances are thread-safe, and should be re-used across multiple threads. By default, each `Client` have their own HTTP connection pool, with a maximum number of connections equal to thread count.
 
@@ -209,6 +191,30 @@ Unless otherwise specified, other classes in the SDK do not have locks protectin
 
 Currently, `Orb::Client` instances are only fork-safe if there are no in-flight HTTP requests.
 
+### Sorbet
+
+#### Enums
+
+Sorbet's typed enums require sub-classing of the [`T::Enum` class](https://sorbet.org/docs/tenum) from the `sorbet-runtime` gem.
+
+Since this library does not depend on `sorbet-runtime`, it uses a [`T.all` intersection type](https://sorbet.org/docs/intersection-types) with a ruby primitive type to construct a "tagged alias" instead.
+
+```ruby
+module Orb::Models::BillingCycleRelativeDate
+  # This alias aids language service driven navigation.
+  TaggedSymbol = T.type_alias { T.all(Symbol, Orb::Models::BillingCycleRelativeDate) }
+end
+```
+
+#### Argument passing trick
+
+It is possible to pass a compatible model / parameter class to a method that expects keyword arguments by using the `**` splat operator.
+
+```ruby
+params = Orb::Models::CustomerCreateParams.new(email: "example-customer@withorb.com", name: "My Customer")
+orb.customers.create(**params)
+```
+
 ## Versioning
 
 This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
@@ -218,3 +224,7 @@ This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` typ
 ## Requirements
 
 Ruby 3.1.0 or higher.
+
+## Contributing
+
+See [the contributing documentation](https://github.com/orbcorp/orb-ruby/tree/main/CONTRIBUTING.md).