@digimuza/saas-core 0.0.2

package/dist/email/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/email/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,GAG1B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,GAKd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,oBAAoB,EAA6B,MAAM,aAAa,CAAC;AAE9E,OAAO,EACL,kBAAkB,GAKnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,sBAAsB,GAMvB,MAAM,gBAAgB,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B;IAC3C,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC;IAEjC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACzE,OAAO,0BAA0B,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,oBAAoB,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,gBAAgB;IAC9B,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC;IACjC,OAAO;QACL,OAAO,EAAE,WAAW,CAAC,WAAW;QAChC,GAAG,CAAC,WAAW,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9E,CAAC;AACJ,CAAC"}

package/dist/email/provider.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The seam between the core and an email provider.
+ *
+ * One method, because sending is all the core needs. Bounce handling, suppression
+ * lists and analytics are the provider's dashboard, not this interface — wrapping
+ * them would mean maintaining a lowest common denominator of every provider's
+ * feature set.
+ */
+export interface EmailProvider {
+    readonly name: string;
+    send(message: OutgoingEmail): Promise<SentEmail>;
+}
+export interface EmailAddress {
+    readonly address: string;
+    readonly name?: string;
+}
+export interface OutgoingEmail {
+    readonly to: readonly EmailAddress[];
+    readonly from: EmailAddress;
+    readonly subject: string;
+    /**
+     * Always present. HTML is optional, but a text part is not: some clients render
+     * only text, and a text-less message scores worse with spam filters.
+     */
+    readonly text: string;
+    readonly html?: string;
+    readonly replyTo?: EmailAddress;
+    readonly cc?: readonly EmailAddress[];
+    readonly bcc?: readonly EmailAddress[];
+    /**
+     * Provider-side deduplication key, where supported.
+     *
+     * Sending is not transactional with the database, so a retried request can send
+     * twice. This is the only defence against that, and providers that ignore it
+     * will simply deliver twice.
+     */
+    readonly idempotencyKey?: string;
+    /** Custom headers, e.g. `List-Unsubscribe`. */
+    readonly headers?: Record<string, string>;
+}
+export interface SentEmail {
+    /** Provider's message id, for correlating with their logs. */
+    readonly id: string;
+    readonly provider: string;
+}
+export declare function formatAddress(address: EmailAddress): string;
+//# sourceMappingURL=provider.d.ts.map

package/dist/email/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/email/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,SAAS,YAAY,EAAE,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAK3D"}

package/dist/email/provider.js

@@ -0,0 +1,7 @@
+export function formatAddress(address) {
+    // Quoted so a display name containing a comma cannot split the header.
+    return address.name === undefined
+        ? address.address
+        : `"${address.name.replace(/"/g, "")}" <${address.address}>`;
+}
+//# sourceMappingURL=provider.js.map

package/dist/email/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/email/provider.ts"],"names":[],"mappings":"AAiDA,MAAM,UAAU,aAAa,CAAC,OAAqB;IACjD,uEAAuE;IACvE,OAAO,OAAO,CAAC,IAAI,KAAK,SAAS;QAC/B,CAAC,CAAC,OAAO,CAAC,OAAO;QACjB,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,OAAO,CAAC,OAAO,GAAG,CAAC;AACjE,CAAC"}

package/dist/email/resend.d.ts

