@waitstate/sdk

Official JavaScript/TypeScript SDK for WaitState - adaptive gating that adds fleet-wide traffic intelligence on top of your existing infrastructure.

Install

npm install @waitstate/sdk

Quick start

import { WaitState } from '@waitstate/sdk';

const ws = new WaitState({
  publishKey: process.env.WAITSTATE_PUBLISH_KEY,
  secretKey: process.env.WAITSTATE_SECRET_KEY,
});

// Synchronous, in-memory, zero network calls on the hot path
const decision = ws.gate('free', 1);

if (!decision.allowed) {
  res.status(429).json({ error: 'rate_limited' });
  return;
}

// Flush on shutdown
process.on('SIGTERM', async () => {
  await ws.shutdown();
  process.exit(0);
});

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | publishKey | string | | Required. From the dashboard. | | secretKey | string | | Required. Store in env vars. | | siteId | string | orgId | Shard key for DO routing. Isolates sites within one org. | | instanceId | string | randomUUID() | Identifies this instance in telemetry. | | pulseInterval | number | 5000 | Initial pulse interval (ms). Server can override. | | safeModeStrategy | string | 'open' | Behavior when lease expires: 'open', 'fixed_rps', or 'last_policy'. Auto-selects 'fixed_rps' if safeModeMaxRps is explicitly set. | | safeModeMaxRps | number | 50 | Max requests/sec in fixed_rps safe mode. | | baseUrl | string | https://api.waitstate.io | Control plane URL. | | onError | function | | Error callback for init/pulse/auth failures. |

How it works

• gate() reads from an in-memory policy cache - synchronous, sub-millisecond.
• The SDK sends health telemetry (pulses) to the control plane on a background timer.
• The control plane evaluates reflex rules and returns an updated policy.
• If the control plane is unreachable, the SDK fails open (allowed: true).
• If the lease expires, the SDK enters safe mode — behavior depends on safeModeStrategy: 'open' (default, allow all), 'fixed_rps' (cap to safeModeMaxRps), or 'last_policy'.
• Zero production dependencies.

Middleware

Drop-in middleware for popular frameworks. Each sub-path export gates requests automatically.

// Express
import { createMiddleware } from '@waitstate/sdk/express';
app.use(createMiddleware({ waitstate: ws, tagFrom: 'x-api-tier' }));

// Fastify
import { createPlugin } from '@waitstate/sdk/fastify';
fastify.register(createPlugin({ waitstate: ws }));

// Hono
import { createMiddleware } from '@waitstate/sdk/hono';
app.use(createMiddleware({ waitstate: ws }));

// Next.js (route handler wrapper)
import { withGate } from '@waitstate/sdk/nextjs';
export const GET = withGate({ waitstate: ws }, async (req) => {
  return Response.json({ ok: true });
});

| Option | Type | Default | Description | |--------|------|---------|-------------| | waitstate | WaitState | | Required. Your SDK instance. | | tagFrom | string | function | | Header name or (req) => string to extract the tag. | | weightFrom | string | function | | Header name or (req) => number to extract the weight. | | retryAfter | number | | Retry-After header value (seconds) on 429 responses. | | onDenied | function | | Custom handler for denied requests. |

Telemetry helpers

// Track latency for a tag
ws.reportLatency(123, 'checkout');

// Track errors for a tag
ws.reportError('checkout');

// Convenience timer
const stop = ws.startTimer('checkout');
await doWork();
stop(); // automatically reports latency

Documentation

Full docs, API reference, and reflex rule guides: waitstate.io/docs

License

Apache 2.0