Configuration

All constructors accept a single StructClientConfig object:

import { StructClient } from "@structbuild/sdk";

const client = new StructClient({
  apiKey: "sk_live_xxx",
  timeout: 10_000,
  retry: {
    maxRetries: 3,
    initialDelayMs: 500,
    maxDelayMs: 30_000,
  },
  headers: {
    "X-App-Version": "1.4.0",
  },
  onRequest: ({ method, url }) => console.log(`${method} ${url}`),
  onResponse: ({ status, durationMs }) => console.log(`${status} in ${durationMs}ms`),
});

Options

Option	Type	Default	Description
`apiKey`	`string`	required	Secret (`sk_`) or JWT public key (`pk_jwt_`). Sent as `X-API-Key`.
`jwt`	`string`	(none)	User JWT, sent as `Authorization: Bearer`. Only used with `pk_jwt_*` keys.
`baseUrl`	`string`	`https://api.struct.to/v1`	Override the REST base URL.
`headers`	`Record<string, string>`	(none)	Extra headers merged into every request.
`timeout`	`number`	`30_000`	Per-request timeout in milliseconds. Enforced with `AbortController`.
`retry`	`RetryConfig`	off	Automatic retry on `429` and `5xx`. Disabled when omitted.
`onRequest`	`(info) => void \| Promise<void>`	(none)	Called before every request.
`onResponse`	`(info) => void \| Promise<void>`	(none)	Called after every response.

Retry

Pass a retry block to enable exponential backoff on retryable failures (429, 500, 502, 503, 504, NetworkError, TimeoutError). Retry-After headers on 429 responses are honoured when present.

const client = new StructClient({
  apiKey: "sk_live_xxx",
  retry: {
    maxRetries: 3,
    initialDelayMs: 500,
    maxDelayMs: 10_000,
  },
});

Field	Default	Description
`maxRetries`	`3`	Maximum retry attempts after the initial request.
`initialDelayMs`	`1000`	Base delay, doubled on each attempt.
`maxDelayMs`	`30_000`	Upper bound on the computed delay.

Hooks

onRequest and onResponse fire around every HTTP call and are useful for logging, tracing, and metrics. Hook errors are swallowed so they never break a request.

const client = new StructClient({
  apiKey: "sk_live_xxx",
  onRequest: ({ method, url, headers }) => {
    tracer.start({ method, url });
  },
  onResponse: ({ method, url, status, durationMs, headers }) => {
    tracer.end({ method, url, status, durationMs });
  },
});

Custom base URL

Enterprise customers with a dedicated domain can point the SDK at their own host by overriding baseUrl. Include the /v1 prefix; the SDK does not add it for you.

const client = new StructClient({
  apiKey: "sk_live_xxx",
  baseUrl: "https://api.yourcompany.com/v1",
});

WebSocket configuration

StructWebSocket and StructAlertsWebSocket share a similar config shape, plus reconnect and subscribe-timeout options. See WebSockets for details.

import { StructWebSocket } from "@structbuild/sdk";

const ws = new StructWebSocket({
  apiKey: "sk_live_xxx",
  baseUrl: "wss://api.yourcompany.com",
  subscribeTimeout: 10_000,
  reconnect: {
    maxRetries: 10,
    initialDelayMs: 500,
    maxDelayMs: 30_000,
  },
});

Introduction

REST

Websockets

Advanced

Options

Retry

Hooks

Custom base URL

WebSocket configuration

​Options

​Retry

​Hooks

​Custom base URL

​WebSocket configuration

Options

Retry

Hooks

Custom base URL

WebSocket configuration