@@ -0,0 +1,22 @@
+import type { EmailProvider } from "./provider.ts";
+/**
+ * Resend adapter.
+ *
+ * ## Verification status
+ *
+ * Written against Resend's documented `POST /emails` endpoint but **not exercised
+ * against live credentials**. Treat it as unverified until it has run against a
+ * real account.
+ *
+ * Resend is the default because its API is a single endpoint with no SDK required
+ * — which keeps this file small enough to audit and leaves nothing to go stale.
+ * Any other provider is a ~20-line adapter; see `docs/email.md`.
+ */
+export interface ResendAdapterOptions {
+    readonly apiKey: string;
+    /** Override for a proxy or a regional endpoint. */
+    readonly apiUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createResendProvider(options: ResendAdapterOptions): EmailProvider;
+//# sourceMappingURL=resend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resend.d.ts","sourceRoot":"","sources":["../../src/email/resend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAA4B,MAAM,eAAe,CAAC;AAG7E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAID,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAsDjF"}

package/dist/email/resend.js

@@ -0,0 +1,51 @@
+import { formatAddress } from "./provider.js";
+const DEFAULT_API_URL = "https://api.resend.com";
+export function createResendProvider(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const baseUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, "");
+    return {
+        name: "resend",
+        async send(message) {
+            const headers = {
+                Authorization: `Bearer ${options.apiKey}`,
+                "Content-Type": "application/json",
+            };
+            /**
+             * Resend reads idempotency from a header rather than the body, and honours
+             * it for 24 hours.
+             */
+            if (message.idempotencyKey !== undefined) {
+                headers["Idempotency-Key"] = message.idempotencyKey;
+            }
+            const response = await fetchImpl(`${baseUrl}/emails`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    from: formatAddress(message.from),
+                    to: message.to.map(formatAddress),
+                    subject: message.subject,
+                    text: message.text,
+                    ...(message.html !== undefined ? { html: message.html } : {}),
+                    ...(message.replyTo !== undefined ? { reply_to: formatAddress(message.replyTo) } : {}),
+                    ...(message.cc !== undefined ? { cc: message.cc.map(formatAddress) } : {}),
+                    ...(message.bcc !== undefined ? { bcc: message.bcc.map(formatAddress) } : {}),
+                    ...(message.headers !== undefined ? { headers: message.headers } : {}),
+                }),
+            });
+            if (!response.ok) {
+                /**
+                 * The response body is not included. Provider errors echo request
+                 * contents, and this message may reach logs — a bounced address is
+                 * personal data and a rejected template could contain a token.
+                 */
+                throw new Error(`Resend rejected the message with status ${response.status}.`);
+            }
+            const body = (await response.json());
+            if (typeof body.id !== "string") {
+                throw new Error("Resend did not return a message id.");
+            }
+            return { id: body.id, provider: "resend" };
+        },
+    };
+}
+//# sourceMappingURL=resend.js.map

package/dist/email/resend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resend.js","sourceRoot":"","sources":["../../src/email/resend.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAsB9C,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD,MAAM,UAAU,oBAAoB,CAAC,OAA6B;IAChE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACxD,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAExE,OAAO;QACL,IAAI,EAAE,QAAQ;QAEd,KAAK,CAAC,IAAI,CAAC,OAAsB;YAC/B,MAAM,OAAO,GAA2B;gBACtC,aAAa,EAAE,UAAU,OAAO,CAAC,MAAM,EAAE;gBACzC,cAAc,EAAE,kBAAkB;aACnC,CAAC;YAEF;;;eAGG;YACH,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;gBACzC,OAAO,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;YACtD,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,OAAO,SAAS,EAAE;gBACpD,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC;oBACjC,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,aAAa,CAAC;oBACjC,OAAO,EAAE,OAAO,CAAC,OAAO;oBACxB,IAAI,EAAE,OAAO,CAAC,IAAI;oBAClB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC7D,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtF,GAAG,CAAC,OAAO,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC1E,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC7E,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACvE,CAAC;aACH,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB;;;;mBAIG;gBACH,MAAM,IAAI,KAAK,CAAC,2CAA2C,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;YACjF,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAqB,CAAC;YACzD,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;YACzD,CAAC;YAED,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;QAC7C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/email/service.d.ts

