Skip to content

SDK 0.5.0: events.track, trackBatch and catalog (ZAL-17) - #3

Merged
renyuanz merged 2 commits into
mainfrom
feat/events-0.5.0
Oct 21, 2026
Merged

renyuanz merged 2 commits into
mainfrom
feat/events-0.5.0

Conversation

@renyuanz

Copy link
Copy Markdown
Contributor

Adds the Events API client for ZAL-17. The public endpoints are live in the app (app#2371): POST /api/v1/events, POST /api/v1/events/batch, GET /api/v1/events/catalog.

  • zalify.events.track(input, { idempotencyKey? }), zalify.events.trackBatch(inputs, …) (≤ 100, per-event results), zalify.events.catalog().
  • Every write sends an Idempotency-Key (fresh UUID unless given). The API uses it as the dedupe key for events without a uniqueId (<key>:<index> on a batch), so the SDK's built-in retries on 429/503/timeouts never record an event twice. A test checks the retry reuses the key.
  • time accepts Date | string; Dates are sent as ISO 8601.
  • ZalifyError gains field (from the API's details.field on event errors). New codes: invalid_event, reserved_event, undeclared_event, payload_too_large (413, not retried), daily_limit.
  • README: Events section (Track events permission, uniqueId, 24-hour rule, batch counts as one request against 120/min, 1M events/day), error table rows.
  • Version 0.5.0 in package.json and VERSION.

Tests: 22 pass (7 new in test/events.test.ts); tsc --noEmit clean; tsup build OK.

Merging publishes: publish.yml on main publishes @zalify/sdk when package.json changes and the version isn't on npm yet, so merging this releases 0.5.0. (The local ci/auto-publish branch is not on main, but main already has a version-driven publish workflow.)

🤖 Generated with Claude Code

renyuanz and others added 2 commits October 21, 2026 23:04
Records a workspace's own events for automations (ZAL-17) through
POST /events, POST /events/batch and GET /events/catalog.

- every track/trackBatch call sends an Idempotency-Key (a fresh UUID
  unless given); the API uses it as the dedupe key for events without
  a uniqueId, so the SDK's own retries never record twice
- time accepts a Date (sent as ISO 8601)
- ZalifyError gains field for event errors; new codes invalid_event,
  reserved_event, undeclared_event, payload_too_large (not retried),
  daily_limit
- README: Events section, error table rows

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
…y key

Review follow-ups:
- no auto Idempotency-Key: it replaced the API's content dedupe, so
  re-running a history import without uniqueIds recorded everything
  again. time is now fixed client-side before the first attempt, so a
  retry resends an identical body and the content hash dedupes it; a
  caller's key passes through unchanged
- JSDoc + README: a caller key must be new per call (<key>:<index>
  collides across batches); duplicate means already recorded, possibly
  by an earlier attempt of the same call
- invalid Date and over-long keys (255, 251 on a batch) fail as
  ZalifyError before any request
- tests: batch retry resends the same body, daily_limit not retried,
  client-side validation
- CI runs contacts and events tests too

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
@renyuanz
renyuanz merged commit 4df184a into main Oct 21, 2026
3 checks passed
@renyuanz
renyuanz deleted the feat/events-0.5.0 branch October 21, 2026 15:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant