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

# Failpath SDK: Instrument Your Backend in TypeScript

> The @failpath/sdk package lets you wrap backend functions with step instrumentation, automatically recording success and error events for your flows.

The Failpath SDK gives you a lightweight, TypeScript-first way to instrument your backend flows. Wrap any async operation with `step()` and the SDK automatically fires `running`, `success`, and `error` events to Failpath — no manual try/catch bookkeeping required. You keep full control over your business logic; the SDK handles the telemetry.

## Installation

<CodeGroup>
  ```bash npm theme={"dark"}
  npm install @failpath/sdk
  ```

  ```bash yarn theme={"dark"}
  yarn add @failpath/sdk
  ```

  ```bash pnpm theme={"dark"}
  pnpm add @failpath/sdk
  ```

  ```bash bun theme={"dark"}
  bun add @failpath/sdk
  ```
</CodeGroup>

## Quick start

The following example covers the full lifecycle: creating a client, starting a run, and instrumenting two steps inside a checkout handler.

```typescript theme={"dark"}
import { createTypedFailpathClient, failpathFlows } from "../.failpath/sdk";

// Create a single client instance for your project
const failpath = createTypedFailpathClient({
  projectKey: process.env.FAILPATH_PROJECT_KEY!,
  defaultMetadata: { env: "production" },
});

export async function handleCheckout(requestId: string) {
  // Start a run — reuse one runId for every step in the same request
  const run = failpath.run(failpathFlows.checkout.slug, {
    runId: requestId,
    metadata: { route: "/checkout" },
  });

  // Wrap each business operation with step()
  const cart = await run.step(failpathFlows.checkout.steps.validateCart, async () => {
    return validateCart();
  });

  await run.step(failpathFlows.checkout.steps.chargeCard, async () => {
    return chargeCard(cart);
  });

  // Explicitly skip an optional step
  await run.skip(failpathFlows.checkout.steps.sendReceiptEmail);

  // Drain queued telemetry before the request or process ends
  await failpath.flush();
}
```

Each `step()` call queues a `running` event before your function executes, then queues `success` or `error` when it completes. Telemetry sends in the background by default, so instrumentation does not add network latency to your request path. Call `failpath.flush()` before a short-lived process exits, or at the end of a serverless request when your runtime does not provide a `waitUntil` hook.

If the wrapped function throws, the SDK records the error and rethrows the original exception so your application error handling remains intact.

## Feature highlights

<CardGroup cols={2}>
  <Card title="TypeScript-first" icon="code">
    Full type declarations are included in the package, and `.failpath/sdk.ts` gives you typed flow slugs and step keys.
  </Card>

  <Card title="Background telemetry" icon="bolt">
    Telemetry sends run in the background by default. Use `flush()` or a runtime `waitUntil` hook when you need deterministic delivery.
  </Card>

  <Card title="Automatic error capture" icon="circle-exclamation">
    When a wrapped step throws, the SDK records the error event and rethrows the original error — no extra try/catch required.
  </Card>

  <Card title="Skip support" icon="forward">
    Use `run.skip()` to mark a step as intentionally skipped, keeping your flow trace complete even when a branch is not taken.
  </Card>

  <Card title="Rich metadata" icon="tag">
    Attach arbitrary metadata at the client, run, or step level. Client-level `defaultMetadata` is merged into every event automatically.
  </Card>

  <Card title="Custom fetch" icon="plug">
    Supply your own `fetch` implementation for runtimes that lack a native one, such as older Node.js versions or edge environments.
  </Card>

  <Card title="Test helper" icon="test-tube">
    Import `createMockFailpathClient()` from `@failpath/sdk/testing` to capture events in automated tests without network calls.
  </Card>
</CardGroup>

## Explore the SDK

<CardGroup cols={3}>
  <Card title="Client" icon="wrench" href="/sdk/client">
    Configure the typed or base client with your project key, metadata defaults, and error handling options.
  </Card>

  <Card title="Typed Keys" icon="braces" href="/sdk/typed-keys">
    Generate `.failpath/sdk.ts` and use autocomplete for flow slugs and step keys.
  </Card>

  <Card title="Runs & Steps" icon="list-check" href="/sdk/runs-and-steps">
    Learn how to start a run, instrument steps, skip branches, and record events manually.
  </Card>

  <Card title="Testing" icon="test-tube" href="/sdk/testing">
    Use the mock client to assert emitted events in unit and integration tests.
  </Card>

  <Card title="Options" icon="sliders" href="/sdk/options">
    Full reference for every configuration option across the client, run, step, and `recordStep` APIs.
  </Card>
</CardGroup>