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' });
await hatched.eggs.updateStatus(egg.eggId, 'ready');
const op = await hatched.eggs.hatch(egg.eggId);

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' });
await hatched.eggs.updateStatus(egg.eggId, 'ready');

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): Promise<EquipItemsResult>

rerenderAppearance(buddyId: string, signal?: AbortSignal): Promise<RerenderAppearanceResult>

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>>

await hatched.eggs.updateStatus(egg.eggId, 'ready');
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(endpointId: string, deliveryId: string, signal?: AbortSignal): Promise<unknown>

redeliver(endpointId: string, deliveryId: string, signal?: AbortSignal): Promise<unknown>

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[] }>

list(audience?: string, signal?: AbortSignal): Promise<PathDefinition[]>

get(definitionId: string, signal?: AbortSignal): Promise<PathDefinitionWithSteps>

create(params: CreatePathDefinitionParams, signal?: AbortSignal): Promise<PathDefinition>

update(definitionId: string, params: UpdatePathDefinitionParams, signal?: AbortSignal): Promise<PathDefinition>

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

setActive(definitionId: string, isActive: boolean, signal?: AbortSignal): Promise<PathDefinition>

addStep(definitionId: string, params: CreatePathStepParams, signal?: AbortSignal): Promise<PathStep>

updateStep(definitionId: string, stepId: string, params: UpdatePathStepParams, signal?: AbortSignal): Promise<PathStep>

deleteStep(definitionId: string, stepId: string, signal?: AbortSignal): Promise<void>

reorderSteps(definitionId: string, ordering: Array<{ id: string; ordinal: number }>, signal?: AbortSignal): Promise<PathStep[]>

addSubStep(definitionId: string, stepId: string, params: CreatePathSubStepParams, signal?: AbortSignal): Promise<PathSubStep>

updateSubStep(definitionId: string, stepId: string, subStepId: string, params: UpdatePathSubStepParams, signal?: AbortSignal): Promise<PathSubStep>

deleteSubStep(definitionId: string, stepId: string, subStepId: string, signal?: AbortSignal): Promise<void>

reorderSubSteps(definitionId: string, stepId: string, ordering: Array<{ id: string; ordinal: number }>, signal?: AbortSignal): Promise<PathSubStep[]>

getForBuddy(buddyId: string, pathKey: string, signal?: AbortSignal): Promise<PathRuntimePayload>

completeSubStep(buddyId: string, pathKey: string, subStepKey: string, signal?: AbortSignal): Promise<ManualCompleteResult>

export interface NoPublishedConfigDetails {
  customerId?: string;
  customer_id?: string;
  publishUrl?: string;
  publish_url?: string;
  docsUrl?: string;
  docs_url?: string;
}

export interface ActiveEggLimitEgg {
  eggId: string;
  status: string;
  createdAt: string;
}

export interface ActiveEggLimitDetails {
  max?: number;
  active?: ActiveEggLimitWireEgg[];
}

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;
  /** Free-form metadata attached to the egg. */
  metadata?: Record<string, unknown>;
  /**
   * When true, return the user's most recent `waiting`/`ready` egg if one
   * already exists instead of creating a new one (idempotent first-run
   * bootstrap; avoids hitting the per-user active-egg cap on retries).
   */
  ensure?: boolean;
}

export interface Egg {
  eggId: string;
  userId: string;
  status: EggStatus;
  visualVariant: number;
  configVersionId: string;
  /** The buddy hatched from this egg. Non-null once `status === 'hatched'`. */
  buddyId: string | null;
  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>;
  progression?: BuddyProgression;
  imageUrl: string | null;
  baseImageUrl: string | null;
  thumbUrl: string | null;
  equippedItems: BuddyEquippedItem[];
  appearance?: BuddyAppearance;
  createdAt: string;
  updatedAt: string;
}

