Build

Use the TypeScript client from server code

Configure one explicit environment, emit typed events, and inspect API failures without hiding the request boundary.

Prerequisites

Node.js 22 or newer and globalThis.fetch, or a supplied fetch implementation
@useeventstack/sdk installed in a server-side package
An organization API key and organization identifier
A registered event contract for the type and schema version you will emit

npm install @useeventstack/sdk

Working flow

Configure and emit

import {
  UseEventStackApiError,
  UseEventStackClient,
  type UseEventStackEnvironment,
} from '@useeventstack/sdk';

function requiredEnv(name: 'USEEVENTSTACK_API_KEY' | 'USEEVENTSTACK_ORGANIZATION_ID'): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

const environment: UseEventStackEnvironment = 'sandbox';
const useeventstack = new UseEventStackClient({
  apiKey: requiredEnv('USEEVENTSTACK_API_KEY'),
  organizationId: requiredEnv('USEEVENTSTACK_ORGANIZATION_ID'),
  baseUrl: process.env.USEEVENTSTACK_API_BASE ?? 'http://localhost:3001',
  environment,
});

try {
  const receipt = await useeventstack.events.deploymentCompleted(
    {
      service: 'api',
      version: '1.0.0',
      environment,
      status: 'healthy',
    },
    {
      environment,
      schemaVersion: 1,
      idempotencyKey: 'deploy-api-1.0.0',
      source: 'ci.release',
    },
  );

  console.log(receipt.event.id);
} catch (error: unknown) {
  if (error instanceof UseEventStackApiError) {
    console.error(error.status, error.code, error.message, error.details);
  } else {
    throw error;
  }
}

Client options

Option	Type	Current behavior
`apiKey`	`string`	Required for server-side usage
`projectId`	`string`	Required — project UUID for tenant isolation
`baseUrl`	`string`	Defaults to `http://localhost:3001`
`organizationId`	`string`	Optional client default; set it explicitly for event writes
`environment`	`'production' \| 'sandbox'`	Defaults to `production`
`fetch`	`typeof fetch`	Defaults to `globalThis.fetch`

Implemented methods

Method	Input boundary
`events.emit(input)` and `emit(input)`	Typed event input with optional organization, environment, correlation, causation, idempotency, source, and schema version
`events.deploymentCompleted(payload, options)`	Typed shortcut for `deployment.completed`
`events.query(options)`	`type`, `correlationId`, `environment`, `projectId`
`events.get(id, environment)`	Event identifier and optional environment
`events.trace(id, environment)`	Event identifier and optional environment
`workflows.query(options)`	`type`, `entity`, `environment`, `projectId`
`workflows.graph(root, environment)`	Optional root identifier and environment
`workflows.list(orgId)` / `.get(id)` / `.create(wf)` / `.update(id, wf)` / `.delete(id)`	Full workflow CRUD
`workflows.toggle(id, 'enable' \| 'disable')`	Enable or disable a workflow
`customActions.list()` / `.get(id)` / `.delete(id)` / `.simulate(id, payload)`	Custom action management and testing
`projections.query(options)`	`projection`, `environment`, `projectId`
`projections.serviceStatus(environment)`	Optional environment
`replay.single(eventId, options)`	Event ID, optional `skipExternalSideEffects`
`replay.bulk(options)`	`eventIds`, `eventType`, `since`, `until`, `limit`
`dlq.list()` / `.reprocess()`	Dead letter queue operations
`apiKeys.list()` / `.create(data)` / `.delete(keyId)`	API key management
`auth.login(creds)` / `.signup(data)` / `.logout()`	Session management (dashboard internal)
`sandbox()`	Returns a client configured for `sandbox`

Expected response

Event emission resolves to the exported EmitEventResponse shape:

interface EmitEventResponse<T extends EventType> {
  event: UseEventStackEvent<T>;
  idempotent_replay?: boolean;
}

Query methods return the types shown by the SDK: event queries return event arrays, workflow queries return unknown arrays, projection queries return unknown arrays, and the graph method returns an unknown value.

Failure diagnosis

Non-success HTTP responses throw UseEventStackApiError. Inspect:

status for the HTTP status
code for the API error identifier
message for the public error message
details for optional structured context such as a payload field

If construction fails with fetch_unavailable, supply a compatible fetch. If an environment-scoped read returns 403, match the query environment to the API key.

Client scope

The client exposes the methods listed above and does not define client timeout or retry options. Add service-level cancellation and failure handling without assuming an undocumented delivery outcome.

Next step

Use Event contracts to align runtime validation with the SDK payload, then inspect the stored result in Activity.