@shware/workflow 2.0.0 → 3.0.0

package/dist/dsl/refs.d.mts

@@ -47,10 +47,11 @@ export type EventRefs<E> = { readonly [K in keyof E]-?: EventRef<E[K]>; };
  */
 export declare function user<U extends UserPropertyBase>(): UserRefs<U>;
 export declare function event<E extends EventMap>(): EventRefs<E>;
-export type PropInput<T> = T | UserPropertyRef<T>;
+/** An impossible field cannot be supplied indirectly through a profile reference either. */
+export type PropInput<T> = [T] extends [never] ? never : T | UserPropertyRef<T>;
 export type PropsInput<P> = { [K in keyof P]: PropInput<P[K]>; };
 /** Props may be omitted when a template declares none, and are required when it does. */
-export type MessageArgs<P> = Record<never, never> extends P ? [props?: PropsInput<P>] : [props: PropsInput<P>];
+export type MessageArgs<P> = Record<string, never> extends P ? [props?: PropsInput<P>] : [props: PropsInput<P>];
 /**
  * Where a payload ref keeps its own state. A payload ref doubles as the table
  * of its sub-fields, so every *string* key it answered for itself shadowed an
@@ -74,9 +75,9 @@ export interface PayloadRef<T> {
   readonly __t?: T;
 }
 /** A payload field ref that is itself an object also acts as a table of its sub-field refs. */
-export type PayloadRefNode<T> = [NonNullable<T>] extends [object] ? PayloadRef<T> & { readonly [K in keyof NonNullable<T> & string]-?: PayloadRefNode<NonNullable<T>[K]>; } : PayloadRef<T>;
+export type PayloadRefNode<T> = [NonNullable<T>] extends [never] ? PayloadRef<T> : [NonNullable<T>] extends [object] ? PayloadRef<T> & { readonly [K in keyof NonNullable<T> & string as [NonNullable<T>[K]] extends [never] ? never : K]-?: PayloadRefNode<NonNullable<T>[K]>; } : PayloadRef<T>;
 /** Payload reference table for an event's payload P — the `p` in `where: (p) => eq(p.platform, 'web')`. */
