chore: documentation improvements

Author: stainless-app[bot]

README.md

@@ -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,35 @@ orb.customers.create(
 )
 ```
 
-## LSP Support
-
-### Solargraph
+## Editor support
 
-This library includes [Solargraph](https://solargraph.org) support for both auto completion and go to definition.
+Some editor language services like [Solargraph](https://github.com/castwide/solargraph?tab=readme-ov-file#gem-support) or [Sorbet](https://sorbet.org/docs/rbi#the-hidden-definitions-rbi) require a manually triggered indexing step before functionalities like auto-completion and go to definition can operate.
 
-```ruby
-gem "solargraph", group: :development
-```
+Please refer to their respective documentation for details. This library also includes a [short guide](https://github.com/orbcorp/orb-ruby/tree/main/CONTRIBUTING.md#editor-support) on how to set up various editor services for internal development.
 
-After Solargraph is installed, **you must populate its index** either via the provided editor command, or by running the following in your terminal:
+## Advanced Concepts
 
-```sh
-bundle exec solargraph gems
-```
+### Model DSL
 
-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.
+This library uses a Model DSL to represent request parameters and response shapes in `lib/orb/models`.
 
-```yaml
-include:
-  - 'vendor/bundle/ruby/*/gems/orb-billing-*/lib/**/*.rb'
-```
+The model classes service as anchor points for both toolchain readable documentation, and language service assisted navigation links. This information also allows the SDK's internals to perform translation between plain and rich data types; e.g., conversion between a `Time` instance and an ISO8601 `String`, and vice versa.
 
-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`.
-
-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.
-
-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:
-
-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
-
-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.
-
-## Advanced
-
 ### 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 +175,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 +193,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 +226,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).

Rakefile

@@ -21,7 +21,7 @@ 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"))
+  sh(*%w[yard server --reload --quiet --bind [::] --port], ENV.fetch("PORT", "8808"))
 end
 
 desc("Run test suites; use `TEST=path/to/test.rb` to run a specific test file")
@@ -111,7 +111,7 @@ end
 desc("Typecheck everything")
 multitask(typecheck: [:"typecheck:steep", :"typecheck:sorbet"])
 
-desc("Lint everything")
+desc("Lint and typecheck")
 multitask(lint: [:"lint:rubocop", :typecheck])
 
 desc("Build yard docs")

lib/orb.rb

@@ -19,15 +19,6 @@
 # We already ship the preferred sorbet manifests in the package itself.
 # `tapioca` currently does not offer us a way to opt out of unnecessary compilation.
 if Object.const_defined?(:Tapioca) && caller.chain([$PROGRAM_NAME]).chain(ARGV).grep(/tapioca/)
-  Warning.warn(
-    <<~WARN
-      \n
-      ⚠️ skipped loading of "orb" gem under `tapioca`.
-
-      This message is normal and expected if you are running a `tapioca` command, and does not impact `.rbi` generation.
-      \n
-    WARN
-  )
   return
 end