API Reference

function createTeardown(options: TeardownOptions): Teardown

import { createTeardown } from "@teardown/server";

const td = createTeardown({
  storage: createMemoryStorage(),
  config: { sessionSecret: process.env.SESSION_SECRET! },
});

import { SDK_NAME } from "@teardown/server";
// "@teardown/server" — a stable namespace for cache keys, headers, etc.

identify(headers: IdentifyHeaders, request: IdentifyRequest): Promise<
  | { success: true; data: IdentifyData }
  | { success: false; error: string }
>

processEvents(headers: EventsHeaders, request: EventsRequest): Promise<
  | { success: true; data: ProcessEventsResult }
  | { success: false; error: string }
>

interface TeardownConfig {
  sessionSecret?: string;       // HMAC key signing client session tokens; required unless a custom signer is supplied
  sessionTokenExpiry?: string;  // jose-format, default "15m"
  sessionTtlMs?: number;        // session row TTL, default 900000 (15m)
  sessionReuseExtendMs?: number;// reuse extension, default 300000 (5m)
  maxEventsPerBatch?: number;   // default 100
}

interface CachePort {
  get<T>(key: string): Promise<T | null>;
  set(key: string, value: unknown, ttlSeconds?: number): Promise<boolean>;
  del(key: string): Promise<boolean>;
}

interface LoggerPort {
  debug(message: string, context?: Record<string, unknown>): void;
  info(message: string, context?: Record<string, unknown>): void;
  warn(message: string, context?: Record<string, unknown>): void;
  error(message: string, context?: Record<string, unknown>): void;
}

interface MetricsPort {
  counter(name: string, value: number, attributes?: MetricAttributes): void;
  histogram(name: string, value: number, attributes?: MetricAttributes): void;
}

interface ClockPort {
  now(): Date;
  uuid(): string;
}

interface TokenSigner {
  sign(claims: SessionTokenClaims): Promise<string>;
  verify(token: string): Promise<SessionTokenPayload | null>;
}

interface SessionTokenClaims {
  sessionId: string;
  deviceId: string;
  userId: string;
  environmentId: string;
  projectId: string;
  orgId: string;
}

import { createJoseSigner } from "@teardown/server";

const signer = createJoseSigner({ secret: process.env.SESSION_SECRET!, expiry: "30m" });
const td = createTeardown({ storage, signer });