@@ -0,0 +1,55 @@
+import type { z } from "zod";
+import type { EmailAddress, EmailProvider, SentEmail } from "./provider.ts";
+import type { EmailTemplateMap, EmailTemplateName, EmailTemplateRegistry } from "./templates.ts";
+export interface SendEmailInput {
+    readonly to: string | EmailAddress | readonly (string | EmailAddress)[];
+    readonly subject: string;
+    readonly text: string;
+    readonly html?: string;
+    /** Overrides the configured sender. */
+    readonly from?: EmailAddress;
+    readonly replyTo?: string | EmailAddress;
+    readonly cc?: readonly (string | EmailAddress)[];
+    readonly bcc?: readonly (string | EmailAddress)[];
+    readonly idempotencyKey?: string;
+    readonly headers?: Record<string, string>;
+}
+/** A send request for one of the registered templates, narrowed by name. */
+export type SendTemplateInput<T extends EmailTemplateMap> = {
+    [K in EmailTemplateName<T>]: {
+        readonly to: string | EmailAddress | readonly (string | EmailAddress)[];
+        readonly template: K;
+        readonly data: z.input<T[K]["schema"]>;
+        readonly from?: EmailAddress;
+        readonly replyTo?: string | EmailAddress;
+        readonly idempotencyKey?: string;
+        readonly headers?: Record<string, string>;
+    };
+}[EmailTemplateName<T>];
+export interface EmailService<T extends EmailTemplateMap> {
+    /** Send an ad-hoc message. */
+    send(input: SendEmailInput): Promise<SentEmail>;
+    /**
+     * Render a registered template and send it.
+     *
+     * `data` is validated against the template's schema first, so a missing field
+     * fails before a message is built rather than producing an email containing
+     * "undefined".
+     */
+    sendTemplate(input: SendTemplateInput<T>): Promise<SentEmail>;
+    /** Render without sending. For previews, and for asserting copy in tests. */
+    render<K extends EmailTemplateName<T>>(template: K, data: z.input<T[K]["schema"]>): {
+        subject: string;
+        text: string;
+        html?: string;
+    };
+}
+export interface EmailServiceDeps<T extends EmailTemplateMap> {
+    readonly provider: EmailProvider;
+    readonly templates: EmailTemplateRegistry<T>;
+    /** Default sender. Read per call, so configuration can resolve lazily. */
+    readonly from: EmailAddress;
+    readonly replyTo?: EmailAddress;
+}
+export declare function createEmailService<T extends EmailTemplateMap>(deps: EmailServiceDeps<T>): EmailService<T>;
+//# sourceMappingURL=service.d.ts.map

package/dist/email/service.d.ts.map

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

package/dist/email/service.js

@@ -0,0 +1,87 @@
+import { InvalidInputError } from "../errors.js";
+function toAddress(value) {
+    return typeof value === "string" ? { address: value } : value;
+}
+function toAddresses(value) {
+    const list = Array.isArray(value) ? value : [value];
+    return list.map(toAddress);
+}
+/** Rudimentary shape check — the provider is authoritative about deliverability. */
+function assertRecipients(recipients) {
+    if (recipients.length === 0) {
+        throw new InvalidInputError("At least one recipient is required.");
+    }
+    for (const recipient of recipients) {
+        if (!recipient.address.includes("@") || /\s/.test(recipient.address)) {
+            // The address is echoed because it came from the caller, not from a secret.
+            throw new InvalidInputError(`"${recipient.address}" is not a valid email address.`);
+        }
+    }
+}
+export function createEmailService(deps) {
+    function lookup(name) {
+        const template = deps.templates.templates[name];
+        if (template === undefined) {
+            throw new InvalidInputError(`Unknown email template "${name}".`);
+        }
+        return template;
+    }
+    function renderTemplate(name, data) {
+        const template = lookup(name);
+        const parsed = template.schema.safeParse(data);
+        if (!parsed.success) {
+            const problems = parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+                .join("; ");
+            throw new InvalidInputError(`Invalid data for email template "${name}": ${problems}`);
+        }
+        return {
+            subject: template.subject(parsed.data),
+            text: template.text(parsed.data),
+            ...(template.html !== undefined ? { html: template.html(parsed.data) } : {}),
+        };
+    }
+    async function dispatch(message) {
+        assertRecipients(message.to);
+        return deps.provider.send(message);
+    }
+    return {
+        async send(input) {
+            return dispatch({
+                to: toAddresses(input.to),
+                from: input.from ?? deps.from,
+                subject: input.subject,
+                text: input.text,
+                ...(input.html !== undefined ? { html: input.html } : {}),
+                ...(input.replyTo !== undefined
+                    ? { replyTo: toAddress(input.replyTo) }
+                    : deps.replyTo !== undefined
+                        ? { replyTo: deps.replyTo }
+                        : {}),
+                ...(input.cc !== undefined ? { cc: toAddresses(input.cc) } : {}),
+                ...(input.bcc !== undefined ? { bcc: toAddresses(input.bcc) } : {}),
+                ...(input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {}),
+                ...(input.headers !== undefined ? { headers: input.headers } : {}),
+            });
+        },
+        async sendTemplate(input) {
+            const rendered = renderTemplate(input.template, input.data);
+            return dispatch({
+                to: toAddresses(input.to),
+                from: input.from ?? deps.from,
+                ...rendered,
+                ...(input.replyTo !== undefined
+                    ? { replyTo: toAddress(input.replyTo) }
+                    : deps.replyTo !== undefined
+                        ? { replyTo: deps.replyTo }
+                        : {}),
+                ...(input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {}),
+                ...(input.headers !== undefined ? { headers: input.headers } : {}),
+            });
+        },
+        render(template, data) {
+            return renderTemplate(template, data);
+        },
+    };
+}
+//# sourceMappingURL=service.js.map

