SDK (JavaScript / TypeScript)

pnpm add @hatched/sdk-js

const hatched = new HatchedClient({
  apiKey: process.env.HATCHED_API_KEY!,
});
const egg = await hatched.eggs.create({ userId: 'user_123' });

const hatched = new HatchedClient({
  publishableKey: 'hatch_pk_xxxxxxxx',
});
const buddy = await hatched.buddies.get('bdy_abc');

health()

getRateLimitInfo()

getLastRequestId(): string | null

create(params: CreateEggParams, signal?: AbortSignal): Promise<Egg>

const egg = await hatched.eggs.create({ userId: 'user_42' });

get(eggId: string, signal?: AbortSignal): Promise<Egg>

list(params: ListEggsParams = {}): Promise<Egg[]>

updateStatus(eggId: string, status: 'ready' | 'cancelled', signal?: AbortSignal): Promise<EggStatusChange>

hatch(eggId: string, signal?: AbortSignal): Promise<HatchResult>

get(buddyId: string, signal?: AbortSignal): Promise<Buddy>

list(params: BuddyListParams = {}): Promise<BuddyList>

updateName(buddyId: string, name: string, signal?: AbortSignal): Promise<Buddy>

archive(buddyId: string, signal?: AbortSignal): Promise<Buddy>

updateSkills(buddyId: string, updates: SkillUpdate[], signal?: AbortSignal)

earn(buddyId: string, params: EarnCoinsParams, idempotencyKey?: string, signal?: AbortSignal)

spend(buddyId: string, params: SpendCoinsParams, idempotencyKey?: string, signal?: AbortSignal)

awardBadge(buddyId: string, badgeKey: string, reason?: string, signal?: AbortSignal)

getBadges(buddyId: string, signal?: AbortSignal)

equip(buddyId: string, params: EquipItemsParams, signal?: AbortSignal)

purchaseItem(buddyId: string, itemId: string, idempotencyKey?: string, signal?: AbortSignal)

getPurchasedItems(buddyId: string, signal?: AbortSignal)

getEvolution(buddyId: string, signal?: AbortSignal)

evolve(buddyId: string, signal?: AbortSignal)

getProgression(buddyId: string, signal?: AbortSignal)

tokens(buddyId: string, signal?: AbortSignal): Promise<TokensSummary>

evolutions(buddyId: string, params: { page?: number; limit?: number; signal?: AbortSignal } = {}): Promise<{
    data: BuddyEvolutionRecord[];
    pagination: { page: number; limit: number; total: number };
  }>

getUserSummary(userId: string, signal?: AbortSignal)

send(params: SendEventParams, signal?: AbortSignal): Promise<EventEffects>

const effects = await hatched.events.send({
  eventId: 'lesson_lsn_42_user_123',
  userId: 'user_123',
  type: 'lesson_completed',
  properties: { score: 94 },
});

sendBatch(events: SendEventParams[], signal?: AbortSignal): Promise<{ results: EventEffects[] }>

get(operationId: string, signal?: AbortSignal): Promise<Operation<TResult>>

wait(operationId: string, options: WaitOptions = {}): Promise<Operation<TResult>>

const op = await hatched.eggs.hatch(egg.eggId);
const finished = await hatched.operations.wait(op.operationId);

waitForCompletion(operationId: string, options: { timeout?: number; interval?: number; signal?: AbortSignal } = {}): Promise<Operation<TResult>>

create(params: CreateSessionParams, signal?: AbortSignal): Promise<SessionToken>

revoke(sessionId: string, signal?: AbortSignal): Promise<void>

create(params: CreateEmbedTokenParams, signal?: AbortSignal): Promise<EmbedToken>

list(signal?: AbortSignal): Promise<WebhookEndpoint[]>

create(params: CreateWebhookParams, signal?: AbortSignal): Promise<WebhookEndpoint>

delete(endpointId: string, signal?: AbortSignal): Promise<void>

deliveries(params: ListDeliveriesParams): Promise<Page<WebhookDelivery>>