export interface BuddyProgression {
  /** Player-facing XP. Currently maps to totalSkillLevel. */
  xp: number;
  totalSkillLevel: number;
  badgeCount: number;
  itemCount: number;
  currentStreak: number;
  longestStreak: number;
  customCounters: Record<string, number>;
}

export interface BuddyEquippedItem {
  itemId: string;
  name: string;
  imageUrl: string | null;
}

export type BuddyAppearanceStatus = 'ready' | 'pending' | 'awaiting_credits' | 'failed';

export interface BuddyAppearance {
  status: BuddyAppearanceStatus;
  operationId: string | null;
  desiredEquippedItemIds: string[];
  renderedEquippedItemIds: string[];
  retryable: boolean;
  message: string | null;
  error: Record<string, unknown> | null;
}

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 EquipItemsResult {
  accepted: boolean;
  operationId: string | null;
  status: 'pending' | 'completed' | string;
  appearanceStatus: BuddyAppearanceStatus | string;
  cached: boolean;
}

export interface RerenderAppearanceResult {
  accepted: boolean;
  operationId: string;
  status: 'pending' | string;
  appearanceStatus: BuddyAppearanceStatus | 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;
  /**
   * Audience (role) this event belongs to. Required for customers with 2+
   * audiences; omit for single-audience customers and the server applies
   * the implicit default. Lowercase, snake_case, max 32 chars.
   */
  audience?: string;
  /** When the event occurred. Defaults to "now" server-side if omitted. */
  occurredAt?: Date | string;
  /** Arbitrary key-value payload forwarded to the rule engine. */
  properties?: Record<string, unknown>;
}

export interface EventStreakUpdate {
  definitionKey: string;
  label: string;
  icon: string;
  current: number;
  longest: number;
  milestoneHit: number | null;
  hero: boolean;
}

export interface EventPathSubStepCompletion {
  pathKey: string;
  stepKey: string;
  subStepKey: string;
  rewardCoins: number;
  rewardBadgeKey: string | null;
}

export interface EventPathStepCompletion {
  pathKey: string;
  stepKey: string;
  rewardCoins: number;
  rewardBadgeKey: string | null;
}

export interface EventPathCompletion {
  pathKey: string;
}

export interface EventPathUpdate {
  pathKey: string;
  subStepCompleted?: EventPathSubStepCompletion;
  stepCompleted?: EventPathStepCompletion;
  pathCompleted?: EventPathCompletion;
}

export interface EventEffects {
  coins?: number;
  badgesAwarded?: string[];
  badgesReady?: string[];
  tokens?: string[];
  /**
   * True when the buddy has met the next evolution condition. If the
   * customer's config does not auto-evolve, call `buddies.evolve(buddyId)`
   * server-side and wait on the returned operation.
   */
  evolutionReady?: boolean;
  streakMilestones?: number[];
  /** Per-streak deltas (current/longest, milestone hits) for active streaks. */
  streakUpdates?: EventStreakUpdate[];
  /**
   * Path widget reconciliation deltas. Each entry covers one sub-step
   * completion plus optional step / path roll-up flags so the host page
   * can paint celebrations without an extra round-trip.
   */
  pathUpdates?: EventPathUpdate[];
}

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[];
  active: boolean;
  status: 'active' | 'paused';
  secret?: string;
  maskedSecret?: string;
  createdAt: string;
  updatedAt: string;
}

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

export interface WebhookDelivery {
  id: string;
  endpointId?: string;
  event: string;
  eventType: string;
  status: 'pending' | 'success' | 'succeeded' | 'failed';
  responseCode?: number | null;
  responseStatus?: number | null;
  attempt: number;
  attempts: number;
  durationMs?: number | null;
  errorMessage?: string | null;
  createdAt: string;
  timestamp: string;
  lastAttemptAt?: string;
}

export interface ListDeliveriesParams {
  endpointId: string;
  status?: 'pending' | 'success' | '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>;
}

export type PathDisplayMode = 'straight' | 'zigzag' | 'stepper';

export type PathIcon = 'path' | 'flame' | 'heart' | 'bolt' | 'star' | 'leaf';

