From d2232db3c6697cef2568494fb2aa8bc8cdf059c4 Mon Sep 17 00:00:00 2001 From: renyuanz Date: Tue, 13 Oct 2026 12:04:13 +0800 Subject: [PATCH 1/3] fix: call fetch on its own so the SDK works on Cloudflare Workers Workers throw "Illegal invocation" when fetch runs with a this other than the global, and config.fetch(...) passed the config object. Found sending Offdesk email from a Worker. Bumps to 0.3.1. Co-Authored-By: Claude Opus 5.5 (1M context) --- package.json | 2 +- src/client.ts | 2 +- src/http.ts | 5 ++++- test/emails.test.ts | 9 +++++++++ 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/package.json b/package.json index 205fe4d..b8a5460 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@zalify/sdk", - "version": "0.3.0", + "version": "0.3.1", "description": "Official Node.js / TypeScript SDK for the Zalify API", "keywords": ["zalify", "email", "transactional email", "contacts", "sdk"], "homepage": "https://github.com/zalify/zalify-node#readme", diff --git a/src/client.ts b/src/client.ts index 61deea2..5e6bace 100644 --- a/src/client.ts +++ b/src/client.ts @@ -3,7 +3,7 @@ import { Emails } from "./emails"; import { Webhooks } from "./webhooks"; import type { HttpConfig } from "./http"; -export const VERSION = "0.3.0"; +export const VERSION = "0.3.1"; export type ZalifyOptions = { /** A Zalify Public API key (`zalify_api_…`). Defaults to `ZALIFY_API_KEY`. */ diff --git a/src/http.ts b/src/http.ts index a81e9df..aa7980f 100644 --- a/src/http.ts +++ b/src/http.ts @@ -64,9 +64,12 @@ export async function request( async function once(config: HttpConfig, init: RequestInit): Promise { const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), config.timeoutMs); + // Called on its own, not as config.fetch(...): Cloudflare Workers reject a fetch + // invoked with any other `this` ("Illegal invocation"). + const fetchImpl = config.fetch; let response: Response; try { - response = await config.fetch(`${config.baseUrl}${init.path}`, { + response = await fetchImpl(`${config.baseUrl}${init.path}`, { method: init.method, headers: { Authorization: `Bearer ${config.apiKey}`, diff --git a/test/emails.test.ts b/test/emails.test.ts index 6a6a02d..eead6c1 100644 --- a/test/emails.test.ts +++ b/test/emails.test.ts @@ -41,6 +41,15 @@ const client = (fetchImpl: typeof fetch, extra = {}) => ...extra, }); +test("fetch is called on its own, as Cloudflare Workers require", async () => { + // Workers throw "Illegal invocation" when fetch runs with another `this` + const fetchImpl = function (this: unknown) { + if (this !== undefined && this !== globalThis) throw new TypeError("Illegal invocation"); + return Promise.resolve(json({ id: "msg_1" })); + } as unknown as typeof fetch; + assert.deepEqual(await client(fetchImpl).emails.send(message), { id: "msg_1" }); +}); + test("send posts the message with the key and an idempotency key", async () => { const { calls, fetchImpl } = scripted([json({ id: "msg_1" })]); const result = await client(fetchImpl).emails.send( From e290e2b16131aeec39a45f8d4dea39e283b59f41 Mon Sep 17 00:00:00 2001 From: renyuanz Date: Tue, 13 Oct 2026 12:14:09 +0800 Subject: [PATCH 2/3] feat: send from a sender email by id; publish from GitHub releases - senderEmailId on a message, instead of from: a sender email from Settings -> Email, whose name, address and Reply-To are used. - emails.listSenders() lists them (GET /email/senders). - .github/workflows/publish.yml publishes to npm with provenance when a GitHub release is published (tag must match package.json), using the NPM_TOKEN repository secret. - 0.4.0. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/publish.yml | 32 ++++++++++++++++++++++++++ README.md | 16 +++++++++++++ package.json | 2 +- src/client.ts | 2 +- src/emails.ts | 42 ++++++++++++++++++++++++++++++++--- src/index.ts | 2 ++ test/emails.test.ts | 27 ++++++++++++++++++++++ 7 files changed, 118 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..e062e06 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,32 @@ +name: Publish +# Publishes @zalify/sdk to npm when a release is published on GitHub. The +# release tag must match package.json's version (v0.4.0 → "0.4.0"). +on: + release: + types: [published] +permissions: + contents: read + id-token: write # npm provenance +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: pnpm + registry-url: https://registry.npmjs.org + - name: Tag matches package.json + run: | + version=$(node -p "require('./package.json').version") + if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then + echo "Release tag ${GITHUB_REF_NAME} doesn't match package.json version ${version}" >&2 + exit 1 + fi + - run: pnpm install --frozen-lockfile + # prepublishOnly runs typecheck, tests and build + - run: pnpm publish --access public --provenance --no-git-checks + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/README.md b/README.md index a15a939..5c81ee1 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,22 @@ const { id } = await zalify.emails.send( - A recipient on your suppression list (an earlier hard bounce or spam complaint) still gets an `id`, but the message is not delivered. - Each day your workspace can email a limited number of addresses it has never emailed before. New workspaces start at 1,000 a day for transactional mail and 500 for marketing. The limit doubles after each day with low bounce and complaint rates, and goes away once it reaches 50,000. Over the limit, sends fail with `new_recipient_limit` (marketing waits until the next day). People you've emailed before are never limited. +### Send from a sender set up in Zalify + +Instead of `from`, pass `senderEmailId`: a sender email from **Settings → Email**. Its name, address and Reply-To are used (your `replyTo` still wins), so they're managed in Zalify rather than in your code. + +```ts +const { data: senders } = await zalify.emails.listSenders(); +// [{ id, name, email, replyTo, verified }] + +await zalify.emails.send( + { senderEmailId: process.env.ZALIFY_SENDER_EMAIL_ID, to, subject, html }, + { idempotencyKey: `reset:${tokenId}` } +); +``` + +A message takes `from` or `senderEmailId`, not both. A sender that isn't in your workspace or isn't verified yet fails with `unverified_sender`. + ## Send a batch Send up to 100 messages in one request. A refused message doesn't fail the others. diff --git a/package.json b/package.json index b8a5460..fd93f0c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@zalify/sdk", - "version": "0.3.1", + "version": "0.4.0", "description": "Official Node.js / TypeScript SDK for the Zalify API", "keywords": ["zalify", "email", "transactional email", "contacts", "sdk"], "homepage": "https://github.com/zalify/zalify-node#readme", diff --git a/src/client.ts b/src/client.ts index 5e6bace..2979568 100644 --- a/src/client.ts +++ b/src/client.ts @@ -3,7 +3,7 @@ import { Emails } from "./emails"; import { Webhooks } from "./webhooks"; import type { HttpConfig } from "./http"; -export const VERSION = "0.3.1"; +export const VERSION = "0.4.0"; export type ZalifyOptions = { /** A Zalify Public API key (`zalify_api_…`). Defaults to `ZALIFY_API_KEY`. */ diff --git a/src/emails.ts b/src/emails.ts index 56fe477..17abe5c 100644 --- a/src/emails.ts +++ b/src/emails.ts @@ -9,11 +9,27 @@ import { type HttpConfig, request } from "./http"; */ export type EmailType = "transactional" | "marketing"; -export type EmailMessage = { - /** `Name
` or a bare address, on a domain verified in Zalify. */ - from: string; +/** + * The sender: a `from` address, or `senderEmailId`, a sender email set up in + * Zalify (Settings → Email; list them with `emails.listSenders()`) whose + * name, address and Reply-To are then used. + */ +export type EmailSender = + | { + /** `Name
` or a bare address, on a domain verified in Zalify. */ + from: string; + senderEmailId?: never; + } + | { + /** A sender email's `id` from `emails.listSenders()`. */ + senderEmailId: string; + from?: never; + }; + +export type EmailMessage = EmailSender & { /** One recipient. Send one message per recipient. */ to: string; + /** Defaults to the sender email's Reply-To with `senderEmailId`. */ replyTo?: string; subject: string; /** Rendered HTML, up to 5 MB. */ @@ -30,6 +46,18 @@ export type EmailMessage = { export type SendEmailParams = EmailMessage & { type?: EmailType }; +/** A sender email from Settings → Email. */ +export type SenderEmail = { + /** Pass as `senderEmailId`. */ + id: string; + name: string; + email: string; + /** Where replies go; null when they go to `email`. */ + replyTo: string | null; + /** Ready to send from. Sends from an unverified sender fail with `unverified_sender`. */ + verified: boolean; +}; + export type SendEmailResult = { /** * The message id. A recipient on your suppression list (an earlier hard @@ -86,6 +114,14 @@ export class Emails { }); } + /** The sender emails your workspace can send from, for `senderEmailId`. */ + async listSenders(): Promise<{ data: SenderEmail[] }> { + return request<{ data: SenderEmail[] }>(this.http, { + method: "GET", + path: "/email/senders", + }); + } + /** * Send up to 100 emails in one request. A refused message doesn't fail the * others: check each entry of `data` for `id` or `error`. diff --git a/src/index.ts b/src/index.ts index 3779ce7..b2fd548 100644 --- a/src/index.ts +++ b/src/index.ts @@ -7,12 +7,14 @@ export type { } from "./contacts"; export type { EmailMessage, + EmailSender, EmailSendError, EmailType, SendBatchParams, SendBatchResult, SendEmailParams, SendEmailResult, + SenderEmail, RequestOptions, } from "./emails"; export { diff --git a/test/emails.test.ts b/test/emails.test.ts index eead6c1..dbc085d 100644 --- a/test/emails.test.ts +++ b/test/emails.test.ts @@ -179,3 +179,30 @@ test("a custom baseUrl is used without a trailing slash", async () => { ); assert.equal(calls[0]?.url, "http://localhost:3000/api/v1/email/send"); }); + +test("send can name a sender email instead of a from address", async () => { + const { calls, fetchImpl } = scripted([json({ id: "msg_1" })]); + const { from: _from, ...rest } = message; + await client(fetchImpl).emails.send({ ...rest, senderEmailId: "se_1" }); + assert.deepEqual(JSON.parse(String(calls[0]?.init.body)), { + ...rest, + senderEmailId: "se_1", + }); +}); + +test("listSenders gets the workspace's sender emails", async () => { + const sender = { + id: "se_1", + name: "Offdesk", + email: "notifications@offdesk.dev", + replyTo: null, + verified: true, + }; + const { calls, fetchImpl } = scripted([json({ data: [sender] })]); + assert.deepEqual(await client(fetchImpl).emails.listSenders(), { + data: [sender], + }); + assert.equal(calls[0]?.url, "https://app.zalify.com/api/v1/email/senders"); + assert.equal(calls[0]?.init.method, "GET"); + assert.equal(calls[0]?.init.body, undefined); +}); From ec51ff3363668ebebd7ceb54591f16f777664803 Mon Sep 17 00:00:00 2001 From: renyuanz Date: Tue, 13 Oct 2026 12:28:01 +0800 Subject: [PATCH 3/3] ci: publish with npm Trusted Publishing when the version is new Like zalify-theme-2026's npm-publish.yml: on push to main, publish if package.json's version isn't on npm yet, authenticated by OIDC instead of an NPM_TOKEN secret. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/publish.yml | 54 +++++++++++++++++++++++------------ 1 file changed, 36 insertions(+), 18 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index e062e06..7d233bd 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,32 +1,50 @@ -name: Publish -# Publishes @zalify/sdk to npm when a release is published on GitHub. The -# release tag must match package.json's version (v0.4.0 → "0.4.0"). +# Publishes @zalify/sdk to npm. +# +# Version-driven: on every push to main (or manual dispatch), if +# package.json's version isn't on npm yet it's published. Releasing is just +# "bump the version, merge"; nothing happens when the version is already out. +# +# Auth is npm Trusted Publishing (OIDC), no token secret. One-time setup on +# npmjs.com (the package must already exist, so the first publish is +# manual): @zalify/sdk → Settings → Trusted Publisher → GitHub Actions, +# repository zalify/zalify-node, workflow "publish.yml". Provenance +# attestations are attached automatically. + +name: npm publish + on: - release: - types: [published] + push: + branches: [main] + workflow_dispatch: + permissions: contents: read - id-token: write # npm provenance + id-token: write # npm Trusted Publishing (OIDC) + +concurrency: + group: npm-publish + cancel-in-progress: false + jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - uses: pnpm/action-setup@v4 + - uses: pnpm/action-setup@v4 # version comes from packageManager in package.json - uses: actions/setup-node@v4 with: - node-version: 22 + node-version: 24 cache: pnpm registry-url: https://registry.npmjs.org - - name: Tag matches package.json + # Trusted Publishing needs npm >= 11.5.1. + - run: npm install -g npm@latest && npm --version + - run: pnpm install --frozen-lockfile + - name: Publish @zalify/sdk (if the version is new) run: | - version=$(node -p "require('./package.json').version") - if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then - echo "Release tag ${GITHUB_REF_NAME} doesn't match package.json version ${version}" >&2 - exit 1 + V=$(node -p "require('./package.json').version") + if npm view "@zalify/sdk@$V" version >/dev/null 2>&1; then + echo "@zalify/sdk@$V already on npm, skipping" + else + # prepublishOnly runs typecheck, tests and build; pnpm >= 10.14 handles OIDC + pnpm publish --access public --no-git-checks fi - - run: pnpm install --frozen-lockfile - # prepublishOnly runs typecheck, tests and build - - run: pnpm publish --access public --provenance --no-git-checks - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}