replay(deliveryId: string, signal?: AbortSignal): Promise<WebhookDelivery>

static verifySignature(rawBody: string | Buffer, signatureHeader: string, secret: string, options: VerifySignatureOptions = {}): boolean

const valid = WebhooksResource.verifySignature(rawBody, header, process.env.HATCHED_WEBHOOK_SECRET!);
if (!valid) return new Response('invalid signature', { status: 400 });

list(signal?: AbortSignal): Promise<{ gates: TokenGate[] }>

unlock(buddyId: string, gateKey: string, signal?: AbortSignal): Promise<UnlockResult>

unlocks(buddyId: string, signal?: AbortSignal): Promise<{ unlocks: BuddyUnlock[] }>

export interface CreditInsufficientDetails {
  required?: number;
  available?: number;
  welcome?: number;
  paid?: number;
  promo?: number;
  upgrade_url?: string;
  top_up_url?: string;
}

export interface EventQuotaExceededDetails {
  used?: number;
  limit?: number;
  reset_at?: string;
  upgrade_url?: string;
}

export interface PlanFeatureLockedDetails {
  feature?: string;
  required_plan?: string;
  current_plan?: string;
  upgrade_url?: string;
}

export type EggStatus = 'waiting' | 'ready' | 'hatching' | 'hatched' | 'cancelled';

export interface CreateEggParams {
  /** The external user id that owns the egg. */
  userId: string;
  /** Optional preset seed used by the config engine. */
  presetId?: string;
  /** Free-form metadata attached to the egg. */
  metadata?: Record<string, unknown>;
}

export interface Egg {
  eggId: string;
  userId: string;
  status: EggStatus;
  visualVariant: number;
  configVersionId: string;
  metadata: Record<string, unknown>;
  createdAt: string;
}

export interface EggStatusChange {
  eggId: string;
  status: EggStatus;
  previousStatus: EggStatus;
}

export interface HatchResult {
  operationId: string;
  status: string;
}

export interface ListEggsParams {
  userId?: string;
  status?: EggStatus;
  page?: number;
  limit?: number;
  signal?: AbortSignal;
}

export interface Buddy {
  id: string;
  customerId: string;
  userId: string;
  audience: string;
  name: string;
  configVersionId: string;
  evolutionStage: number;
  coins: number;
  status: 'active' | 'archived';
  skills: Record<string, number>;
  tokens: Record<string, number>;
  imageUrl: string | null;
  thumbUrl: string | null;
  equippedItems: string[];
  createdAt: string;
  updatedAt: string;
}

export interface BuddyListParams {
  userId?: string;
  status?: string;
  evolutionStage?: number;
  page?: number;
  limit?: number;
  sort?: string;
  order?: 'asc' | 'desc';
  signal?: AbortSignal;
}

export interface SkillUpdate {
  key: string;
  action: 'increase' | 'decrease' | 'set';
  amount?: number;
  value?: number;
}

export interface EarnCoinsParams {
  amount: number;
  reason: string;
  referenceId?: string;
  /**
   * Token key to earn. Defaults to the customer's `primary` token. Passing
   * a progression token grants progress; passing any other configured token
   * key is accepted by the rule engine. Omit to earn the default coin / primary.
   */
  token?: string;
}

export interface SpendCoinsParams {
  amount: number;
  reason: string;
  itemId?: string;
  /**
   * Token key to spend. Defaults to the customer's `primary` token. Spending
   * a progression token fails with ValidationError('progression_not_spendable').
   */
  token?: string;
}

export interface TokenBalance {
  /** Canonical `primary` or `progression` identifier. */
  kind: 'primary' | 'progression';
  /** Customer-defined token key (e.g. `gems`, `xp`). */
  key: string;
  /** Human-readable label for display. */
  label: string;
  /** Current balance. */
  balance: number;
  /** Lifetime earned (earn ledger sum). */
  lifetimeEarned: number;
  /** Lifetime spent (spend ledger sum) — always 0 for progression. */
  lifetimeSpent: number;
}

