> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trace-db.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trace-db.com/_mcp/server.

# SDKs

TraceDB v0.1.1 uses standalone SDK repositories and Fern pull-request
generation. SDK repos keep their package identity, registry workflows, legal
files, README ownership, and release configuration; generated client changes
flow through Fern PRs and Fern Replay patches when intentional edits inside
generated files are needed.

Public package promotion waits for v1. Until then, the v0.1.x package names and
install snippets below are for invited/private alpha access, not a public
registry availability claim.

## Packages

| Language                | Package        | Private alpha install            |
| ----------------------- | -------------- | -------------------------------- |
| TypeScript / JavaScript | `@tracedb/sdk` | `npm install @tracedb/sdk@0.1.1` |
| Python                  | `tracedb`      | `pip install tracedb==0.1.1`     |
| Rust                    | `tracedb-sdk`  | `tracedb-sdk = "0.1.1"`          |

Each SDK targets the same HTTP `/v1` contract. When a generated SDK exposes
operation names that differ from a hand-written wrapper or older README, the
current OpenAPI operation shape is the authoritative contract; the staged v0.1.1
package version is only an artifact identifier and tracking receipt.

`tracedb-go` is reserved as the future Go SDK repository, but it is not a
supported Hosted Alpha SDK surface until its repository README, registry
receipts, and `platform-contract-v0` surface list all agree.

## Generation Posture

* Fern generation stays in `pull-request` mode.
* SDK repositories use `.fernignore` to preserve repo-owned files such as
  READMEs, release workflows, lockfiles, legal files, and package config.
* Fern Replay is the preferred way to carry intentional edits inside generated
  files.
* Local agents do not run Fern generation, package dry-runs, local builds, or
  local test suites on this workstation. CircleCI and registry workflows own
  heavy validation.

## Runtime Contract

The HTTP contract defines bearer-token authentication, optional hosted routing
metadata, standard `{ "error": string, "code"?: string }` JSON errors, GraphQL
`data` / `errors` envelopes, read-only safe retry boundaries, and keyed
idempotency retry boundaries.

The supported higher-level SDK wrappers document their route-aware retry
behavior in their owning repositories. Raw generated transports may expose
transport-level retry knobs before a wrapper has classified a request. For
write/admin calls where idempotency matters, set generated-client retry counts
such as `maxRetries` / `max_retries` to `0`, or use a documented wrapper method
whose README has route-aware retry evidence for that call.

Use [Quickstarts](/start/quickstarts) for private alpha package access and
environment setup, and [Idempotency and Retries](/operations/idempotency-and-retries)
for retry boundaries.