@growth-labs/notify 0.1.0

package/README.md

@@ -0,0 +1,226 @@
+# @growth-labs/notify
+
+Worker-compatible human notification delivery for Slack and email.
+
+Use this package when a Worker needs to alert people about operational events:
+daily digest completion/failure, auth monitor incidents, Tail Worker error
+capture, or migration status updates.
+
+It is deliberately small:
+
+- Slack incoming webhooks
+- Cloudflare Send Email binding
+- Resend REST API fallback
+- fixed severity routing
+- caller-supplied dedup and audit hooks
+- no D1, KV, queues, or background work
+
+## Install
+
+```bash
+pnpm add @growth-labs/notify
+```
+
+## Basic Usage
+
+```ts
+import { notify } from '@growth-labs/notify'
+
+const result = await notify(env, {
+	channels: ['slack', 'email'],
+	severity: 'critical',
+	title: 'Auth surface down',
+	body: '/login/ returning 503 for 12 minutes. Last good: 09:32 UTC.',
+	dedupKey: 'auth-monitor:fronts.co:login:down',
+	dedupFn: async (key) => {
+		// Caller-owned persistence, for example D1 or KV.
+		return false
+	},
+	onSent: async (record) => {
+		// Caller-owned audit log.
+		console.log(record)
+	},
+})
+
+if (result.failed.length > 0) {
+	console.warn('Notification delivery failed', result.failed)
+}
+```
+
+## Severity Routing
+
+The caller always provides the requested channel list. Severity filters that
+list:
+
+| Severity | Slack | Email |
+| --- | --- | --- |
+| `info` | yes | no |
+| `warning` | yes | no |
+| `critical` | yes | yes |
+
+Example: `channels: ['email']` with `severity: 'info'` sends nothing and
+returns:
+
+```ts
+{
+	attempted: ['email'],
+	sent: [],
+	skipped: [{ channel: 'email', reason: 'severity-routing' }],
+	failed: [],
+}
+```
+
+Routing is not configurable in v0.1. If an event should reach email, it should
+be `critical`.
+
+## Environment
+
+```ts
+interface NotifyEnv {
+	NOTIFY_SLACK_WEBHOOK?: string
+	SEND_EMAIL?: { send(message: unknown): Promise<unknown> }
+	RESEND_API_KEY?: string
+	NOTIFY_EMAIL_TO?: string
+	NOTIFY_EMAIL_FROM?: string
+}
+```
+
+| Channel | Required values |
+| --- | --- |
+| Slack | `NOTIFY_SLACK_WEBHOOK` |
+| Email via Cloudflare | `SEND_EMAIL`, `NOTIFY_EMAIL_TO`, `NOTIFY_EMAIL_FROM` |
+| Email via Resend | `RESEND_API_KEY`, `NOTIFY_EMAIL_TO`, `NOTIFY_EMAIL_FROM` |
+
+If a requested and severity-allowed channel is missing required values,
+`notify()` skips that channel with reason `missing-binding`. It does not throw.
+
+## Cloudflare Email
+
+Cloudflare is the default email provider:
+
+```ts
+await notify(env, {
+	channels: ['email'],
+	severity: 'critical',
+	title: 'Digest failed',
+	body: 'The 2026-05-18 digest job failed.',
+})
+```
+
+Configure the Worker binding:
+
+```toml
+[[send_email]]
+name = "SEND_EMAIL"
+```
+
+Cloudflare Email requires the destination address to be verified through Email
+Routing or Email Service setup before sends are accepted. If the binding rejects
+with a destination-verification error, notify records that provider error in
+`result.failed[]`; the package does not attempt verification.
+
+## Resend Fallback
+
+Use Resend when the incident being reported could affect Cloudflare delivery
+itself:
+
+```ts
+await notify(env, {
+	channels: ['slack', 'email'],
+	severity: 'critical',
+	title: 'Cloudflare auth worker unavailable',
+	body: 'The monitor cannot reach the auth worker from two regions.',
+	emailProvider: 'resend',
+})
+```
+
+Resend sends a POST to `https://api.resend.com/emails` with bearer auth from
+`RESEND_API_KEY`.
+
+## Slack Blocks
+
+Slack payloads always include `text: title` as the fallback. If you do not pass
+blocks, notify sends:
+
+```ts
+[
+	{
+		type: 'section',
+		text: { type: 'mrkdwn', text: `*${title}*\n${body}` },
+	},
+]
+```
+
+Pass `blocks` when the caller owns richer formatting. Email ignores `blocks`.
+
+## Dedup And Audit Hooks
+
+Dedup is caller-owned:
+
+```ts
+await notify(env, {
+	channels: ['slack'],
+	severity: 'warning',
+	title: 'Queue backlog',
+	body: 'Email queue has been above threshold for 10 minutes.',
+	dedupKey: 'mailer:queue-backlog',
+	dedupFn: async (key) => alreadySentRecently(key),
+})
+```
+
+`dedupFn` is called per channel before dispatch. If it returns `true`, the
+channel is skipped with reason `deduped`. If it throws, notify warns and sends
+anyway. Over-delivery is safer than silently dropping an alert.
+
+`onSent` runs once per successful adapter dispatch:
+
+```ts
+await notify(env, {
+	channels: ['slack', 'email'],
+	severity: 'critical',
+	title: 'Monitor failed',
+	body: 'The auth monitor detected a production outage.',
+	onSent: async (record) => writeAuditRecord(record),
+})
+```
+
+Errors from `onSent` are caught and logged with `console.warn`; a successful
+send is not reversed by an audit failure.
+
+## Result Shape
+
+```ts
+interface NotifyResult {
+	attempted: Channel[]
+	sent: Channel[]
+	skipped: {
+		channel: Channel
+		reason: 'deduped' | 'missing-binding' | 'severity-routing'
+	}[]
+	failed: { channel: Channel; error: string }[]
+}
+```
+
+Input validation can throw for an invalid shape: empty `channels`, missing
+`title`, missing `body`, unsupported severity, unsupported channel, or
+unsupported email provider.
+
+Adapter delivery failures never throw from `notify()`. They are captured in
+`failed[]` and logged with `console.warn`.
+
+## Exports
+
+```ts
+export { notify } from '@growth-labs/notify'
+export type {
+	Channel,
+	EmailProvider,
+	NotifyEnv,
+	NotifyInput,
+	NotifyResult,
+	SendEmailBinding,
+	SentRecord,
+	Severity,
+	SlackBlock,
+} from '@growth-labs/notify'
+```