-export type PayloadRefs<P> = [P] extends [object] ? { readonly [K in keyof P & string]-?: PayloadRefNode<P[K]>; } : Record<string, PayloadRef<unknown>>;
+export type PayloadRefs<P> = [P] extends [object] ? { readonly [K in keyof P & string as [P[K]] extends [never] ? never : K]-?: PayloadRefNode<P[K]>; } : Record<string, PayloadRef<unknown>>;
 /**
  * Nested Proxy: every string key extends the dotted path, so an author's field
  * may be named anything — including `path` or `type`. The ref's own path reads

package/dist/dsl/refs.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"refs.d.mts","names":[],"sources":["../../src/dsl/refs.ts"],"mappings":";;;;;;;;;;;;;;;;;;iBAmBiB,gBAAgB;WACtB;WACA;WACA,MAAM;;;iBAIA,SAAS;WACf;WACA;WACA,MAAM;;;YAIL,SAAS,iBAAiB,WAAW,MAAM,gBAAgB,EAAE;;YAG7D,UAAU,iBAAiB,WAAW,MAAM,SAAS,EAAE;;;;;;;;;;;;;;;wBAgBnD,KAAK,UAAU,qBAAqB,SAAS;wBAM7C,MAAM,UAAU,aAAa,UAAU;YAM3C,UAAU,KAAK,IAAI,gBAAgB;YACnC,WAAW,QAAQ,WAAW,IAAI,UAAU,EAAE;;YAG9C,YAAY,KACtB,6BAA6B,KAAK,QAAQ,WAAW,OAAO,OAAO,WAAW;;;;;;;;;;;qBAcnE;;;;;;;;iBASI,WAAW;YAChB;WACD,MAAM;;;YAIL,eAAe,MAAM,YAAY,uBACzC,WAAW,iBACC,WAAW,YAAY,gBAAgB,eAAe,YAAY,GAAG,SAEjF,WAAW;;YAGH,YAAY,MAAM,kCACd,WAAW,eAAe,eAAe,EAAE,SACvD,eAAe;;;;;;;wBAQH,YAAY,GAAG,kBAAc,YAAY"}
+{"version":3,"file":"refs.d.mts","names":[],"sources":["../../src/dsl/refs.ts"],"mappings":";;;;;;;;;;;;;;;;;;iBAmBiB,gBAAgB;WACtB;WACA;WACA,MAAM;;;iBAIA,SAAS;WACf;WACA;WACA,MAAM;;;YAIL,SAAS,iBAAiB,WAAW,MAAM,gBAAgB,EAAE;;YAG7D,UAAU,iBAAiB,WAAW,MAAM,SAAS,EAAE;;;;;;;;;;;;;;;wBAgBnD,KAAK,UAAU,qBAAqB,SAAS;wBAM7C,MAAM,UAAU,aAAa,UAAU;;YAO3C,UAAU,MAAM,6BAA6B,IAAI,gBAAgB;YACjE,WAAW,QAAQ,WAAW,IAAI,UAAU,EAAE;;YAG9C,YAAY,KACtB,8BAA8B,KAAK,QAAQ,WAAW,OAAO,OAAO,WAAW;;;;;;;;;;;qBAcpE;;;;;;;;iBASI,WAAW;YAChB;WACD,MAAM;;;YAIL,eAAe,MAAM,YAAY,sBACzC,WAAW,MACV,YAAY,uBACX,WAAW,iBAEP,WAAW,YAAY,gBAAgB,YAAY,GAAG,8BAA8B,MACjF,eAAe,YAAY,GAAG,SAErC,WAAW;;YAGL,YAAY,MAAM,kCAEd,WAAW,eAAe,EAAE,8BAA8B,MAAM,eACxE,EAAE,SAGN,eAAe;;;;;;;wBAQH,YAAY,GAAG,kBAAc,YAAY"}

package/dist/dsl/refs.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"refs.mjs","names":[],"sources":["../../src/dsl/refs.ts"],"sourcesContent":["import type { EventMap, UserPropertyBase } from './base';\n\n/**\n * Reference tables — the DSL's only two type-injection points (drizzle's\n * column-object pattern): `u = user<UserProperty>()` and `e = event<Event>()`.\n * Every other function in the DSL is generic-free and reads types off these\n * references.\n *\n * Type technique: phantom types. `UserPropertyRef<T>` carries the property's\n * type in an optional, never-assigned `__t` — purely so free functions like\n * `eq` can infer T from the reference. At runtime a ref is just\n * `{ type, path }`, produced by a Proxy on property access.\n */\n\n/**\n * User-property reference (drizzle's column equivalent), shared by predicates\n * (eq/gt/…) and message-prop personalization. The phantom type __t is how a\n * free function reads the property's type off the reference.\n */\nexport interface UserPropertyRef<T> {\n  readonly type: 'user_property';\n  readonly path: string;\n  readonly __t?: T;\n}\n\n/** Event reference: the argument to `performed`; future payload where-clauses and value refs hang off it. */\nexport interface EventRef<P = unknown> {\n  readonly type: 'event_ref';\n  readonly name: string;\n  readonly __p?: P;\n}\n\n/** Property reference table: `u.subscription_status` is a UserPropertyRef (drizzle's `users.email`). */\nexport type UserRefs<U> = { readonly [K in keyof U]-?: UserPropertyRef<U[K]> };\n\n/** Event reference table: `e.purchase` is an EventRef. */\nexport type EventRefs<E> = { readonly [K in keyof E]-?: EventRef<E[K]> };\n\n/**\n * Build the reference tables: the app calls each once in its schema module and\n * exports the result (implemented with a Proxy — property access *is* the reference).\n *\n *   export const u = user<UserProperty>();\n *   export const e = event<Event>();\n *\n * From then on predicates and personalization are all property access:\n * eq(u.subscription_status, 'active'), performed(e.purchase, { within: '30 days' }),\n * { plan: u.subscription_plan }.\n *\n * Properties are deliberately single-level: the data source is a database\n * table and is naturally flat, so nested paths are out of scope.\n */\nexport function user<U extends UserPropertyBase>(): UserRefs<U> {\n  return new Proxy({} as UserRefs<U>, {\n    get: (_target, prop) => ({ type: 'user_property', path: String(prop) }),\n  });\n}\n\nexport function event<E extends EventMap>(): EventRefs<E> {\n  return new Proxy({} as EventRefs<E>, {\n    get: (_target, prop) => ({ type: 'event_ref', name: String(prop) }),\n  });\n}\n\nexport type PropInput<T> = T | UserPropertyRef<T>;\nexport type PropsInput<P> = { [K in keyof P]: PropInput<P[K]> };\n\n/** Props may be omitted when a template declares none, and are required when it does. */\nexport type MessageArgs<P> =\n  Record<never, never> extends P ? [props?: PropsInput<P>] : [props: PropsInput<P>];\n\n/* ------------------------------ payload references ----------------------------- */\n\n/**\n * Where a payload ref keeps its own state. A payload ref doubles as the table\n * of its sub-fields, so every *string* key it answered for itself shadowed an\n * author's field of that name: with a payload field called `path`,\n * `performed(e.page_view, (p) => eq(p.path, '/pricing'))` type-checked, handed\n * `prop()` the ref's own prefix instead of a sub-ref, and compiled to a\n * *profile* predicate on a property named 'path' — a mistake that only\n * surfaced later, as a zod error nowhere near the line that caused it. A symbol\n * key cannot be reached by `p.<field>`, so no field name can collide with it.\n */\nexport const PAYLOAD_PATH: unique symbol = Symbol('workflow.payloadPath');\n\n/**\n * Event-payload reference: what a `where` callback's parameter hands out. The\n * path it carries is dotted for nested fields ('tags.utm_source'). Predicates\n * accept it alongside UserPropertyRef and compile to a `payload` condition —\n * which is only valid inside `performed({ where })` / the event trigger's\n * `where` (compileBundle enforces the placement).\n */\nexport interface PayloadRef<T> {\n  readonly [PAYLOAD_PATH]: string;\n  readonly __t?: T;\n}\n\n/** A payload field ref that is itself an object also acts as a table of its sub-field refs. */\nexport type PayloadRefNode<T> = [NonNullable<T>] extends [object]\n  ? PayloadRef<T> & {\n      readonly [K in keyof NonNullable<T> & string]-?: PayloadRefNode<NonNullable<T>[K]>;\n    }\n  : PayloadRef<T>;\n\n/** Payload reference table for an event's payload P — the `p` in `where: (p) => eq(p.platform, 'web')`. */\nexport type PayloadRefs<P> = [P] extends [object]\n  ? { readonly [K in keyof P & string]-?: PayloadRefNode<P[K]> }\n  : Record<string, PayloadRef<unknown>>;\n\n/**\n * Nested Proxy: every string key extends the dotted path, so an author's field\n * may be named anything — including `path` or `type`. The ref's own path reads\n * off PAYLOAD_PATH, the one key a field name cannot spell.\n * @internal used by performed() and trigger.event() to hand `p` to a where callback\n */\nexport function payloadRefs<P>(prefix = ''): PayloadRefs<P> {\n  return new Proxy({} as PayloadRefs<P>, {\n    get: (_target, prop) => {\n      if (prop === PAYLOAD_PATH) return prefix;\n      // Other symbols are the runtime's own probes (inspection, iteration, thenable checks), never fields\n      if (typeof prop === 'symbol') return undefined;\n      return payloadRefs(prefix === '' ? prop : `${prefix}.${prop}`);\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAoDA,SAAgB,OAAgD;CAC9D,OAAO,IAAI,MAAM,CAAC,GAAkB,EAClC,MAAM,SAAS,UAAU;EAAE,MAAM;EAAiB,MAAM,OAAO,IAAI;CAAE,GACvE,CAAC;AACH;AAEA,SAAgB,QAA0C;CACxD,OAAO,IAAI,MAAM,CAAC,GAAmB,EACnC,MAAM,SAAS,UAAU;EAAE,MAAM;EAAa,MAAM,OAAO,IAAI;CAAE,GACnE,CAAC;AACH;;;;;;;;;;;AAqBA,MAAa,eAA8B,OAAO,sBAAsB;;;;;;;AAgCxE,SAAgB,YAAe,SAAS,IAAoB;CAC1D,OAAO,IAAI,MAAM,CAAC,GAAqB,EACrC,MAAM,SAAS,SAAS;EACtB,IAAI,SAAS,cAAc,OAAO;EAElC,IAAI,OAAO,SAAS,UAAU,OAAO,KAAA;EACrC,OAAO,YAAY,WAAW,KAAK,OAAO,GAAG,OAAO,GAAG,MAAM;CAC/D,EACF,CAAC;AACH"}
+{"version":3,"file":"refs.mjs","names":[],"sources":["../../src/dsl/refs.ts"],"sourcesContent":["import type { EventMap, UserPropertyBase } from './base';\n\n/**\n * Reference tables — the DSL's only two type-injection points (drizzle's\n * column-object pattern): `u = user<UserProperty>()` and `e = event<Event>()`.\n * Every other function in the DSL is generic-free and reads types off these\n * references.\n *\n * Type technique: phantom types. `UserPropertyRef<T>` carries the property's\n * type in an optional, never-assigned `__t` — purely so free functions like\n * `eq` can infer T from the reference. At runtime a ref is just\n * `{ type, path }`, produced by a Proxy on property access.\n */\n\n/**\n * User-property reference (drizzle's column equivalent), shared by predicates\n * (eq/gt/…) and message-prop personalization. The phantom type __t is how a\n * free function reads the property's type off the reference.\n */\nexport interface UserPropertyRef<T> {\n  readonly type: 'user_property';\n  readonly path: string;\n  readonly __t?: T;\n}\n\n/** Event reference: the argument to `performed`; future payload where-clauses and value refs hang off it. */\nexport interface EventRef<P = unknown> {\n  readonly type: 'event_ref';\n  readonly name: string;\n  readonly __p?: P;\n}\n\n/** Property reference table: `u.subscription_status` is a UserPropertyRef (drizzle's `users.email`). */\nexport type UserRefs<U> = { readonly [K in keyof U]-?: UserPropertyRef<U[K]> };\n\n/** Event reference table: `e.purchase` is an EventRef. */\nexport type EventRefs<E> = { readonly [K in keyof E]-?: EventRef<E[K]> };\n\n/**\n * Build the reference tables: the app calls each once in its schema module and\n * exports the result (implemented with a Proxy — property access *is* the reference).\n *\n *   export const u = user<UserProperty>();\n *   export const e = event<Event>();\n *\n * From then on predicates and personalization are all property access:\n * eq(u.subscription_status, 'active'), performed(e.purchase, { within: '30 days' }),\n * { plan: u.subscription_plan }.\n *\n * Properties are deliberately single-level: the data source is a database\n * table and is naturally flat, so nested paths are out of scope.\n */\nexport function user<U extends UserPropertyBase>(): UserRefs<U> {\n  return new Proxy({} as UserRefs<U>, {\n    get: (_target, prop) => ({ type: 'user_property', path: String(prop) }),\n  });\n}\n\nexport function event<E extends EventMap>(): EventRefs<E> {\n  return new Proxy({} as EventRefs<E>, {\n    get: (_target, prop) => ({ type: 'event_ref', name: String(prop) }),\n  });\n}\n\n/** An impossible field cannot be supplied indirectly through a profile reference either. */\nexport type PropInput<T> = [T] extends [never] ? never : T | UserPropertyRef<T>;\nexport type PropsInput<P> = { [K in keyof P]: PropInput<P[K]> };\n\n/** Props may be omitted when a template declares none, and are required when it does. */\nexport type MessageArgs<P> =\n  Record<string, never> extends P ? [props?: PropsInput<P>] : [props: PropsInput<P>];\n\n/* ------------------------------ payload references ----------------------------- */\n\n/**\n * Where a payload ref keeps its own state. A payload ref doubles as the table\n * of its sub-fields, so every *string* key it answered for itself shadowed an\n * author's field of that name: with a payload field called `path`,\n * `performed(e.page_view, (p) => eq(p.path, '/pricing'))` type-checked, handed\n * `prop()` the ref's own prefix instead of a sub-ref, and compiled to a\n * *profile* predicate on a property named 'path' — a mistake that only\n * surfaced later, as a zod error nowhere near the line that caused it. A symbol\n * key cannot be reached by `p.<field>`, so no field name can collide with it.\n */\nexport const PAYLOAD_PATH: unique symbol = Symbol('workflow.payloadPath');\n\n/**\n * Event-payload reference: what a `where` callback's parameter hands out. The\n * path it carries is dotted for nested fields ('tags.utm_source'). Predicates\n * accept it alongside UserPropertyRef and compile to a `payload` condition —\n * which is only valid inside `performed({ where })` / the event trigger's\n * `where` (compileBundle enforces the placement).\n */\nexport interface PayloadRef<T> {\n  readonly [PAYLOAD_PATH]: string;\n  readonly __t?: T;\n}\n\n/** A payload field ref that is itself an object also acts as a table of its sub-field refs. */\nexport type PayloadRefNode<T> = [NonNullable<T>] extends [never]\n  ? PayloadRef<T>\n  : [NonNullable<T>] extends [object]\n    ? PayloadRef<T> & {\n        readonly [\n          K in keyof NonNullable<T> & string as [NonNullable<T>[K]] extends [never] ? never : K\n        ]-?: PayloadRefNode<NonNullable<T>[K]>;\n      }\n    : PayloadRef<T>;\n\n/** Payload reference table for an event's payload P — the `p` in `where: (p) => eq(p.platform, 'web')`. */\nexport type PayloadRefs<P> = [P] extends [object]\n  ? {\n      readonly [K in keyof P & string as [P[K]] extends [never] ? never : K]-?: PayloadRefNode<\n        P[K]\n      >;\n    }\n  : Record<string, PayloadRef<unknown>>;\n\n/**\n * Nested Proxy: every string key extends the dotted path, so an author's field\n * may be named anything — including `path` or `type`. The ref's own path reads\n * off PAYLOAD_PATH, the one key a field name cannot spell.\n * @internal used by performed() and trigger.event() to hand `p` to a where callback\n */\nexport function payloadRefs<P>(prefix = ''): PayloadRefs<P> {\n  return new Proxy({} as PayloadRefs<P>, {\n    get: (_target, prop) => {\n      if (prop === PAYLOAD_PATH) return prefix;\n      // Other symbols are the runtime's own probes (inspection, iteration, thenable checks), never fields\n      if (typeof prop === 'symbol') return undefined;\n      return payloadRefs(prefix === '' ? prop : `${prefix}.${prop}`);\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAoDA,SAAgB,OAAgD;CAC9D,OAAO,IAAI,MAAM,CAAC,GAAkB,EAClC,MAAM,SAAS,UAAU;EAAE,MAAM;EAAiB,MAAM,OAAO,IAAI;CAAE,GACvE,CAAC;AACH;AAEA,SAAgB,QAA0C;CACxD,OAAO,IAAI,MAAM,CAAC,GAAmB,EACnC,MAAM,SAAS,UAAU;EAAE,MAAM;EAAa,MAAM,OAAO,IAAI;CAAE,GACnE,CAAC;AACH;;;;;;;;;;;AAsBA,MAAa,eAA8B,OAAO,sBAAsB;;;;;;;AAwCxE,SAAgB,YAAe,SAAS,IAAoB;CAC1D,OAAO,IAAI,MAAM,CAAC,GAAqB,EACrC,MAAM,SAAS,SAAS;EACtB,IAAI,SAAS,cAAc,OAAO;EAElC,IAAI,OAAO,SAAS,UAAU,OAAO,KAAA;EACrC,OAAO,YAAY,WAAW,KAAK,OAAO,GAAG,OAAO,GAAG,MAAM;CAC/D,EACF,CAAC;AACH"}

package/dist/dsl/template.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"template.cjs","names":[],"sources":["../../src/dsl/template.ts"],"sourcesContent":["/**\n * Templates in the DSL. The four channels with template definitions (email, push, discord,\n * slack) take the definition itself — `.email(welcome, props)` — so its Zod `props` schema types\n * the call (`PropsOf`) and its `id` lands in the IR. The channels rendered by app-supplied\n * senders (sms, in-app, survey) have no definition; they take a hand-typed reference by key.\n */\n\nimport type * as core from 'zod/v4/core';\nimport type { DiscordTemplate, EmailTemplate, PushTemplate, SlackTemplate } from '../templates';\n\nexport type Channel = 'email' | 'sms' | 'push' | 'in_app' | 'slack' | 'discord' | 'survey';\n\nexport type EmptyProps = Record<never, never>;\n\n/** A template by key, its props typed by hand: for the channels without template definitions. */\nexport interface TemplateRef<C extends Channel = Channel, P extends object = EmptyProps> {\n  readonly channel: C;\n  readonly key: string;\n  readonly __props?: P;\n}\n\nexport interface TemplateFactory {\n  sms<P extends object = EmptyProps>(key: string): TemplateRef<'sms', P>;\n  inApp<P extends object = EmptyProps>(key: string): TemplateRef<'in_app', P>;\n  survey<P extends object = EmptyProps>(key: string): TemplateRef<'survey', P>;\n}\n\nconst makeTemplate =\n  <C extends Channel>(channel: C) =>\n  <P extends object = EmptyProps>(key: string): TemplateRef<C, P> => ({ channel, key });\n\n/**\n * Template references for the channels an app-supplied sender renders:\n *\n *   const code = template.sms<{ code: string }>('login_code');\n */\nexport const template: TemplateFactory = {\n  sms: makeTemplate('sms'),\n  inApp: makeTemplate('in_app'),\n  survey: makeTemplate('survey'),\n};\n\n/** Template props: the input type of the template's Zod `props` schema — what the DSL passes. */\nexport type PropsOf<M> = M extends\n  | EmailTemplate<infer S>\n  | PushTemplate<infer S>\n  | DiscordTemplate<infer S, never>\n  | SlackTemplate<infer S, never>\n  ? core.input<S> extends object\n    ? core.input<S>\n    : EmptyProps\n  : never;\n"],"mappings":";;AA2BA,MAAM,gBACgB,aACY,SAAoC;CAAE;CAAS;AAAI;;;;;;AAOrF,MAAa,WAA4B;CACvC,KAAK,aAAa,KAAK;CACvB,OAAO,aAAa,QAAQ;CAC5B,QAAQ,aAAa,QAAQ;AAC/B"}
+{"version":3,"file":"template.cjs","names":[],"sources":["../../src/dsl/template.ts"],"sourcesContent":["/**\n * Templates in the DSL. The four channels with template definitions (email, push, discord,\n * slack) take the definition itself — `.email(welcome, props)` — so its Zod `props` schema types\n * the call (`PropsOf`) and its `id` lands in the IR. The channels rendered by app-supplied\n * senders (sms, in-app, survey) have no definition; they take a hand-typed reference by key.\n */\n\nimport type * as core from 'zod/v4/core';\nimport type { DiscordTemplate, EmailTemplate, PushTemplate, SlackTemplate } from '../templates';\n\nexport type Channel = 'email' | 'sms' | 'push' | 'in_app' | 'slack' | 'discord' | 'survey';\n\nexport type EmptyProps = Record<string, never>;\n\n/** A template by key, its props typed by hand: for the channels without template definitions. */\nexport interface TemplateRef<C extends Channel = Channel, P extends object = object> {\n  readonly channel: C;\n  readonly key: string;\n  readonly __props?: P;\n}\n\nexport interface TemplateFactory {\n  sms<P extends object = EmptyProps>(key: string): TemplateRef<'sms', P>;\n  inApp<P extends object = EmptyProps>(key: string): TemplateRef<'in_app', P>;\n  survey<P extends object = EmptyProps>(key: string): TemplateRef<'survey', P>;\n}\n\nconst makeTemplate =\n  <C extends Channel>(channel: C) =>\n  <P extends object = EmptyProps>(key: string): TemplateRef<C, P> => ({ channel, key });\n\n/**\n * Template references for the channels an app-supplied sender renders:\n *\n *   const code = template.sms<{ code: string }>('login_code');\n */\nexport const template: TemplateFactory = {\n  sms: makeTemplate('sms'),\n  inApp: makeTemplate('in_app'),\n  survey: makeTemplate('survey'),\n};\n\n/** Template props: the input type of the template's Zod `props` schema — what the DSL passes. */\nexport type PropsOf<M> = M extends\n  | EmailTemplate<infer S>\n  | PushTemplate<infer S>\n  | DiscordTemplate<infer S, never>\n  | SlackTemplate<infer S, never>\n  ? core.input<S> extends object\n    ? core.input<S>\n    : EmptyProps\n  : never;\n"],"mappings":";;AA2BA,MAAM,gBACgB,aACY,SAAoC;CAAE;CAAS;AAAI;;;;;;AAOrF,MAAa,WAA4B;CACvC,KAAK,aAAa,KAAK;CACvB,OAAO,aAAa,QAAQ;CAC5B,QAAQ,aAAa,QAAQ;AAC/B"}

package/dist/dsl/template.d.cts

@@ -2,9 +2,9 @@ import { DiscordTemplate, EmailTemplate, PushTemplate, SlackTemplate } from "../
 import * as core from "zod/v4/core";
 //#region src/dsl/template.d.ts
 export type Channel = 'email' | 'sms' | 'push' | 'in_app' | 'slack' | 'discord' | 'survey';
-export type EmptyProps = Record<never, never>;
+export type EmptyProps = Record<string, never>;
 /** A template by key, its props typed by hand: for the channels without template definitions. */
-export interface TemplateRef<C extends Channel = Channel, P extends object = EmptyProps> {
+export interface TemplateRef<C extends Channel = Channel, P extends object = object> {
   readonly channel: C;
   readonly key: string;
   readonly __props?: P;

package/dist/dsl/template.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.cts","names":[],"sources":["../../src/dsl/template.ts"],"mappings":";;;YAUY;YAEA,aAAa;;iBAGR,YAAY,UAAU,UAAU,SAAS,mBAAmB;WAClE,SAAS;WACT;WACA,UAAU;;iBAGJ;EACf,IAAI,mBAAmB,YAAY,cAAc,mBAAmB;EACpE,MAAM,mBAAmB,YAAY,cAAc,sBAAsB;EACzE,OAAO,mBAAmB,YAAY,cAAc,sBAAsB;;;;;;;qBAY/D,UAAU;;YAOX,QAAQ,KAAK,UACrB,oBAAoB,KACpB,mBAAmB,KACnB,sBAAsB,YACtB,oBAAoB,YACpB,KAAK,MAAM,oBACT,KAAK,MAAM,KACX"}
+{"version":3,"file":"template.d.cts","names":[],"sources":["../../src/dsl/template.ts"],"mappings":";;;YAUY;YAEA,aAAa;;iBAGR,YAAY,UAAU,UAAU,SAAS;WAC/C,SAAS;WACT;WACA,UAAU;;iBAGJ;EACf,IAAI,mBAAmB,YAAY,cAAc,mBAAmB;EACpE,MAAM,mBAAmB,YAAY,cAAc,sBAAsB;EACzE,OAAO,mBAAmB,YAAY,cAAc,sBAAsB;;;;;;;qBAY/D,UAAU;;YAOX,QAAQ,KAAK,UACrB,oBAAoB,KACpB,mBAAmB,KACnB,sBAAsB,YACtB,oBAAoB,YACpB,KAAK,MAAM,oBACT,KAAK,MAAM,KACX"}

package/dist/dsl/template.d.mts

@@ -2,9 +2,9 @@ import { DiscordTemplate, EmailTemplate, PushTemplate, SlackTemplate } from "../
 import * as core from "zod/v4/core";
 //#region src/dsl/template.d.ts
 export type Channel = 'email' | 'sms' | 'push' | 'in_app' | 'slack' | 'discord' | 'survey';
-export type EmptyProps = Record<never, never>;
+export type EmptyProps = Record<string, never>;
 /** A template by key, its props typed by hand: for the channels without template definitions. */
-export interface TemplateRef<C extends Channel = Channel, P extends object = EmptyProps> {
+export interface TemplateRef<C extends Channel = Channel, P extends object = object> {
   readonly channel: C;
   readonly key: string;
   readonly __props?: P;

package/dist/dsl/template.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.mts","names":[],"sources":["../../src/dsl/template.ts"],"mappings":";;;YAUY;YAEA,aAAa;;iBAGR,YAAY,UAAU,UAAU,SAAS,mBAAmB;WAClE,SAAS;WACT;WACA,UAAU;;iBAGJ;EACf,IAAI,mBAAmB,YAAY,cAAc,mBAAmB;EACpE,MAAM,mBAAmB,YAAY,cAAc,sBAAsB;EACzE,OAAO,mBAAmB,YAAY,cAAc,sBAAsB;;;;;;;qBAY/D,UAAU;;YAOX,QAAQ,KAAK,UACrB,oBAAoB,KACpB,mBAAmB,KACnB,sBAAsB,YACtB,oBAAoB,YACpB,KAAK,MAAM,oBACT,KAAK,MAAM,KACX"}
+{"version":3,"file":"template.d.mts","names":[],"sources":["../../src/dsl/template.ts"],"mappings":";;;YAUY;YAEA,aAAa;;iBAGR,YAAY,UAAU,UAAU,SAAS;WAC/C,SAAS;WACT;WACA,UAAU;;iBAGJ;EACf,IAAI,mBAAmB,YAAY,cAAc,mBAAmB;EACpE,MAAM,mBAAmB,YAAY,cAAc,sBAAsB;EACzE,OAAO,mBAAmB,YAAY,cAAc,sBAAsB;;;;;;;qBAY/D,UAAU;;YAOX,QAAQ,KAAK,UACrB,oBAAoB,KACpB,mBAAmB,KACnB,sBAAsB,YACtB,oBAAoB,YACpB,KAAK,MAAM,oBACT,KAAK,MAAM,KACX"}

package/dist/dsl/template.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"template.mjs","names":[],"sources":["../../src/dsl/template.ts"],"sourcesContent":["/**\n * Templates in the DSL. The four channels with template definitions (email, push, discord,\n * slack) take the definition itself — `.email(welcome, props)` — so its Zod `props` schema types\n * the call (`PropsOf`) and its `id` lands in the IR. The channels rendered by app-supplied\n * senders (sms, in-app, survey) have no definition; they take a hand-typed reference by key.\n */\n\nimport type * as core from 'zod/v4/core';\nimport type { DiscordTemplate, EmailTemplate, PushTemplate, SlackTemplate } from '../templates';\n\nexport type Channel = 'email' | 'sms' | 'push' | 'in_app' | 'slack' | 'discord' | 'survey';\n\nexport type EmptyProps = Record<never, never>;\n\n/** A template by key, its props typed by hand: for the channels without template definitions. */\nexport interface TemplateRef<C extends Channel = Channel, P extends object = EmptyProps> {\n  readonly channel: C;\n  readonly key: string;\n  readonly __props?: P;\n}\n\nexport interface TemplateFactory {\n  sms<P extends object = EmptyProps>(key: string): TemplateRef<'sms', P>;\n  inApp<P extends object = EmptyProps>(key: string): TemplateRef<'in_app', P>;\n  survey<P extends object = EmptyProps>(key: string): TemplateRef<'survey', P>;\n}\n\nconst makeTemplate =\n  <C extends Channel>(channel: C) =>\n  <P extends object = EmptyProps>(key: string): TemplateRef<C, P> => ({ channel, key });\n\n/**\n * Template references for the channels an app-supplied sender renders:\n *\n *   const code = template.sms<{ code: string }>('login_code');\n */\nexport const template: TemplateFactory = {\n  sms: makeTemplate('sms'),\n  inApp: makeTemplate('in_app'),\n  survey: makeTemplate('survey'),\n};\n\n/** Template props: the input type of the template's Zod `props` schema — what the DSL passes. */\nexport type PropsOf<M> = M extends\n  | EmailTemplate<infer S>\n  | PushTemplate<infer S>\n  | DiscordTemplate<infer S, never>\n  | SlackTemplate<infer S, never>\n  ? core.input<S> extends object\n    ? core.input<S>\n    : EmptyProps\n  : never;\n"],"mappings":";AA2BA,MAAM,gBACgB,aACY,SAAoC;CAAE;CAAS;AAAI;;;;;;AAOrF,MAAa,WAA4B;CACvC,KAAK,aAAa,KAAK;CACvB,OAAO,aAAa,QAAQ;CAC5B,QAAQ,aAAa,QAAQ;AAC/B"}
+{"version":3,"file":"template.mjs","names":[],"sources":["../../src/dsl/template.ts"],"sourcesContent":["/**\n * Templates in the DSL. The four channels with template definitions (email, push, discord,\n * slack) take the definition itself — `.email(welcome, props)` — so its Zod `props` schema types\n * the call (`PropsOf`) and its `id` lands in the IR. The channels rendered by app-supplied\n * senders (sms, in-app, survey) have no definition; they take a hand-typed reference by key.\n */\n\nimport type * as core from 'zod/v4/core';\nimport type { DiscordTemplate, EmailTemplate, PushTemplate, SlackTemplate } from '../templates';\n\nexport type Channel = 'email' | 'sms' | 'push' | 'in_app' | 'slack' | 'discord' | 'survey';\n\nexport type EmptyProps = Record<string, never>;\n\n/** A template by key, its props typed by hand: for the channels without template definitions. */\nexport interface TemplateRef<C extends Channel = Channel, P extends object = object> {\n  readonly channel: C;\n  readonly key: string;\n  readonly __props?: P;\n}\n\nexport interface TemplateFactory {\n  sms<P extends object = EmptyProps>(key: string): TemplateRef<'sms', P>;\n  inApp<P extends object = EmptyProps>(key: string): TemplateRef<'in_app', P>;\n  survey<P extends object = EmptyProps>(key: string): TemplateRef<'survey', P>;\n}\n\nconst makeTemplate =\n  <C extends Channel>(channel: C) =>\n  <P extends object = EmptyProps>(key: string): TemplateRef<C, P> => ({ channel, key });\n\n/**\n * Template references for the channels an app-supplied sender renders:\n *\n *   const code = template.sms<{ code: string }>('login_code');\n */\nexport const template: TemplateFactory = {\n  sms: makeTemplate('sms'),\n  inApp: makeTemplate('in_app'),\n  survey: makeTemplate('survey'),\n};\n\n/** Template props: the input type of the template's Zod `props` schema — what the DSL passes. */\nexport type PropsOf<M> = M extends\n  | EmailTemplate<infer S>\n  | PushTemplate<infer S>\n  | DiscordTemplate<infer S, never>\n  | SlackTemplate<infer S, never>\n  ? core.input<S> extends object\n    ? core.input<S>\n    : EmptyProps\n  : never;\n"],"mappings":";AA2BA,MAAM,gBACgB,aACY,SAAoC;CAAE;CAAS;AAAI;;;;;;AAOrF,MAAa,WAA4B;CACvC,KAAK,aAAa,KAAK;CACvB,OAAO,aAAa,QAAQ;CAC5B,QAAQ,aAAa,QAAQ;AAC/B"}

package/dist/email-sender.cjs

@@ -0,0 +1,62 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_email = require("./email.cjs");
+//#region src/email-sender.ts
+/**
+* The email channel over any transport: render → tracking applied to the HTML → the tracked
+* links committed → the transport. The links resolve before the email exists anywhere a
+* scanner could follow them.
+*/
+var EmailSender = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	async send(message) {
+		if (message.channel !== "email") throw new Error(`EmailSender: unsupported channel '${message.channel}'`);
+		if (message.recipient === void 0) throw new Error(`EmailSender: no recipient for user '${message.userId}'`);
+		const { subject, html, from, replyTo, unsubscribeUrl } = await this.options.render(message.template, message.props);
+		const tracked = message.tracking === void 0 ? html : trackEmail(html, message.tracking, unsubscribeUrl);
+		await message.tracking?.commit?.();
+		await this.options.transport.send({
+			from,
+			to: message.recipient,
+			...replyTo === void 0 ? {} : { replyTo },
+			subject,
+			html: tracked,
+			idempotencyKey: message.idempotencyKey
+		});
+	}
+};
+const LINK = /(<a\b[^>]*?\shref\s*=\s*)(["'])(https?:\/\/[^"']+)\2/gi;
+/**
+* An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through
+* `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back) —
+* as the unsubscribe link when it is the one the email was rendered with, so what a click on it
+* means is fixed when the email is sent — and the open pixel appended before `</body>`, or at the
+* end when there is none.
+*/
+function trackEmail(html, tracking, unsubscribeUrl) {
+	const { link, pixel } = tracking;
+	let out = html;
+	if (link !== void 0) out = out.replace(LINK, (_, start, quote, attribute) => {
+		const url = unescapeAttribute(attribute);
+		const purpose = require_email.isUnsubscribeLink(url, unsubscribeUrl) ? "unsubscribe" : "link";
+		return `${start}${quote}${escapeAttribute(link(url, purpose))}${quote}`;
+	});
+	if (pixel !== void 0) {
+		const image = `<img src="${escapeAttribute(pixel)}" width="1" height="1" alt="" style="display:block;border:0;width:1px;height:1px" />`;
+		out = /<\/body>/i.test(out) ? out.replace(/<\/body>/i, `${image}</body>`) : `${out}${image}`;
+	}
+	return out;
+}
+function unescapeAttribute(value) {
+	return value.replaceAll("&amp;", "&").replaceAll("&quot;", "\"").replaceAll("&#x27;", "'");
+}
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+}
+//#endregion
+exports.EmailSender = EmailSender;
+exports.trackEmail = trackEmail;
+
+//# sourceMappingURL=email-sender.cjs.map

package/dist/email-sender.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-sender.cjs","names":["isUnsubscribeLink"],"sources":["../src/email-sender.ts"],"sourcesContent":["import { type EmailAddress, type ResolvedEmail, isUnsubscribeLink } from './email';\nimport type { MessageSender, MessageTracking, OutboundMessage } from './engine/ports';\nimport type { ScalarIR } from './ir';\n\n/**\n * The email channel, split where the runtime stops mattering: `EmailSender` renders a copy,\n * applies its tracking and commits the tracked links — the same on every host — and hands the\n * finished email to an `EmailTransport`, the only part that knows a provider (SES, Cloudflare\n * Email, ...). Nothing here imports a platform module, so a Worker and a Lambda share it.\n */\n\n/** A rendered email: the template's resolved metadata (`resolveEmail`), its subject and its HTML. */\nexport interface RenderedEmail extends ResolvedEmail {\n  subject: string;\n  html: string;\n}\n\n/**\n * Template renderer, injected by the app — this package's core stays free of\n * any react-email dependency (`@shware/workflow/react-email` ships one over a\n * registry). The subject comes back final: it is sent exactly as written, from\n * the template's own sender, and the unsubscribe link is the one the HTML was\n * rendered with.\n */\nexport type EmailRenderer = (\n  template: string,\n  props: Record<string, ScalarIR | undefined>\n) => Promise<RenderedEmail>;\n\n/** A finished email, as a transport takes it: rendered, tracked, addressed. */\nexport interface EmailMessage {\n  from: EmailAddress;\n  to: string;\n  replyTo?: EmailAddress;\n  subject: string;\n  html: string;\n  /**\n   * `${instanceId}:${nodeId}`: the copy's identity, stable across retries and replays. A provider\n   * that de-duplicates on a key receives it; one that cannot (SES) still sends at least once —\n   * the window between the provider accepting the email and the step's checkpoint stays open.\n   */\n  idempotencyKey: string;\n}\n\n/**\n * One email provider. Throwing hands the retry to the durable step; resolving means the provider\n * accepted the email (not that it was delivered).\n */\nexport interface EmailTransport {\n  send(message: EmailMessage): Promise<{ providerMessageId?: string }>;\n}\n\nexport interface EmailSenderOptions {\n  transport: EmailTransport;\n  render: EmailRenderer;\n}\n\n/**\n * The email channel over any transport: render → tracking applied to the HTML → the tracked\n * links committed → the transport. The links resolve before the email exists anywhere a\n * scanner could follow them.\n */\nexport class EmailSender implements MessageSender {\n  constructor(private readonly options: EmailSenderOptions) {}\n\n  async send(message: OutboundMessage): Promise<void> {\n    if (message.channel !== 'email') {\n      throw new Error(`EmailSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`EmailSender: no recipient for user '${message.userId}'`);\n    }\n    const { subject, html, from, replyTo, unsubscribeUrl } = await this.options.render(\n      message.template,\n      message.props\n    );\n    const tracked =\n      message.tracking === undefined ? html : trackEmail(html, message.tracking, unsubscribeUrl);\n    await message.tracking?.commit?.();\n    await this.options.transport.send({\n      from,\n      to: message.recipient,\n      ...(replyTo === undefined ? {} : { replyTo }),\n      subject,\n      html: tracked,\n      idempotencyKey: message.idempotencyKey,\n    });\n  }\n}\n\nconst LINK = /(<a\\b[^>]*?\\shref\\s*=\\s*)([\"'])(https?:\\/\\/[^\"']+)\\2/gi;\n\n/**\n * An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through\n * `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back) —\n * as the unsubscribe link when it is the one the email was rendered with, so what a click on it\n * means is fixed when the email is sent — and the open pixel appended before `</body>`, or at the\n * end when there is none.\n */\nexport function trackEmail(\n  html: string,\n  tracking: MessageTracking,\n  unsubscribeUrl?: string\n): string {\n  const { link, pixel } = tracking;\n  let out = html;\n  if (link !== undefined) {\n    out = out.replace(LINK, (_, start: string, quote: string, attribute: string) => {\n      const url = unescapeAttribute(attribute);\n      const purpose = isUnsubscribeLink(url, unsubscribeUrl) ? 'unsubscribe' : 'link';\n      return `${start}${quote}${escapeAttribute(link(url, purpose))}${quote}`;\n    });\n  }\n  if (pixel !== undefined) {\n    const image = `<img src=\"${escapeAttribute(pixel)}\" width=\"1\" height=\"1\" alt=\"\" style=\"display:block;border:0;width:1px;height:1px\" />`;\n    out = /<\\/body>/i.test(out) ? out.replace(/<\\/body>/i, `${image}</body>`) : `${out}${image}`;\n  }\n  return out;\n}\n\nfunction unescapeAttribute(value: string): string {\n  return value.replaceAll('&amp;', '&').replaceAll('&quot;', '\"').replaceAll('&#x27;', \"'\");\n}\n\nfunction escapeAttribute(value: string): string {\n  return value.replaceAll('&', '&amp;').replaceAll('\"', '&quot;');\n}\n"],"mappings":";;;;;;;;AA8DA,IAAa,cAAb,MAAkD;CACnB;CAA7B,YAAY,SAA8C;EAA7B,KAAA,UAAA;CAA8B;CAE3D,MAAM,KAAK,SAAyC;EAClD,IAAI,QAAQ,YAAY,SACtB,MAAM,IAAI,MAAM,qCAAqC,QAAQ,QAAQ,EAAE;EAEzE,IAAI,QAAQ,cAAc,KAAA,GACxB,MAAM,IAAI,MAAM,uCAAuC,QAAQ,OAAO,EAAE;EAE1E,MAAM,EAAE,SAAS,MAAM,MAAM,SAAS,mBAAmB,MAAM,KAAK,QAAQ,OAC1E,QAAQ,UACR,QAAQ,KACV;EACA,MAAM,UACJ,QAAQ,aAAa,KAAA,IAAY,OAAO,WAAW,MAAM,QAAQ,UAAU,cAAc;EAC3F,MAAM,QAAQ,UAAU,SAAS;EACjC,MAAM,KAAK,QAAQ,UAAU,KAAK;GAChC;GACA,IAAI,QAAQ;GACZ,GAAI,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ;GAC3C;GACA,MAAM;GACN,gBAAgB,QAAQ;EAC1B,CAAC;CACH;AACF;AAEA,MAAM,OAAO;;;;;;;;AASb,SAAgB,WACd,MACA,UACA,gBACQ;CACR,MAAM,EAAE,MAAM,UAAU;CACxB,IAAI,MAAM;CACV,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,QAAQ,OAAO,GAAG,OAAe,OAAe,cAAsB;EAC9E,MAAM,MAAM,kBAAkB,SAAS;EACvC,MAAM,UAAUA,cAAAA,kBAAkB,KAAK,cAAc,IAAI,gBAAgB;EACzE,OAAO,GAAG,QAAQ,QAAQ,gBAAgB,KAAK,KAAK,OAAO,CAAC,IAAI;CAClE,CAAC;CAEH,IAAI,UAAU,KAAA,GAAW;EACvB,MAAM,QAAQ,aAAa,gBAAgB,KAAK,EAAE;EAClD,MAAM,YAAY,KAAK,GAAG,IAAI,IAAI,QAAQ,aAAa,GAAG,MAAM,QAAQ,IAAI,GAAG,MAAM;CACvF;CACA,OAAO;AACT;AAEA,SAAS,kBAAkB,OAAuB;CAChD,OAAO,MAAM,WAAW,SAAS,GAAG,CAAC,CAAC,WAAW,UAAU,IAAG,CAAC,CAAC,WAAW,UAAU,GAAG;AAC1F;AAEA,SAAS,gBAAgB,OAAuB;CAC9C,OAAO,MAAM,WAAW,KAAK,OAAO,CAAC,CAAC,WAAW,MAAK,QAAQ;AAChE"}

package/dist/email-sender.d.cts

@@ -0,0 +1,70 @@
+import { ScalarIR } from "./ir.cjs";
+import { MessageSender, MessageTracking, OutboundMessage } from "./engine/ports.cjs";
+import { EmailAddress, ResolvedEmail } from "./email.cjs";
+//#region src/email-sender.d.ts
+/**
+ * The email channel, split where the runtime stops mattering: `EmailSender` renders a copy,
+ * applies its tracking and commits the tracked links — the same on every host — and hands the
+ * finished email to an `EmailTransport`, the only part that knows a provider (SES, Cloudflare
+ * Email, ...). Nothing here imports a platform module, so a Worker and a Lambda share it.
+ */
+/** A rendered email: the template's resolved metadata (`resolveEmail`), its subject and its HTML. */
+export interface RenderedEmail extends ResolvedEmail {
+  subject: string;
+  html: string;
+}
+/**
+ * Template renderer, injected by the app — this package's core stays free of
+ * any react-email dependency (`@shware/workflow/react-email` ships one over a
+ * registry). The subject comes back final: it is sent exactly as written, from
+ * the template's own sender, and the unsubscribe link is the one the HTML was
+ * rendered with.
+ */
+export type EmailRenderer = (template: string, props: Record<string, ScalarIR | undefined>) => Promise<RenderedEmail>;
+/** A finished email, as a transport takes it: rendered, tracked, addressed. */
+export interface EmailMessage {
+  from: EmailAddress;
+  to: string;
+  replyTo?: EmailAddress;
+  subject: string;
+  html: string;
+  /**
+   * `${instanceId}:${nodeId}`: the copy's identity, stable across retries and replays. A provider
+   * that de-duplicates on a key receives it; one that cannot (SES) still sends at least once —
+   * the window between the provider accepting the email and the step's checkpoint stays open.
+   */
+  idempotencyKey: string;
+}
+/**
+ * One email provider. Throwing hands the retry to the durable step; resolving means the provider
+ * accepted the email (not that it was delivered).
+ */
+export interface EmailTransport {
+  send(message: EmailMessage): Promise<{
+    providerMessageId?: string;
+  }>;
+}
+export interface EmailSenderOptions {
+  transport: EmailTransport;
+  render: EmailRenderer;
+}
+/**
+ * The email channel over any transport: render → tracking applied to the HTML → the tracked
+ * links committed → the transport. The links resolve before the email exists anywhere a
+ * scanner could follow them.
+ */
+export declare class EmailSender implements MessageSender {
+  private readonly options;
+  constructor(options: EmailSenderOptions);
+  send(message: OutboundMessage): Promise<void>;
+}
+/**
+ * An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through
+ * `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back) —
+ * as the unsubscribe link when it is the one the email was rendered with, so what a click on it
+ * means is fixed when the email is sent — and the open pixel appended before `</body>`, or at the
+ * end when there is none.
+ */
+export declare function trackEmail(html: string, tracking: MessageTracking, unsubscribeUrl?: string): string;
+//#endregion
+//# sourceMappingURL=email-sender.d.cts.map

package/dist/email-sender.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-sender.d.cts","names":[],"sources":["../src/email-sender.ts"],"mappings":";;;;;;;;;;;iBAYiB,sBAAsB;EACrC;EACA;;;;;;;;;YAUU,iBACV,kBACA,OAAO,eAAe,0BACnB,QAAQ;;iBAGI;EACf,MAAM;EACN;EACA,UAAU;EACV;EACA;;;;;;EAMA;;;;;;iBAOe;EACf,KAAK,SAAS,eAAe;IAAU;;;iBAGxB;EACf,WAAW;EACX,QAAQ;;;;;;;qBAQG,uBAAuB;mBACL;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB;;;;;;;;;wBAkCxB,WACd,cACA,UAAU,iBACV"}

package/dist/email-sender.d.mts

@@ -0,0 +1,70 @@
+import { ScalarIR } from "./ir.mjs";
+import { MessageSender, MessageTracking, OutboundMessage } from "./engine/ports.mjs";
+import { EmailAddress, ResolvedEmail } from "./email.mjs";
+//#region src/email-sender.d.ts
+/**
+ * The email channel, split where the runtime stops mattering: `EmailSender` renders a copy,
+ * applies its tracking and commits the tracked links — the same on every host — and hands the
+ * finished email to an `EmailTransport`, the only part that knows a provider (SES, Cloudflare
+ * Email, ...). Nothing here imports a platform module, so a Worker and a Lambda share it.
+ */
+/** A rendered email: the template's resolved metadata (`resolveEmail`), its subject and its HTML. */
+export interface RenderedEmail extends ResolvedEmail {
+  subject: string;
+  html: string;
+}
+/**
+ * Template renderer, injected by the app — this package's core stays free of
+ * any react-email dependency (`@shware/workflow/react-email` ships one over a
+ * registry). The subject comes back final: it is sent exactly as written, from
+ * the template's own sender, and the unsubscribe link is the one the HTML was
+ * rendered with.
+ */
+export type EmailRenderer = (template: string, props: Record<string, ScalarIR | undefined>) => Promise<RenderedEmail>;
+/** A finished email, as a transport takes it: rendered, tracked, addressed. */
+export interface EmailMessage {
+  from: EmailAddress;
+  to: string;
+  replyTo?: EmailAddress;
+  subject: string;
+  html: string;
+  /**
+   * `${instanceId}:${nodeId}`: the copy's identity, stable across retries and replays. A provider
+   * that de-duplicates on a key receives it; one that cannot (SES) still sends at least once —
+   * the window between the provider accepting the email and the step's checkpoint stays open.
+   */
+  idempotencyKey: string;
+}
+/**
+ * One email provider. Throwing hands the retry to the durable step; resolving means the provider
+ * accepted the email (not that it was delivered).
+ */
+export interface EmailTransport {
+  send(message: EmailMessage): Promise<{
+    providerMessageId?: string;
+  }>;
+}
+export interface EmailSenderOptions {
+  transport: EmailTransport;
+  render: EmailRenderer;
+}
+/**
+ * The email channel over any transport: render → tracking applied to the HTML → the tracked
+ * links committed → the transport. The links resolve before the email exists anywhere a
+ * scanner could follow them.
+ */
+export declare class EmailSender implements MessageSender {
+  private readonly options;
+  constructor(options: EmailSenderOptions);
+  send(message: OutboundMessage): Promise<void>;
+}
+/**
+ * An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through
+ * `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back) —
+ * as the unsubscribe link when it is the one the email was rendered with, so what a click on it
+ * means is fixed when the email is sent — and the open pixel appended before `</body>`, or at the
+ * end when there is none.
+ */
+export declare function trackEmail(html: string, tracking: MessageTracking, unsubscribeUrl?: string): string;
+//#endregion
+//# sourceMappingURL=email-sender.d.mts.map

package/dist/email-sender.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-sender.d.mts","names":[],"sources":["../src/email-sender.ts"],"mappings":";;;;;;;;;;;iBAYiB,sBAAsB;EACrC;EACA;;;;;;;;;YAUU,iBACV,kBACA,OAAO,eAAe,0BACnB,QAAQ;;iBAGI;EACf,MAAM;EACN;EACA,UAAU;EACV;EACA;;;;;;EAMA;;;;;;iBAOe;EACf,KAAK,SAAS,eAAe;IAAU;;;iBAGxB;EACf,WAAW;EACX,QAAQ;;;;;;;qBAQG,uBAAuB;mBACL;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB;;;;;;;;;wBAkCxB,WACd,cACA,UAAU,iBACV"}

package/dist/email-sender.mjs

@@ -0,0 +1,60 @@
+import { isUnsubscribeLink } from "./email.mjs";
+//#region src/email-sender.ts
+/**
+* The email channel over any transport: render → tracking applied to the HTML → the tracked
+* links committed → the transport. The links resolve before the email exists anywhere a
+* scanner could follow them.
+*/
+var EmailSender = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	async send(message) {
+		if (message.channel !== "email") throw new Error(`EmailSender: unsupported channel '${message.channel}'`);
+		if (message.recipient === void 0) throw new Error(`EmailSender: no recipient for user '${message.userId}'`);
+		const { subject, html, from, replyTo, unsubscribeUrl } = await this.options.render(message.template, message.props);
+		const tracked = message.tracking === void 0 ? html : trackEmail(html, message.tracking, unsubscribeUrl);
+		await message.tracking?.commit?.();
+		await this.options.transport.send({
+			from,
+			to: message.recipient,
+			...replyTo === void 0 ? {} : { replyTo },
+			subject,
+			html: tracked,
+			idempotencyKey: message.idempotencyKey
+		});
+	}
+};
+const LINK = /(<a\b[^>]*?\shref\s*=\s*)(["'])(https?:\/\/[^"']+)\2/gi;
+/**
+* An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through
+* `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back) —
+* as the unsubscribe link when it is the one the email was rendered with, so what a click on it
+* means is fixed when the email is sent — and the open pixel appended before `</body>`, or at the
+* end when there is none.
+*/
+function trackEmail(html, tracking, unsubscribeUrl) {
+	const { link, pixel } = tracking;
+	let out = html;
+	if (link !== void 0) out = out.replace(LINK, (_, start, quote, attribute) => {
+		const url = unescapeAttribute(attribute);
+		const purpose = isUnsubscribeLink(url, unsubscribeUrl) ? "unsubscribe" : "link";
+		return `${start}${quote}${escapeAttribute(link(url, purpose))}${quote}`;
+	});
+	if (pixel !== void 0) {
+		const image = `<img src="${escapeAttribute(pixel)}" width="1" height="1" alt="" style="display:block;border:0;width:1px;height:1px" />`;
+		out = /<\/body>/i.test(out) ? out.replace(/<\/body>/i, `${image}</body>`) : `${out}${image}`;
+	}
+	return out;
+}
+function unescapeAttribute(value) {
+	return value.replaceAll("&amp;", "&").replaceAll("&quot;", "\"").replaceAll("&#x27;", "'");
+}
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+}
+//#endregion
+export { EmailSender, trackEmail };
+
+//# sourceMappingURL=email-sender.mjs.map

package/dist/email-sender.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-sender.mjs","names":[],"sources":["../src/email-sender.ts"],"sourcesContent":["import { type EmailAddress, type ResolvedEmail, isUnsubscribeLink } from './email';\nimport type { MessageSender, MessageTracking, OutboundMessage } from './engine/ports';\nimport type { ScalarIR } from './ir';\n\n/**\n * The email channel, split where the runtime stops mattering: `EmailSender` renders a copy,\n * applies its tracking and commits the tracked links — the same on every host — and hands the\n * finished email to an `EmailTransport`, the only part that knows a provider (SES, Cloudflare\n * Email, ...). Nothing here imports a platform module, so a Worker and a Lambda share it.\n */\n\n/** A rendered email: the template's resolved metadata (`resolveEmail`), its subject and its HTML. */\nexport interface RenderedEmail extends ResolvedEmail {\n  subject: string;\n  html: string;\n}\n\n/**\n * Template renderer, injected by the app — this package's core stays free of\n * any react-email dependency (`@shware/workflow/react-email` ships one over a\n * registry). The subject comes back final: it is sent exactly as written, from\n * the template's own sender, and the unsubscribe link is the one the HTML was\n * rendered with.\n */\nexport type EmailRenderer = (\n  template: string,\n  props: Record<string, ScalarIR | undefined>\n) => Promise<RenderedEmail>;\n\n/** A finished email, as a transport takes it: rendered, tracked, addressed. */\nexport interface EmailMessage {\n  from: EmailAddress;\n  to: string;\n  replyTo?: EmailAddress;\n  subject: string;\n  html: string;\n  /**\n   * `${instanceId}:${nodeId}`: the copy's identity, stable across retries and replays. A provider\n   * that de-duplicates on a key receives it; one that cannot (SES) still sends at least once —\n   * the window between the provider accepting the email and the step's checkpoint stays open.\n   */\n  idempotencyKey: string;\n}\n\n/**\n * One email provider. Throwing hands the retry to the durable step; resolving means the provider\n * accepted the email (not that it was delivered).\n */\nexport interface EmailTransport {\n  send(message: EmailMessage): Promise<{ providerMessageId?: string }>;\n}\n\nexport interface EmailSenderOptions {\n  transport: EmailTransport;\n  render: EmailRenderer;\n}\n\n/**\n * The email channel over any transport: render → tracking applied to the HTML → the tracked\n * links committed → the transport. The links resolve before the email exists anywhere a\n * scanner could follow them.\n */\nexport class EmailSender implements MessageSender {\n  constructor(private readonly options: EmailSenderOptions) {}\n\n  async send(message: OutboundMessage): Promise<void> {\n    if (message.channel !== 'email') {\n      throw new Error(`EmailSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`EmailSender: no recipient for user '${message.userId}'`);\n    }\n    const { subject, html, from, replyTo, unsubscribeUrl } = await this.options.render(\n      message.template,\n      message.props\n    );\n    const tracked =\n      message.tracking === undefined ? html : trackEmail(html, message.tracking, unsubscribeUrl);\n    await message.tracking?.commit?.();\n    await this.options.transport.send({\n      from,\n      to: message.recipient,\n      ...(replyTo === undefined ? {} : { replyTo }),\n      subject,\n      html: tracked,\n      idempotencyKey: message.idempotencyKey,\n    });\n  }\n}\n\nconst LINK = /(<a\\b[^>]*?\\shref\\s*=\\s*)([\"'])(https?:\\/\\/[^\"']+)\\2/gi;\n\n/**\n * An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through\n * `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back) —\n * as the unsubscribe link when it is the one the email was rendered with, so what a click on it\n * means is fixed when the email is sent — and the open pixel appended before `</body>`, or at the\n * end when there is none.\n */\nexport function trackEmail(\n  html: string,\n  tracking: MessageTracking,\n  unsubscribeUrl?: string\n): string {\n  const { link, pixel } = tracking;\n  let out = html;\n  if (link !== undefined) {\n    out = out.replace(LINK, (_, start: string, quote: string, attribute: string) => {\n      const url = unescapeAttribute(attribute);\n      const purpose = isUnsubscribeLink(url, unsubscribeUrl) ? 'unsubscribe' : 'link';\n      return `${start}${quote}${escapeAttribute(link(url, purpose))}${quote}`;\n    });\n  }\n  if (pixel !== undefined) {\n    const image = `<img src=\"${escapeAttribute(pixel)}\" width=\"1\" height=\"1\" alt=\"\" style=\"display:block;border:0;width:1px;height:1px\" />`;\n    out = /<\\/body>/i.test(out) ? out.replace(/<\\/body>/i, `${image}</body>`) : `${out}${image}`;\n  }\n  return out;\n}\n\nfunction unescapeAttribute(value: string): string {\n  return value.replaceAll('&amp;', '&').replaceAll('&quot;', '\"').replaceAll('&#x27;', \"'\");\n}\n\nfunction escapeAttribute(value: string): string {\n  return value.replaceAll('&', '&amp;').replaceAll('\"', '&quot;');\n}\n"],"mappings":";;;;;;;AA8DA,IAAa,cAAb,MAAkD;CACnB;CAA7B,YAAY,SAA8C;EAA7B,KAAA,UAAA;CAA8B;CAE3D,MAAM,KAAK,SAAyC;EAClD,IAAI,QAAQ,YAAY,SACtB,MAAM,IAAI,MAAM,qCAAqC,QAAQ,QAAQ,EAAE;EAEzE,IAAI,QAAQ,cAAc,KAAA,GACxB,MAAM,IAAI,MAAM,uCAAuC,QAAQ,OAAO,EAAE;EAE1E,MAAM,EAAE,SAAS,MAAM,MAAM,SAAS,mBAAmB,MAAM,KAAK,QAAQ,OAC1E,QAAQ,UACR,QAAQ,KACV;EACA,MAAM,UACJ,QAAQ,aAAa,KAAA,IAAY,OAAO,WAAW,MAAM,QAAQ,UAAU,cAAc;EAC3F,MAAM,QAAQ,UAAU,SAAS;EACjC,MAAM,KAAK,QAAQ,UAAU,KAAK;GAChC;GACA,IAAI,QAAQ;GACZ,GAAI,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ;GAC3C;GACA,MAAM;GACN,gBAAgB,QAAQ;EAC1B,CAAC;CACH;AACF;AAEA,MAAM,OAAO;;;;;;;;AASb,SAAgB,WACd,MACA,UACA,gBACQ;CACR,MAAM,EAAE,MAAM,UAAU;CACxB,IAAI,MAAM;CACV,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,QAAQ,OAAO,GAAG,OAAe,OAAe,cAAsB;EAC9E,MAAM,MAAM,kBAAkB,SAAS;EACvC,MAAM,UAAU,kBAAkB,KAAK,cAAc,IAAI,gBAAgB;EACzE,OAAO,GAAG,QAAQ,QAAQ,gBAAgB,KAAK,KAAK,OAAO,CAAC,IAAI;CAClE,CAAC;CAEH,IAAI,UAAU,KAAA,GAAW;EACvB,MAAM,QAAQ,aAAa,gBAAgB,KAAK,EAAE;EAClD,MAAM,YAAY,KAAK,GAAG,IAAI,IAAI,QAAQ,aAAa,GAAG,MAAM,QAAQ,IAAI,GAAG,MAAM;CACvF;CACA,OAAO;AACT;AAEA,SAAS,kBAAkB,OAAuB;CAChD,OAAO,MAAM,WAAW,SAAS,GAAG,CAAC,CAAC,WAAW,UAAU,IAAG,CAAC,CAAC,WAAW,UAAU,GAAG;AAC1F;AAEA,SAAS,gBAAgB,OAAuB;CAC9C,OAAO,MAAM,WAAW,KAAK,OAAO,CAAC,CAAC,WAAW,MAAK,QAAQ;AAChE"}

package/dist/email.cjs

@@ -5,6 +5,26 @@ function formatEmailAddress(address) {
 	if (typeof address === "string") return address;
 	return address.name === void 0 ? address.email : `${address.name} <${address.email}>`;
 }
+const ASCII = /^[\x20-\x7e]*$/;
+const SPECIALS = /[()<>[\]:;@\\,."]/;
+/**
+* An address as a mail API reads it (RFC 5322): a display name with specials is quoted, one
+* outside ASCII is a MIME encoded-word — raw non-ASCII names are refused (SES), and an unquoted
+* comma splits the address in two.
+*/
+function mimeAddress(address) {
+	if (typeof address === "string") return address;
+	const { email, name } = address;
+	if (name === void 0 || name === "") return email;
+	if (!ASCII.test(name)) {
+		const bytes = new TextEncoder().encode(name);
+		let binary = "";
+		for (const byte of bytes) binary += String.fromCharCode(byte);
+		return `=?UTF-8?B?${btoa(binary)}?= <${email}>`;
+	}
+	if (SPECIALS.test(name)) return `"${name.replace(/(["\\])/g, "\\$1")}" <${email}>`;
+	return `${name} <${email}>`;
+}
 /** The template's metadata, its `unsubscribeUrl` falling back to the config's. Leaves both untouched. */
 function resolveEmail(template, config) {
 	const unsubscribeUrl = template.unsubscribeUrl ?? config?.unsubscribeUrl;
@@ -67,6 +87,7 @@ exports.assertEmailMetadata = assertEmailMetadata;
 exports.assertUnsubscribeUrl = assertUnsubscribeUrl;
 exports.formatEmailAddress = formatEmailAddress;
 exports.isUnsubscribeLink = isUnsubscribeLink;
+exports.mimeAddress = mimeAddress;
 exports.resolveEmail = resolveEmail;
 
 //# sourceMappingURL=email.cjs.map

package/dist/email.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"email.cjs","names":[],"sources":["../src/email.ts"],"sourcesContent":["import type { EmailTemplate } from './templates';\n\n/**\n * Email metadata: who a template's email comes from, where replies go, and the unsubscribe link\n * its layout carries. Each `emailTemplate` declares its own `from` (and `replyTo`, if replies should\n * go elsewhere); the unsubscribe link is the template's `unsubscribeUrl`, else the config's\n * `email.unsubscribeUrl`, else none. `resolveEmail` is that rule, and the sender, the renderer,\n * the Worker's preview and the studio all go through it. No React and no I/O here, so a browser\n * can import it.\n */\n\n/** An address as the transports take it: bare, or with a display name. */\nexport type EmailAddress = string | { email: string; name?: string };\n\n/** `Name <email>`, or the bare address. */\nexport function formatEmailAddress(address: EmailAddress): string {\n  if (typeof address === 'string') return address;\n  return address.name === undefined ? address.email : `${address.name} <${address.email}>`;\n}\n\n/** The config's `email`: what every email template shares. */\nexport interface EmailConfig {\n  /**\n   * The unsubscribe link of every email template that names none of its own. The layout reads it\n   * with `useEmailContext()`; sent, it is tracked like every link, but following it shows a\n   * confirmation page, and only the confirmation (a POST no link scanner sends) unsubscribes.\n   */\n  unsubscribeUrl?: string;\n  /** How the Worker tells a person's opens and clicks from a machine's (see the reporting classifier). */\n  tracking?: {\n    /**\n     * An open or click this many milliseconds after delivery is a weak machine signal — machine\n     * only together with another (a second link within seconds); 1000 by default. A person\n     * tapping a mail notification can click within a few seconds, so keep it short.\n     */\n    quickClickMs?: number;\n  };\n}\n\n/** One template's email metadata, resolved against the config. */\nexport interface ResolvedEmail {\n  from: EmailAddress;\n  /** Absent when the template names none: the email goes out without a Reply-To. */\n  replyTo?: EmailAddress;\n  /** Absent when neither the template nor the config names one: the email has no unsubscribe link. */\n  unsubscribeUrl?: string;\n}\n\n/** The template's metadata, its `unsubscribeUrl` falling back to the config's. Leaves both untouched. */\nexport function resolveEmail(\n  template: Pick<EmailTemplate, 'from' | 'replyTo' | 'unsubscribeUrl'>,\n  config?: EmailConfig\n): ResolvedEmail {\n  const unsubscribeUrl = template.unsubscribeUrl ?? config?.unsubscribeUrl;\n  return {\n    from: template.from,\n    ...(template.replyTo === undefined ? {} : { replyTo: template.replyTo }),\n    ...(unsubscribeUrl === undefined ? {} : { unsubscribeUrl }),\n  };\n}\n\nconst ADDRESS = /^[^\\s@<>]+@[^\\s@<>]+$/;\n\n/** Throws naming `where` when `address` is neither `user@host` nor `{ email: 'user@host', name? }`. */\nexport function assertEmailAddress(address: unknown, where: string): void {\n  const email =\n    typeof address === 'object' && address !== null\n      ? (address as { email?: unknown }).email\n      : address;\n  const name =\n    typeof address === 'object' && address !== null\n      ? (address as { name?: unknown }).name\n      : undefined;\n  if (typeof email !== 'string' || !ADDRESS.test(email)) {\n    throw new TypeError(`${where} must be an email address or { email, name? }`);\n  }\n  if (name !== undefined && typeof name !== 'string') {\n    throw new TypeError(`${where}.name must be a string`);\n  }\n}\n\n/** Throws naming `where` unless `url` is an absolute http(s) URL; '' and null are not a way to leave it out. */\nexport function assertUnsubscribeUrl(url: unknown, where: string): void {\n  let parsed: URL | undefined;\n  try {\n    parsed = typeof url === 'string' ? new URL(url) : undefined;\n  } catch {\n    parsed = undefined;\n  }\n  if (parsed === undefined || (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')) {\n    throw new TypeError(`${where} must be an http(s) URL (leave it out for none)`);\n  }\n}\n\n/** The config's `email` and every registered template's metadata; throws on the first invalid value. */\nexport function assertEmailConfig(\n  config: { email?: EmailConfig },\n  templates: Iterable<EmailTemplate>\n): void {\n  if (Object.hasOwn(config, 'emails')) {\n    throw new TypeError(\n      \"the config's `emails` is gone: `from` and `replyTo` are declared on each emailTemplate, \" +\n        'and the rest moved to `email: { unsubscribeUrl, tracking }`'\n    );\n  }\n  const email = config.email;\n  if (email !== undefined) {\n    if (email.unsubscribeUrl !== undefined) {\n      assertUnsubscribeUrl(email.unsubscribeUrl, 'email.unsubscribeUrl');\n    }\n    const quick = email.tracking?.quickClickMs;\n    if (\n      quick !== undefined &&\n      !(typeof quick === 'number' && Number.isFinite(quick) && quick >= 0)\n    ) {\n      throw new TypeError('email.tracking.quickClickMs must be a non-negative number');\n    }\n  }\n  for (const template of templates)\n    assertEmailMetadata(template, `email template '${template.id}'`);\n}\n\n/** A template's own `from` / `replyTo` / `unsubscribeUrl`, as `emailTemplate` checks them. */\nexport function assertEmailMetadata(\n  template: { from?: unknown; replyTo?: unknown; unsubscribeUrl?: unknown },\n  where: string\n): void {\n  assertEmailAddress(template.from, `${where}: from`);\n  if (template.replyTo !== undefined) assertEmailAddress(template.replyTo, `${where}: replyTo`);\n  if (template.unsubscribeUrl !== undefined) {\n    assertUnsubscribeUrl(template.unsubscribeUrl, `${where}: unsubscribeUrl`);\n  }\n}\n\n/** The unsubscribe link may carry its own query (a token, a list): the path names it. */\nexport function isUnsubscribeLink(url: string, unsubscribeUrl: string | undefined): boolean {\n  if (unsubscribeUrl === undefined) return false;\n  try {\n    const a = new URL(url);\n    const b = new URL(unsubscribeUrl);\n    return a.origin === b.origin && a.pathname === b.pathname;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;AAeA,SAAgB,mBAAmB,SAA+B;CAChE,IAAI,OAAO,YAAY,UAAU,OAAO;CACxC,OAAO,QAAQ,SAAS,KAAA,IAAY,QAAQ,QAAQ,GAAG,QAAQ,KAAK,IAAI,QAAQ,MAAM;AACxF;;AA+BA,SAAgB,aACd,UACA,QACe;CACf,MAAM,iBAAiB,SAAS,kBAAkB,QAAQ;CAC1D,OAAO;EACL,MAAM,SAAS;EACf,GAAI,SAAS,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,SAAS,QAAQ;EACtE,GAAI,mBAAmB,KAAA,IAAY,CAAC,IAAI,EAAE,eAAe;CAC3D;AACF;AAEA,MAAM,UAAU;;AAGhB,SAAgB,mBAAmB,SAAkB,OAAqB;CACxE,MAAM,QACJ,OAAO,YAAY,YAAY,YAAY,OACtC,QAAgC,QACjC;CACN,MAAM,OACJ,OAAO,YAAY,YAAY,YAAY,OACtC,QAA+B,OAChC,KAAA;CACN,IAAI,OAAO,UAAU,YAAY,CAAC,QAAQ,KAAK,KAAK,GAClD,MAAM,IAAI,UAAU,GAAG,MAAM,8CAA8C;CAE7E,IAAI,SAAS,KAAA,KAAa,OAAO,SAAS,UACxC,MAAM,IAAI,UAAU,GAAG,MAAM,uBAAuB;AAExD;;AAGA,SAAgB,qBAAqB,KAAc,OAAqB;CACtE,IAAI;CACJ,IAAI;EACF,SAAS,OAAO,QAAQ,WAAW,IAAI,IAAI,GAAG,IAAI,KAAA;CACpD,QAAQ;EACN,SAAS,KAAA;CACX;CACA,IAAI,WAAW,KAAA,KAAc,OAAO,aAAa,YAAY,OAAO,aAAa,SAC/E,MAAM,IAAI,UAAU,GAAG,MAAM,gDAAgD;AAEjF;;AAGA,SAAgB,kBACd,QACA,WACM;CACN,IAAI,OAAO,OAAO,QAAQ,QAAQ,GAChC,MAAM,IAAI,UACR,qJAEF;CAEF,MAAM,QAAQ,OAAO;CACrB,IAAI,UAAU,KAAA,GAAW;EACvB,IAAI,MAAM,mBAAmB,KAAA,GAC3B,qBAAqB,MAAM,gBAAgB,sBAAsB;EAEnE,MAAM,QAAQ,MAAM,UAAU;EAC9B,IACE,UAAU,KAAA,KACV,EAAE,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,KAAK,SAAS,IAElE,MAAM,IAAI,UAAU,2DAA2D;CAEnF;CACA,KAAK,MAAM,YAAY,WACrB,oBAAoB,UAAU,mBAAmB,SAAS,GAAG,EAAE;AACnE;;AAGA,SAAgB,oBACd,UACA,OACM;CACN,mBAAmB,SAAS,MAAM,GAAG,MAAM,OAAO;CAClD,IAAI,SAAS,YAAY,KAAA,GAAW,mBAAmB,SAAS,SAAS,GAAG,MAAM,UAAU;CAC5F,IAAI,SAAS,mBAAmB,KAAA,GAC9B,qBAAqB,SAAS,gBAAgB,GAAG,MAAM,iBAAiB;AAE5E;;AAGA,SAAgB,kBAAkB,KAAa,gBAA6C;CAC1F,IAAI,mBAAmB,KAAA,GAAW,OAAO;CACzC,IAAI;EACF,MAAM,IAAI,IAAI,IAAI,GAAG;EACrB,MAAM,IAAI,IAAI,IAAI,cAAc;EAChC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE;CACnD,QAAQ;EACN,OAAO;CACT;AACF"}
+{"version":3,"file":"email.cjs","names":[],"sources":["../src/email.ts"],"sourcesContent":["import type { EmailTemplate } from './templates';\n\n/**\n * Email metadata: who a template's email comes from, where replies go, and the unsubscribe link\n * its layout carries. Each `emailTemplate` declares its own `from` (and `replyTo`, if replies should\n * go elsewhere); the unsubscribe link is the template's `unsubscribeUrl`, else the config's\n * `email.unsubscribeUrl`, else none. `resolveEmail` is that rule, and the sender, the renderer,\n * the Worker's preview and the studio all go through it. No React and no I/O here, so a browser\n * can import it.\n */\n\n/** An address as the transports take it: bare, or with a display name. */\nexport type EmailAddress = string | { email: string; name?: string };\n\n/** `Name <email>`, or the bare address. */\nexport function formatEmailAddress(address: EmailAddress): string {\n  if (typeof address === 'string') return address;\n  return address.name === undefined ? address.email : `${address.name} <${address.email}>`;\n}\n\nconst ASCII = /^[\\x20-\\x7e]*$/;\nconst SPECIALS = /[()<>[\\]:;@\\\\,.\"]/;\n\n/**\n * An address as a mail API reads it (RFC 5322): a display name with specials is quoted, one\n * outside ASCII is a MIME encoded-word — raw non-ASCII names are refused (SES), and an unquoted\n * comma splits the address in two.\n */\nexport function mimeAddress(address: EmailAddress): string {\n  if (typeof address === 'string') return address;\n  const { email, name } = address;\n  if (name === undefined || name === '') return email;\n  if (!ASCII.test(name)) {\n    const bytes = new TextEncoder().encode(name);\n    let binary = '';\n    for (const byte of bytes) binary += String.fromCharCode(byte);\n    return `=?UTF-8?B?${btoa(binary)}?= <${email}>`;\n  }\n  if (SPECIALS.test(name)) return `\"${name.replace(/([\"\\\\])/g, '\\\\$1')}\" <${email}>`;\n  return `${name} <${email}>`;\n}\n\n/** The config's `email`: what every email template shares. */\nexport interface EmailConfig {\n  /**\n   * The unsubscribe link of every email template that names none of its own. The layout reads it\n   * with `useEmailContext()`; sent, it is tracked like every link, but following it shows a\n   * confirmation page, and only the confirmation (a POST no link scanner sends) unsubscribes.\n   */\n  unsubscribeUrl?: string;\n  /** How the Worker tells a person's opens and clicks from a machine's (see the reporting classifier). */\n  tracking?: {\n    /**\n     * An open or click this many milliseconds after delivery is a weak machine signal — machine\n     * only together with another (a second link within seconds); 1000 by default. A person\n     * tapping a mail notification can click within a few seconds, so keep it short.\n     */\n    quickClickMs?: number;\n  };\n}\n\n/** One template's email metadata, resolved against the config. */\nexport interface ResolvedEmail {\n  from: EmailAddress;\n  /** Absent when the template names none: the email goes out without a Reply-To. */\n  replyTo?: EmailAddress;\n  /** Absent when neither the template nor the config names one: the email has no unsubscribe link. */\n  unsubscribeUrl?: string;\n}\n\n/** The template's metadata, its `unsubscribeUrl` falling back to the config's. Leaves both untouched. */\nexport function resolveEmail(\n  template: Pick<EmailTemplate, 'from' | 'replyTo' | 'unsubscribeUrl'>,\n  config?: EmailConfig\n): ResolvedEmail {\n  const unsubscribeUrl = template.unsubscribeUrl ?? config?.unsubscribeUrl;\n  return {\n    from: template.from,\n    ...(template.replyTo === undefined ? {} : { replyTo: template.replyTo }),\n    ...(unsubscribeUrl === undefined ? {} : { unsubscribeUrl }),\n  };\n}\n\nconst ADDRESS = /^[^\\s@<>]+@[^\\s@<>]+$/;\n\n/** Throws naming `where` when `address` is neither `user@host` nor `{ email: 'user@host', name? }`. */\nexport function assertEmailAddress(address: unknown, where: string): void {\n  const email =\n    typeof address === 'object' && address !== null\n      ? (address as { email?: unknown }).email\n      : address;\n  const name =\n    typeof address === 'object' && address !== null\n      ? (address as { name?: unknown }).name\n      : undefined;\n  if (typeof email !== 'string' || !ADDRESS.test(email)) {\n    throw new TypeError(`${where} must be an email address or { email, name? }`);\n  }\n  if (name !== undefined && typeof name !== 'string') {\n    throw new TypeError(`${where}.name must be a string`);\n  }\n}\n\n/** Throws naming `where` unless `url` is an absolute http(s) URL; '' and null are not a way to leave it out. */\nexport function assertUnsubscribeUrl(url: unknown, where: string): void {\n  let parsed: URL | undefined;\n  try {\n    parsed = typeof url === 'string' ? new URL(url) : undefined;\n  } catch {\n    parsed = undefined;\n  }\n  if (parsed === undefined || (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')) {\n    throw new TypeError(`${where} must be an http(s) URL (leave it out for none)`);\n  }\n}\n\n/** The config's `email` and every registered template's metadata; throws on the first invalid value. */\nexport function assertEmailConfig(\n  config: { email?: EmailConfig },\n  templates: Iterable<EmailTemplate>\n): void {\n  if (Object.hasOwn(config, 'emails')) {\n    throw new TypeError(\n      \"the config's `emails` is gone: `from` and `replyTo` are declared on each emailTemplate, \" +\n        'and the rest moved to `email: { unsubscribeUrl, tracking }`'\n    );\n  }\n  const email = config.email;\n  if (email !== undefined) {\n    if (email.unsubscribeUrl !== undefined) {\n      assertUnsubscribeUrl(email.unsubscribeUrl, 'email.unsubscribeUrl');\n    }\n    const quick = email.tracking?.quickClickMs;\n    if (\n      quick !== undefined &&\n      !(typeof quick === 'number' && Number.isFinite(quick) && quick >= 0)\n    ) {\n      throw new TypeError('email.tracking.quickClickMs must be a non-negative number');\n    }\n  }\n  for (const template of templates)\n    assertEmailMetadata(template, `email template '${template.id}'`);\n}\n\n/** A template's own `from` / `replyTo` / `unsubscribeUrl`, as `emailTemplate` checks them. */\nexport function assertEmailMetadata(\n  template: { from?: unknown; replyTo?: unknown; unsubscribeUrl?: unknown },\n  where: string\n): void {\n  assertEmailAddress(template.from, `${where}: from`);\n  if (template.replyTo !== undefined) assertEmailAddress(template.replyTo, `${where}: replyTo`);\n  if (template.unsubscribeUrl !== undefined) {\n    assertUnsubscribeUrl(template.unsubscribeUrl, `${where}: unsubscribeUrl`);\n  }\n}\n\n/** The unsubscribe link may carry its own query (a token, a list): the path names it. */\nexport function isUnsubscribeLink(url: string, unsubscribeUrl: string | undefined): boolean {\n  if (unsubscribeUrl === undefined) return false;\n  try {\n    const a = new URL(url);\n    const b = new URL(unsubscribeUrl);\n    return a.origin === b.origin && a.pathname === b.pathname;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;AAeA,SAAgB,mBAAmB,SAA+B;CAChE,IAAI,OAAO,YAAY,UAAU,OAAO;CACxC,OAAO,QAAQ,SAAS,KAAA,IAAY,QAAQ,QAAQ,GAAG,QAAQ,KAAK,IAAI,QAAQ,MAAM;AACxF;AAEA,MAAM,QAAQ;AACd,MAAM,WAAW;;;;;;AAOjB,SAAgB,YAAY,SAA+B;CACzD,IAAI,OAAO,YAAY,UAAU,OAAO;CACxC,MAAM,EAAE,OAAO,SAAS;CACxB,IAAI,SAAS,KAAA,KAAa,SAAS,IAAI,OAAO;CAC9C,IAAI,CAAC,MAAM,KAAK,IAAI,GAAG;EACrB,MAAM,QAAQ,IAAI,YAAY,CAAC,CAAC,OAAO,IAAI;EAC3C,IAAI,SAAS;EACb,KAAK,MAAM,QAAQ,OAAO,UAAU,OAAO,aAAa,IAAI;EAC5D,OAAO,aAAa,KAAK,MAAM,EAAE,MAAM,MAAM;CAC/C;CACA,IAAI,SAAS,KAAK,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ,YAAY,MAAM,EAAE,KAAK,MAAM;CAChF,OAAO,GAAG,KAAK,IAAI,MAAM;AAC3B;;AA+BA,SAAgB,aACd,UACA,QACe;CACf,MAAM,iBAAiB,SAAS,kBAAkB,QAAQ;CAC1D,OAAO;EACL,MAAM,SAAS;EACf,GAAI,SAAS,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,SAAS,QAAQ;EACtE,GAAI,mBAAmB,KAAA,IAAY,CAAC,IAAI,EAAE,eAAe;CAC3D;AACF;AAEA,MAAM,UAAU;;AAGhB,SAAgB,mBAAmB,SAAkB,OAAqB;CACxE,MAAM,QACJ,OAAO,YAAY,YAAY,YAAY,OACtC,QAAgC,QACjC;CACN,MAAM,OACJ,OAAO,YAAY,YAAY,YAAY,OACtC,QAA+B,OAChC,KAAA;CACN,IAAI,OAAO,UAAU,YAAY,CAAC,QAAQ,KAAK,KAAK,GAClD,MAAM,IAAI,UAAU,GAAG,MAAM,8CAA8C;CAE7E,IAAI,SAAS,KAAA,KAAa,OAAO,SAAS,UACxC,MAAM,IAAI,UAAU,GAAG,MAAM,uBAAuB;AAExD;;AAGA,SAAgB,qBAAqB,KAAc,OAAqB;CACtE,IAAI;CACJ,IAAI;EACF,SAAS,OAAO,QAAQ,WAAW,IAAI,IAAI,GAAG,IAAI,KAAA;CACpD,QAAQ;EACN,SAAS,KAAA;CACX;CACA,IAAI,WAAW,KAAA,KAAc,OAAO,aAAa,YAAY,OAAO,aAAa,SAC/E,MAAM,IAAI,UAAU,GAAG,MAAM,gDAAgD;AAEjF;;AAGA,SAAgB,kBACd,QACA,WACM;CACN,IAAI,OAAO,OAAO,QAAQ,QAAQ,GAChC,MAAM,IAAI,UACR,qJAEF;CAEF,MAAM,QAAQ,OAAO;CACrB,IAAI,UAAU,KAAA,GAAW;EACvB,IAAI,MAAM,mBAAmB,KAAA,GAC3B,qBAAqB,MAAM,gBAAgB,sBAAsB;EAEnE,MAAM,QAAQ,MAAM,UAAU;EAC9B,IACE,UAAU,KAAA,KACV,EAAE,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,KAAK,SAAS,IAElE,MAAM,IAAI,UAAU,2DAA2D;CAEnF;CACA,KAAK,MAAM,YAAY,WACrB,oBAAoB,UAAU,mBAAmB,SAAS,GAAG,EAAE;AACnE;;AAGA,SAAgB,oBACd,UACA,OACM;CACN,mBAAmB,SAAS,MAAM,GAAG,MAAM,OAAO;CAClD,IAAI,SAAS,YAAY,KAAA,GAAW,mBAAmB,SAAS,SAAS,GAAG,MAAM,UAAU;CAC5F,IAAI,SAAS,mBAAmB,KAAA,GAC9B,qBAAqB,SAAS,gBAAgB,GAAG,MAAM,iBAAiB;AAE5E;;AAGA,SAAgB,kBAAkB,KAAa,gBAA6C;CAC1F,IAAI,mBAAmB,KAAA,GAAW,OAAO;CACzC,IAAI;EACF,MAAM,IAAI,IAAI,IAAI,GAAG;EACrB,MAAM,IAAI,IAAI,IAAI,cAAc;EAChC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE;CACnD,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/email.d.cts

@@ -15,6 +15,12 @@ export type EmailAddress = string | {
 };
 /** `Name <email>`, or the bare address. */
 export declare function formatEmailAddress(address: EmailAddress): string;
+/**
+ * An address as a mail API reads it (RFC 5322): a display name with specials is quoted, one
+ * outside ASCII is a MIME encoded-word — raw non-ASCII names are refused (SES), and an unquoted
+ * comma splits the address in two.
+ */
+export declare function mimeAddress(address: EmailAddress): string;
 /** The config's `email`: what every email template shares. */
 export interface EmailConfig {
   /**

package/dist/email.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"email.d.cts","names":[],"sources":["../src/email.ts"],"mappings":";;;;;;;;;;;YAYY;EAA0B;EAAe;;;wBAGrC,mBAAmB,SAAS;;iBAM3B;;;;;;EAMf;;EAEA;;;;;;IAME;;;;iBAKa;EACf,MAAM;;EAEN,UAAU;;EAEV;;;wBAIc,aACd,UAAU,KAAK,uDACf,SAAS,cACR;;wBAYa,mBAAmB,kBAAkB;;wBAkBrC,qBAAqB,cAAc;;wBAanC,kBACd;EAAU,QAAQ;GAClB,WAAW,SAAS;;wBA0BN,oBACd;EAAY;EAAgB;EAAmB;GAC/C;;wBAUc,kBAAkB,aAAa"}
+{"version":3,"file":"email.d.cts","names":[],"sources":["../src/email.ts"],"mappings":";;;;;;;;;;;YAYY;EAA0B;EAAe;;;wBAGrC,mBAAmB,SAAS;;;;;;wBAa5B,YAAY,SAAS;;iBAepB;;;;;;EAMf;;EAEA;;;;;;IAME;;;;iBAKa;EACf,MAAM;;EAEN,UAAU;;EAEV;;;wBAIc,aACd,UAAU,KAAK,uDACf,SAAS,cACR;;wBAYa,mBAAmB,kBAAkB;;wBAkBrC,qBAAqB,cAAc;;wBAanC,kBACd;EAAU,QAAQ;GAClB,WAAW,SAAS;;wBA0BN,oBACd;EAAY;EAAgB;EAAmB;GAC/C;;wBAUc,kBAAkB,aAAa"}

package/dist/email.d.mts

@@ -15,6 +15,12 @@ export type EmailAddress = string | {
 };
 /** `Name <email>`, or the bare address. */
 export declare function formatEmailAddress(address: EmailAddress): string;
+/**
+ * An address as a mail API reads it (RFC 5322): a display name with specials is quoted, one
+ * outside ASCII is a MIME encoded-word — raw non-ASCII names are refused (SES), and an unquoted
+ * comma splits the address in two.
+ */
+export declare function mimeAddress(address: EmailAddress): string;
 /** The config's `email`: what every email template shares. */
 export interface EmailConfig {
   /**

package/dist/email.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"email.d.mts","names":[],"sources":["../src/email.ts"],"mappings":";;;;;;;;;;;YAYY;EAA0B;EAAe;;;wBAGrC,mBAAmB,SAAS;;iBAM3B;;;;;;EAMf;;EAEA;;;;;;IAME;;;;iBAKa;EACf,MAAM;;EAEN,UAAU;;EAEV;;;wBAIc,aACd,UAAU,KAAK,uDACf,SAAS,cACR;;wBAYa,mBAAmB,kBAAkB;;wBAkBrC,qBAAqB,cAAc;;wBAanC,kBACd;EAAU,QAAQ;GAClB,WAAW,SAAS;;wBA0BN,oBACd;EAAY;EAAgB;EAAmB;GAC/C;;wBAUc,kBAAkB,aAAa"}
+{"version":3,"file":"email.d.mts","names":[],"sources":["../src/email.ts"],"mappings":";;;;;;;;;;;YAYY;EAA0B;EAAe;;;wBAGrC,mBAAmB,SAAS;;;;;;wBAa5B,YAAY,SAAS;;iBAepB;;;;;;EAMf;;EAEA;;;;;;IAME;;;;iBAKa;EACf,MAAM;;EAEN,UAAU;;EAEV;;;wBAIc,aACd,UAAU,KAAK,uDACf,SAAS,cACR;;wBAYa,mBAAmB,kBAAkB;;wBAkBrC,qBAAqB,cAAc;;wBAanC,kBACd;EAAU,QAAQ;GAClB,WAAW,SAAS;;wBA0BN,oBACd;EAAY;EAAgB;EAAmB;GAC/C;;wBAUc,kBAAkB,aAAa"}

package/dist/email.mjs

@@ -4,6 +4,26 @@ function formatEmailAddress(address) {
 	if (typeof address === "string") return address;
 	return address.name === void 0 ? address.email : `${address.name} <${address.email}>`;
 }
+const ASCII = /^[\x20-\x7e]*$/;
+const SPECIALS = /[()<>[\]:;@\\,."]/;
+/**
+* An address as a mail API reads it (RFC 5322): a display name with specials is quoted, one
+* outside ASCII is a MIME encoded-word — raw non-ASCII names are refused (SES), and an unquoted
+* comma splits the address in two.
+*/
+function mimeAddress(address) {
+	if (typeof address === "string") return address;
+	const { email, name } = address;
+	if (name === void 0 || name === "") return email;
+	if (!ASCII.test(name)) {
+		const bytes = new TextEncoder().encode(name);
+		let binary = "";
+		for (const byte of bytes) binary += String.fromCharCode(byte);
+		return `=?UTF-8?B?${btoa(binary)}?= <${email}>`;
+	}
+	if (SPECIALS.test(name)) return `"${name.replace(/(["\\])/g, "\\$1")}" <${email}>`;
+	return `${name} <${email}>`;
+}
 /** The template's metadata, its `unsubscribeUrl` falling back to the config's. Leaves both untouched. */
 function resolveEmail(template, config) {
 	const unsubscribeUrl = template.unsubscribeUrl ?? config?.unsubscribeUrl;
@@ -60,6 +80,6 @@ function isUnsubscribeLink(url, unsubscribeUrl) {
 	}
 }
 //#endregion
-export { assertEmailAddress, assertEmailConfig, assertEmailMetadata, assertUnsubscribeUrl, formatEmailAddress, isUnsubscribeLink, resolveEmail };
+export { assertEmailAddress, assertEmailConfig, assertEmailMetadata, assertUnsubscribeUrl, formatEmailAddress, isUnsubscribeLink, mimeAddress, resolveEmail };
 
 //# sourceMappingURL=email.mjs.map