cadenya 0.51.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eee358f41c4676b08825c038d3f5be16d39d1e3f6530b997b6122f5f278bcd4c
-  data.tar.gz: a51b13f4d27021161b7e6d58f1cc59893ea9172cbc31be2a52f3635d45107b27
+  metadata.gz: 848ebb2b39aa33946683d9bb929d35b07eb615cc8babce18f4f3ca3ae46440b7
+  data.tar.gz: 753a08e80d462781aed796a2a96ac29801d68b7136d29fdd1ddffdd57853eb39
 SHA512:
-  metadata.gz: 037be4c3e8a660d36912ec09643515e2d3046efe190e299b329616d76f2180f54ad058f421051861b4fd7d5e62427637d528d66fcea476acece02d637b9c13f7
-  data.tar.gz: 95a41747fcd2eb24babb22327c2ef1d1638b11f9bf787a4aa72ff531a1a866363c8edf56daa618c26375a50117ea24f23b223498c3cbbb9b98fc341d95e249d1
+  metadata.gz: 428b7b7b043d6b41b920b1146c502bbd453fb8c340a2feb46a50d12162baa0ce57c0ef45cd5fdf0def9d494cfa81d10deef488397dab6dbd8fd0e4b5b45afecc
+  data.tar.gz: 198b736f259553305b7f5b90df3caf15c2e798152e4c8d92dbefcfa601d624d21e4b0984e724d1dd9a736195fcc86fe23c94dcc15f37d398c7d87bcd026b17a6

data/README.md

@@ -1,297 +1,93 @@
-# Cadenya Ruby API library
+# Cadenya Ruby SDK
 
-The Cadenya Ruby library provides convenient access to the Cadenya REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/cadenya/cadenya-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
+The official Ruby client for the Cadenya API. Generated by redwood.
+Built on Faraday with typed model classes and Enumerable pages.
 
