@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

package/dist/template-resolver/template-meta.d.ts

@@ -0,0 +1,85 @@
+import * as z from "zod";
+import { type TemplateKind } from "./constants.js";
+export declare const templateSlugSchema: z.ZodString;
+export declare const MAIL_CATEGORIES: readonly ["transactional", "marketing"];
+export type MailCategory = (typeof MAIL_CATEGORIES)[number];
+declare const mailMetaSchema: z.ZodPreprocess<z.ZodObject<{
+    subject: z.ZodString;
+    previewText: z.ZodOptional<z.ZodString>;
+    layoutSlug: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodEnum<{
+        marketing: "marketing";
+        transactional: "transactional";
+    }>>;
+    senderName: z.ZodOptional<z.ZodString>;
+    replyTo: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodEmail>>;
+}, z.core.$strict>, unknown>;
+export declare const pdfAttachmentFileNamePatternSchema: z.ZodString;
+declare const pdfMetaSchema: z.ZodObject<{
+    layoutSlug: z.ZodOptional<z.ZodString>;
+    pageFormat: z.ZodOptional<z.ZodEnum<{
+        A4: "A4";
+        Letter: "Letter";
+    }>>;
+    orientation: z.ZodOptional<z.ZodEnum<{
+        landscape: "landscape";
+        portrait: "portrait";
+    }>>;
+    printBackground: z.ZodOptional<z.ZodBoolean>;
+    layoutHeaderFooter: z.ZodOptional<z.ZodBoolean>;
+    margins: z.ZodOptional<z.ZodObject<{
+        top: z.ZodOptional<z.ZodNumber>;
+        right: z.ZodOptional<z.ZodNumber>;
+        bottom: z.ZodOptional<z.ZodNumber>;
+        left: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    fileName: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const mailLayoutMetaSchema: z.ZodObject<{
+    width: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<560>, z.ZodLiteral<600>, z.ZodLiteral<640>]>>;
+    font: z.ZodOptional<z.ZodEnum<{
+        sans: "sans";
+        serif: "serif";
+    }>>;
+    outerBackground: z.ZodOptional<z.ZodString>;
+    accentLine: z.ZodOptional<z.ZodEnum<{
+        branding: "branding";
+        none: "none";
+    }>>;
+    buttonStyle: z.ZodOptional<z.ZodEnum<{
+        "filled-rounded": "filled-rounded";
+        "filled-square": "filled-square";
+        outline: "outline";
+    }>>;
+}, z.core.$strict>;
+declare const pdfLayoutMetaSchema: z.ZodObject<{}, z.core.$strict>;
+export type MailTemplateMeta = z.infer<typeof mailMetaSchema>;
+export type PdfTemplateMeta = z.infer<typeof pdfMetaSchema>;
+export type MailLayoutMeta = z.infer<typeof mailLayoutMetaSchema>;
+export type LayoutTemplateMeta = MailLayoutMeta | z.infer<typeof pdfLayoutMetaSchema>;
+export type TemplateMeta = MailTemplateMeta | PdfTemplateMeta | LayoutTemplateMeta;
+export declare function isMailTemplateMeta(meta: TemplateMeta | null): meta is MailTemplateMeta;
+export declare function readPdfTemplateMeta(meta: TemplateMeta | null): PdfTemplateMeta | null;
+export declare function readMailLayoutMeta(meta: unknown): MailLayoutMeta;
+export type TemplateMetaIssue = {
+    readonly path: string;
+    /** The setting the issue is about (`subject`), `meta` when it concerns the object as a whole. */
+    readonly field: string;
+    /** The value is absent or empty, as opposed to present and wrong. */
+    readonly missing: boolean;
+    /** Parser wording; for logs and tests, never for the UI. */
+    readonly message: string;
+};
+export type TemplateMetaResult = {
+    readonly ok: true;
+    readonly meta: TemplateMeta | null;
+} | {
+    readonly ok: false;
+    readonly issues: readonly TemplateMetaIssue[];
+};
+export declare function parseTemplateMeta(kind: TemplateKind, raw: unknown): TemplateMetaResult;
+export {};

package/dist/template-resolver/template-meta.js

@@ -0,0 +1,145 @@
+import * as z from "zod";
+import { HEX_COLOR_PATTERN, PDF_ORIENTATIONS, PDF_PAGE_FORMATS, } from "./constants.js";
+// One or more kebab segments joined by ":" — notification templates are seeded
+// under their qualified name `feature:notify:name`.
+export const templateSlugSchema = z
+    .string()
+    .min(1)
+    .max(120)
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9]+(-[a-z0-9]+)*)*$/, "slug must be kebab-case segments joined by ':'");
+export const MAIL_CATEGORIES = ["transactional", "marketing"];
+// Header values: a CR/LF would let an author inject extra mail headers.
+const singleLine = (max) => z
+    .string()
+    .max(max)
+    .refine((value) => !/[\r\n]/.test(value), "must not contain line breaks");
+// Rows saved before the sender key was dropped still carry it; discard it on read so they stay editable.
+function withoutLegacySender(raw) {
+    if (typeof raw !== "object" || raw === null || !("sender" in raw))
+        return raw;
+    const { sender: _legacySender, ...rest } = raw;
+    return rest;
+}
+const mailMetaSchema = z.preprocess(withoutLegacySender, z
+    .object({
+    subject: singleLine(200).min(1),
+    previewText: singleLine(200).optional(),
+    layoutSlug: templateSlugSchema.optional(),
+    category: z.enum(MAIL_CATEGORIES).optional(),
+    senderName: singleLine(80).min(1).optional(),
+    replyTo: singleLine(254).pipe(z.email()).optional(),
+})
+    .strict());
+const marginMm = z.number().finite().min(0).max(100).optional();
+// The file name ends up in a Content-Disposition header and on disk.
+const FORBIDDEN_FILE_NAME = /[/\\";]|\.\./;
+// Name of a PDF rendered into a mail; {{placeholders}} are filled at render time.
+export const pdfAttachmentFileNamePatternSchema = singleLine(200)
+    .min(1)
+    .refine((value) => !FORBIDDEN_FILE_NAME.test(value), 'must not contain / \\ " ; or ..')
+    .refine((value) => value.toLowerCase().endsWith(".pdf"), "must end with .pdf");
+const pdfMetaSchema = z
+    .object({
+    layoutSlug: templateSlugSchema.optional(),
+    pageFormat: z.enum(PDF_PAGE_FORMATS).optional(),
+    orientation: z.enum(PDF_ORIENTATIONS).optional(),
+    printBackground: z.boolean().optional(),
+    layoutHeaderFooter: z.boolean().optional(),
+    margins: z
+        .object({ top: marginMm, right: marginMm, bottom: marginMm, left: marginMm })
+        .strict()
+        .optional(),
+    fileName: singleLine(200)
+        .min(1)
+        .refine((value) => !FORBIDDEN_FILE_NAME.test(value), 'must not contain / \\ " ; or ..')
+        .optional(),
+    metadata: z
+        .object({ title: singleLine(200).optional(), author: singleLine(200).optional() })
+        .strict()
+        .optional(),
+})
+    .strict();
+const MAIL_LAYOUT_FONTS = ["sans", "serif"];
+const MAIL_LAYOUT_ACCENT_LINES = ["branding", "none"];
+const MAIL_LAYOUT_BUTTON_STYLES = ["filled-rounded", "filled-square", "outline"];
+const mailLayoutMetaSchema = z
+    .object({
+    width: z.union([z.literal(560), z.literal(600), z.literal(640)]).optional(),
+    font: z.enum(MAIL_LAYOUT_FONTS).optional(),
+    outerBackground: z.string().regex(HEX_COLOR_PATTERN, "must be a #rrggbb color").optional(),
+    accentLine: z.enum(MAIL_LAYOUT_ACCENT_LINES).optional(),
+    buttonStyle: z.enum(MAIL_LAYOUT_BUTTON_STYLES).optional(),
+})
+    .strict();
+const pdfLayoutMetaSchema = z.object({}).strict();
+export function isMailTemplateMeta(meta) {
+    return meta !== null && "subject" in meta;
+}
+export function readPdfTemplateMeta(meta) {
+    const parsed = pdfMetaSchema.safeParse(meta);
+    return parsed.success ? parsed.data : null;
+}
+export function readMailLayoutMeta(meta) {
+    const parsed = mailLayoutMetaSchema.safeParse(meta ?? {});
+    return parsed.success ? parsed.data : {};
+}
+function valueAt(raw, path) {
+    let current = raw;
+    for (const key of path) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = Object.entries(current).find(([name]) => name === String(key))?.[1];
+    }
+    return current;
+}
+function schemaForKind(kind) {
+    switch (kind) {
+        case "mail":
+            return mailMetaSchema;
+        case "document-pdf":
+            return pdfMetaSchema;
+        case "mail-layout":
+            return mailLayoutMetaSchema;
+        case "pdf-layout":
+            return pdfLayoutMetaSchema;
+        default:
+            return null;
+    }
+}
+// Kinds without a meta schema must not carry meta at all; mail needs it,
+// layouts and PDFs may omit it.
+export function parseTemplateMeta(kind, raw) {
+    const schema = schemaForKind(kind);
+    if (schema === null) {
+        return raw === undefined || raw === null
+            ? { ok: true, meta: null }
+            : {
+                ok: false,
+                issues: [
+                    {
+                        path: "meta",
+                        field: "meta",
+                        missing: false,
+                        message: `kind ${kind} does not take meta`,
+                    },
+                ],
+            };
+    }
+    if ((raw === undefined || raw === null) && kind !== "mail")
+        return { ok: true, meta: null };
+    const parsed = schema.safeParse(raw ?? undefined);
+    if (parsed.success)
+        return { ok: true, meta: parsed.data };
+    return {
+        ok: false,
+        issues: parsed.error.issues.map((issue) => {
+            const value = valueAt(raw, issue.path);
+            return {
+                path: ["meta", ...issue.path.map(String)].join("."),
+                field: issue.path.length === 0 ? "meta" : String(issue.path[0]),
+                missing: value === undefined || value === "",
+                message: issue.message,
+            };
+        }),
+    };
+}

