@cadenya/cadenya 0.135.0 → 1.0.0

package/README.md

@@ -1,418 +1,146 @@
-# Cadenya TypeScript API Library
+# Cadenya TypeScript SDK
 
-[![NPM version](<https://img.shields.io/npm/v/@cadenya/cadenya.svg?label=npm%20(stable)>)](https://npmjs.org/package/@cadenya/cadenya) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@cadenya/cadenya)
+The official TypeScript client for the Cadenya API. Generated by redwood.
+Dependency-free ESM built on native `fetch`.
 
-This library provides convenient access to the Cadenya REST API from server-side TypeScript or JavaScript.
-
-The REST API documentation can be found on [docs.cadenya.com](https://docs.cadenya.com). The full API of this library can be found in [api.md](api.md).
-
-It is maintained by Cadenya, including our coding agents. Community pull requests are welcome.
-
-## Installation
+## Install
 
 ```sh
 npm install @cadenya/cadenya
 ```
 
-## Usage
-
-The full API of this library can be found in [api.md](api.md).
-
-<!-- prettier-ignore -->
-```js
-import Cadenya from '@cadenya/cadenya';
-
-const client = new Cadenya({
-  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
-});
-
-const objective = await client.objectives.create({
-  workspaceId: 'workspace_01HXKD2E5NQXAMPLE0000000',
-  agentId: 'agent_01HXKD2E5NQXAMPLE0000000',
-  systemPromptData: { customer_name: 'Ada' },
-  firstUserMessage: 'Summarize the open support tickets from yesterday.',
-});
-
-console.log(objective.configSnapshot);
-```
-
-## Streaming responses
-
-We provide support for streaming responses using Server Sent Events (SSE).
+## Getting started
 
 ```ts
 import Cadenya from '@cadenya/cadenya';
 
+// Reads CADENYA_API_KEY (and CADENYA_WORKSPACE_ID) from the environment when
+// options are omitted. Explicit blank values are configuration errors.
 const client = new Cadenya();
 
-const stream = await client.objectives.streamEvents('obj_01HXKD2E5NQXAMPLE0000000', {
-  workspaceId: 'workspace_01HXKD2E5NQXAMPLE0000000',
-});
-for await (const objectiveEvent of stream) {
-  console.log(objectiveEvent.data);
-}
+const result = await client.accounts.retrieve();
 ```
 
-If you need to cancel a stream, you can `break` from the loop
-or call `stream.controller.abort()`.
+## Errors
 
-### Request & Response types
+Non-2xx responses throw `APIError` (google.rpc Status: `status`, `code`,
+`message`, `details`). Connection failures throw `APIConnectionError`;
+user aborts throw `APIUserAbortError`; a request that cannot be
+constructed locally (unserializable body) throws `APIRequestError` with
+no network attempt and no retry.
 
-This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
+## Timeouts
 
-<!-- prettier-ignore -->
-```ts
-import Cadenya from '@cadenya/cadenya';
+Ordinary requests have a 60s deadline (through body decode) that throws
+`APITimeoutError`; configure client-wide with `timeout` or per request
+with `options.timeout` (<= 0 disables). Streams bound only response-header
+acquisition — body lifetime stays under your `AbortSignal`.
 
-const client = new Cadenya({
-  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
-});
-
-const account: Cadenya.Account = await client.account.retrieve();
-```
+## Retries
 
-Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
+Automatic retries apply only to idempotent methods (GET/HEAD/PUT/DELETE)
+and default to 0. Enable client-wide with `maxRetries`; opt a single
+mutation in per request with `options.maxRetries`. Retry counts normalize
+to a bounded 0–10 integer; `Retry-After` (seconds or HTTP-date) is honored
+and backoff sleeps wake on abort.
 
-## Handling errors
+## Pagination
 
-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 `APIError` will be thrown:
-
-<!-- prettier-ignore -->
 ```ts
-const account = await client.account.retrieve().catch(async (err) => {
-  if (err instanceof Cadenya.APIError) {
-    console.log(err.status); // 400
-    console.log(err.name); // BadRequestError
-    console.log(err.headers); // {server: 'nginx', ...}
-  } else {
-    throw err;
-  }
-});
-```
-
-Error codes are as follows:
-
-| Status Code | Error Type                 |
-| ----------- | -------------------------- |
-| 400         | `BadRequestError`          |
-| 401         | `AuthenticationError`      |
-| 403         | `PermissionDeniedError`    |
-| 404         | `NotFoundError`            |
-| 422         | `UnprocessableEntityError` |
-| 429         | `RateLimitError`           |
-| >=500       | `InternalServerError`      |
-| N/A         | `APIConnectionError`       |
-
-### Retries
-
-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, and >=500 Internal errors will all be retried by default.
-
-You can use the `maxRetries` option to configure or disable this:
-
-<!-- prettier-ignore -->
-```js
-// Configure the default for all requests:
-const client = new Cadenya({
-  maxRetries: 0, // default is 2
-});
-
-// Or, configure per-request:
-await client.account.retrieve({
-  maxRetries: 5,
-});
-```
-
-### Timeouts
-
-Requests time out after 1 minute by default. You can configure this with a `timeout` option:
-
-<!-- prettier-ignore -->
-```ts
-// Configure the default for all requests:
-const client = new Cadenya({
-  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
-});
-
-// Override per-request:
-await client.account.retrieve({
-  timeout: 5 * 1000,
-});
-```
-
-On timeout, an `APIConnectionTimeoutError` is thrown.
-
-Note that requests which time out will be [retried twice by default](#retries).
-
-## Auto-pagination
-
-List methods in the Cadenya API are paginated.
-You can use the `for await … of` syntax to iterate through items across all pages:
-
-```ts
-async function fetchAllAIProviderKeys(params) {
-  const allAIProviderKeys = [];
-  // Automatically fetches more pages as needed.
-  for await (const aiProviderKey of client.aiProviderKeys.list({
-    workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
-  })) {
-    allAIProviderKeys.push(aiProviderKey);
-  }
-  return allAIProviderKeys;
-}
-```
-
-Alternatively, you can request a single page at a time:
-
-```ts
-let page = await client.aiProviderKeys.list({
-  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
-});
-for (const aiProviderKey of page.items) {
-  console.log(aiProviderKey);
+const page = await client.apiKeys.list();
+for await (const item of page) {
+  // auto-fetches every page
 }
-
-// Convenience methods are provided for manually paginating:
-while (page.hasNextPage()) {
-  page = await page.getNextPage();
-  // ...
-}
-```
-
-## Advanced Usage
-
-### Accessing raw Response data (e.g., headers)
-
-The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
-This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
-
-You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
-Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
-
-<!-- prettier-ignore -->
-```ts
-const client = new Cadenya();
-
-const response = await client.account.retrieve().asResponse();
-console.log(response.headers.get('X-My-Header'));
-console.log(response.statusText); // access the underlying Response object
-
-const { data: account, response: raw } = await client.account.retrieve().withResponse();
-console.log(raw.headers.get('X-My-Header'));
-console.log(account.info);
 ```
 
-### Logging
+## Raw response access
 
-> [!IMPORTANT]
-> All log messages are intended for debugging only. The format and content of log messages
-> may change between releases.
-
-#### Log levels
-
-The log level can be configured in two ways:
-
-1. Via the `CADENYA_LOG` environment variable
-2. Using the `logLevel` client option (overrides the environment variable if set)
+Plain methods return an `APIPromise`: awaiting yields the decoded value;
+`.withResponse()` pairs it with the `Response` (status, headers);
+`.asResponse()` — called synchronously, before any `await` — yields the raw
+`Response` with the body UNCONSUMED, so you own reading it:
 
 ```ts
-import Cadenya from '@cadenya/cadenya';
+const { data, response } = await client.accounts.retrieve().withResponse();
+console.log(response.status, response.headers.get('x-request-id'));
 
-const client = new Cadenya({
-  logLevel: 'debug', // Show all log messages
-});
+const raw = await client.accounts.retrieve().asResponse();
+const body = await raw.text();
 ```
 
-Available log levels, from most to least verbose:
-
-- `'debug'` - Show debug messages, info, warnings, and errors
-- `'info'` - Show info messages, warnings, and errors
-- `'warn'` - Show warnings and errors (default)
-- `'error'` - Show only errors
-- `'off'` - Disable all logging
-
-At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
-Some authentication-related headers are redacted, but sensitive data in request and response bodies
-may still be visible.
-
-#### Custom logger
-
-By default, this library logs to `globalThis.console`. You can also provide a custom logger.
-Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
+A dropped (never-awaited) call still cleans up after itself: the response
+is consumed and the request deadline is released automatically.
 
-When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
-below the configured level will not be sent to your logger.
+## Logging
 
 ```ts
-import Cadenya from '@cadenya/cadenya';
-import pino from 'pino';
-
-const logger = pino();
-
-const client = new Cadenya({
-  logger: logger.child({ name: 'Cadenya' }),
-  logLevel: 'debug', // Send all messages to pino, allowing it to filter
-});
+const client = new Cadenya({ logLevel: 'debug' }); // or logger: myLogger
 ```
 
-### 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.
+`'warn'` (default) logs only retries; `'debug'` adds one line per request
+and response (method, path, status, duration); `'off'` silences the SDK.
+Headers and bodies are NEVER logged.
 
-#### Undocumented endpoints
+## Streaming (SSE)
 
-To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.
-Options on the client, such as retries, will be respected when making these requests.
+A stream wraps one HTTP response body, so it can be consumed **once**, with
+one of two views — pick whichever fits and iterate that one:
 
 ```ts
-await client.post('/some/path', {
-  body: { some_prop: 'foo' },
-  query: { some_query_arg: 'bar' },
-});
+// View 1 (normal case): iterate decoded event payloads directly.
+const stream = await client.objectives.streamEvents(objectiveId, params);
+for await (const event of stream) {
+  // event is the typed payload
+}
 ```
 
-#### Undocumented request params
-
-To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
-parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
-send will be sent as-is.
-
 ```ts
-client.objectives.create({
+// View 2 (alternative): stream.events() keeps the SSE metadata envelope,
+// so the payload sits one level deeper: { event, data, id }.
+const envelopes = await client.objectives.streamEvents(objectiveId, params);
+for await (const { data, id } of envelopes.events()) {
   // ...
-  // @ts-expect-error baz is not yet public
-  baz: 'undocumented option',
-});
-```
-
-For requests with the `GET` verb, any extra params will be in the query, all other requests will send the
-extra param in the body.
-
-If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
-options.
-
-#### Undocumented response properties
-
-To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
-the response object, or cast the response object to the requisite type. Like the request params, we do not
-validate or strip extra properties from the response from the API.
-
-### Customizing the fetch client
-
-By default, this library expects a global `fetch` function is defined.
-
-If you want to use a different `fetch` function, you can either polyfill the global:
-
-```ts
-import fetch from 'my-fetch';
-
-globalThis.fetch = fetch;
-```
-
-Or pass it to the client:
-
-```ts
-import Cadenya from '@cadenya/cadenya';
-import fetch from 'my-fetch';
-
-const client = new Cadenya({ fetch });
-```
-
-### Fetch options
-
-If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
-
-```ts
-import Cadenya from '@cadenya/cadenya';
-
-const client = new Cadenya({
-  fetchOptions: {
-    // `RequestInit` options
-  },
-});
+}
 ```
 
-#### Configuring proxies
-
-To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
-options to requests:
-
-**Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
+Streams RECONNECT AUTOMATICALLY on mid-stream transport drops (like
+EventSource): they resume from the last received event id, retry at most 5
+times per outage with backoff (honoring the server's `retry:` hint), and
+reset the budget once events flow again. A clean stream end, `close()`, and
+a caller abort never reconnect; HTTP-level reconnect failures (e.g. expired
+credentials) surface immediately. Opt out with `{ reconnect: false }` in
+request options — then drops raise `APIConnectionError` and you can resume
+manually:
 
 ```ts
-import Cadenya from '@cadenya/cadenya';
-import * as undici from 'undici';
-
-const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
-const client = new Cadenya({
-  fetchOptions: {
-    dispatcher: proxyAgent,
-  },
+const resumed = await client.objectives.streamEvents(objectiveId, params, {
+  lastEventId: stream.lastEventId,
 });
+try {
+  for await (const event of resumed) {
+    // ...
+  }
+} finally {
+  await resumed.close();
+}
 ```
 
-**Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
-
-```ts
-import Cadenya from '@cadenya/cadenya';
-
-const client = new Cadenya({
-  fetchOptions: {
-    proxy: 'http://localhost:8888',
-  },
-});
-```
+Consume (or close) every opened stream — an unconsumed stream holds its
+connection until `close()`.
 
-**Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+## Webhooks (no API key required)
 
 ```ts
-import Cadenya from 'npm:@cadenya/cadenya';
+import { Webhooks } from '@cadenya/cadenya';
 
-const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
-const client = new Cadenya({
-  fetchOptions: {
-    client: httpClient,
-  },
-});
+const webhooks = new Webhooks(process.env.CADENYA_WEBHOOK_SECRET);
+const event = await webhooks.unwrap(payload, request.headers);
 ```
 
-## Frequently Asked Questions
-
-## Semantic versioning
-
-This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
-
-1. Changes that only affect static types, without breaking runtime behavior.
-2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
-3. Changes that we do not expect to impact the vast majority of users in practice.
-
-We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
-
-We are keen for your feedback; please open an [issue](https://www.github.com/cadenya/cadenya-typescript/issues) with questions, bugs, or suggestions.
-
-## Requirements
-
-TypeScript >= 4.9 is supported.
-
-The following runtimes are supported:
-
-- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
-- Deno v1.28.0 or higher.
-- Bun 1.0 or later.
-- Cloudflare Workers.
-- Vercel Edge Runtime.
-- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
-- Nitro v2.6 or greater.
-
-Note that React Native is not supported at this time.
-
-If you are interested in other runtime environments, please open or upvote an issue on GitHub.
+Verification follows Standard Webhooks (24–64 byte decoded secrets,
+integer timestamps, bounded tolerance). This verifies the signature; it is
+not runtime schema validation of the payload shape.
 
-## Contributing
+## Reference
 
-See [the contributing documentation](./CONTRIBUTING.md).
+See [api.md](api.md) for every method signature.