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_designer_priya' });
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

getLastRetryMetadata()

await hatched.events.send({ eventId, userId: 'user_42', type: 'lesson_completed' });
const retry = hatched.getLastRetryMetadata();
if (retry && retry.attempts > 1) {
  logger.info({ attempts: retry.attempts, reasons: retry.reasons });
}

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

// Greenwave Learning Co. — a new instructional designer joins the workspace.
const egg = await hatched.eggs.create({ userId: 'user_designer_priya' });
await hatched.eggs.updateStatus(egg.eggId, 'ready');

// Multi-audience workspace: bind the buddy to the right audience up front
// so audience-scoped widgets (streak/badges/marketplace) resolve.
await hatched.eggs.create({ userId: 'user_rep_amir', audience: 'sales_rep', ensure: true });

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>

// Greenwave Learning Co. — list the first page of active buddies.
const { data: buddies } = await hatched.buddies.list({
  status: 'active',
  limit: 25,
});

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): Promise<{ badges: Badge[] }>

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)

prestigeStatus(signal?: AbortSignal): Promise<PrestigeStatus>

prestige(signal?: AbortSignal): Promise<PrestigeResult>

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

// Greenwave Learning Co. — Priya completed the week's module review.
const effects = await hatched.events.send({
  eventId: 'lesson_module_review_user_designer_priya_2026_05_03',
  userId: 'user_designer_priya',
  type: 'lesson_completed',
  properties: { score: 94, module: 'module_review_week_4' },
});

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>

rotateSecret(endpointId: string, signal?: AbortSignal): Promise<{ secret: string }>

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

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

const valid = WebhooksResource.verifySignature(
  rawBody,
  req.headers['x-hatched-signature'],
  process.env.HATCHED_WEBHOOK_SECRET!,
  { timestamp: req.headers['x-hatched-timestamp'] },
);
if (!valid) return new Response('invalid signature', { status: 400 });

zero(signal?: AbortSignal): Promise<PlayerZeroResult>

const { buddy } = await hatched.players.zero();
await hatched.events.ingest({
  userId: buddy.userId, // "player-0"
  type: 'lesson.completed',
  eventId: 'evt_demo_1',
});

zeroStatus(signal?: AbortSignal): Promise<PlayerZeroStatus>

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>

list(params: MarketplaceListParams = {}): Promise<MarketplaceListResponse>

gift(params: GiftItemParams): Promise<GiftItemResult>

previewOutfit(slotItemMap: SlotItemMap, signal?: AbortSignal): Promise<OutfitPreviewResponse>

compositionStatus(variantId: string, signal?: AbortSignal): Promise<CompositionStatusResponse>

listOutfits(signal?: AbortSignal): Promise<OutfitListResponse>

saveOutfit(params: SaveOutfitParams, idempotencyKey?: string, signal?: AbortSignal): Promise<OutfitSummary>

activateOutfit(outfitId: string, signal?: AbortSignal): Promise<ActivateOutfitResponse>

deleteOutfit(outfitId: string, signal?: AbortSignal): Promise<DeleteOutfitResponse>

list(params: BadgeListParams = {}): Promise<BadgeListResponse>

get(params: LeaderboardParams = {}): Promise<LeaderboardResponse>

get(signal?: AbortSignal): Promise<NextBestActionResponse>

me(signal?: AbortSignal): Promise<MyTeamResponse>

leave(teamId: string, signal?: AbortSignal): Promise<{ left: boolean }>

send(params: SendKudosParams): Promise<SentKudos>

// Greenwave Learning Co. — a senior designer recognises a junior's question.
await hatched.kudos.send({
  toBuddyId: 'buddy_priya_buddy',
  kudoTypeKey: 'patient_teacher',
  message: 'Your follow-up on the module review walkthrough was exactly the prompt I needed.',
});

types(signal?: AbortSignal): Promise<KudoTypeView[]>

received(limit = 10, signal?: AbortSignal): Promise<KudosFeedEntry[]>

given(limit = 10, signal?: AbortSignal): Promise<GivenKudosResponse>

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

join(questId: string, signal?: AbortSignal): Promise<JoinGroupQuestResult>

leave(questId: string, signal?: AbortSignal): Promise<LeaveGroupQuestResult>

list(params: { status?: GroupQuestStatus; teamId?: string } = {}, signal?: AbortSignal): Promise<AdminGroupQuest[]>

create(params: CreateGroupQuestParams, signal?: AbortSignal): Promise<AdminGroupQuest>

update(questId: string, params: UpdateGroupQuestParams, signal?: AbortSignal): Promise<AdminGroupQuest>

publish(questId: string, signal?: AbortSignal): Promise<AdminGroupQuest>

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

