Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .github/workflows/sdk-client-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,8 @@ jobs:
fail-fast: false
matrix:
caido-version:
- 0.56.0
- 0.57.0
- 0.58.0
- 0.59.0

services:
caido:
Expand Down
5 changes: 4 additions & 1 deletion knip.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,10 @@ const config: KnipConfig = {
"packages/sdk-client": {
project: ["src/**/*.ts!", "tests/**/*.ts!"],
ignore: ["src/**/__generated__/**"],
ignoreDependencies: ["@caido/schema-proxy", "@caido/schema-proxy-v0.56"],
ignoreDependencies: [
"@caido/schema-proxy",
"@caido/schema-proxy-v0.58",
],
},
"packages/server-auth": {
project: ["src/**/*.ts!"],
Expand Down
41 changes: 41 additions & 0 deletions packages/sdk-client/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Releases before 0.6.0 predate this file.

## Unreleased

## [0.6.0] - 2026-11-03

### Breaking Changes

- The minimum supported Caido version is now 0.58.0. The bundled 0.56 and 0.57 transport forks are gone, and `latest` targets 0.59.0.
- AI provider credentials moved out of `instance.settings` into their own `instance.ai` SDK. `InstanceSettings.ai` and the `ai` group of `instance.settings.set()` are removed. Caido 0.59.0 replaced the four fixed providers with a named-provider API, which `instance.ai` reports as unsupported rather than writing to the old shape.
- `replay.sessions.createPipeline()` is folded into `replay.sessions.create({ kind: "HTTP_PIPELINE", … })`.
- `ReplaySessionHttpOnePipeline` and `ReplayEntryHttpOnePipeline` are now `ReplaySessionPipeline` and `ReplayEntryPipeline`. The session kind is `HTTP_PIPELINE` on every supported instance; 0.58's `HTTP_ONE_PIPELINE` is mapped on the wire.
- `CreateRequestOptions.source` takes the `Source` union instead of a `string`. `alteration`, `parentId` and `response` are removed, because no supported schema accepts them on `createRequest`.
- `ReplayWsMessage.editIds` is replaced by `edits`, which carries `{ id, alteration }` per revision, and `alteration` is the `Alteration` union rather than a `string`.
- `ReplayRequestSource.raw` is now encoded by the SDK, so it takes the request bytes rather than base64. Callers that were base64-encoding it themselves must stop.
- `ReplaySessionSDK` no longer takes a `ReplayEntrySDK`; sessions reach their entries through the session SDK itself.
- `ReplaySessionSDK.setActiveEntry()` and `ReplaySession.setActiveEntry()` return the updated session instead of `void`, and no longer re-read it.

### Added

- WebSocket replay sessions: `replay.startWs()`, `replay.watchWs()`, `ReplayWsTask.sendMessage()`, `.sendDraft()` and `.stop()`, and `ReplayEntryWs` carrying the handshake, the exchanged messages, the stream and the pending draft.
- Pipeline replay sessions and entries, with `PipelineStrategy` covering sequential, last-byte-synchronization and single-packet-attack dispatch.
- `ReplaySessionUnknown` and `ReplayEntryUnknown`, so a session kind this SDK does not model stays listable instead of throwing.
- Const enums for `ReplaySessionKind`, `PipelineStrategyKind`, `FailureBehavior`, `StreamMessageDirection`, `StreamWsMessageFormat`, `Alteration` and `Source`.
- `ReplaySessionSDK.entriesOf(sessionId)`, and `ReplaySession.entries()` on every session kind.
- `stripHttp2ConnectionHeaders` on replay session settings (Caido 0.59.0).

### Fixed

- `request.create()` selected `error` and `request` on `CreateRequestPayload`, which has only ever held `id` and `responseId`, so the call failed against every release.
- The DNS rewrite document named `DnsRewrite`, `DnsIpResolver` and `CreateDnsRewriteInput`, which no schema since 0.55.3 defines, so `dnsRewrite.create()` could not validate.
- `encodeBlob()` threw on any code point above U+00FF and could overflow the stack on large payloads.
- `replay.sessions.create()` sent `requestSource.raw` unencoded, which the `Blob` scalar rejects, so seeding a session from raw bytes never worked ([#37](https://github.com/caido/sdk-js/issues/37)).
- A failed `/health` probe is no longer cached forever, so `Version` can resolve once the instance recovers.
Original file line number Diff line number Diff line change
@@ -1,28 +1,28 @@
schema: ./node_modules/@caido/schema-proxy-v0.56/schema.graphql
schema: ./node_modules/@caido/schema-proxy-v0.58/schema.graphql
documents:
- ./src/transport/v0.56/documents/*.graphql
- ./src/transport/v0.58/documents/*.graphql
- ./src/transport/latest/documents/connectionInfo.graphql
- ./src/transport/latest/documents/request.graphql
- ./src/transport/latest/documents/range.graphql
- ./src/transport/latest/documents/errors.graphql
- ./src/transport/latest/documents/range.graphql
- ./src/transport/latest/documents/request.graphql
- ./src/transport/latest/documents/task.graphql

generates:
./src/transport/v0.56/__generated__/enums.ts:
./src/transport/v0.58/__generated__/enums.ts:
plugins:
- typescript
config:
namingConvention:
typeNames: keep
onlyEnums: true

./src/transport/v0.56/__generated__/types.ts:
./src/transport/v0.58/__generated__/types.ts:
plugins:
- typescript
config:
enumValues: './enums.js'

./src/transport/v0.56/__generated__/:
./src/transport/v0.58/__generated__/:
plugins:
- typescript-operations
- typed-document-node
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ The SDK must talk to Caido instances running different releases. GraphQL schema
## Rules for contributors and agents

1. **Canonical transport lives in `transport/latest/`** — documents, `__generated__/`, and `convert/` for the current schema. This is the default path for every operation.
2. **Overrides are additive** — when an operation **shape** differs on an older instance (removed/renamed fields, new required arguments, union/interface refactors), add `transport/v0.XX/documents/<op>.graphql` and a hand-written codegen config against the matching npm schema alias. Do **not** add per-SDK-class convert files under `transport/`.
2. **Overrides are additive** — when an operation **shape** differs on an older instance (removed/renamed fields, new required arguments, union/interface refactors), add `transport/v0.XX/documents/<op>.graphql` and a hand-written codegen config against the matching npm schema alias. Drop a fork once the release it serves is out of support. Do **not** add per-SDK-class convert files under `transport/`.
3. **`convert/` is for shared wire primitives only** — blob decoding, connection info, request/response shapes, pagination, etc. SDK entity classes (`ReplayEntry`, `ReplaySession`, …) map their own wire fragments inside the class constructor. No `Mapped*` intermediate types and no `transport/*/convert/<entity>.ts` files.
4. **Additive input fields do not require overrides** — when a schema release only adds optional or new input fields (e.g. `global` on `CreateFilterPresetInput`), keep the canonical document and pass the new field from the SDK. Older instances ignore unknown input fields; do not fork the operation or branch on version for that field alone.
5. **Branch with `await version.gte(TransportVersion.X_Y_Z)`** — each override is guarded by an explicit semver threshold from `TransportVersion` in `types/versioned.ts`. Canonical transport is the `if` branch at the introducing threshold; older transport is the `else` path. Use `if`/`else` blocks — not a derived schema string or secondary version comparison.
6. **`TransportVersion` identifies bundled forks** — a const object of full semver strings (`"0.56.0"`, `"0.57.0"`, …). Never use prefixed aliases like `"v0.56"` or a separate `"latest"` label. Add a new key when a new override fork is introduced.
6. **`TransportVersion` identifies bundled forks** — a const object of full semver strings (`"0.58.0"`, `"0.59.0"`, …). Never use prefixed aliases like `"v0.58"` or a separate `"latest"` label. Add a key when a fork is introduced, and remove it when the fork is dropped.
7. **Wrap wire fragments in `Versioned`** — call sites pass `versioned(TransportVersion.X_Y_Z, fragment)` into SDK entity constructors. Define a `VersionedOf<{ [TransportVersion.X]: LatestFragment; [TransportVersion.Y]: V0Fragment }>` alias per entity. The constructor `switch`es on `fragment.version` and assigns public fields directly from `fragment.data`. Reuse generated fragment types for field types where possible (e.g. `V056ReplayEntryFullFragment["settings"]`).
8. **`Version` is exported** — readonly handle with `Version.of(semver)` for seeded version (no fetch) and lazy resolution via shared `RestClient` otherwise. `await version.get()` and `await version.gte(...)` are async.
9. **Shared wire clients** — `GraphQLClient` and `RestClient` are shared by the client and all SDKs. They are not forked per schema version.
Expand All @@ -27,7 +27,7 @@ src/
documents/*.graphql
__generated__/
convert/ ← shared primitives only (blob, network, request, …)
v0.56/ ← only when an operation diverges
v0.58/ ← only when an operation diverges
documents/replay.graphql
__generated__/replay.ts
types/
Expand All @@ -38,8 +38,9 @@ src/

## Build

- Install older schemas via npm aliases: `"@caido/schema-proxy-v0.56": "npm:@caido/schema-proxy@0.56.0"`.
- Hand-written `codegen.v0.56.yml` per override version; latest uses `codegen.yml`.
- Install older schemas via npm aliases: `"@caido/schema-proxy-v0.58": "npm:@caido/schema-proxy@0.58.3"`.
- Hand-written `codegen.v0.58.yml` per override version; latest uses `codegen.yml`.
- Pin the alias to the **last patch** of the release line. Some `@caido/schema-proxy` patch versions were published from a release candidate and do not match the image of the same tag; verify against `proxy-backend`'s `schema.graphql` at that git tag before pinning.
- Override documents codegen independently against their version's schema — not merged with canonical.

## Considered options
Expand Down
21 changes: 21 additions & 0 deletions packages/sdk-client/docs/adr/0003-one-method-many-interfaces.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# One method, many interfaces

When an SDK operation has variants, it is a single method with overloaded signatures discriminated by a field on the options object, not one method per variant. `WorkflowSDK.test` is the reference implementation: one `test(options)` with `kind: "convert" | "passive" | "active"`, three overloads, and one `switch` in the body.

## Rules for contributors and agents

1. **Overload, do not multiply methods** — `create(options)` with a `kind` discriminator, never `create()` plus `createPipeline()` plus `createWs()`. A reader finds one entry point and the type system picks the right return.
2. **Discriminate on a field the caller already sets** — reuse the schema's own notion of variant (`kind`, `source`, `strategy`) rather than inventing a parallel one.
3. **Give each variant its own options type** — `CreateReplaySessionHttpOptions`, `CreateReplaySessionWsOptions`, … and a union alias for the implementation signature. Each overload names one variant type and one return type.
4. **The implementation signature is not public** — it takes the union and returns the union; only the overloads above it are what consumers see. Keep a final `(options: Union): Promise<Union>` overload when callers legitimately hold an undiscriminated value.
5. **One `switch` on the discriminator** — the body dispatches once, at the top. Per-variant work goes in private methods, not in a second dispatch.

## Considered options

- **A method per variant** — rejected: the surface grows with every schema variant, related operations drift apart, and consumers have to know which name maps to which kind.
- **A single untyped method** — rejected: callers lose the return narrowing that makes the discriminator worth having.

## Consequences

- Adding a replay session kind means adding an options type, an overload and a `case`, not a new public method.
- Variants that an instance is too old to serve fail inside the single method, so the version check lives in one place.
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# SDKs are injected, never constructed in a method

SDK classes are wired once, in a constructor, and passed down. No method body calls `new SomeSDK(...)`.

## Rules for contributors and agents

1. **Build the graph at the root** — `Client` constructs the top-level SDKs, each top-level SDK constructs its sub-SDKs. `ReplaySDK` owns the single `ReplayEntrySDK` and the single `ReplaySessionSDK`.
2. **Entities hold a reference to the SDK that produced them** — `ReplaySession` takes a `ReplaySessionSDK` and delegates `setActiveEntry` and `entries` to it. It does not rebuild one to call itself.
3. **Never `new` an SDK inside a method** — a fresh SDK duplicates transport state, hides its dependencies from the constructor signature, and makes the wiring impossible to see from the root.
4. **Optional constructor parameters are not an escape hatch** — `entrySdk?: ReplayEntrySDK` with a `?? new ReplayEntrySDK(...)` fallback is the same violation with a default. Make the dependency required.
5. **Data classes take no clients they do not use** — `ReplayEntry` reads from a fragment and exposes fields, so it holds no `GraphQLClient`. Only handles that make further calls (`Task`, `ReplaySession`) hold one.

## Considered options

- **Construct on demand** — rejected: it looks cheap, but every call site then decides which transport the new SDK talks over, and a version-resolution cache is rebuilt per call.
- **A service locator** — rejected: it hides the same dependencies behind a lookup instead of a constructor parameter.

## Consequences

- A new SDK dependency is a constructor parameter, which makes the cost of adding it visible in the diff.
- Entities are cheap to build, because the expensive wiring is shared with the SDK that produced them.
22 changes: 22 additions & 0 deletions packages/sdk-client/docs/adr/0005-user-facing-documentation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Documentation comments address users, not maintainers

A JSDoc comment on a public SDK symbol tells a consumer what to pass and what they get back. Schema history, transport forks and the reasoning behind an implementation belong in code comments, ADRs or the changelog.

## Rules for contributors and agents

1. **Record availability as `Added in: Caido vX.Y.Z`** — one line, the way Node documents its own API. Not a sentence about which releases renamed what.
2. **No release archaeology in JSDoc** — "supported only on 0.58.x because the types were renamed in 0.59.0" is maintainer context. The user needs "Added in: Caido v0.58.0"; the SDK handles the rest.
3. **Document the parameters and the result** — `@param` for each option that is not obvious, `@returns` for what comes back, `@example` where a call is worth seeing.
4. **Per-option behaviour lives on the option type's field**, not in the method's JSDoc, so it shows up wherever that type is used.
5. **Explain implementation choices in a normal comment**, next to the code that needs explaining, and keep it to what a reader cannot infer. A comment that restates the line below it is noise.
6. **No generated-sounding prose** — no "comprehensive", "robust", "seamless". Say what the thing does.

## Considered options

- **Document every version threshold in JSDoc** — rejected: consumers read the SDK surface, not its compatibility matrix, and the prose goes stale at every release.
- **Drop availability notes entirely** — rejected: a consumer on an older instance needs to know why a method throws.

## Consequences

- The generated reference documentation reads as an API reference rather than a changelog.
- When a fork is dropped, the JSDoc does not need rewriting: `Added in:` stays true forever.
11 changes: 6 additions & 5 deletions packages/sdk-client/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@caido/sdk-client",
"version": "0.5.2",
"version": "0.6.0",
"description": "Client SDK for interacting with a Caido instance",
"author": "Caido Labs Inc. <dev@caido.io>",
"repository": "https://github.com/caido/sdk-js/",
Expand All @@ -22,13 +22,14 @@
}
},
"files": [
"dist/*"
"dist/*",
"CHANGELOG.md"
],
"scripts": {
"build": "tsdown",
"typecheck": "tsc --noEmit",
"generate": "pnpm generate:graphql && pnpm generate:rest",
"generate:graphql": "graphql-codegen --config codegen.v0.56.yml && graphql-codegen --config codegen.yml",
"generate:graphql": "graphql-codegen --config codegen.v0.58.yml && graphql-codegen --config codegen.yml",
"generate:rest": "openapi-ts",
"test": "vitest run",
"test:unit": "vitest run --project unit"
Expand All @@ -46,8 +47,8 @@
"zod": "^4.3.0"
},
"devDependencies": {
"@caido/schema-proxy": "0.57.0",
"@caido/schema-proxy-v0.56": "npm:@caido/schema-proxy@0.56.0",
"@caido/schema-proxy": "0.59.1",
"@caido/schema-proxy-v0.58": "npm:@caido/schema-proxy@0.58.3",
"@graphql-codegen/cli": "5.0.3",
"@graphql-codegen/near-operation-file-preset": "3.0.0",
"@graphql-codegen/typed-document-node": "5.0.11",
Expand Down
2 changes: 1 addition & 1 deletion packages/sdk-client/src/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ export class Client {
this.dnsUpstream = new DNSUpstreamSDK(this.graphql);
this.dnsRewrite = new DNSRewriteSDK(this.graphql);
this.hostedFile = new HostedFileSDK(this.graphql);
this.instance = new InstanceSDK(this.graphql);
this.instance = new InstanceSDK(this.graphql, this.version);
this.finding = new FindingSDK(this.graphql);
this.request = new RequestSDK(this.graphql);
this.workflow = new WorkflowSDK(this.graphql);
Expand Down
Loading
Loading