package/dist/email/service.js.map

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

package/dist/email/templates.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+/**
+ * A typed email template.
+ *
+ * Same shape as the event registry, for the same reason: the Zod schema gives the
+ * compile-time payload type *and* validates at runtime, so a template rendered
+ * with the wrong data fails before a message is built rather than producing an
+ * email with `undefined` in it.
+ */
+export interface EmailTemplate<TSchema extends z.ZodType = z.ZodType> {
+    readonly schema: TSchema;
+    readonly subject: (data: z.output<TSchema>) => string;
+    readonly text: (data: z.output<TSchema>) => string;
+    /** Optional. A text part is mandatory; HTML is an enhancement. */
+    readonly html?: (data: z.output<TSchema>) => string;
+}
+export type EmailTemplateMap = Record<string, EmailTemplate>;
+/**
+ * Build one template, inferring the payload type from its own schema.
+ *
+ * The wrapper is load-bearing. TypeScript cannot infer a callback's parameter
+ * from a *sibling* property of the same object literal, so writing the template
+ * inline would leave `data` as `unknown` in `subject` and `text`. Binding the
+ * schema generic inside this call is what types them.
+ */
+export declare function emailTemplate<S extends z.ZodType>(template: {
+    readonly schema: S;
+    readonly subject: (data: z.output<S>) => string;
+    readonly text: (data: z.output<S>) => string;
+    readonly html?: (data: z.output<S>) => string;
+}): EmailTemplate<S>;
+export interface EmailTemplateRegistry<T extends EmailTemplateMap = EmailTemplateMap> {
+    readonly templates: T;
+}
+/**
+ * Declare a set of templates.
+ *
+ * ```ts
+ * export const appTemplates = defineEmailTemplates({
+ *   "project.shared": emailTemplate({
+ *     schema: z.object({ projectName: z.string(), sharedBy: z.string() }),
+ *     subject: (data) => `${data.sharedBy} shared "${data.projectName}" with you`,
+ *     text: (data) => `${data.sharedBy} shared ${data.projectName}.`,
+ *   }),
+ * });
+ * ```
+ */
+export declare function defineEmailTemplates<const T extends EmailTemplateMap>(templates: T): EmailTemplateRegistry<T>;
+/** Combine the core templates with an application's own. Duplicates throw. */
+export declare function mergeEmailTemplates<A extends EmailTemplateMap, B extends EmailTemplateMap>(first: EmailTemplateRegistry<A>, second: EmailTemplateRegistry<B>): EmailTemplateRegistry<A & B>;
+/**
+ * Replace core templates with your own.
+ *
+ * Separate from `mergeEmailTemplates` so that overriding the core's copy is a
+ * visible decision rather than a silent shadowing — the copy and branding of an
+ * invitation email is exactly the sort of thing an application *should* replace.
+ */
+export declare function overrideEmailTemplates<A extends EmailTemplateMap, B extends EmailTemplateMap>(first: EmailTemplateRegistry<A>, second: EmailTemplateRegistry<B>): EmailTemplateRegistry<Omit<A, keyof B> & B>;
+export type EmailTemplateName<T extends EmailTemplateMap> = keyof T & string;
+/**
+ * Templates the core needs in order to function.
+ *
+ * Only one, deliberately. The core *creates* workspace invitations, and there is
+ * no way to deliver the single-use token without an email — so this one must
+ * exist. Welcome, security and billing emails are product copy: shipping a
+ * default would mean shipping branding decisions, and every application would
+ * override it anyway.
+ *
+ * The wording here is intentionally plain. Override it with
+ * `overrideEmailTemplates` for anything customer-facing.
+ */
+export declare const coreEmailTemplates: EmailTemplateRegistry<{
+    readonly "workspace.invitation": EmailTemplate<z.ZodObject<{
+        workspaceName: z.ZodString;
+        inviterName: z.ZodOptional<z.ZodString>;
+        acceptUrl: z.ZodURL;
+        expiresAt: z.ZodDate;
+    }, z.core.$strip>>;
+}>;
+export type CoreEmailTemplates = (typeof coreEmailTemplates)["templates"];
+//# sourceMappingURL=templates.d.ts.map