forceResolve(questId: string, signal?: AbortSignal): Promise<ForceResolveResult>

setAvailability(params: { available: boolean; signal?: AbortSignal }): Promise<{ available: boolean }>

teamMentors(teamId: string, signal?: AbortSignal): Promise<MentorDirectoryEntry[]>

logSession(params: LogSessionParams): Promise<LogSessionResult>

sessionsForMe(signal?: AbortSignal): Promise<MentorSessionsResponse>

recordTelemetry(params: RecordBragTelemetryParams): Promise<BragTelemetryResult>

sendSlackPost(params: SendBragSlackPostParams): Promise<BragSlackPostResult>

list(params: ListTeamEventsParams = {}): Promise<TeamEventsPage>

clap(eventId: string, signal?: AbortSignal): Promise<ClapResult>

today(signal?: AbortSignal): Promise<SocialNormsTodayResponse>

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

create(params: CreateCauseParams, signal?: AbortSignal): Promise<AdminCause>

update(causeId: string, params: UpdateCauseParams, signal?: AbortSignal): Promise<AdminCause>

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

preview30Days(causeId: string, signal?: AbortSignal): Promise<CausePreview>

preview(signal?: AbortSignal): Promise<FoundingCohortPreview>

backfill(signal?: AbortSignal): Promise<FoundingCohortBackfillResult>

listAudit(page = 1, signal?: AbortSignal): Promise<{
    entries: FoundingCohortAuditEntry[];
    page: number;
    has_more: boolean;
  }>

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

schedule(params: ScheduleFlashSaleParams): Promise<FlashSale>

cancel(saleId: string, signal?: AbortSignal): Promise<FlashSale>

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

create(params: CreateLotteryParams): Promise<LotteryDefinition>

update(lotteryId: string, params: UpdateLotteryParams): Promise<LotteryDefinition>

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

draws(lotteryId: string, signal?: AbortSignal): Promise<LotteryDraw[]>

previewNextDraw(lotteryId: string, signal?: AbortSignal): Promise<LotteryNextDrawPreview>

simulateDraw(lotteryId: string, signal?: AbortSignal): Promise<SimulatedLotteryDraw>

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

create(params: CreateEventBadgeParams): Promise<EventBadgeDefinition>

update(campaignId: string, params: UpdateEventBadgeParams): Promise<EventBadgeDefinition>

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

list(signal?: AbortSignal): Promise<ProfileTemplateList>

create(params: CreateProfileTemplateParams): Promise<ProfileTemplate>

update(templateId: string, params: UpdateProfileTemplateParams): Promise<ProfileTemplate>

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

applyBulk(params: BulkApplyProfileTemplateParams): Promise<{ applied: number }>

me(signal?: AbortSignal): Promise<LeagueWidgetSnapshot>

bossFightProgress(signal?: AbortSignal): Promise<BossFightProgressView>

seasonHighlights(seasonId: string, signal?: AbortSignal): Promise<LeagueSeasonHighlightsSnapshot>

latestSeasonHighlights(signal?: AbortSignal): Promise<LeagueSeasonHighlightsSnapshot>

questions(signal?: AbortSignal): Promise<HexadSurveyQuestionsResponse>

submit(params: SubmitHexadSurveyParams): Promise<HexadSurveySubmitResult>

me(signal?: AbortSignal): Promise<HexadSurveyMyResponse>

deleteMine(signal?: AbortSignal): Promise<void>

whoami(signal?: AbortSignal): Promise<WhoamiResult>

list(params: ListNotificationsParams = {}): Promise<NotificationFeedPage>

unreadCount(signal?: AbortSignal): Promise<UnreadCountResult>

dismissAll(signal?: AbortSignal): Promise<DismissAllResult>

markRead(id: string, signal?: AbortSignal): Promise<Notification>

dismiss(id: string, signal?: AbortSignal): Promise<DismissResult>

snooze(id: string, hours?: number, signal?: AbortSignal): Promise<Notification>

getState(signal?: AbortSignal): Promise<MysteryBoxState>

claim(signal?: AbortSignal): Promise<MysteryBoxClaimResult>

listMyProposals(signal?: AbortSignal): Promise<MyProposalsView>

submitProposal(params: SubmitProposalParams): Promise<Proposal>

getNotification(signal?: AbortSignal): Promise<FreeLunchNotification>

acknowledge(id: string, signal?: AbortSignal): Promise<FreeLunchAcknowledgeResult>

getResult(signal?: AbortSignal): Promise<BeginnersLuckResult>

recordRendered(params: RecordWidgetRenderedParams = {}): Promise<WidgetRenderedResult>