export interface TokensSummary {
  primary: TokenBalance | null;
  progression: TokenBalance | null;
}

export interface BuddyEvolutionRecord {
  id: string;
  buddyId: string;
  fromStage: number;
  toStage: number;
  triggeredByEventId: string | null;
  imageUrl: string | null;
  source: 'prod' | 'demo' | 'auto';
  metadata: Record<string, unknown>;
  occurredAt: string;
}

export interface EquipItemsParams {
  equip?: string[];
  unequip?: string[];
}

export interface BuddyList {
  data: Buddy[];
  meta: { total: number; page: number; limit: number };
}

export interface SendEventParams {
  /** Stable id used for idempotency. Re-sending the same eventId is a no-op. */
  eventId: string;
  /** External user id the event belongs to. */
  userId: string;
  /** Event type (e.g. `lesson_completed`, `workout_finished`). */
  type: string;
  /** When the event occurred. Defaults to "now" if omitted. */
  occurredAt?: Date | string;
  /** Arbitrary key-value payload forwarded to the rule engine. */
  properties?: Record<string, unknown>;
}

export interface EventEffects {
  coins?: number;
  badgesAwarded?: string[];
  badgesReady?: string[];
  tokens?: string[];
  evolutionReady?: boolean;
  streakMilestones?: number[];
}

export type OperationStatus = 'pending' | 'processing' | 'completed' | 'failed';

export interface Operation<TResult = unknown> {
  operationId: string;
  /** Alias for {@link Operation.operationId} for callers that prefer `id`. */
  id: string;
  type: string;
  status: OperationStatus;
  result?: TResult;
  error?: string;
  createdAt: string;
  updatedAt: string;
}

export interface WaitOptions {
  /** Maximum total time to wait, in milliseconds. Default 30_000. */
  timeoutMs?: number;
  /** Poll interval, in milliseconds. Default 2000. */
  intervalMs?: number;
  /** External abort signal. */
  signal?: AbortSignal;
}

export interface CreateSessionParams {
  buddyId: string;
  userId: string;
  scopes: string[];
  ttlSeconds?: number;
}

export interface SessionToken {
  token: string;
  sessionId: string;
  expiresAt: string;
  scopes: string[];
}

export interface CreateEmbedTokenParams {
  buddyId: string;
  userId: string;
  ttlSeconds?: number;
}

export interface EmbedToken {
  token: string;
  expiresAt: string;
  mode: 'read-only';
}

export interface WebhookEndpoint {
  id: string;
  url: string;
  events: string[];
  status: 'active' | 'paused';
  secret: string;
  createdAt: string;
  updatedAt: string;
}

export interface CreateWebhookParams {
  url: string;
  events: string[];
  description?: string;
}

export interface WebhookDelivery {
  id: string;
  endpointId: string;
  event: string;
  status: 'pending' | 'succeeded' | 'failed';
  responseStatus?: number;
  attempts: number;
  createdAt: string;
  lastAttemptAt?: string;
}

export interface ListDeliveriesParams {
  endpointId: string;
  status?: 'pending' | 'succeeded' | 'failed';
  cursor?: string;
  limit?: number;
  signal?: AbortSignal;
}

export interface Page<T> {
  data: T[];
  nextCursor: string | null;
}

export interface VerifySignatureOptions {
  /** Maximum clock-skew in seconds. Defaults to 5 minutes. */
  toleranceSeconds?: number;
  /** Clock used for timestamp validation — useful in tests. */
  now?: () => number;
}

export interface TokenGate {
  id: string;
  gateKey: string;
  tokenKey: string;
  cost: number;
  label: string | null;
  description: string | null;
  metadata: Record<string, unknown>;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

export interface UnlockResult {
  gateKey: string;
  unlocked: true;
  alreadyUnlocked: boolean;
  unlockedAt: string;
  balanceAfter: number | null;
  metadata: Record<string, unknown>;
}

export interface BuddyUnlock {
  gateKey: string;
  unlockedAt: string;
  metadata: Record<string, unknown>;
}