Release notes for @hatched/sdk-js. Produced by changesets on every merge to main.

@hatched/sdk-js

1.0.0

Major Changes

• 6dff237: PathDisplayMode renamed: replace 'path' with 'straight' (clean centered column) and add 'zigzag' (Duolingo-style alternating sides). Existing 'path' consumers must migrate to 'straight'. The legacy half-zigzag rendering (node offset, text static) is removed.

Minor Changes

• d73cafe: First-run bootstrap ergonomics: eggs.create({ userId, ensure: true }) now reuses the user's existing waiting/ready egg instead of creating a new one (avoids the per-user active-egg cap on retries). Egg responses include buddyId (non-null once the egg is hatched). Two new typed 409 errors are surfaced: NoPublishedConfigError (raised by eggs.create before a config version is published — exposes publishUrl) and ActiveEggLimitError (raised when the active-egg cap is hit — exposes max and active[] with the existing egg ids/statuses).

0.5.0

Minor Changes

• d758872: Add paths resource — guided multi-step journeys (Duolingo-style). New client.paths exposes admin CRUD over path definitions, steps, and sub-steps; setActive() flips the audience's single active path atomically; getForBuddy() returns the buddy-scoped runtime payload with locked / available / completed sub-step states; completeSubStep() manually marks a sub-step done and returns cascade flags so callers can celebrate without an extra round-trip. Sub-steps support an optional contentUrl + ctaLabel for deep-linking into a customer's LMS.

  events.send() response now also exposes streakUpdates and pathUpdates on the returned EventEffects, so a single track call can drive streak counters and path widgets in addition to coins/badges without an extra fetch.

• 42907d4: Added new feature: path and performance improvements

0.4.4

Patch Changes

• ea76743: Republish 0.4.3 with corrected package metadata: repository.url and bugs.url now point to the public SDK repo at github.com/hatched-live/hatched-sdk-js. (0.4.3 was never published to npm.)

0.4.3

Patch

• Buddy appearance types — Buddy now exposes baseImageUrl, typed equipped item objects, and the appearance status block used by the persistent AI compositing pipeline.
• Equip result typing — buddies.equip() now returns a typed { accepted, operationId, status, appearanceStatus, cached } result so clients can distinguish instant cache hits from queued appearance generation.
• Rerender appearance — new buddies.rerenderAppearance(buddyId) method backed by POST /buddies/:id/appearance/rerender. Use when appearance.status === 'failed' (especially error.code === 'needs_rerender' after the appearance pipeline migration) to regenerate the bare stage image. Equipped items are cleared from the rendered set; re-equip after status returns to ready.

Behavior change (non-breaking type-wise, breaking semantically)

• Evolution no longer blocks on item composite failure. Previously, if the bare stage image succeeded but compositing equipped items failed, the buddy stayed on the prior stage and the evolve operation was marked failed. Now the buddy advances to the new stage with its bare base image and appearance reports failed or awaiting_credits. The evolve operation completes successfully and the appearance recovery flow re-attempts the composite.
• Awaiting-credits self-recovery. When equip/evolve hits a credit limit, an internal scheduler retries with exponential backoff (60s → 5m → 15m → 30m). Clients should poll buddy.appearance rather than the original operation status to track final resolution.

0.4.1

Patch

• Docs domain — all references now point to docs.hatched.live (single canonical domain). The legacy docs.hatched.com host is retired; error messages, README links, and package.json.homepage have been updated. No API or behavior changes.

0.4.0

Minor

• Publishable-key hardening — browser keys can mint scoped read-only embed tokens, but no longer mint interactive widget sessions. Interactive session tokens stay server-only.
• Webhooks resource alignment — SDK methods now target the production /webhook-configs API and unwrap dashboard response envelopes.
• Docs/examples refresh — README snippets, widget examples, and auth guidance now match the current CDN loader and Authorization: Bearer API model.

0.3.0

Major