export interface ApiKeyConfig extends BaseConfig {
  /** Secret API key (hatch_live_*, hatch_test_*). Server-only. */
  apiKey: string;
  publishableKey?: never;
  widgetToken?: never;
}

export interface PublishableKeyConfig extends BaseConfig {
  /** Browser-safe publishable key (hatch_pk_*). Scoped auth. */
  publishableKey: string;
  apiKey?: never;
  widgetToken?: never;
}

export interface WidgetTokenConfig extends BaseConfig {
  /** Widget embed/session token minted by the server. Browser-safe, buddy-scoped. */
  widgetToken: string;
  apiKey?: never;
  publishableKey?: never;
}

export type HatchedClientConfig =
  | ApiKeyConfig
  | PublishableKeyConfig
  | WidgetTokenConfig;

paginate(fetchPage: (page: number) => Promise<OffsetPage<T>>, options: PaginateOptions = {}): AsyncIterableIterator<T>

for await (const buddy of paginate(
  (page) => hatched.buddies.list({ page, limit: 100, status: 'active' }),
)) {
  if (buddy.id === target) break; // early-exit; iterator stops paging
}

paginateCursor(fetchPage: (cursor?: string) => Promise<CursorPage<T>>, options: PaginateOptions = {}): AsyncIterableIterator<T>

for await (const op of paginateCursor(
  (cursor) => hatched.operations.list({ cursor, limit: 100 }),
)) {
  console.log(op.id);
}

collect(fetchPage: (page: number) => Promise<OffsetPage<T>>, options: PaginateOptions = {}): Promise<T[]>

const allActive = await collect(
  (page) => hatched.buddies.list({ page, limit: 100, status: 'active' }),
);

collectCursor(fetchPage: (cursor?: string) => Promise<CursorPage<T>>, options: PaginateOptions = {}): Promise<T[]>

const allOps = await collectCursor(
  (cursor) => hatched.operations.list({ cursor, limit: 100 }),
);

consoleLogger(): SdkLogger

verifyExpressRequest(req: MinimalExpressRequest, secret: string | readonly string[], options: VerifyAdapterOptions = {}): VerifyResult

verifyFastifyRequest(req: MinimalFastifyRequest, secret: string | readonly string[], options: VerifyAdapterOptions = {}): VerifyResult

verifyHonoRequest(c: MinimalHonoContext, secret: string | readonly string[], options: VerifyAdapterOptions = {}): Promise<VerifyResult>

verifyNextAppRequest(req: MinimalFetchRequest, secret: string | readonly string[], options: VerifyAdapterOptions = {}): Promise<VerifyResult>

verifyNextPagesRequest(req: MinimalPagesRequest, rawBody: Buffer | string, secret: string | readonly string[], options: VerifyAdapterOptions = {}): VerifyResult

import { ErrorCode, HatchedError } from '@hatched/sdk-js';

try {
  await hatched.events.send({ eventId, userId: 'user_42', type: 'lesson_completed' });
} catch (err) {
  if (err instanceof HatchedError) {
    switch (err.code) {
      case ErrorCode.EventQuotaExceeded: showUpgradeBanner(); break;
      case ErrorCode.RateLimited: queueRetry(err.retryAfter); break;
      case ErrorCode.PlanFeatureLocked: hideFeature(); break;
      default: throw err;
    }
  }
}

export const ErrorCode = {
  // 400 — bad request
  BadRequest: 'bad_request',
  InsufficientBalance: 'insufficient_balance',
  TooManyItems: 'too_many_items',
  CategoryConflict: 'category_conflict',
  MissingAudience: 'missing_audience',
  UnknownAudience: 'unknown_audience',

  // 422 — validation
  ValidationFailed: 'validation_failed',

  // 401 / 403 — auth & scope
  Unauthorized: 'unauthorized',
  Forbidden: 'forbidden',
  PublishableKeyScope: 'publishable_key_scope',
  WidgetTokenScope: 'widget_token_scope',
  PlanFeatureLocked: 'plan_feature_locked',
  CapabilityDisabled: 'capability_disabled',

  // 402 — billing
  PaymentRequired: 'payment_required',
  CreditInsufficient: 'credit_insufficient',
  EventQuotaExceeded: 'event_quota_exceeded',
  OnboardingCapReached: 'onboarding_cap_reached',

  // 404 — not found
  ResourceNotFound: 'resource_not_found',
  NotFound: 'not_found',

  // 409 — conflicts
  Conflict: 'conflict',
  ConfigVersionMismatch: 'config_version_mismatch',
  NoPublishedConfig: 'no_published_config',
  ActiveEggLimit: 'active_egg_limit',
  IdempotencyKeyConflict: 'idempotency_key_conflict',

  // 429 — throttling
  RateLimited: 'rate_limited',

  // 502 — upstream
  UpstreamImageError: 'upstream_image_error',
  BadGateway: 'bad_gateway',

  // 503 — service unavailable
  ServiceUnavailable: 'service_unavailable',
  OnboardingExtractFailed: 'onboarding_extract_failed',

  // 500 — internal
  InternalServerError: 'internal_server_error',
} as const;

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