package/dist/email/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/email/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAClE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;IACtD,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;CACrD;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE;IAC3D,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;CAC/C,GAAG,aAAa,CAAC,CAAC,CAAC,CAEnB;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB;IAClF,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EACnE,SAAS,EAAE,CAAC,GACX,qBAAqB,CAAC,CAAC,CAAC,CAE1B;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,SAAS,gBAAgB,EACxF,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAC/B,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC/B,qBAAqB,CAAC,CAAC,GAAG,CAAC,CAAC,CAY9B;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,gBAAgB,EAAE,CAAC,SAAS,gBAAgB,EAC3F,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAC/B,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC/B,qBAAqB,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAE7C;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,gBAAgB,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;;;;;;;EAsB7B,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,WAAW,CAAC,CAAC"}

package/dist/email/templates.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { InvalidInputError } from "../errors.js";
+/**
+ * Build one template, inferring the payload type from its own schema.
+ *
+ * The wrapper is load-bearing. TypeScript cannot infer a callback's parameter
+ * from a *sibling* property of the same object literal, so writing the template
+ * inline would leave `data` as `unknown` in `subject` and `text`. Binding the
+ * schema generic inside this call is what types them.
+ */
+export function emailTemplate(template) {
+    return template;
+}
+/**
+ * Declare a set of templates.
+ *
+ * ```ts
+ * export const appTemplates = defineEmailTemplates({
+ *   "project.shared": emailTemplate({
+ *     schema: z.object({ projectName: z.string(), sharedBy: z.string() }),
+ *     subject: (data) => `${data.sharedBy} shared "${data.projectName}" with you`,
+ *     text: (data) => `${data.sharedBy} shared ${data.projectName}.`,
+ *   }),
+ * });
+ * ```
+ */
+export function defineEmailTemplates(templates) {
+    return { templates };
+}
+/** Combine the core templates with an application's own. Duplicates throw. */
+export function mergeEmailTemplates(first, second) {
+    const collisions = Object.keys(second.templates).filter((key) => key in first.templates);
+    if (collisions.length > 0) {
+        throw new InvalidInputError(`Email templates already defined: ${collisions.join(", ")}. ` +
+            `Rename the application's templates, or override deliberately with ` +
+            `overrideEmailTemplates().`);
+    }
+    return { templates: { ...first.templates, ...second.templates } };
+}
+/**
+ * Replace core templates with your own.
+ *
+ * Separate from `mergeEmailTemplates` so that overriding the core's copy is a
+ * visible decision rather than a silent shadowing — the copy and branding of an
+ * invitation email is exactly the sort of thing an application *should* replace.
+ */
+export function overrideEmailTemplates(first, second) {
+    return { templates: { ...first.templates, ...second.templates } };
+}
+/**
+ * Templates the core needs in order to function.
+ *
+ * Only one, deliberately. The core *creates* workspace invitations, and there is
+ * no way to deliver the single-use token without an email — so this one must
+ * exist. Welcome, security and billing emails are product copy: shipping a
+ * default would mean shipping branding decisions, and every application would
+ * override it anyway.
+ *
+ * The wording here is intentionally plain. Override it with
+ * `overrideEmailTemplates` for anything customer-facing.
+ */
+export const coreEmailTemplates = defineEmailTemplates({
+    "workspace.invitation": emailTemplate({
+        schema: z.object({
+            workspaceName: z.string().min(1),
+            inviterName: z.string().min(1).optional(),
+            /** Absolute URL carrying the single-use token. */
+            acceptUrl: z.url(),
+            expiresAt: z.date(),
+        }),
+        subject: (data) => `You have been invited to join ${data.workspaceName}`,
+        text: (data) => [
+            data.inviterName === undefined
+                ? `You have been invited to join ${data.workspaceName}.`
+                : `${data.inviterName} has invited you to join ${data.workspaceName}.`,
+            "",
+            "Accept the invitation:",
+            data.acceptUrl,
+            "",
+            `This link expires on ${data.expiresAt.toISOString()} and can be used once.`,
+        ].join("\n"),
+    }),
+});
+//# sourceMappingURL=templates.js.map

