SDK integration

Use an SDK when you want application-level event metadata, explicit capture lifecycle, or a boundary that a transparent TCP proxy cannot interpret. All SDKs ultimately use the versioned DRC HTTP API.

Node.js / TypeScript

The published package metadata is @drc/sdk version 1.0.0. The compatibility package in drc-node is @spinxog/drc.

npm install @drc/sdk

Basic capture and replay:

import { DRCClient } from "@drc/sdk";

const drc = new DRCClient({
  baseURL: process.env.DRC_ENDPOINT!,
  apiKey: process.env.DRC_API_KEY,
});

const execution = await drc.startCapture("checkout", ["release:candidate"], "staging");
await drc.recordEvent(execution.execution_id, {
  execution_id: execution.execution_id,
  event_type: "http_request",
  timestamp: Date.now(),
  data: { method: "GET", path: "/health" },
});

const replay = await drc.startReplay({
  execution_id: execution.execution_id,
  mode: "strict",
});
console.log(replay.job_id, replay.status);

The client also exposes getExecution, getEvents, search, and diff. The compatibility package additionally exposes expressMiddleware, fastifyMiddleware, and databaseMiddleware.

Python

The Python project is drc-sdk and requires Python 3.10 or newer:

python -m pip install drc-sdk

For the repository package with Flask/FastAPI extras:

python -m pip install -e 'drc-python[flask,fastapi]'

Basic capture and replay:

import os
from drc_sdk.client import DRCClient, DRCEvent, ReplayConfig

client = DRCClient(
    base_url=os.environ["DRC_ENDPOINT"],
    api_key=os.environ["DRC_API_KEY"],
)

execution = client.start_capture(
    service_name="checkout",
    tags=["release:candidate"],
    environment="staging",
)
client.record_event(
    execution.execution_id,
    DRCEvent(
        execution_id=execution.execution_id,
        event_type="http_request",
        data={"method": "GET", "path": "/health"},
    ),
)
replay = client.start_replay(
    ReplayConfig(execution_id=execution.execution_id, mode="strict")
)
print(replay.job_id, replay.status)

The Python client exposes get_execution, get_events, search, start_replay, and diff. The drc-python client also provides middleware helpers and convenience capture methods.

Python body privacy

The drc-python client defaults capture_bodies=False. Body capture is opt-in and bounded by max_capture_body_bytes. Headers, URLs, SQL, and error text are redacted or bounded by the client, but review application-specific sensitive fields before enabling capture.

Go

The repository Go module is github.com/spinxog/DRC/sdk/go. It exposes NewClient/NewClientWithError, WithAPIKey, StartCapture, RecordEvent, GetExecution, GetEvents, Search, and StartReplay.

package main

import (
    "context"
    "encoding/json"
    "log"
    "os"

    drc "github.com/spinxog/DRC/sdk/go/drc"
)

func main() {
    client, err := drc.NewClientWithError(
        os.Getenv("DRC_ENDPOINT"),
        drc.WithAPIKey(os.Getenv("DRC_API_KEY")),
    )
    if err != nil {
        log.Fatal(err)
    }

    execution, err := client.StartCapture(context.Background(), "checkout", []string{"release:candidate"})
    if err != nil {
        log.Fatal(err)
    }

    event := drc.DRCEvent{
        EventType: "http_request",
        Data: json.RawMessage(`{"method":"GET","path":"/health"}`),
    }
    if err := client.RecordEvent(context.Background(), execution.ExecutionID, event); err != nil {
        log.Fatal(err)
    }
}

Use NewClientWithError when invalid URLs must fail during startup. Use a context with deadlines for all network calls.

Shared client rules

• Use HTTPS for non-local endpoints.
• Keep API keys outside source control and MCP/project files.
• Treat execution and event IDs as opaque strings; URL-encode them.
• Persist replay job IDs and poll with backoff.
• Respect 1 MiB event-data and bounded metadata contracts.
• Do not interpret a successful HTTP response as a successful application verification; inspect replay status, divergence, completeness, and result semantics.
• Call the deletion API only after checking retention/legal-hold requirements.

Compatibility

Pin package versions in applications and run the SDK test suites against the deployed API version before upgrading. Treat server error codes and documented result fields as the integration contract.