package/dist/template-resolver/template-preview.d.ts

@@ -0,0 +1,103 @@
+import type { HandlerContext, SessionUser, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
+import { type KumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { type MailAttachmentRef } from "../renderer-foundation/index.js";
+import { type TemplateScope } from "./constants.js";
+import { validateTemplateDraft } from "./handlers/validate.query.js";
+import { type LayoutRegions, type TemplateWriteScope } from "./layout-regions.js";
+import { type PdfTemplateMeta } from "./template-meta.js";
+export declare function sampleValuesFor(variables: TemplateVariables): Record<string, unknown>;
+export type PreviewCheckCode = "resources_resolved" | "text_present" | "size_under_cap" | "required_placeholders";
+export type PreviewCheck = {
+    readonly code: PreviewCheckCode;
+    readonly ok: boolean;
+    readonly i18nKey: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+};
+export type PreviewAttachment = {
+    readonly kind: "inline";
+    readonly cid: string;
+    readonly name: string;
+    readonly sizeBytes: number;
+} | {
+    readonly kind: "file";
+    readonly name: string;
+    readonly sizeBytes: number;
+} | {
+    readonly kind: "rendered-pdf";
+    readonly name: string;
+    readonly templateSlug: string;
+};
+export type PreviewLayout = {
+    readonly slug: string;
+    readonly scope: TemplateScope;
+    readonly html: string;
+    readonly regions: LayoutRegions;
+};
+export type TemplatePreviewInput = {
+    readonly slug: string;
+    readonly kind: "mail" | "document-pdf";
+    readonly locale: string;
+    readonly content?: string | undefined;
+    readonly meta?: unknown;
+    readonly variableSchema: Readonly<Record<string, unknown>>;
+};
+type ValidationResponse = Awaited<ReturnType<typeof validateTemplateDraft>>["response"];
+export type TemplatePreview = {
+    readonly kind: TemplatePreviewInput["kind"];
+    readonly subject: string | null;
+    readonly previewText: string | null;
+    readonly html: string;
+    /** Mail only: `html` with resolved inline images as data URIs, for showing in a browser. */
+    readonly displayHtml?: string;
+    readonly text: string | null;
+    readonly attachments: readonly PreviewAttachment[];
+    readonly layout: PreviewLayout | null;
+    /** Mail only: which layout version the html was rendered through. */
+    readonly mailLayout?: {
+        readonly slug: string;
+        readonly scope: TemplateScope;
+        readonly version: number;
+    } | null;
+    readonly sampleValues: Readonly<Record<string, unknown>>;
+    readonly checks: readonly PreviewCheck[];
+    readonly validation: ValidationResponse;
+};
+export type TemplatePreviewOutcome = {
+    readonly ok: true;
+    readonly preview: TemplatePreview;
+    /** What the send path needs to attach; kept out of the response shown to the editor. */
+    readonly mailAttachments: readonly MailAttachmentRef[];
+    readonly sender: {
+        readonly fromName?: string;
+        readonly replyTo?: string;
+    };
+} | {
+    readonly ok: false;
+    readonly error: KumikoError;
+};
+export declare const MIME_PART_OVERHEAD_BYTES = 512;
+export declare function encodedAttachmentBytes(rawBytes: number): number;
+export declare function estimateMailBytes(args: {
+    readonly html: string;
+    readonly text: string;
+    readonly attachments: readonly PreviewAttachment[];
+}): number;
+export type DocumentDraftOutcome = {
+    readonly ok: true;
+    readonly content: string;
+    readonly meta: PdfTemplateMeta | null;
+    readonly variableSchema: Readonly<Record<string, unknown>>;
+    readonly sampleValues: Readonly<Record<string, unknown>>;
+} | {
+    readonly ok: false;
+    readonly error: KumikoError;
+};
+export declare function evaluateDocumentDraft(ctx: HandlerContext, user: SessionUser, scope: TemplateWriteScope, draft: {
+    readonly slug: string;
+    readonly locale: string;
+    readonly content: string;
+    readonly meta?: unknown;
+    readonly variableSchema: Readonly<Record<string, unknown>>;
+}): Promise<DocumentDraftOutcome>;
+export declare function renderTemplatePreview(ctx: HandlerContext, user: SessionUser, input: TemplatePreviewInput): Promise<TemplatePreviewOutcome>;
+export {};