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 5c81ee1..60b6013 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,48 @@ 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, 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. + +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 +150,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 +161,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` 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. ## 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..72af2f6 --- /dev/null +++ b/src/events.ts @@ -0,0 +1,202 @@ +import { ZalifyError } from "./errors"; +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 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; + /** + * 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 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; +}; + +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 = { + /** + * 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 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) {} + + /** + * 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 { + checkKey(options.idempotencyKey, MAX_IDEMPOTENCY_KEY); + const body = toBody(input, new Date().toISOString()); + return request(this.http, { + method: "POST", + path: "/events", + body, + idempotencyKey: options.idempotencyKey, + }); + } + + /** + * 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 { + 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 }, + idempotencyKey: options.idempotencyKey, + }); + } + + /** 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..058229e --- /dev/null +++ b/test/events.test.ts @@ -0,0 +1,264 @@ +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 no 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.equal(header(calls[0]?.init, "Idempotency-Key"), undefined); +}); + +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; + 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(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 () => { + 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" }, time: (body as { events: Array<{ time: string }> }).events[1]?.time }, + ], + }); + 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"); +});