> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prodbreak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK

> The control client: connect to a world and drive it. JavaScript/TypeScript first; Python mirrors it.

The SDK is a thin, typed wrapper over the [HTTP API](/reference/wire). In tests you get a `Sandbox`
handle from your plugin; you can also `connect` to one directly. Examples are TypeScript; the Python
SDK mirrors them one-for-one in `snake_case`.

```ts theme={null}
import { prodbreak } from "@prod-break/sdk";

const sandbox = await prodbreak.connect({
  url: process.env.PRODBREAK_URL!,
  key: process.env.PRODBREAK_KEY!,
});
```

## The `Sandbox` handle

| Member                | Signature                 | What it does                                            |
| --------------------- | ------------------------- | ------------------------------------------------------- |
| `seed`                | `seed(resource, objects)` | Silent insert of history. [Guide](/guides/seed-history) |
| `reset`               | `reset({ t0? })`          | Empty state, rewind clock to t0.                        |
| `state`               | `state(resource?)`        | Introspect the world (debug aid).                       |
| `client`              | `client<T>()`             | The vendor SDK, base-URL repointed at this world.       |
| `lastResolutionTrace` | `lastResolutionTrace()`   | Why the last call's fields resolved as they did.        |
| `faults`              | —                         | Force outcomes. ↓                                       |
| `world`               | —                         | Trigger external causes. ↓                              |
| `clock`               | —                         | Advance time. ↓                                         |
| `webhooks`            | —                         | Register endpoints, run a sink. ↓                       |
| `exogenous`           | —                         | Pin out-of-control values. ↓                            |

## `sandbox.faults`

```ts theme={null}
sandbox.faults.arm(resource, operation, {
  status: number, code: string, message?: string,
  count?: number,                                  // omit = until cleared
  match?: { input?: object, credential_id?: string },
});
sandbox.faults.clear(id?);                          // one by id, or all
```

[Guide: Force an error →](/guides/force-an-error)

## `sandbox.world`

```ts theme={null}
sandbox.world.trigger(event, data?);   // fire an external cause; 409 if its precondition fails
sandbox.world.next();                  // the live "what can happen next" set
```

[Concept: Causes, not effects →](/concepts/causes-not-effects)

## `sandbox.clock`

```ts theme={null}
sandbox.clock.advance("5s");                       // due events fire in order, before this resolves
sandbox.clock.setDurations({ run_settle: "0s" });  // collapse named durations for deterministic CI
```

[Concept: The virtual clock →](/concepts/clock)

## `sandbox.webhooks`

```ts theme={null}
const inbox = await sandbox.webhooks.sink();        // local HTTP receiver: { url, secret, waitFor, all }
sandbox.webhooks.register(url, { subscribe: [...] }); // → { id, secret }
sandbox.webhooks.unregister(id);
```

[Guide: Test a webhook →](/guides/test-a-webhook)

## `sandbox.exogenous`

```ts theme={null}
sandbox.exogenous.pin(match, field_path, value);   // result-keyed override
sandbox.exogenous.on(event, field_path, value);    // event-name sugar → same pin
sandbox.exogenous.clear(id);
```

`match` is `{ operation, resource?, credential_id?, source_id?, input? }`. Most-specific match wins;
setting a faithful field is rejected. The same surface selects a [forceable
branch](/concepts/branching).

[Concept: Setting values & the trace →](/concepts/pins-and-trace)

<Note>
  Surface omitted from the MVP, by design: sequenced values ("tapes"), freeze/step clock verbs,
  `replay` seeding. They're reserved in the HTTP contract so the SDK grows into them without breaking v1.
</Note>