cartesia-ai/cartesia-js

1. Overall shape

- This is a generated TypeScript SDK for the Cartesia API, not an application server.

- The public entrypoint is src/index.ts, which exposes a Cartesia client, resource namespaces, shared types, and helpers like toFile.

- The SDK targets multiple runtimes via a fetch-first design: browser, Node, Deno, Bun, and edge environments.

2. Primary architectural flow

- Consumer code instantiates Cartesia from src/client.ts.

- A resource method such as client.tts.generate() or client.voices.list() builds a request, sends it through the client’s transport layer, and returns an APIPromise.

- That promise can be awaited for parsed data, or inspected as a raw Response through helpers like .asResponse() and .withResponse().

3. Resource layer: API surface by domain

- src/resources/ is the main API mapping layer and mirrors Cartesia product areas: tts, stt, voices, voice-changer, datasets, agents, fine-tunes, pronunciation-dicts, and access-token.

- Each domain is split into endpoint-specific modules and index files, so architecture diagrams should show a resource namespace tree underneath the client.

- src/resources/top-level.ts and src/resources/shared.ts provide common request/response shapes reused across domains.

4. Core abstractions

- src/core/ contains the reusable SDK primitives:

- resource.ts for base resource behavior

- api-promise.ts for lazy response handling

- pagination.ts for auto-pagination

- streaming.ts for streamed responses

- uploads.ts for file upload handling

- EventEmitter.ts for event-driven flows

- These abstractions are the backbone underneath the generated resource methods, keeping the domain modules thin.

5. HTTP transport and request construction

- src/client.ts and src/internal/request-options.ts coordinate request options like retries, timeout, headers, fetch overrides, and logging.

- src/internal/headers.ts, src/internal/qs/, src/internal/parse.ts, and src/internal/utils/ handle request serialization: query strings, headers, base64, UUIDs, sleep/backoff, and environment detection.

- The library assumes a global fetch by default but allows a custom fetch implementation or runtime-specific proxy/client settings.

6. Response handling, pagination, and errors

- Parsing and error mapping are centralized in src/internal/errors.ts, src/error.ts, and src/core/error.ts.

- Non-2xx responses become typed API errors, while connection failures and timeouts become connection-specific errors.

- Pagination is abstracted so list endpoints can be consumed either page-by-page or via async iteration across pages.

7. File upload subsystem

- Upload support is split across src/core/uploads.ts, src/uploads.ts, src/internal/uploads.ts, and src/internal/to-file.ts.

- The SDK accepts several upload forms: web File, fetch Response, Node streams, or converted binary data.

- This is especially important for dataset file endpoints, where upload handling affects both request shape and runtime compatibility.

8. Realtime/websocket subsystem

- Realtime speech features use a separate websocket path in src/internal/ws.ts, src/internal/ws-adapter-browser.ts, src/internal/ws-adapter-node.ts, and src/internal/lib/tts/ws.ts.

- STT and TTS each have dedicated websocket-oriented resource trees under src/resources/stt/ and src/resources/tts/.

- The STT side is further split into auto-finalize and manual-finalize flows, indicating different session lifecycles and completion semantics.

9. Backwards compatibility layer

- src/backcompat/ contains wrappers and adapters for older shapes of the public API.

- Files like tts-wrapper.ts, voices-wrapper.ts, voice-changer-wrapper.ts, and types.ts suggest the SDK preserves older method signatures or object shapes while routing to the newer resource model.

- This layer sits between the main public export surface and the newer generated resource structure.

10. Platform and runtime shims

- src/internal/shims.ts, shim-types.ts, and detect-platform.ts provide runtime-specific branching.

- These abstractions matter because the SDK must work across browser, Node, Bun, Deno, and edge runtimes without depending on Node-only APIs.

- The websocket adapter split is the clearest sign that runtime differences are treated as a first-class architectural boundary.

11. Testing strategy

- tests/ mirrors the source layout, with dedicated tests for API resources, internals, query-string behavior, uploads, streaming, websocket behavior, and helper utilities.

- The structure suggests the repo is validated both at the contract level, for generated endpoints, and at the utility level, for cross-runtime helpers.

- This mirrors the SDK architecture: transport, parsing, and domain resources are all independently exercised.

12. Build, release, and repository tooling

- scripts/ contains formatting, linting, test, build, and packaging helpers; bin/publish-npm and GitHub workflows handle release publication.

- The project uses TypeScript build configs, Jest, ESLint, Prettier, and release automation via Release Please and CI workflows.

- api.md is the generated API reference, reinforcing that the repository is source-first but documentation-driven.

13. Examples and integration points

- examples/node_examples.ts and examples/nextjs/ show how the SDK is consumed in Node and a React/Next.js environment.

- The Next.js example includes an API route, which demonstrates server-side token usage rather than a browser-only integration.

- These examples are useful for diagramming the “consumer side” of the architecture: app code calls the SDK, the SDK calls Cartesia’s REST or realtime endpoints.

14. High-level diagram boundary

- The main external boundary is the Cartesia API itself, accessed over HTTP and websocket connections.

- Internally, the SDK is organized as: public client → resource namespaces → core abstractions → internal transport/serialization/runtime helpers.

- Backcompat and runtime adapters sit at the edges, while generated resources and shared core utilities form the center of the system.