package/dist/email/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/email/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAoBjD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAsB,QAKlD;IACC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAY;IAEZ,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CACjC,KAA+B,EAC/B,MAAgC;IAEhC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAEzF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,iBAAiB,CACzB,oCAAoC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC3D,oEAAoE;YACpE,2BAA2B,CAC9B,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAA+B,EAC/B,MAAgC;IAEhC,OAAO,EAAE,SAAS,EAAE,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,SAAS,EAA0B,EAAE,CAAC;AAC5F,CAAC;AAID;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;IACrD,sBAAsB,EAAE,aAAa,CAAC;QACpC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;YACf,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;YACzC,kDAAkD;YAClD,SAAS,EAAE,CAAC,CAAC,GAAG,EAAE;YAClB,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE;SACpB,CAAC;QACF,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,iCAAiC,IAAI,CAAC,aAAa,EAAE;QACxE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CACb;YACE,IAAI,CAAC,WAAW,KAAK,SAAS;gBAC5B,CAAC,CAAC,iCAAiC,IAAI,CAAC,aAAa,GAAG;gBACxD,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,4BAA4B,IAAI,CAAC,aAAa,GAAG;YACxE,EAAE;YACF,wBAAwB;YACxB,IAAI,CAAC,SAAS;YACd,EAAE;YACF,wBAAwB,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,wBAAwB;SAC7E,CAAC,IAAI,CAAC,IAAI,CAAC;KACf,CAAC;CACH,CAAC,CAAC"}

package/dist/entitlements/index.d.ts

@@ -0,0 +1,10 @@
+export { createEntitlementsService, type EntitlementsService, type EntitlementsServiceDeps, type LimitCheck, type RecordUsageOptions, type ResolvedEntitlements, type UsageWindow, } from "./service.ts";
+/**
+ * Default service, bound to the configuration-driven database handle.
+ *
+ * No fallback plan is configured, so a workspace without a live subscription has
+ * no entitlements. Build your own with `createEntitlementsService` to grant a
+ * free tier.
+ */
+export declare const entitlements: import("./service.ts").EntitlementsService;
+//# sourceMappingURL=index.d.ts.map

package/dist/entitlements/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entitlements/index.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC;AAEtB;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,4CAIvB,CAAC"}

package/dist/entitlements/index.js

