Skip to main content
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

npm install @failpath/sdk

​
Quick start

The following example covers the full lifecycle: creating a client, starting a run, and instrumenting two steps inside a checkout handler. 
import { createFailpathClient } from "@failpath/sdk";

// Create a single client instance for your project
const failpath = createFailpathClient({
  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("checkout", {
    runId: requestId,
    metadata: { route: "/checkout" },
  });

  // Wrap each business operation with step()
  const cart = await run.step("validate-cart", async () => {
    return validateCart();
  });

  await run.step("charge-card", async () => {
    return chargeCard(cart);
  });

  // Explicitly skip an optional step
  await run.skip("send-receipt-email");
}
Each step() call sends a running event before your function executes, then sends success or error when it completes. If the wrapped function throws, the SDK records the error and rethrows the original exception so your application error handling remains intact.

​
Feature highlights

TypeScript-first

Full type declarations are included in the package. No separate @types install needed.

Fire-and-forget telemetry

Telemetry sends are non-blocking by default. A failed send never crashes your handler unless you opt in with throwOnSendError.

Automatic error capture

When a wrapped step throws, the SDK records the error event and rethrows the original error — no extra try/catch required.

Skip support

Use run.skip() to mark a step as intentionally skipped, keeping your flow trace complete even when a branch is not taken.

Rich metadata

Attach arbitrary metadata at the client, run, or step level. Client-level defaultMetadata is merged into every event automatically.

Custom fetch

Supply your own fetch implementation for runtimes that lack a native one, such as older Node.js versions or edge environments.

​
Explore the SDK

Client

Configure createFailpathClient() with your project key, metadata defaults, and error handling options.

Runs & Steps

Learn how to start a run, instrument steps, skip branches, and record events manually.

Options

Full reference for every configuration option across the client, run, step, and recordStep APIs.