import pino from 'pino';
const log = pino({ name: 'hatched' });
const hatched = new HatchedClient({
  apiKey: process.env.HATCHED_API_KEY!,
  logger: log,
});

// Minimal "ignore debug, send warnings to Sentry" adapter
const hatched = new HatchedClient({
  apiKey: process.env.HATCHED_API_KEY!,
  debug: false,
  logger: {
    warn: (msg, fields) => Sentry.captureMessage(msg, { extra: fields }),
  },
});

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

export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;

export interface HttpClientConfig {
  baseUrl: string;
  apiKey?: string;
  publishableKey?: string;
  widgetToken?: string;
  timeout: number;
  maxRetries: number;
  debug: boolean;
  fetch?: FetchLike;
  userAgent: string;
  logger?: SdkLogger;
}

export interface RateLimitSnapshot {
  limit?: number;
  remaining?: number;
  reset?: number;
  retryAfter?: number;
}

export interface RetryMetadata {
  attempts: number;
  reasons: Array<'5xx' | '429' | '408' | 'network'>;
  totalDelayMs: number;
  totalElapsedMs: number;
}

export interface RequestOptions {
  headers?: Record<string, string>;
  idempotent?: boolean;
  signal?: AbortSignal;
  /** When false, skips automatic camelCase → snake_case mapping on the body. */
  mapCase?: boolean;
  /** Query parameters (camelCase; converted to snake_case on the wire). */
  query?: Record<string, string | number | boolean | undefined>;
  /**
   * Whether this endpoint accepts publishable keys. When `false` (default
   * for mutations) and the client is initialised with a publishable key,
   * the SDK throws `PublishableKeyScopeError` without a network round-trip.
   */
  allowPublishable?: boolean;
  /** Whether this endpoint accepts a widget embed/session token. */
  allowWidgetToken?: boolean;
}

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

export interface CreateEggParams {
  /** The external user id that owns the egg. */
  userId: string;
  /**
   * Binds the egg — and the buddy it hatches into — to a named audience.
   * Audience-scoped content (streaks, badges, marketplace items) is keyed by
   * audience, so a buddy born in the wrong audience makes those widgets 404 or
   * render empty. Single-audience workspaces can omit this (the server binds the
   * sole configured audience automatically); multi-audience workspaces must set
   * it. This is shorthand for `metadata.audience` and takes precedence over it.
   */
  audience?: 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 type AuraTier = 'mythic' | 'legendary' | 'epic' | 'rare' | 'common';

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;
  auraTier?: AuraTier;
  /** HTCH-27 — true when the buddy has no equipped items. */
  isNaked?: boolean;
  /** HTCH-105 — F4.4 true when the buddy holds the mentor role. */
  isMentor?: boolean;
  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 interface Badge {
  badgeKey: string;
  label: string;
  description: string | null;
  /**
   * HTCH-16 user-facing "How to earn" copy. Distinct from `description`
   * (admin-internal) — the badges widget renders this in the locked-tile
   * tooltip. Falls back to `description` when null.
   */
  criteriaCopy: string | null;
  iconUrl: string | null;
  awardedAt: string;
  coinReward: number;
  alreadyAwarded: boolean;
}

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 type PrestigeBlockReason =
  | 'disabled'
  | 'not_max_stage'
  | 'appearance_pending'
  | 'cooldown_active'
  | 'champion_required';

export type PrestigeAuraTint = 'none' | 'silver' | 'gold' | 'rainbow';

export interface PrestigeStatus {
  /** False when the tenant has not enabled the prestige loop. */
  available: boolean;
  canPrestige: boolean;
  reason: PrestigeBlockReason | null;
  prestigeLevel: number;
  evolutionStage: number;
  maxEvolutionStage: number;
  /** When `cooldown_active`, the ISO instant the cooldown clears. */
  cooldownEndsAt: string | null;
}

export interface PrestigeResult {
  prestigeLevel: number;
  fromEvolutionStage: number;
  evolutionStage: number;
  auraTint: PrestigeAuraTint;
  prestigedAt: string;
  seasonId: string | null;
  /** The buddy's image after the reset (reverted to its clean base). */
  imageUrl: string;
}

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