@@ -0,0 +1,28 @@
+/**
+ * Public entitlements surface: `@digimuza/saas-core/entitlements`. Server-only.
+ *
+ * Billing and authorization answer different questions. Authorization asks "may
+ * this user do it?"; entitlements ask "has this workspace paid for it?" Both must
+ * pass, and product code should never inspect a plan name to decide either:
+ *
+ * ```ts
+ * await authorization.require(context, "projects.create");
+ * await entitlements.require(context, "ai_generation");
+ * ```
+ */
+import { getDatabase } from "../db/client.js";
+import { createEntitlementsService } from "./service.js";
+export { createEntitlementsService, } from "./service.js";
+/**
+ * Default service, bound to the configuration-driven database handle.
+ *
+ * No fallback plan is configured, so a workspace without a live subscription has
+ * no entitlements. Build your own with `createEntitlementsService` to grant a
+ * free tier.
+ */
+export const entitlements = createEntitlementsService({
+    get db() {
+        return getDatabase();
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/entitlements/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entitlements/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EACL,yBAAyB,GAO1B,MAAM,cAAc,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,yBAAyB,CAAC;IACpD,IAAI,EAAE;QACJ,OAAO,WAAW,EAAE,CAAC;IACvB,CAAC;CACF,CAAC,CAAC"}

package/dist/entitlements/service.d.ts

@@ -0,0 +1,83 @@
+import type { CoreDatabase } from "../db/types.ts";
+import type { Entitlement, Plan } from "../db/schema/index.ts";
+import type { WorkspaceContext } from "../workspaces/context.ts";
+/**
+ * The window over which metered usage is counted.
+ *
+ * Aligned to the subscription's billing period when there is one, because that
+ * is what a customer is paying for. Workspaces on a fallback plan have no
+ * period, so the current UTC calendar month is used — an all-time total would
+ * make a monthly quota permanently exhausted.
+ */
+export interface UsageWindow {
+    readonly start: Date;
+    readonly end: Date;
+}
+export interface LimitCheck {
+    /** Whether the requested quantity fits within the remaining quota. */
+    readonly allowed: boolean;
+    /** Null when unlimited. */
+    readonly limit: number | null;
+    readonly used: number;
+    /** Null when unlimited. */
+    readonly remaining: number | null;
+    readonly window: UsageWindow;
+}
+export interface RecordUsageOptions {
+    readonly quantity?: number;
+    /**
+     * Deduplication key. A retried request reusing it is counted once, so a
+     * network retry does not consume the customer's quota twice.
+     */
+    readonly idempotencyKey?: string;
+    readonly occurredAt?: Date;
+}
+export interface ResolvedEntitlements {
+    readonly plan: Plan | undefined;
+    readonly byKey: ReadonlyMap<string, Entitlement>;
+}
+export interface EntitlementsService {
+    /** The plan whose entitlements apply, via the live subscription or the fallback. */
+    resolvePlan(context: WorkspaceContext): Promise<Plan | undefined>;
+    /** Everything the workspace is entitled to, keyed by entitlement key. */
+    resolve(context: WorkspaceContext): Promise<ResolvedEntitlements>;
+    /** Whether the workspace's plan includes this feature or limit at all. */
+    has(context: WorkspaceContext, key: string): Promise<boolean>;
+    /** As {@link has}, but throws {@link EntitlementRequiredError}. */
+    require(context: WorkspaceContext, key: string): Promise<void>;
+    /**
+     * The quota for a limit entitlement.
+     *
+     * `null` means unlimited; `0` means explicitly none. A key the plan does not
+     * include also yields `0`, so an unconfigured limit fails closed.
+     */
+    getLimit(context: WorkspaceContext, key: string): Promise<number | null>;
+    /** Whether `quantity` more units fit within the quota for the current period. */
+    checkLimit(context: WorkspaceContext, key: string, quantity?: number): Promise<LimitCheck>;
+    /** As {@link checkLimit}, but throws {@link LimitExceededError}. */
+    requireLimit(context: WorkspaceContext, key: string, quantity?: number): Promise<LimitCheck>;
+    /** Consumption in the current period. */
+    getUsage(context: WorkspaceContext, key: string): Promise<number>;
+    /** Append a usage record. Does not itself enforce the limit. */
+    recordUsage(context: WorkspaceContext, key: string, options?: RecordUsageOptions): Promise<void>;
+    /**
+     * Check the quota and record the consumption together.
+     *
+     * @throws LimitExceededError without recording anything.
+     */
+    consume(context: WorkspaceContext, key: string, options?: RecordUsageOptions): Promise<LimitCheck>;
+}
+export interface EntitlementsServiceDeps {
+    readonly db: CoreDatabase;
+    /**
+     * Plan applied to workspaces with no live subscription — a free tier.
+     *
+     * Omit it and such workspaces have no entitlements at all, which is the safe
+     * default but leaves no room for a free plan.
+     */
+    readonly fallbackPlanKey?: string;
+    /** Injected for deterministic tests. */
+    readonly now?: () => Date;
+}
+export declare function createEntitlementsService(deps: EntitlementsServiceDeps): EntitlementsService;
+//# sourceMappingURL=service.d.ts.map

package/dist/entitlements/service.d.ts.map

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