• Two-tier token model. Tokens now have an explicit kind: primary (spendable via buddies.spend, marketplace purchases, gate unlocks) or progression (earn-only, feeds evolution readiness). token_config DTOs unlocked from the legacy 4-tuple (hatch_token/evolution_token/reroll_token/gift_token) — customers now pick their own token_key (e.g. gems, mana, xp). Spending a progression token returns progression_not_spendable.
• Canonical item categories. The two coexisting taxonomies (hat/held_item/… vs headwear/eyewear/…) collapse into 8 canonical slots: background, body, feet, hand, neck, face, head, accessory. Migration 023 normalises existing rows and locks the column via CHECK.

Minor

• buddies.tokens(buddyId) — typed primary + progression balance snapshot with lifetime earn/spend sums.
• buddies.evolutions(buddyId) — paginated stage-transition timeline (prod + demo). Backed by a new buddy_evolutions table that captures every evolve with its image and trigger event.
• GatesResource — new hatched.gates.unlock(buddyId, gateKey) / unlocks(buddyId) primitive. Customers author gates in the dashboard (gate_key, token_key, cost, metadata); end-users spend tokens to unlock features. Unlock is idempotent — repeat calls return alreadyUnlocked: true without touching the economy.
• Equip safety rails — TooManyItemsError (max 4 equipped) and CategoryConflictError (two non-accessory items in the same category) surface at the SDK layer with details carrying the specifics.
• Stage-aware item artwork — items.stage_image_urls jsonb lets designers ship stage-2-specific hats; the composite pipeline picks the right variant per stage.
• Evolve×equip pipeline (pre-0.4.3) — the initial implementation attempted to block operations.wait(evolveOp) until equipped items were composited. In 0.4.3 this was replaced by buddy.appearance status recovery so stage advancement can complete even when item compositing is delayed.
• Theme-aware defaults — empty marketplace or token bundle at onboarding seeds from a theme-appropriate catalog (fantasy → gems/mana + fantasy items, fitness → reps/streaks, etc.). Source tracked in customers.settings.applied_sources.

0.2.1

Patch

• Docs: README now has a dedicated "Two ways to authenticate" section with a secret-vs-publishable key comparison, a browser-safe publishable-key example, and a per-resource secret/publishable capability matrix. No code changes.

0.2.0

Major

• camelCase public surface — all params and response fields exposed by the SDK are now camelCase. Snake_case wire format is converted transparently. Migration: rename user_id → userId, event_id → eventId, occurred_at → occurredAt, etc. The same applies to response fields (egg.egg_id → egg.eggId, op.operation_id → op.operationId).
• Operation.wait — operations.waitForCompletion has been replaced with the shorter operations.wait. The old name is still exported as a deprecated alias.

Minor

• Server-only runtime guard — the SDK now throws when constructed in a browser-like environment with a secret key. Override with allowBrowser: true (test-only).
• Publishable key support — browser-safe HatchedClient({ publishableKey }) constructor variant. Only read endpoints and embedTokens.create are allowed; mutation methods return PublishableKeyScopeError at runtime.
• Automatic retries — exponential backoff + jitter on network errors, 408, 429 (retry-after honoured), and 5xx. Configurable via maxRetries (default 3).
• AbortSignal on every method — pass signal to cancel in-flight requests; combined with the internal timeout via AbortSignal.any.
• Request id tracking — hatched.getLastRequestId() exposes the X-Request-Id of the most recent response. SDK-generated request ids are sent on every call.
• Webhooks resource — hatched.webhooks.list/create/delete/deliveries/replay + WebhooksResource.verifySignature(rawBody, header, secret) for Hatched-Signature verification.
• New error classes — AuthError (base for 401/403), PublishableKeyScopeError, ConfigVersionMismatchError, and a ResourceNotFoundError alias for NotFoundError.
• tsup dual build — dist/index.mjs, dist/index.cjs, plus .d.ts/.d.cts. Subpath exports for tree-shaking: @hatched/sdk-js/errors, @hatched/sdk-js/webhooks.
• sideEffects: false — enables aggressive tree-shaking by bundlers.
• timeoutMs alias — equivalent to timeout, aligns with the docs.
• fetch override — supply a custom fetch implementation for edge runtimes and tests.

Fixes

• Correct URL concatenation — paths now preserve the base /api/v1 prefix (previously absolute paths could drop it).

0.1.1

Initial private-preview release.