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

@hatched/sdk-js

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.
• Atomic evolve×equip — operations.wait(evolveOp) now returns the final stage image with all equipped items already composited. Previously the client observed a bare-stage frame before items reappeared. Demo path also unified.
• 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 widgetSessions.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.