-It is generated with [Stainless](https://www.stainless.com/).
+## Install
 
-## Documentation
-
-Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/cadenya).
-
-The REST API documentation can be found on [docs.cadenya.com](https://docs.cadenya.com).
-
-## Installation
-
-To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
-
-<!-- x-release-please-start-version -->
-
-```ruby
-gem "cadenya", "~> 0.51.1"
+```sh
+gem install cadenya
 ```
 
-<!-- x-release-please-end -->
-
-## Usage
+## Getting started
 
 ```ruby
-require "bundler/setup"
 require "cadenya"
 
-cadenya = Cadenya::Client.new(
-  api_key: ENV["CADENYA_API_KEY"] # This is the default and can be omitted
-)
-
-objective = cadenya.objectives.create(
-  workspace_id: "workspace_01HXKD2E5NQXAMPLE0000000",
-  agent_id: "agent_01HXKD2E5NQXAMPLE0000000",
-  system_prompt_data: {customer_name: "Ada"},
-  first_user_message: "Summarize the open support tickets from yesterday."
-)
+# Reads CADENYA_API_KEY (and CADENYA_WORKSPACE_ID) from the environment when
+# arguments are omitted. Explicit blank values raise ArgumentError and
+# never fall back to the environment.
+client = Cadenya::Client.new
 
-puts(objective.configSnapshot)
+result = client.accounts.retrieve
 ```
 
-### Streaming
+## Requests are snake_case throughout
 
-We provide support for streaming responses using Server-Sent Events (SSE).
+Nested request hashes take snake_case keys (symbols or strings) and are
+translated to wire names at the HTTP boundary; your own data inside
+JSON/map fields is never rewritten.
 
 ```ruby
-stream = cadenya.objectives.stream_events_streaming(
-  "obj_01HXKD2E5NQXAMPLE0000000",
-  workspace_id: "workspace_01HXKD2E5NQXAMPLE0000000"
+client.api_keys.create(
+  metadata: {"name" => "sample"},
+  spec: {}
 )
-
-stream.each do |objective|
-  puts(objective.data)
-end
 ```
 
-### Pagination
-
-List methods in the Cadenya API are paginated.
+## Errors
 
-This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+Non-2xx responses raise `Cadenya::APIError` (google.rpc Status:
+`status_code`, `code`, `details`). Protocol surprises raise
+`APIResponseError`; connection failures raise `APIConnectionError`.
 
-```ruby
-page = cadenya.ai_provider_keys.list
+## Retries
 
-# Fetch single item from page.
-ai_provider_key = page.items[0]
-puts(ai_provider_key.metadata)
+Automatic retries apply only to idempotent methods (GET/HEAD/PUT/DELETE)
+and default to 0; counts normalize to a bounded 0–10 integer. Streaming
+requests never auto-retry, and a caller-supplied Faraday connection's
+timeout policy is authoritative.
 
-# Automatically fetches more pages as needed.
-page.auto_paging_each do |ai_provider_key|
-  puts(ai_provider_key.metadata)
-end
-```
 
-Alternatively, you can use the `#next_page?` and `#next_page` methods for more granular control working with pages.
+## Pagination
 
 ```ruby
-if page.next_page?
-  new_page = page.next_page
-  puts(new_page.items[0].metadata)
+client.api_keys.list.each do |item|
+  # iterating a page auto-fetches every page (also: auto_paging_each)
 end
 ```
 
-### Handling errors
-
-When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Cadenya::Errors::APIError` will be thrown:
+## Streaming (SSE)
 
 ```ruby
-begin
-  account = cadenya.account.retrieve
-rescue Cadenya::Errors::APIConnectionError => e
-  puts("The server could not be reached")
-  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
-rescue Cadenya::Errors::RateLimitError => e
-  puts("A 429 status code was received; we should back off a bit.")
-rescue Cadenya::Errors::APIStatusError => e
-  puts("Another non-200-range status code was received")
-  puts(e.status)
-end
+stream = client.objectives.stream_events(objective_id)
+stream.each { |event| ... }
+
+# Stop deterministically — from the consuming block or another thread.
+# Iteration ends cleanly at the next received chunk (keep-alives included)
+# and the HTTP response/socket is released. Streams are single-use:
+# re-enumerating raises IOError.
+stream.close
+
+# Resume after a disconnect: the checkpoint persists per the SSE spec.
+resumed = client.objectives.stream_events(objective_id, last_event_id: stream.last_event_id)
+resumed.each { |event| ... }
 ```
 
-Error codes are as follows:
-
-| Cause            | Error Type                 |
-| ---------------- | -------------------------- |
-| HTTP 400         | `BadRequestError`          |
-| HTTP 401         | `AuthenticationError`      |
-| HTTP 403         | `PermissionDeniedError`    |
-| HTTP 404         | `NotFoundError`            |
-| HTTP 409         | `ConflictError`            |
-| HTTP 422         | `UnprocessableEntityError` |
-| HTTP 429         | `RateLimitError`           |
-| HTTP >= 500      | `InternalServerError`      |
-| Other HTTP error | `APIStatusError`           |
-| Timeout          | `APITimeoutError`          |
-| Network error    | `APIConnectionError`       |
-
-### Retries
+`close` from another thread interrupts even a read blocked on a silent
+socket: the stream's cancel handle tears the transport down immediately.
 
-Certain errors will be automatically retried 0 times by default, with a short exponential backoff.
-
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
-
-You can use the `max_retries` option to configure or disable this:
+## Webhooks (no API key required)
 
 ```ruby
-# Configure the default for all requests:
-cadenya = Cadenya::Client.new(
-  max_retries: 0 # default is 0
-)
-
-# Or, configure per-request:
-cadenya.account.retrieve(request_options: {max_retries: 5})
-```
-
-### Timeouts
-
-By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
-
-```ruby
-# Configure the default for all requests:
-cadenya = Cadenya::Client.new(
-  timeout: nil # default is 60
-)
-
-# Or, configure per-request:
-cadenya.account.retrieve(request_options: {timeout: 5})
+Cadenya::Webhooks.verify(ENV.fetch("CADENYA_WEBHOOK_SECRET"), payload, headers)
+# or, with typed decoding via a client: client.unwrap_webhook(payload, headers)
 ```
 
-On timeout, `Cadenya::Errors::APITimeoutError` is raised.
-
-Note that requests that time out are retried by default.
-
-## Advanced concepts
-
-### BaseModel
-
-All parameter and response objects inherit from `Cadenya::Internal::Type::BaseModel`, which provides several conveniences, including:
-
-1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
-
-2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
-
-3. Both instances and the classes themselves can be pretty-printed.
-
-4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
-
-### Making custom or undocumented requests
-
-#### Undocumented properties
-
-You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
-
-Note: the `extra_` parameters of the same name overrides the documented parameters.
-
-```ruby
-account =
-  cadenya.account.retrieve(
-    request_options: {
-      extra_query: {my_query_parameter: value},
-      extra_body: {my_body_parameter: value},
-      extra_headers: {"my-header": value}
-    }
-  )
-
-puts(account[:my_undocumented_property])
-```
-
-#### 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 request, as seen in the examples above.
-
-#### Undocumented endpoints
-
-To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
-
-```ruby
-response = client.request(
-  method: :post,
-  path: '/undocumented/endpoint',
-  query: {"dog": "woof"},
-  headers: {"useful-header": "interesting-value"},
-  body: {"hello": "world"}
-)
-```
-
-### Concurrency & connection pooling
-
-The `Cadenya::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
-
-Each instance of `Cadenya::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
-
-When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
-
-Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
-
-## Sorbet
-
-This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
-
-You can provide typesafe request parameters like so:
-
-```ruby
-cadenya.objectives.create(
-  workspace_id: "workspace_01HXKD2E5NQXAMPLE0000000",
-  agent_id: "agent_01HXKD2E5NQXAMPLE0000000",
-  system_prompt_data: {customer_name: "Ada"},
-  first_user_message: "Summarize the open support tickets from yesterday."
-)
-```
-
-Or, equivalently:
-
-```ruby
-# Hashes work, but are not typesafe:
-cadenya.objectives.create(
-  workspace_id: "workspace_01HXKD2E5NQXAMPLE0000000",
-  agent_id: "agent_01HXKD2E5NQXAMPLE0000000",
-  system_prompt_data: {customer_name: "Ada"},
-  first_user_message: "Summarize the open support tickets from yesterday."
-)
-
-# You can also splat a full Params class:
-params = Cadenya::ObjectiveCreateParams.new(
-  workspace_id: "workspace_01HXKD2E5NQXAMPLE0000000",
-  agent_id: "agent_01HXKD2E5NQXAMPLE0000000",
-  system_prompt_data: {customer_name: "Ada"},
-  first_user_message: "Summarize the open support tickets from yesterday."
-)
-cadenya.objectives.create(**params)
-```
-
-### Enums
-
-Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
-
-```ruby
-# :STATE_UNSPECIFIED
-puts(Cadenya::AgentListParams::State::STATE_UNSPECIFIED)
-
-# Revealed type: `T.all(Cadenya::AgentListParams::State, Symbol)`
-T.reveal_type(Cadenya::AgentListParams::State::STATE_UNSPECIFIED)
-```
-
-Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
-
-```ruby
-# Using the enum constants preserves the tagged type information:
-cadenya.agents.list(
-  state: Cadenya::AgentListParams::State::STATE_UNSPECIFIED,
-  # …
-)
-
-# Literal values are also permissible:
-cadenya.agents.list(
-  state: :STATE_UNSPECIFIED,
-  # …
-)
-```
-
-## 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.
-
-This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
-
-## Requirements
-
-Ruby 3.2.0 or higher.
+Verification follows Standard Webhooks (24–64 byte decoded secrets,
+integer timestamps, bounded tolerance).
 
-## Contributing
+## Reference
 
-See [the contributing documentation](https://github.com/cadenya/cadenya-ruby/tree/main/CONTRIBUTING.md).
+The full method reference ships in the gem as `api.md` (also in the
+repository).