export type PathConditionType =
  | 'event_count'
  | 'milestone'
  | 'streak'
  | 'skill_level'
  | 'collection'
  | 'evolution'
  | 'coin'
  | 'badge_earned'
  | 'gate_unlocked'
  | 'custom';

export interface PathCondition {
  type: PathConditionType;
  config: Record<string, unknown>;
}

export interface PathDefinition {
  id: string;
  customerId: string;
  audience: string;
  key: string;
  label: string;
  description: string | null;
  icon: PathIcon;
  accentColor: string | null;
  displayMode: PathDisplayMode;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

export interface PathStep {
  id: string;
  pathDefinitionId: string;
  key: string;
  label: string;
  description: string | null;
  icon: string | null;
  ordinal: number;
  unlockCondition: Record<string, unknown> | null;
  completionCondition: PathCondition | null;
  rewardCoins: number;
  rewardBadgeKey: string | null;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

export interface PathSubStep {
  id: string;
  pathStepId: string;
  key: string;
  label: string;
  description: string | null;
  ordinal: number;
  completionCondition: PathCondition | null;
  allowManualComplete: boolean;
  allowSkipAhead: boolean;
  rewardCoins: number;
  rewardBadgeKey: string | null;
  contentUrl: string | null;
  ctaLabel: string | null;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

export type PathSubStepStatus = 'locked' | 'available' | 'completed';

export interface PathSubStepRuntime {
  id: string;
  key: string;
  label: string;
  description: string | null;
  ordinal: number;
  rewardCoins: number;
  rewardBadgeKey: string | null;
  contentUrl: string | null;
  ctaLabel: string | null;
  allowManualComplete: boolean;
  allowSkipAhead: boolean;
  isActive: boolean;
  status: PathSubStepStatus;
  completedAt: string | null;
}

export interface PathStepRuntime {
  id: string;
  key: string;
  label: string;
  description: string | null;
  icon: string | null;
  ordinal: number;
  rewardCoins: number;
  rewardBadgeKey: string | null;
  isActive: boolean;
  unlocked: boolean;
  completed: boolean;
  subSteps: PathSubStepRuntime[];
}

export interface PathRuntimePayload {
  definition: {
    key: string;
    label: string;
    description: string | null;
    icon: PathIcon;
    accentColor: string | null;
    displayMode: PathDisplayMode;
  };
  steps: PathStepRuntime[];
  currentStepKey: string | null;
  completed: boolean;
  completedAt: string | null;
}

export interface CreatePathDefinitionParams {
  audience?: string;
  key: string;
  label: string;
  description?: string;
  icon?: PathIcon;
  accentColor?: string;
  displayMode?: PathDisplayMode;
  isActive?: boolean;
}

export type UpdatePathDefinitionParams = Partial<CreatePathDefinitionParams>;

export interface CreatePathStepParams {
  key: string;
  label: string;
  description?: string;
  icon?: string;
  ordinal: number;
  unlockCondition?: Record<string, unknown>;
  completionCondition?: PathCondition;
  rewardCoins?: number;
  rewardBadgeKey?: string;
  isActive?: boolean;
}

export type UpdatePathStepParams = Partial<CreatePathStepParams>;

export interface CreatePathSubStepParams {
  key: string;
  label: string;
  description?: string;
  ordinal: number;
  completionCondition?: PathCondition;
  allowManualComplete?: boolean;
  allowSkipAhead?: boolean;
  rewardCoins?: number;
  rewardBadgeKey?: string;
  contentUrl?: string;
  ctaLabel?: string;
  isActive?: boolean;
}

export type UpdatePathSubStepParams = Partial<CreatePathSubStepParams>;

export interface ManualCompleteResult {
  alreadyCompleted: boolean;
  subStepKey: string;
  stepKey: string;
  stepCompleted: boolean;
  pathCompleted: boolean;
  rewardCoins: number;
  rewardBadgeKey: string | null;
}