package/SPEC.md

@@ -0,0 +1,103 @@
+# @growth-labs/notify v0.1.0 Package Spec
+
+Status: ready for implementation. Date: 2026-05-14.
+
+## Goal
+
+Ship `@growth-labs/notify@0.1.0`, a leaf package that sends human-facing
+notifications through Slack and email from Cloudflare Workers. It provides one
+API, fixed severity routing, caller-supplied dedup/audit hooks, and retry-aware
+delivery.
+
+This package does not store state, classify severity, own D1/KV, or format
+domain-specific messages. Callers pass `severity`, `title`, `body`, optional
+Slack Block Kit `blocks`, optional `dedupFn`, and optional `onSent`.
+
+## Public API
+
+```ts
+import { notify } from '@growth-labs/notify'
+
+await notify(env, {
+	channels: ['slack', 'email'],
+	severity: 'critical',
+	title: 'Auth surface down',
+	body: '/login/ returning 503 for 12 minutes.',
+	blocks: [],
+	dedupKey: 'auth-monitor:fronts.co:login:down',
+	dedupFn: async (key) => false,
+	onSent: async (record) => undefined,
+	emailProvider: 'resend',
+})
+```
+
+The package exports `notify()` and the public types `Severity`, `Channel`,
+`NotifyInput`, `NotifyEnv`, `SlackBlock`, `SentRecord`, and `NotifyResult`.
+
+## Severity Routing
+
+The caller supplies the requested `channels`; severity filters that list.
+
+| Severity | Slack | Email |
+| --- | --- | --- |
+| `info` | yes | no |
+| `warning` | yes | no |
+| `critical` | yes | yes |
+
+Routing is fixed in v0.1. If `channels: ['email']` is paired with
+`severity: 'info'`, `notify()` returns a skipped email record with reason
+`severity-routing` and sends nothing.
+
+## Environment
+
+```ts
+interface NotifyEnv {
+	NOTIFY_SLACK_WEBHOOK?: string
+	SEND_EMAIL?: SendEmailBinding
+	RESEND_API_KEY?: string
+	NOTIFY_EMAIL_TO?: string
+	NOTIFY_EMAIL_FROM?: string
+}
+```
+
+Slack requires `NOTIFY_SLACK_WEBHOOK`. Cloudflare email requires `SEND_EMAIL`,
+`NOTIFY_EMAIL_TO`, and `NOTIFY_EMAIL_FROM`. Resend requires `RESEND_API_KEY`,
+`NOTIFY_EMAIL_TO`, and `NOTIFY_EMAIL_FROM`.
+
+## Adapter Behavior
+
+Slack posts to the incoming webhook with `Content-Type: application/json`.
+Payloads always include `text: input.title`; when no blocks are supplied, the
+adapter sends a section block containing `*title*\nbody`.
+
+Cloudflare email uses the Worker Send Email binding and constructs an RFC 822
+message for `EmailMessage`. The HTML body is derived from the plain text body by
+escaping HTML special characters and replacing newlines with `<br>`.
+
+Resend posts to `https://api.resend.com/emails` with `Authorization: Bearer
+<RESEND_API_KEY>` and sends `from`, `to: [NOTIFY_EMAIL_TO]`, `subject`, `text`,
+and `html`.
+
+All adapters retry up to three attempts. Network errors and 5xx responses retry.
+4xx responses do not retry. Final adapter failures are returned in
+`NotifyResult.failed` and warn to `console.warn`.
+
+## Dispatch Invariants
+
+1. `notify()` may throw for invalid input, but never throws for adapter delivery
+   failure.
+2. `onSent` runs exactly once per successful adapter dispatch.
+3. `dedupFn` failure warns and proceeds with sending.
+4. Every final adapter failure warns through `console.warn`.
+5. The package stores no state and starts no background work.
+6. Channels dispatch in series and in caller-provided order.
+7. Missing bindings skip the channel instead of throwing.
+
+## Documentation Requirements
+
+README must cover install, basic usage, severity routing, required bindings and
+environment, Cloudflare Email destination verification, Resend fallback use
+cases, dedup hooks, audit hooks, and result shape.
+
+`packages-docs/notify.md`, `PACKAGES.md`, and `docs/agent/package-catalog.yaml`
+must be updated with the new package.

