From 949388795f640e8bfc5da2213e18ede2e1f45370 Mon Sep 17 00:00:00 2001 From: renyuanz Date: Wed, 21 Oct 2026 23:04:26 +0800 Subject: [PATCH 1/2] feat: events.track, trackBatch and catalog (0.5.0) 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) --- README.md | 53 +++++++++++- package.json | 4 +- src/client.ts | 5 +- src/errors.ts | 9 ++ src/events.ts | 161 ++++++++++++++++++++++++++++++++++++ src/http.ts | 7 ++ src/index.ts | 12 +++ test/events.test.ts | 196 ++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 441 insertions(+), 6 deletions(-) create mode 100644 src/events.ts create mode 100644 test/events.test.ts diff --git a/README.md b/README.md index 5c81ee1..549d209 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The official Node.js / TypeScript SDK for the [Zalify](https://zalify.com) API. -It sends transactional and marketing email from your own domains through Zalify, with retries, idempotency, and typed errors. It has no runtime dependencies and needs Node 18+ (or any runtime with `fetch`). +It sends transactional and marketing email from your own domains through Zalify, keeps contacts in sync, and records your own events for automations, with retries, idempotency, and typed errors. It has no runtime dependencies and needs Node 18+ (or any runtime with `fetch`). ```bash npm install @zalify/sdk @@ -11,7 +11,7 @@ npm install @zalify/sdk ## Before you start 1. In your Zalify workspace, go to **Settings → Email** and add a sending domain, then publish the DNS records it shows (DKIM TXT + MAIL FROM CNAME). Add a `_dmarc` TXT too (`v=DMARC1; p=none` to start). -2. In **Settings → Developer**, create an API key and tick **Send email** (and **Manage contacts** to add contacts). A key can only do what it was created with. +2. In **Settings → Developer**, create an API key and tick **Send email** (**Manage contacts** to add contacts, **Track events** to record events). A key can only do what it was created with. 3. Keep the key on your server, e.g. in `ZALIFY_API_KEY`. Never ship it to a browser. ## Send an email @@ -88,6 +88,47 @@ const contact = await zalify.contacts.upsert({ - Adding a contact to a list can start that list's automations, such as a welcome series. - Calls are safe to retry; the same email updates the same contact. +## Events + +Record what people do in your product, e.g. a finished quiz or a confirmed booking, so automations can start on it, filter on its properties and stop on it. The key needs the **Track events** permission (记录事件). + +```ts +await zalify.events.track({ + event: "Quiz Completed", + customer: { externalId: user.id, email: user.email }, + properties: { result: "dry skin", score: 82 }, + uniqueId: `quiz:${attempt.id}`, +}); +// { id, profileId, duplicate: false, recordedOnly: false } +``` + +- Any name works and needs no setup: the first time an event arrives it appears in the automation editor, with its properties. Names an integration owns (`shopify_*`, `zalify.*`) are refused (`reserved_event`). +- The person is found by `externalId`, then `email`, then `phone`. Someone new is created as a contact **without** a subscription, so an event never makes anyone marketable. +- Give each event a `uniqueId`: the same id is recorded once (`duplicate: true` after that), however often you send it. +- `time` defaults to now and may be up to 365 days back. Events more than 24 hours old are recorded but never start or end an automation (`recordedOnly: true`), so importing history won't email anyone. +- `properties` is any JSON object up to 64 KB. Automations compare a field the way the condition asks (`82` and `"82"` are the same to "at least 80"), so changing a field's type doesn't break them. + +Send up to 100 at once; each event succeeds or fails on its own: + +```ts +const { accepted, failed, results } = await zalify.events.trackBatch([ + { event: "Booking Confirmed", customer: { email: "a@example.com" }, uniqueId: "booking:1" }, + { event: "Booking Confirmed", customer: { email: "b@example.com" }, uniqueId: "booking:2" }, +]); +for (const item of results) { + if (item.status === "error") console.warn(item.index, item.error.code, item.error.message); +} +``` + +List the events your automations can use: + +```ts +const { events } = await zalify.events.catalog(); +// [{ name: "Quiz Completed", source: "custom", canTrigger: true, properties: [{ path: "/score", type: "number", … }], … }] +``` + +A batch counts as one request against the key's limit of 120 requests a minute, and a workspace can record up to 1,000,000 events a day (`daily_limit`). + ## Errors, retries and idempotency Every failure is a `ZalifyError` with a stable `code`, the HTTP `status`, and `details` for validation errors. @@ -108,7 +149,7 @@ try { | code | status | meaning | | --- | --- | --- | | `unauthorized` | 401 | missing or invalid API key | -| `missing_scope` | 403 | the key lacks the permission: **Send email** or **Manage contacts** | +| `missing_scope` | 403 | the key lacks the permission: **Send email**, **Manage contacts** or **Track events** | | `email_not_enabled` | 403 | the workspace has no sending set up yet | | `contacts_not_enabled` | 403 | the workspace has no contacts set up yet | | `list_not_found` | 404 | a list in `lists` isn't in your workspace (nothing was written) | @@ -119,10 +160,16 @@ try { | `idempotency_conflict` | 409 | the idempotency key was used for a different request | | `rate_limited` | 429 | over 120 requests a minute for this key (a batch counts once) | | `new_recipient_limit` | 429 | the recipient is new to your workspace and today's allowance of new recipients is used; it resets at 00:00 UTC (`retryAfter`) | +| `invalid_event` | 422 | an event was refused, e.g. properties over 64 KB or `time` out of range (see `field`) | +| `reserved_event` | 422 | the event name belongs to an integration (`shopify_*`, `zalify.*`, …) | +| `payload_too_large` | 413 | the body is over 2 MB (one event) or 8 MB (a batch); not retried | +| `daily_limit` | 429 | the workspace recorded 1,000,000 events today (UTC) | | `unavailable` | 503 | temporary; safe to retry with the same idempotency key | The SDK retries `rate_limited`, `unavailable`, `idempotency_in_progress`, timeouts and network errors on its own, up to `maxRetries` (default 3). It honors `Retry-After`, and won't wait longer than `maxRetryDelayMs` (default 10 s). Retries always reuse the request's idempotency key, so they never send twice. +For events, give each one a `uniqueId`: without one, the SDK's idempotency key stands in for it, which only covers the SDK's own retries. + Pass your own `idempotencyKey` per logical email, such as `reset:${tokenId}` or `invite:${inviteId}`. Then even retrying the whole call after a crash or deploy sends once. Without one, the SDK makes a key per call, which only covers its own retries. ## Options diff --git a/package.json b/package.json index fd93f0c..62fe6c2 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,8 @@ { "name": "@zalify/sdk", - "version": "0.4.0", + "version": "0.5.0", "description": "Official Node.js / TypeScript SDK for the Zalify API", - "keywords": ["zalify", "email", "transactional email", "contacts", "sdk"], + "keywords": ["zalify", "email", "transactional email", "contacts", "events", "sdk"], "homepage": "https://github.com/zalify/zalify-node#readme", "repository": { "type": "git", diff --git a/src/client.ts b/src/client.ts index 2979568..2520c6e 100644 --- a/src/client.ts +++ b/src/client.ts @@ -1,9 +1,10 @@ import { Contacts } from "./contacts"; import { Emails } from "./emails"; +import { Events } from "./events"; import { Webhooks } from "./webhooks"; import type { HttpConfig } from "./http"; -export const VERSION = "0.4.0"; +export const VERSION = "0.5.0"; export type ZalifyOptions = { /** A Zalify Public API key (`zalify_api_…`). Defaults to `ZALIFY_API_KEY`. */ @@ -25,6 +26,7 @@ export type ZalifyOptions = { export class Zalify { readonly emails: Emails; readonly contacts: Contacts; + readonly events: Events; readonly webhooks: Webhooks; constructor(apiKeyOrOptions?: string | ZalifyOptions) { @@ -58,6 +60,7 @@ export class Zalify { }; this.emails = new Emails(http); this.contacts = new Contacts(http); + this.events = new Events(http); this.webhooks = new Webhooks(options.webhookSecret); } } diff --git a/src/errors.ts b/src/errors.ts index 6bea0e7..9ed8048 100644 --- a/src/errors.ts +++ b/src/errors.ts @@ -19,6 +19,11 @@ export type ZalifyErrorCode = | "unverified_sender" | "not_subscribed" | "new_recipient_limit" + | "payload_too_large" + | "invalid_event" + | "reserved_event" + | "undeclared_event" + | "daily_limit" | "suppressed" | "rejected" | "network_error" @@ -32,6 +37,8 @@ export class ZalifyError extends Error { readonly status: number; /** Field-level validation messages for `invalid_request`. */ readonly details?: string[]; + /** The offending field for event errors, e.g. `customer.externalId`. */ + readonly field?: string; /** Seconds the API asked to wait (429, 409 in progress). */ readonly retryAfter?: number; @@ -40,6 +47,7 @@ export class ZalifyError extends Error { code: ZalifyErrorCode; status: number; details?: string[]; + field?: string; retryAfter?: number; }) { super(init.message); @@ -47,6 +55,7 @@ export class ZalifyError extends Error { this.code = init.code; this.status = init.status; if (init.details) this.details = init.details; + if (init.field) this.field = init.field; if (init.retryAfter !== undefined) this.retryAfter = init.retryAfter; } diff --git a/src/events.ts b/src/events.ts new file mode 100644 index 0000000..1ea034c --- /dev/null +++ b/src/events.ts @@ -0,0 +1,161 @@ +import { randomUUID } from "node:crypto"; +import { type HttpConfig, request } from "./http"; + +export type EventCustomer = { + /** Your own id for the person (scoped to your workspace). */ + externalId?: string; + email?: string; + /** E.164, e.g. `+14155550123`. */ + phone?: string; +}; + +export type EventInput = { + /** + * The event name, e.g. `Quiz Completed` (1–64 characters, as written). + * Names owned by an integration (`shopify_*`, `zalify.*`, …) are refused. + * No registration needed: a new name shows up in the event catalog once + * it arrives. + */ + event: string; + /** + * Who did it: found by `externalId`, then `email`, then `phone`. Someone + * new is created with no subscription or consent. At least one is needed. + */ + customer: EventCustomer; + /** Any JSON object (≤ 64 KB, ≤ 5 levels deep). Flows filter on it. */ + properties?: Record; + /** An amount the event carries, e.g. an order total. */ + value?: number; + /** ISO 4217 code for `value`, e.g. `USD`. */ + valueCurrency?: string; + /** + * Your dedupe key: the same `uniqueId` is recorded once, however often + * it's sent. Without one, the SDK's idempotency key plays that part for + * its own retries. + */ + uniqueId?: string; + /** + * When it happened (default: now). Up to 365 days back; events more than + * 24 hours old are recorded but never start or end a flow. + */ + time?: Date | string; +}; + +export type TrackEventResult = { + id: string; + profileId: string; + /** The same event (same `uniqueId`) was recorded before; nothing new happened. */ + duplicate: boolean; + /** More than 24 hours old: recorded, but no flow starts or ends on it. */ + recordedOnly: boolean; +}; + +export type TrackBatchItem = + | { + index: number; + status: "accepted" | "duplicate"; + id: string; + profileId: string; + duplicate: boolean; + recordedOnly: boolean; + } + | { + index: number; + status: "error"; + error: { code: string; message: string; field?: string }; + }; + +export type TrackBatchResult = { + accepted: number; + duplicates: number; + failed: number; + /** One per event, in request order. */ + results: TrackBatchItem[]; +}; + +export type CatalogEventProperty = { + /** JSON pointer into the event's properties, e.g. `/quiz/score`. */ + path: string; + /** The type last seen; a hint only, flows choose their own comparison. */ + type: "string" | "number" | "boolean" | "date" | "list" | "object"; + label: { en: string; zh: string } | null; + /** Your own events: when the key was last seen. */ + lastSeenAt: string | null; +}; + +export type CatalogEvent = { + name: string; + label: { en: string; zh: string } | null; + /** The integration (`shopify`, `zalify`, …) or `custom` for your own events. */ + source: string; + canTrigger: boolean; + canExit: boolean; + valuePath: string | null; + properties: CatalogEventProperty[]; + available: boolean; + /** e.g. `integration_not_connected`. */ + unavailableReason: string | null; + lastSeenAt: string | null; + eventCount: number | null; +}; + +export type EventCatalog = { events: CatalogEvent[] }; + +export type TrackOptions = { + /** + * Retrying with the same key records the event once (it becomes the + * event's `uniqueId` when it has none; on a batch, `:`). + * Defaults to a fresh UUID per call, so the SDK's own retries are safe. + */ + idempotencyKey?: string; +}; + +const toBody = (input: EventInput) => ({ + ...input, + ...(input.time instanceof Date ? { time: input.time.toISOString() } : {}), +}); + +export class Events { + constructor(private readonly http: HttpConfig) {} + + /** + * Record one event. Needs a key with Track events. Counts as one request + * against the key's rate limit. + */ + async track( + input: EventInput, + options: TrackOptions = {} + ): Promise { + return request(this.http, { + method: "POST", + path: "/events", + body: toBody(input), + idempotencyKey: options.idempotencyKey ?? randomUUID(), + }); + } + + /** + * Record up to 100 events in one request; each succeeds or fails on its + * own (check `results`). The whole batch counts as one request against + * the rate limit. + */ + async trackBatch( + inputs: EventInput[], + options: TrackOptions = {} + ): Promise { + return request(this.http, { + method: "POST", + path: "/events/batch", + body: { events: inputs.map(toBody) }, + idempotencyKey: options.idempotencyKey ?? randomUUID(), + }); + } + + /** The events your flows can start, filter and exit on. */ + async catalog(): Promise { + return request(this.http, { + method: "GET", + path: "/events/catalog", + }); + } +} diff --git a/src/http.ts b/src/http.ts index aa7980f..c86c57e 100644 --- a/src/http.ts +++ b/src/http.ts @@ -131,6 +131,13 @@ async function once(config: HttpConfig, init: RequestInit): Promise { details: Array.isArray(payload.details) ? payload.details.filter((d): d is string => typeof d === "string") : undefined, + field: + payload.details && + typeof payload.details === "object" && + !Array.isArray(payload.details) && + typeof (payload.details as { field?: unknown }).field === "string" + ? (payload.details as { field: string }).field + : undefined, retryAfter: parseRetryAfter(response.headers.get("retry-after")), }); } diff --git a/src/index.ts b/src/index.ts index b2fd548..ee39893 100644 --- a/src/index.ts +++ b/src/index.ts @@ -5,6 +5,18 @@ export type { UpsertContactParams, UpsertContactResult, } from "./contacts"; +export type { + CatalogEvent, + CatalogEventProperty, + EventCatalog, + EventCustomer, + EventInput, + Events, + TrackBatchItem, + TrackBatchResult, + TrackEventResult, + TrackOptions, +} from "./events"; export type { EmailMessage, EmailSender, diff --git a/test/events.test.ts b/test/events.test.ts new file mode 100644 index 0000000..1183690 --- /dev/null +++ b/test/events.test.ts @@ -0,0 +1,196 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { Zalify, ZalifyError } from "../src/index"; + +const json = (body: unknown, status = 200, headers: Record = {}) => + new Response(JSON.stringify(body), { + status, + headers: { "content-type": "application/json", ...headers }, + }); + +const header = (init: RequestInit | undefined, name: string) => + (init?.headers as Record | undefined)?.[name]; + +test("track posts the event with an ISO time and an idempotency key", async () => { + const calls: Array<{ url: string; init: RequestInit }> = []; + const fetchImpl = (async (url: string, init: RequestInit) => { + calls.push({ url, init }); + return json( + { id: "e1", profileId: "p1", duplicate: false, recordedOnly: false }, + 202 + ); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl }); + + const result = await zalify.events.track({ + event: "Quiz Completed", + customer: { externalId: "u_1", email: "a@example.com" }, + properties: { score: 82 }, + uniqueId: "quiz:1", + time: new Date("2026-10-21T08:00:00Z"), + }); + + assert.deepEqual(result, { + id: "e1", + profileId: "p1", + duplicate: false, + recordedOnly: false, + }); + assert.equal(calls[0]?.url, "https://app.zalify.com/api/v1/events"); + assert.equal(calls[0]?.init.method, "POST"); + assert.deepEqual(JSON.parse(String(calls[0]?.init.body)), { + event: "Quiz Completed", + customer: { externalId: "u_1", email: "a@example.com" }, + properties: { score: 82 }, + uniqueId: "quiz:1", + time: "2026-10-21T08:00:00.000Z", + }); + assert.ok(header(calls[0]?.init, "Idempotency-Key")); +}); + +test("track retries 503 with the same idempotency key", async () => { + const keys: Array = []; + const responses = [ + json({ error: "Temporarily unavailable", code: "unavailable" }, 503), + json({ id: "e1", profileId: "p1", duplicate: false, recordedOnly: false }, 202), + ]; + const fetchImpl = (async (_url: string, init: RequestInit) => { + keys.push(header(init, "Idempotency-Key")); + return responses.shift(); + }) as unknown as typeof fetch; + const zalify = new Zalify({ + apiKey: "zalify_api_test", + fetch: fetchImpl, + maxRetryDelayMs: 5, + }); + + await zalify.events.track({ event: "Signed Up", customer: { email: "a@example.com" } }); + assert.equal(keys.length, 2); + assert.ok(keys[0]); + assert.equal(keys[0], keys[1]); +}); + +test("track passes a caller's idempotency key through", async () => { + let key: string | undefined; + const fetchImpl = (async (_url: string, init: RequestInit) => { + key = header(init, "Idempotency-Key"); + return json({ id: "e1", profileId: "p1", duplicate: true, recordedOnly: false }, 202); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl }); + + const result = await zalify.events.track( + { event: "Signed Up", customer: { email: "a@example.com" } }, + { idempotencyKey: "signup:42" } + ); + assert.equal(key, "signup:42"); + assert.equal(result.duplicate, true); +}); + +test("trackBatch returns per-event results in order", async () => { + let body: unknown; + const fetchImpl = (async (url: string, init: RequestInit) => { + assert.equal(url, "https://app.zalify.com/api/v1/events/batch"); + body = JSON.parse(String(init.body)); + return json({ + accepted: 1, + duplicates: 0, + failed: 1, + results: [ + { index: 0, status: "accepted", id: "e1", profileId: "p1", duplicate: false, recordedOnly: false }, + { + index: 1, + status: "error", + error: { code: "reserved_event", message: "'shopify_order_paid' belongs to Shopify", field: "event" }, + }, + ], + }); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl }); + + const result = await zalify.events.trackBatch([ + { event: "Booking Confirmed", customer: { email: "a@example.com" }, time: "2026-10-21T08:00:00Z" }, + { event: "shopify_order_paid", customer: { email: "b@example.com" } }, + ]); + + assert.deepEqual(body, { + events: [ + { event: "Booking Confirmed", customer: { email: "a@example.com" }, time: "2026-10-21T08:00:00Z" }, + { event: "shopify_order_paid", customer: { email: "b@example.com" } }, + ], + }); + assert.equal(result.failed, 1); + const second = result.results[1]; + assert.equal(second?.status, "error"); + if (second?.status === "error") assert.equal(second.error.code, "reserved_event"); +}); + +test("event errors carry code and field and are not retried", async () => { + let calls = 0; + const fetchImpl = (async () => { + calls++; + return json( + { + error: "properties must be 64 KB or less", + code: "invalid_event", + details: { field: "properties" }, + }, + 422 + ); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl, maxRetryDelayMs: 5 }); + + await assert.rejects( + zalify.events.track({ event: "Big", customer: { email: "a@example.com" } }), + (error: unknown) => + error instanceof ZalifyError && + error.code === "invalid_event" && + error.status === 422 && + error.field === "properties" + ); + assert.equal(calls, 1); +}); + +test("413 payload_too_large is not retried", async () => { + let calls = 0; + const fetchImpl = (async () => { + calls++; + return json({ error: "The request body must be 8 MB or less.", code: "payload_too_large" }, 413); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl, maxRetryDelayMs: 5 }); + + await assert.rejects( + zalify.events.trackBatch([{ event: "X", customer: { email: "a@example.com" } }]), + (error: unknown) => + error instanceof ZalifyError && error.code === "payload_too_large" && !error.retryable + ); + assert.equal(calls, 1); +}); + +test("catalog reads the event catalog", async () => { + const fetchImpl = (async (url: string, init: RequestInit) => { + assert.equal(url, "https://app.zalify.com/api/v1/events/catalog"); + assert.equal(init.method, "GET"); + return json({ + events: [ + { + name: "Quiz Completed", + label: null, + source: "custom", + canTrigger: true, + canExit: true, + valuePath: null, + properties: [{ path: "/score", type: "number", label: null, lastSeenAt: "2026-10-21T08:00:00Z" }], + available: true, + unavailableReason: null, + lastSeenAt: "2026-10-21T08:00:00Z", + eventCount: 3, + }, + ], + }); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl }); + + const { events } = await zalify.events.catalog(); + assert.equal(events[0]?.name, "Quiz Completed"); + assert.equal(events[0]?.properties[0]?.type, "number"); +}); From 94c94604a44c057c2e5afcc411fcd900007a7959 Mon Sep 17 00:00:00 2001 From: renyuanz Date: Wed, 21 Oct 2026 23:10:12 +0800 Subject: [PATCH 2/2] fix(events): content dedupe for retries instead of an auto idempotency 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 (: 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) --- .github/workflows/ci.yml | 3 +- README.md | 5 ++- src/events.ts | 71 ++++++++++++++++++++++++++-------- test/events.test.ts | 82 ++++++++++++++++++++++++++++++++++++---- 4 files changed, 136 insertions(+), 25 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1f8b1a0..46eff33 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,7 +24,8 @@ jobs: - uses: actions/setup-node@v4 with: node-version: ${{ matrix.node }} - - run: node --import tsx --test test/emails.test.ts test/webhooks.test.ts + # Files listed explicitly: Node 18's --test takes no globs. + - run: node --import tsx --test test/contacts.test.ts test/emails.test.ts test/events.test.ts test/webhooks.test.ts - name: Built package loads (CJS + ESM) run: | node -e "const { Zalify } = require('./dist/index.cjs'); new Zalify('k')" diff --git a/README.md b/README.md index 549d209..60b6013 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,8 @@ await zalify.events.track({ - Any name works and needs no setup: the first time an event arrives it appears in the automation editor, with its properties. Names an integration owns (`shopify_*`, `zalify.*`) are refused (`reserved_event`). - The person is found by `externalId`, then `email`, then `phone`. Someone new is created as a contact **without** a subscription, so an event never makes anyone marketable. -- Give each event a `uniqueId`: the same id is recorded once (`duplicate: true` after that), however often you send it. +- Give each event a `uniqueId`: the same id is recorded once, however often you send it. `duplicate: true` means it was already recorded, by an earlier call or by an earlier attempt of this one that the SDK retried. +- Without a `uniqueId`, the API dedupes on the event's content (name, person, `time`, properties). The SDK sets `time` before the first attempt, so its own retries can't record an event twice. - `time` defaults to now and may be up to 365 days back. Events more than 24 hours old are recorded but never start or end an automation (`recordedOnly: true`), so importing history won't email anyone. - `properties` is any JSON object up to 64 KB. Automations compare a field the way the condition asks (`82` and `"82"` are the same to "at least 80"), so changing a field's type doesn't break them. @@ -168,7 +169,7 @@ try { The SDK retries `rate_limited`, `unavailable`, `idempotency_in_progress`, timeouts and network errors on its own, up to `maxRetries` (default 3). It honors `Retry-After`, and won't wait longer than `maxRetryDelayMs` (default 10 s). Retries always reuse the request's idempotency key, so they never send twice. -For events, give each one a `uniqueId`: without one, the SDK's idempotency key stands in for it, which only covers the SDK's own retries. +For events, give each one a `uniqueId` rather than an `idempotencyKey`. If you do pass an `idempotencyKey` to `track`/`trackBatch`, use a new one for every call: events without a `uniqueId` take `` (or `:` in a batch) as their dedupe key, so reusing a key across different batches makes the later ones come back as duplicates without being recorded. Pass your own `idempotencyKey` per logical email, such as `reset:${tokenId}` or `invite:${inviteId}`. Then even retrying the whole call after a crash or deploy sends once. Without one, the SDK makes a key per call, which only covers its own retries. diff --git a/src/events.ts b/src/events.ts index 1ea034c..72af2f6 100644 --- a/src/events.ts +++ b/src/events.ts @@ -1,4 +1,4 @@ -import { randomUUID } from "node:crypto"; +import { ZalifyError } from "./errors"; import { type HttpConfig, request } from "./http"; export type EventCustomer = { @@ -30,8 +30,9 @@ export type EventInput = { valueCurrency?: string; /** * Your dedupe key: the same `uniqueId` is recorded once, however often - * it's sent. Without one, the SDK's idempotency key plays that part for - * its own retries. + * it's sent. Without one, the API dedupes on the event's content (name, + * person, time, properties); the SDK fixes `time` before the first + * attempt so its own retries resend the same event. */ uniqueId?: string; /** @@ -44,7 +45,10 @@ export type EventInput = { export type TrackEventResult = { id: string; profileId: string; - /** The same event (same `uniqueId`) was recorded before; nothing new happened. */ + /** + * The event was already recorded, by an earlier call or by an earlier + * attempt of this one that the SDK retried. Either way it's recorded once. + */ duplicate: boolean; /** More than 24 hours old: recorded, but no flow starts or ends on it. */ recordedOnly: boolean; @@ -103,17 +107,47 @@ export type EventCatalog = { events: CatalogEvent[] }; export type TrackOptions = { /** - * Retrying with the same key records the event once (it becomes the - * event's `uniqueId` when it has none; on a batch, `:`). - * Defaults to a fresh UUID per call, so the SDK's own retries are safe. + * Optional. Retrying the whole call with the same key records each event + * once: an event without a `uniqueId` takes the key as its dedupe key + * (`:` on a batch). Use a new key for every call: reusing one + * across different batches makes event N of each batch collide, and the + * later ones come back as duplicates without being recorded. Prefer + * `uniqueId` on the events themselves. At most 255 characters (251 on a + * batch). */ idempotencyKey?: string; }; -const toBody = (input: EventInput) => ({ - ...input, - ...(input.time instanceof Date ? { time: input.time.toISOString() } : {}), -}); +const MAX_IDEMPOTENCY_KEY = 255; + +const invalid = (message: string, field?: string) => + new ZalifyError({ message, code: "invalid_request", status: 0, field }); + +/** + * The event as sent. `time` is fixed here, once, before the first attempt + * (now when not given), so a retry resends an identical body and the API's + * content dedupe records the event once. + */ +const toBody = (input: EventInput, now: string, field = "time") => { + let time: string; + if (input.time === undefined) { + time = now; + } else if (input.time instanceof Date) { + if (Number.isNaN(input.time.getTime())) { + throw invalid("time is an invalid Date", field); + } + time = input.time.toISOString(); + } else { + time = input.time; + } + return { ...input, time }; +}; + +const checkKey = (key: string | undefined, max: number) => { + if (key !== undefined && key.length > max) { + throw invalid(`idempotencyKey must be ${max} characters or fewer`); + } +}; export class Events { constructor(private readonly http: HttpConfig) {} @@ -126,11 +160,13 @@ export class Events { input: EventInput, options: TrackOptions = {} ): Promise { + checkKey(options.idempotencyKey, MAX_IDEMPOTENCY_KEY); + const body = toBody(input, new Date().toISOString()); return request(this.http, { method: "POST", path: "/events", - body: toBody(input), - idempotencyKey: options.idempotencyKey ?? randomUUID(), + body, + idempotencyKey: options.idempotencyKey, }); } @@ -143,11 +179,16 @@ export class Events { inputs: EventInput[], options: TrackOptions = {} ): Promise { + checkKey(options.idempotencyKey, MAX_IDEMPOTENCY_KEY - 4); + const now = new Date().toISOString(); + const events = inputs.map((input, index) => + toBody(input, now, `events.${index}.time`) + ); return request(this.http, { method: "POST", path: "/events/batch", - body: { events: inputs.map(toBody) }, - idempotencyKey: options.idempotencyKey ?? randomUUID(), + body: { events }, + idempotencyKey: options.idempotencyKey, }); } diff --git a/test/events.test.ts b/test/events.test.ts index 1183690..058229e 100644 --- a/test/events.test.ts +++ b/test/events.test.ts @@ -11,7 +11,7 @@ const json = (body: unknown, status = 200, headers: Record = {}) const header = (init: RequestInit | undefined, name: string) => (init?.headers as Record | undefined)?.[name]; -test("track posts the event with an ISO time and an idempotency key", async () => { +test("track posts the event with an ISO time and no idempotency key", async () => { const calls: Array<{ url: string; init: RequestInit }> = []; const fetchImpl = (async (url: string, init: RequestInit) => { calls.push({ url, init }); @@ -45,16 +45,18 @@ test("track posts the event with an ISO time and an idempotency key", async () = uniqueId: "quiz:1", time: "2026-10-21T08:00:00.000Z", }); - assert.ok(header(calls[0]?.init, "Idempotency-Key")); + assert.equal(header(calls[0]?.init, "Idempotency-Key"), undefined); }); -test("track retries 503 with the same idempotency key", async () => { +test("track fixes time once, so a 503 retry resends the same body", async () => { + const bodies: string[] = []; const keys: Array = []; const responses = [ json({ error: "Temporarily unavailable", code: "unavailable" }, 503), json({ id: "e1", profileId: "p1", duplicate: false, recordedOnly: false }, 202), ]; const fetchImpl = (async (_url: string, init: RequestInit) => { + bodies.push(String(init.body)); keys.push(header(init, "Idempotency-Key")); return responses.shift(); }) as unknown as typeof fetch; @@ -65,9 +67,75 @@ test("track retries 503 with the same idempotency key", async () => { }); await zalify.events.track({ event: "Signed Up", customer: { email: "a@example.com" } }); - assert.equal(keys.length, 2); - assert.ok(keys[0]); - assert.equal(keys[0], keys[1]); + assert.equal(bodies.length, 2); + assert.equal(bodies[0], bodies[1]); + assert.match(JSON.parse(bodies[0] ?? "{}").time, /^\d{4}-\d{2}-\d{2}T/); + assert.deepEqual(keys, [undefined, undefined]); +}); + +test("trackBatch fixes time once, so a 503 retry resends the same body", async () => { + const bodies: string[] = []; + const responses = [ + json({ error: "Temporarily unavailable", code: "unavailable" }, 503), + json({ accepted: 2, duplicates: 0, failed: 0, results: [] }), + ]; + const fetchImpl = (async (_url: string, init: RequestInit) => { + bodies.push(String(init.body)); + return responses.shift(); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl, maxRetryDelayMs: 5 }); + + await zalify.events.trackBatch([ + { event: "A", customer: { email: "a@example.com" } }, + { event: "B", customer: { email: "b@example.com" } }, + ]); + assert.equal(bodies.length, 2); + assert.equal(bodies[0], bodies[1]); +}); + +test("daily_limit 429 is not retried", async () => { + let calls = 0; + const fetchImpl = (async () => { + calls++; + return json({ error: "Daily event limit reached", code: "daily_limit" }, 429); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl, maxRetryDelayMs: 5 }); + + await assert.rejects( + zalify.events.track({ event: "X", customer: { email: "a@example.com" } }), + (error: unknown) => error instanceof ZalifyError && error.code === "daily_limit" + ); + assert.equal(calls, 1); +}); + +test("an invalid Date or an over-long key fails before any request", async () => { + let calls = 0; + const fetchImpl = (async () => { + calls++; + return json({}); + }) as unknown as typeof fetch; + const zalify = new Zalify({ apiKey: "zalify_api_test", fetch: fetchImpl }); + + await assert.rejects( + zalify.events.track({ event: "X", customer: { email: "a@example.com" }, time: new Date("nope") }), + (error: unknown) => + error instanceof ZalifyError && error.code === "invalid_request" && error.field === "time" + ); + await assert.rejects( + zalify.events.trackBatch( + [{ event: "X", customer: { email: "a@example.com" } }], + { idempotencyKey: "k".repeat(252) } + ), + (error: unknown) => error instanceof ZalifyError && error.code === "invalid_request" + ); + await assert.rejects( + zalify.events.track( + { event: "X", customer: { email: "a@example.com" } }, + { idempotencyKey: "k".repeat(256) } + ), + (error: unknown) => error instanceof ZalifyError && error.code === "invalid_request" + ); + assert.equal(calls, 0); }); test("track passes a caller's idempotency key through", async () => { @@ -115,7 +183,7 @@ test("trackBatch returns per-event results in order", async () => { assert.deepEqual(body, { events: [ { event: "Booking Confirmed", customer: { email: "a@example.com" }, time: "2026-10-21T08:00:00Z" }, - { event: "shopify_order_paid", customer: { email: "b@example.com" } }, + { event: "shopify_order_paid", customer: { email: "b@example.com" }, time: (body as { events: Array<{ time: string }> }).events[1]?.time }, ], }); assert.equal(result.failed, 1);