package/dist/adapters/cf-email.d.ts

@@ -0,0 +1,12 @@
+import { type RetryOptions, type RetryResult } from '../retry.js';
+import type { NotifyEnv, NotifyInput } from '../types.js';
+export declare function hasCloudflareEmailBinding(env: NotifyEnv): boolean;
+export declare function dispatchCloudflareEmail(env: NotifyEnv, input: NotifyInput, retryOptions?: Partial<RetryOptions>): Promise<RetryResult<void>>;
+export declare function buildRfc822Message(input: {
+    from: string;
+    to: string;
+    subject: string;
+    bodyText: string;
+    bodyHtml: string;
+}): string;
+//# sourceMappingURL=cf-email.d.ts.map

package/dist/adapters/cf-email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-email.d.ts","sourceRoot":"","sources":["../../src/adapters/cf-email.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,YAAY,EACjB,KAAK,WAAW,EAGhB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAIzD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAMjE;AAED,wBAAsB,uBAAuB,CAC5C,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAClC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CA2B5B;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CAChB,GAAG,MAAM,CAsBT"}

package/dist/adapters/cf-email.js

@@ -0,0 +1,88 @@
+import { DeliveryError, errorMessage, shouldRetryDeliveryError, withRetry, } from '../retry.js';
+export function hasCloudflareEmailBinding(env) {
+    return (typeof env.SEND_EMAIL?.send === 'function' &&
+        isNonEmptyString(env.NOTIFY_EMAIL_FROM) &&
+        isNonEmptyString(env.NOTIFY_EMAIL_TO));
+}
+export async function dispatchCloudflareEmail(env, input, retryOptions) {
+    return withRetry(async () => {
+        const sender = env.SEND_EMAIL;
+        const from = env.NOTIFY_EMAIL_FROM;
+        const to = env.NOTIFY_EMAIL_TO;
+        if (typeof sender?.send !== 'function' || !isNonEmptyString(from) || !isNonEmptyString(to)) {
+            throw new DeliveryError('Cloudflare SEND_EMAIL binding or email addresses are missing', false);
+        }
+        const EmailMessage = await loadEmailMessage();
+        const raw = buildRfc822Message({
+            from,
+            to,
+            subject: input.title,
+            bodyText: input.body,
+            bodyHtml: buildHtmlBody(input.body),
+        });
+        await sender.send(new EmailMessage(from, to, raw));
+    }, (error) => shouldRetryCloudflareEmail(error), retryOptions);
+}
+export function buildRfc822Message(input) {
+    const boundary = 'gl-notify-boundary';
+    return [
+        `From: ${sanitizeHeader(input.from)}`,
+        `To: ${sanitizeHeader(input.to)}`,
+        `Subject: ${sanitizeHeader(input.subject)}`,
+        'MIME-Version: 1.0',
+        `Content-Type: multipart/alternative; boundary="${boundary}"`,
+        '',
+        `--${boundary}`,
+        'Content-Type: text/plain; charset=UTF-8',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        input.bodyText,
+        `--${boundary}`,
+        'Content-Type: text/html; charset=UTF-8',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        input.bodyHtml,
+        `--${boundary}--`,
+        '',
+    ].join('\r\n');
+}
+function shouldRetryCloudflareEmail(error) {
+    const status = statusCode(error);
+    if (status && status >= 400 && status < 500) {
+        return false;
+    }
+    const message = errorMessage(error).toLowerCase();
+    if (message.includes('destination not verified')) {
+        return false;
+    }
+    return shouldRetryDeliveryError(error);
+}
+async function loadEmailMessage() {
+    const module = await import('cloudflare:email');
+    return module.EmailMessage;
+}
+function buildHtmlBody(body) {
+    return `<p>${escapeHtml(body).replace(/\n/g, '<br>')}</p>`;
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function sanitizeHeader(value) {
+    return value.replace(/[\r\n]+/g, ' ').trim();
+}
+function statusCode(error) {
+    if (!error || typeof error !== 'object') {
+        return undefined;
+    }
+    const status = error.status;
+    return typeof status === 'number' ? status : undefined;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+//# sourceMappingURL=cf-email.js.map

package/dist/adapters/cf-email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-email.js","sourceRoot":"","sources":["../../src/adapters/cf-email.ts"],"names":[],"mappings":"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"}

package/dist/adapters/resend.d.ts

@@ -0,0 +1,5 @@
+import { type RetryOptions, type RetryResult } from '../retry.js';
+import type { NotifyEnv, NotifyInput } from '../types.js';
+export declare function hasResendBinding(env: NotifyEnv): boolean;
+export declare function dispatchResendEmail(env: NotifyEnv, input: NotifyInput, retryOptions?: Partial<RetryOptions>): Promise<RetryResult<void>>;
+//# sourceMappingURL=resend.d.ts.map

package/dist/adapters/resend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resend.d.ts","sourceRoot":"","sources":["../../src/adapters/resend.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,WAAW,EAGhB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAIzD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAMxD;AAED,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAClC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAgC5B"}

package/dist/adapters/resend.js

@@ -0,0 +1,52 @@
+import { DeliveryError, shouldRetryDeliveryError, withRetry, } from '../retry.js';
+const RESEND_EMAILS_URL = 'https://api.resend.com/emails';
+export function hasResendBinding(env) {
+    return (isNonEmptyString(env.RESEND_API_KEY) &&
+        isNonEmptyString(env.NOTIFY_EMAIL_FROM) &&
+        isNonEmptyString(env.NOTIFY_EMAIL_TO));
+}
+export async function dispatchResendEmail(env, input, retryOptions) {
+    return withRetry(async () => {
+        if (!hasResendBinding(env)) {
+            throw new DeliveryError('Resend API key or email addresses are missing', false);
+        }
+        const response = await fetch(RESEND_EMAILS_URL, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${env.RESEND_API_KEY}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                from: env.NOTIFY_EMAIL_FROM,
+                to: [env.NOTIFY_EMAIL_TO],
+                subject: input.title,
+                text: input.body,
+                html: buildHtmlBody(input.body),
+            }),
+        });
+        if (!response.ok) {
+            throw new DeliveryError(await responseErrorMessage('Resend', response), response.status >= 500);
+        }
+    }, (error) => shouldRetryDeliveryError(error), retryOptions);
+}
+async function responseErrorMessage(label, response) {
+    const body = await response.text();
+    return body.trim()
+        ? `${label} responded ${response.status}: ${body}`
+        : `${label} responded ${response.status}`;
+}
+function buildHtmlBody(body) {
+    return `<p>${escapeHtml(body).replace(/\n/g, '<br>')}</p>`;
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+//# sourceMappingURL=resend.js.map

package/dist/adapters/resend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resend.js","sourceRoot":"","sources":["../../src/adapters/resend.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,aAAa,EAGb,wBAAwB,EACxB,SAAS,GACT,MAAM,aAAa,CAAA;AAGpB,MAAM,iBAAiB,GAAG,+BAA+B,CAAA;AAEzD,MAAM,UAAU,gBAAgB,CAAC,GAAc;IAC9C,OAAO,CACN,gBAAgB,CAAC,GAAG,CAAC,cAAc,CAAC;QACpC,gBAAgB,CAAC,GAAG,CAAC,iBAAiB,CAAC;QACvC,gBAAgB,CAAC,GAAG,CAAC,eAAe,CAAC,CACrC,CAAA;AACF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,GAAc,EACd,KAAkB,EAClB,YAAoC;IAEpC,OAAO,SAAS,CACf,KAAK,IAAI,EAAE;QACV,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,aAAa,CAAC,+CAA+C,EAAE,KAAK,CAAC,CAAA;QAChF,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,iBAAiB,EAAE;YAC/C,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACR,aAAa,EAAE,UAAU,GAAG,CAAC,cAAc,EAAE;gBAC7C,cAAc,EAAE,kBAAkB;aAClC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACpB,IAAI,EAAE,GAAG,CAAC,iBAAiB;gBAC3B,EAAE,EAAE,CAAC,GAAG,CAAC,eAAe,CAAC;gBACzB,OAAO,EAAE,KAAK,CAAC,KAAK;gBACpB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC;aAC/B,CAAC;SACF,CAAC,CAAA;QAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YAClB,MAAM,IAAI,aAAa,CACtB,MAAM,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAC9C,QAAQ,CAAC,MAAM,IAAI,GAAG,CACtB,CAAA;QACF,CAAC;IACF,CAAC,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,wBAAwB,CAAC,KAAK,CAAC,EAC1C,YAAY,CACZ,CAAA;AACF,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,KAAa,EAAE,QAAkB;IACpE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;IAClC,OAAO,IAAI,CAAC,IAAI,EAAE;QACjB,CAAC,CAAC,GAAG,KAAK,cAAc,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE;QAClD,CAAC,CAAC,GAAG,KAAK,cAAc,QAAQ,CAAC,MAAM,EAAE,CAAA;AAC3C,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IAClC,OAAO,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAA;AAC3D,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAChC,OAAO,KAAK;SACV,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AACzB,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAA;AACxD,CAAC"}

package/dist/adapters/slack.d.ts

@@ -0,0 +1,5 @@
+import { type RetryOptions, type RetryResult } from '../retry.js';
+import type { NotifyEnv, NotifyInput } from '../types.js';
+export declare function hasSlackBinding(env: NotifyEnv): boolean;
+export declare function dispatchSlack(env: NotifyEnv, input: NotifyInput, retryOptions?: Partial<RetryOptions>): Promise<RetryResult<void>>;
+//# sourceMappingURL=slack.d.ts.map

package/dist/adapters/slack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.d.ts","sourceRoot":"","sources":["../../src/adapters/slack.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,WAAW,EAGhB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzD,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAEvD;AAED,wBAAsB,aAAa,CAClC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAClC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CA2B5B"}

package/dist/adapters/slack.js

@@ -0,0 +1,41 @@
+import { DeliveryError, shouldRetryDeliveryError, withRetry, } from '../retry.js';
+export function hasSlackBinding(env) {
+    return isNonEmptyString(env.NOTIFY_SLACK_WEBHOOK);
+}
+export async function dispatchSlack(env, input, retryOptions) {
+    return withRetry(async () => {
+        const webhook = env.NOTIFY_SLACK_WEBHOOK;
+        if (!isNonEmptyString(webhook)) {
+            throw new DeliveryError('NOTIFY_SLACK_WEBHOOK is missing', false);
+        }
+        const response = await fetch(webhook, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                text: input.title,
+                blocks: input.blocks ?? defaultBlocks(input),
+            }),
+        });
+        if (!response.ok) {
+            throw new DeliveryError(await responseErrorMessage('Slack webhook', response), response.status >= 500);
+        }
+    }, (error) => shouldRetryDeliveryError(error), retryOptions);
+}
+function defaultBlocks(input) {
+    return [
+        {
+            type: 'section',
+            text: { type: 'mrkdwn', text: `*${input.title}*\n${input.body}` },
+        },
+    ];
+}
+async function responseErrorMessage(label, response) {
+    const body = await response.text();
+    return body.trim()
+        ? `${label} responded ${response.status}: ${body}`
+        : `${label} responded ${response.status}`;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+//# sourceMappingURL=slack.js.map

package/dist/adapters/slack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.js","sourceRoot":"","sources":["../../src/adapters/slack.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,aAAa,EAGb,wBAAwB,EACxB,SAAS,GACT,MAAM,aAAa,CAAA;AAGpB,MAAM,UAAU,eAAe,CAAC,GAAc;IAC7C,OAAO,gBAAgB,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAA;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,GAAc,EACd,KAAkB,EAClB,YAAoC;IAEpC,OAAO,SAAS,CACf,KAAK,IAAI,EAAE;QACV,MAAM,OAAO,GAAG,GAAG,CAAC,oBAAoB,CAAA;QACxC,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,aAAa,CAAC,iCAAiC,EAAE,KAAK,CAAC,CAAA;QAClE,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE;YACrC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACpB,IAAI,EAAE,KAAK,CAAC,KAAK;gBACjB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,aAAa,CAAC,KAAK,CAAC;aAC5C,CAAC;SACF,CAAC,CAAA;QAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YAClB,MAAM,IAAI,aAAa,CACtB,MAAM,oBAAoB,CAAC,eAAe,EAAE,QAAQ,CAAC,EACrD,QAAQ,CAAC,MAAM,IAAI,GAAG,CACtB,CAAA;QACF,CAAC;IACF,CAAC,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,wBAAwB,CAAC,KAAK,CAAC,EAC1C,YAAY,CACZ,CAAA;AACF,CAAC;AAED,SAAS,aAAa,CAAC,KAAkB;IACxC,OAAO;QACN;YACC,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,EAAE,IAAI,EAAE,QAAiB,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC,KAAK,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE;SAC1E;KACD,CAAA;AACF,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,KAAa,EAAE,QAAkB;IACpE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;IAClC,OAAO,IAAI,CAAC,IAAI,EAAE;QACjB,CAAC,CAAC,GAAG,KAAK,cAAc,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE;QAClD,CAAC,CAAC,GAAG,KAAK,cAAc,QAAQ,CAAC,MAAM,EAAE,CAAA;AAC3C,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAA;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { notify } from './notify.js';
+export type { Channel, EmailProvider, NotifyEnv, NotifyInput, NotifyResult, SendEmailBinding, SentRecord, Severity, SlackBlock, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EACX,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,QAAQ,EACR,UAAU,GACV,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { notify } from './notify.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA"}

package/dist/notify.d.ts

@@ -0,0 +1,3 @@
+import type { NotifyEnv, NotifyInput, NotifyResult } from './types.js';
+export declare function notify(env: NotifyEnv, input: NotifyInput): Promise<NotifyResult>;
+//# sourceMappingURL=notify.d.ts.map

package/dist/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../src/notify.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAA0B,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAa9F,wBAAsB,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAmEtF"}

package/dist/notify.js

@@ -0,0 +1,124 @@
+import { dispatchCloudflareEmail, hasCloudflareEmailBinding } from './adapters/cf-email.js';
+import { dispatchResendEmail, hasResendBinding } from './adapters/resend.js';
+import { dispatchSlack, hasSlackBinding } from './adapters/slack.js';
+const VALID_CHANNELS = new Set(['slack', 'email']);
+const VALID_SEVERITIES = new Set(['info', 'warning', 'critical']);
+const VALID_EMAIL_PROVIDERS = new Set(['cloudflare', 'resend']);
+export async function notify(env, input) {
+    validateInput(input);
+    const result = {
+        attempted: [...input.channels],
+        sent: [],
+        skipped: [],
+        failed: [],
+    };
+    const allowed = input.channels.filter((channel) => isAllowedBySeverity(channel, input.severity));
+    for (const channel of input.channels) {
+        if (!allowed.includes(channel)) {
+            result.skipped.push({ channel, reason: 'severity-routing' });
+        }
+    }
+    for (const channel of allowed) {
+        if (input.dedupKey && input.dedupFn) {
+            try {
+                const shouldSkip = await input.dedupFn(input.dedupKey);
+                if (shouldSkip) {
+                    result.skipped.push({ channel, reason: 'deduped' });
+                    continue;
+                }
+            }
+            catch (err) {
+                console.warn('@growth-labs/notify: dedupFn threw, proceeding with send', {
+                    dedupKey: input.dedupKey,
+                    err,
+                });
+            }
+        }
+        const adapter = selectAdapter(channel, input.emailProvider ?? 'cloudflare');
+        if (!adapter.hasRequiredBindings(env)) {
+            result.skipped.push({ channel, reason: 'missing-binding' });
+            continue;
+        }
+        const dispatchResult = await adapter.dispatch(env, input);
+        if (dispatchResult.ok) {
+            result.sent.push(channel);
+            if (input.onSent) {
+                try {
+                    await input.onSent({
+                        channel,
+                        severity: input.severity,
+                        title: input.title,
+                        dedupKey: input.dedupKey,
+                        attempts: dispatchResult.attempts,
+                        sentAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    console.warn('@growth-labs/notify: onSent hook threw', { channel, err });
+                }
+            }
+        }
+        else {
+            result.failed.push({ channel, error: dispatchResult.error });
+            console.warn(`@growth-labs/notify: ${adapter.failureLabel} delivery failed`, {
+                title: input.title,
+                attempts: dispatchResult.attempts,
+                error: dispatchResult.error,
+            });
+        }
+    }
+    return result;
+}
+function selectAdapter(channel, emailProvider) {
+    if (channel === 'slack') {
+        return {
+            channel,
+            failureLabel: 'slack',
+            hasRequiredBindings: hasSlackBinding,
+            dispatch: dispatchSlack,
+        };
+    }
+    if (emailProvider === 'resend') {
+        return {
+            channel,
+            failureLabel: 'resend',
+            hasRequiredBindings: hasResendBinding,
+            dispatch: dispatchResendEmail,
+        };
+    }
+    return {
+        channel,
+        failureLabel: 'cf-email',
+        hasRequiredBindings: hasCloudflareEmailBinding,
+        dispatch: dispatchCloudflareEmail,
+    };
+}
+function isAllowedBySeverity(channel, severity) {
+    if (channel === 'slack') {
+        return true;
+    }
+    return severity === 'critical';
+}
+function validateInput(input) {
+    if (!Array.isArray(input.channels) || input.channels.length === 0) {
+        throw new Error('@growth-labs/notify: channels must include at least one channel');
+    }
+    for (const channel of input.channels) {
+        if (!VALID_CHANNELS.has(channel)) {
+            throw new Error(`@growth-labs/notify: unsupported channel "${String(channel)}"`);
+        }
+    }
+    if (!VALID_SEVERITIES.has(input.severity)) {
+        throw new Error(`@growth-labs/notify: unsupported severity "${String(input.severity)}"`);
+    }
+    if (typeof input.title !== 'string' || input.title.trim() === '') {
+        throw new Error('@growth-labs/notify: title is required');
+    }
+    if (typeof input.body !== 'string' || input.body.trim() === '') {
+        throw new Error('@growth-labs/notify: body is required');
+    }
+    if (input.emailProvider !== undefined && !VALID_EMAIL_PROVIDERS.has(input.emailProvider)) {
+        throw new Error(`@growth-labs/notify: unsupported emailProvider "${String(input.emailProvider)}"`);
+    }
+}
+//# sourceMappingURL=notify.js.map

package/dist/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../src/notify.ts"],"names":[],"mappings":"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"}

package/dist/retry.d.ts

@@ -0,0 +1,23 @@
+export interface RetryOptions {
+    maxAttempts: number;
+    baseMs: number;
+    multiplier: number;
+    jitterFactor: number;
+}
+export type RetryResult<T> = {
+    ok: true;
+    value: T;
+    attempts: number;
+} | {
+    ok: false;
+    error: string;
+    attempts: number;
+};
+export declare class DeliveryError extends Error {
+    readonly retryable: boolean;
+    constructor(message: string, retryable: boolean);
+}
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, shouldRetry: (err: unknown, attempt: number) => boolean, options?: Partial<RetryOptions>): Promise<RetryResult<T>>;
+export declare function shouldRetryDeliveryError(error: unknown): boolean;
+export declare function errorMessage(error: unknown): string;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AASjD,qBAAa,aAAc,SAAQ,KAAK;aAGtB,SAAS,EAAE,OAAO;gBADlC,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,OAAO;CAKnC;AAED,wBAAsB,SAAS,CAAC,CAAC,EAChC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,EACvD,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC7B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAoBzB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKhE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYnD"}

package/dist/retry.js

@@ -0,0 +1,64 @@
+const DEFAULT_RETRY_OPTIONS = {
+    maxAttempts: 3,
+    baseMs: 250,
+    multiplier: 4,
+    jitterFactor: 0.2,
+};
+export class DeliveryError extends Error {
+    retryable;
+    constructor(message, retryable) {
+        super(message);
+        this.retryable = retryable;
+        this.name = 'DeliveryError';
+    }
+}
+export async function withRetry(fn, shouldRetry, options) {
+    const resolved = { ...DEFAULT_RETRY_OPTIONS, ...options };
+    const maxAttempts = Math.max(1, Math.floor(resolved.maxAttempts));
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            const value = await fn(attempt);
+            return { ok: true, value, attempts: attempt };
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxAttempts || !shouldRetry(error, attempt)) {
+                return { ok: false, error: errorMessage(error), attempts: attempt };
+            }
+            await sleep(delayForAttempt(attempt, resolved));
+        }
+    }
+    return { ok: false, error: errorMessage(lastError), attempts: maxAttempts };
+}
+export function shouldRetryDeliveryError(error) {
+    if (error instanceof DeliveryError) {
+        return error.retryable;
+    }
+    return true;
+}
+export function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+function delayForAttempt(attempt, options) {
+    const baseDelay = options.baseMs * options.multiplier ** (attempt - 1);
+    const jitter = 1 + (Math.random() * 2 - 1) * options.jitterFactor;
+    return Math.max(0, Math.round(baseDelay * jitter));
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export type Severity = 'info' | 'warning' | 'critical';
+export type Channel = 'slack' | 'email';
+export type EmailProvider = 'cloudflare' | 'resend';
+export interface SlackBlock {
+    type: string;
+    text?: {
+        type: 'mrkdwn' | 'plain_text';
+        text: string;
+    };
+    [key: string]: unknown;
+}
+export interface SentRecord {
+    channel: Channel;
+    severity: Severity;
+    title: string;
+    dedupKey?: string;
+    attempts: number;
+    sentAt: number;
+}
+export interface NotifyInput {
+    channels: Channel[];
+    severity: Severity;
+    title: string;
+    body: string;
+    blocks?: SlackBlock[];
+    dedupKey?: string;
+    dedupFn?: (dedupKey: string) => Promise<boolean>;
+    onSent?: (record: SentRecord) => Promise<void>;
+    emailProvider?: EmailProvider;
+}
+export interface SendEmailBinding {
+    send(message: unknown): Promise<unknown>;
+}
+export interface NotifyEnv {
+    NOTIFY_SLACK_WEBHOOK?: string;
+    SEND_EMAIL?: SendEmailBinding;
+    RESEND_API_KEY?: string;
+    NOTIFY_EMAIL_TO?: string;
+    NOTIFY_EMAIL_FROM?: string;
+}
+export interface NotifyResult {
+    attempted: Channel[];
+    sent: Channel[];
+    skipped: {
+        channel: Channel;
+        reason: 'deduped' | 'missing-binding' | 'severity-routing';
+    }[];
+    failed: {
+        channel: Channel;
+        error: string;
+    }[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAA;AACtD,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,OAAO,CAAA;AACvC,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,QAAQ,CAAA;AAEnD,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACtD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,UAAU;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAChD,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9C,aAAa,CAAC,EAAE,aAAa,CAAA;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,SAAS;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,YAAY;IAC5B,SAAS,EAAE,OAAO,EAAE,CAAA;IACpB,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,OAAO,EAAE;QACR,OAAO,EAAE,OAAO,CAAA;QAChB,MAAM,EAAE,SAAS,GAAG,iBAAiB,GAAG,kBAAkB,CAAA;KAC1D,EAAE,CAAA;IACH,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC7C"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@growth-labs/notify",
+  "version": "0.1.0",
+  "description": "Worker-compatible human notification delivery for Slack and email with severity routing, retry, and caller-supplied dedup hooks.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SPEC.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "tsc --noEmit -p tsconfig.test.json && vitest run",
+    "test:watch": "vitest",
+    "check": "biome check src/ __tests__"
+  }
+}