@dev-crew-berlin/enter-js-utils 0.99.1 → 0.99.3

package/dist/lib/email-handlebars.js

@@ -1,5 +1,5 @@
 import Handlebars from 'handlebars';
-import { makeGoogleWalletLink, makeQrCodeLink, makeRegistrationLink, makeTrackingLink, makeUnsubscribeLink, makeWalletLink } from './email-links';
+import { makeFileLink, makeGoogleWalletLink, makeQrCodeLink, makeRegistrationLink, makeTrackingLink, makeUnsubscribeLink, makeWalletLink } from './email-links';
 
 /**
  * A from-scratch TS port of the pybars helper set registered in
@@ -389,6 +389,9 @@ function registerLinkHelpers(hb, linkOptions, ctx) {
   hb.registerHelper('google_wallet_link', function (id) {
     return safe(makeGoogleWalletLink(linkOptions, id ?? ctx.attendeeId));
   });
+  hb.registerHelper('file', function (path) {
+    return safe(makeFileLink(linkOptions, path));
+  });
   hb.registerHelper('qr_code_link', function (...args) {
     const {
       explicit

package/dist/lib/email-handlebars.test.js

@@ -336,4 +336,8 @@ describe('link helpers', () => {
     });
     expect(html).toBe('https://test.frontend.example/home');
   });
+  it('file builds an unsigned /files/{path} link', async () => {
+    const html = await renderEn('{{file "attachments/agenda.pdf"}}', {});
+    expect(html).toBe('https://test.frontend.example/files/attachments/agenda.pdf');
+  });
 });

package/dist/lib/email-links.d.ts

@@ -36,6 +36,7 @@ export declare function makeRegistrationLink(options: LinkBuilderOptions, args:
 }): string;
 export declare function makeWalletLink(options: LinkBuilderOptions, attendeeId: string): string;
 export declare function makeGoogleWalletLink(options: LinkBuilderOptions, attendeeId: string): string;
+export declare function makeFileLink(options: LinkBuilderOptions, path: string): string;
 export declare function makeQrCodeLink(options: LinkBuilderOptions, args: {
     content: string;
     size?: number;

package/dist/lib/email-links.js

@@ -55,6 +55,9 @@ export function makeWalletLink(options, attendeeId) {
 export function makeGoogleWalletLink(options, attendeeId) {
   return `https://${options.domain}/google-wallet/${attendeeId}`;
 }
+export function makeFileLink(options, path) {
+  return `https://${options.domain}/files/${path}`;
+}
 export function makeQrCodeLink(options, args) {
   const params = new URLSearchParams({
     content: args.content,

package/dist/lib/email-links.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import jws from 'jws';
-import { makeGoogleWalletLink, makeQrCodeLink, makeRegistrationLink, makeTrackingLink, makeUnsubscribeLink, makeWalletLink } from './email-links';
+import { makeFileLink, makeGoogleWalletLink, makeQrCodeLink, makeRegistrationLink, makeTrackingLink, makeUnsubscribeLink, makeWalletLink } from './email-links';
 
 /**
  * Mirrors FrontendConfig's link builders
@@ -277,6 +277,11 @@ describe('makeGoogleWalletLink', () => {
     expect(makeGoogleWalletLink(options, 'att-1')).toBe('https://example.com/google-wallet/att-1');
   });
 });
+describe('makeFileLink', () => {
+  it('builds an unsigned /files/{path} link', () => {
+    expect(makeFileLink(options, 'attachments/agenda.pdf')).toBe('https://example.com/files/attachments/agenda.pdf');
+  });
+});
 describe('makeQrCodeLink', () => {
   it('builds a link under /qr/', () => {
     const link = makeQrCodeLink(options, {

package/dist/lib/email-render.d.ts

@@ -0,0 +1,38 @@
+import { PartialResolver } from './email-handlebars';
+import { LinkBuilderOptions } from './email-links';
+import { MailTemplateProps } from './mail-template-props';
+import { Attendee, PublicEmailContent } from '../models';
+export type RenderedEmailContent = {
+    subject: string;
+    toAddress: {
+        name: string;
+        email: string;
+    };
+    fromAddress: {
+        name: string;
+        email: string;
+    };
+    cc: string[];
+    bcc: string[];
+    reply: string;
+    pdfHtml: string;
+    pdfName: string;
+    props: MailTemplateProps;
+};
+/**
+ * Pure rendering: given an already-fetched attendee + email content, runs
+ * every field/block through the Handlebars engine and resolves the props a
+ * per-client `emails/{mail_name}.tsx` template needs. No API calls here --
+ * fetching (attendee, content, legacy templates, and any per-client extra
+ * data like payment info) is entirely the caller's responsibility, since it
+ * varies per client and has nothing to do with rendering itself.
+ */
+export declare function renderEmailContent(args: {
+    content: PublicEmailContent;
+    attendee: Attendee;
+    mailName: string;
+    attendeeId: string;
+    mailingId?: string;
+    linkOptions: LinkBuilderOptions;
+    resolvePartial: PartialResolver;
+}): Promise<RenderedEmailContent>;

package/dist/lib/email-render.js

@@ -0,0 +1,104 @@
+import { renderHandlebars } from './email-handlebars';
+import { parseAddress, splitAddressList } from './parse-address';
+async function renderValue(value, data, handlebarsOptions) {
+  if (value.type === 'text') return value.content;
+  return renderHandlebars(value.content, data, handlebarsOptions);
+}
+
+/**
+ * Pure rendering: given an already-fetched attendee + email content, runs
+ * every field/block through the Handlebars engine and resolves the props a
+ * per-client `emails/{mail_name}.tsx` template needs. No API calls here --
+ * fetching (attendee, content, legacy templates, and any per-client extra
+ * data like payment info) is entirely the caller's responsibility, since it
+ * varies per client and has nothing to do with rendering itself.
+ */
+export async function renderEmailContent(args) {
+  const {
+    content,
+    attendee,
+    mailName,
+    attendeeId,
+    mailingId,
+    linkOptions,
+    resolvePartial
+  } = args;
+  const attendeeJson = attendee.toJSON();
+  const lang = attendee.language ?? 'en';
+  const linkContext = {
+    attendeeId,
+    emailName: mailName,
+    mailingId,
+    // the legacy renderer disables tracking only for mailgun accounts with
+    // their own link tracking enabled -- that's instance-level email_sender
+    // config the frontend doesn't otherwise need, so default to tracking
+    // on; a template can still pass `{{link url false}}` to opt out.
+    trackingEnabled: true
+  };
+  const handlebarsData = {
+    id: attendeeId,
+    mailing_id: mailingId,
+    language: lang,
+    userdata: attendeeJson.userdata ?? {},
+    ...attendeeJson
+  };
+  const handlebarsOptions = {
+    lang,
+    languages: [lang, 'en', 'de'].filter((v, i, arr) => arr.indexOf(v) === i),
+    linkOptions,
+    linkContext,
+    resolvePartial
+  };
+  const [subject, to, toName, from, cc, bcc, reply, pre, pdfHtml] = await Promise.all([renderValue(content.subject, handlebarsData, handlebarsOptions), renderValue(content.to, handlebarsData, handlebarsOptions), renderValue(content.to_name, handlebarsData, handlebarsOptions), renderValue(content.from, handlebarsData, handlebarsOptions), renderValue(content.cc, handlebarsData, handlebarsOptions), renderValue(content.bcc, handlebarsData, handlebarsOptions), renderValue(content.reply, handlebarsData, handlebarsOptions), renderValue(content.pre, handlebarsData, handlebarsOptions), renderValue(content.pdf, handlebarsData, handlebarsOptions)]);
+  // mirrors the legacy renderer (app/emails.py): only render the pdf
+  // filename if there's actually a pdf body to attach it to.
+  const pdfName = pdfHtml ? await renderValue(content.pdfname, handlebarsData, handlebarsOptions) : '';
+  const renderedBlocks = await Promise.all([...content.blocks].sort((a, b) => a.sort_order - b.sort_order).map(async block => {
+    if (block.value.type === 'text') {
+      return {
+        key: block.key,
+        name: block.name,
+        type: 'text',
+        content: block.value.content
+      };
+    }
+    return {
+      key: block.key,
+      name: block.name,
+      type: 'html',
+      html: await renderHandlebars(block.value.content, handlebarsData, handlebarsOptions)
+    };
+  }));
+  const props = {
+    instanceName: linkOptions.instanceName,
+    attendee,
+    content,
+    linkOptions,
+    linkContext,
+    renderedFields: {
+      subject,
+      to,
+      toName,
+      from,
+      cc,
+      bcc,
+      reply,
+      pre
+    },
+    renderedBlocks
+  };
+  const fromAddress = parseAddress(from);
+  const toAddress = parseAddress(to);
+  if (toName && !toAddress.name) toAddress.name = toName;
+  return {
+    subject,
+    toAddress,
+    fromAddress,
+    cc: splitAddressList(cc),
+    bcc: splitAddressList(bcc),
+    reply,
+    pdfHtml,
+    pdfName,
+    props
+  };
+}

package/dist/lib/email-render.test.js

@@ -0,0 +1,293 @@
+import { describe, it, expect, vi } from 'vitest';
+import { renderEmailContent } from './email-render';
+const linkOptions = {
+  jwtSecret: 'test-secret',
+  instanceName: 'test-instance',
+  domain: 'test.example.com'
+};
+const notFoundPartial = vi.fn().mockResolvedValue('Template not found');
+function fakeAttendee(overrides = {}) {
+  const json = {
+    id: 'att-1',
+    language: 'en',
+    userdata: {
+      vorname: 'Max',
+      email: 'max@example.com'
+    },
+    ...overrides
+  };
+  return {
+    ...json,
+    toJSON: () => json
+  };
+}
+describe('renderEmailContent', () => {
+  it('renders fixed fields and blocks through the Handlebars engine, sorted by sort_order', async () => {
+    const result = await renderEmailContent({
+      attendee: fakeAttendee(),
+      mailName: 'welcome',
+      attendeeId: 'att-1',
+      linkOptions,
+      resolvePartial: notFoundPartial,
+      content: {
+        subject: {
+          type: 'handlebars',
+          content: 'Welcome {{userdata.vorname}}!'
+        },
+        to: {
+          type: 'handlebars',
+          content: '{{userdata.email}}'
+        },
+        to_name: {
+          type: 'text',
+          content: ''
+        },
+        from: {
+          type: 'text',
+          content: 'sender@example.com'
+        },
+        cc: {
+          type: 'text',
+          content: ''
+        },
+        bcc: {
+          type: 'text',
+          content: ''
+        },
+        reply: {
+          type: 'text',
+          content: ''
+        },
+        pre: {
+          type: 'text',
+          content: ''
+        },
+        pdf: {
+          type: 'handlebars',
+          content: '<p>Ticket for {{userdata.vorname}}</p>'
+        },
+        pdfname: {
+          type: 'handlebars',
+          content: '{{userdata.vorname}}.pdf'
+        },
+        blocks: [{
+          key: 'second',
+          name: 'Second',
+          sort_order: 1,
+          value: {
+            type: 'text',
+            content: 'Second block'
+          }
+        }, {
+          key: 'first',
+          name: 'First',
+          sort_order: 0,
+          value: {
+            type: 'handlebars',
+            content: 'Hi {{userdata.vorname}}'
+          }
+        }]
+      }
+    });
+    expect(result.subject).toBe('Welcome Max!');
+    expect(result.toAddress).toEqual({
+      name: '',
+      email: 'max@example.com'
+    });
+    expect(result.fromAddress).toEqual({
+      name: '',
+      email: 'sender@example.com'
+    });
+    expect(result.pdfHtml).toBe('<p>Ticket for Max</p>');
+    expect(result.pdfName).toBe('Max.pdf');
+    expect(result.props.renderedBlocks).toEqual([{
+      key: 'first',
+      name: 'First',
+      type: 'html',
+      html: 'Hi Max'
+    }, {
+      key: 'second',
+      name: 'Second',
+      type: 'text',
+      content: 'Second block'
+    }]);
+  });
+  it('leaves the pdf filename empty when there is no pdf body to attach it to', async () => {
+    const result = await renderEmailContent({
+      attendee: fakeAttendee(),
+      mailName: 'welcome',
+      attendeeId: 'att-1',
+      linkOptions,
+      resolvePartial: notFoundPartial,
+      content: {
+        subject: {
+          type: 'text',
+          content: 'Hello'
+        },
+        to: {
+          type: 'text',
+          content: 'a@b.com'
+        },
+        to_name: {
+          type: 'text',
+          content: ''
+        },
+        from: {
+          type: 'text',
+          content: 'sender@example.com'
+        },
+        cc: {
+          type: 'text',
+          content: ''
+        },
+        bcc: {
+          type: 'text',
+          content: ''
+        },
+        reply: {
+          type: 'text',
+          content: ''
+        },
+        pre: {
+          type: 'text',
+          content: ''
+        },
+        pdf: {
+          type: 'text',
+          content: ''
+        },
+        pdfname: {
+          type: 'text',
+          content: 'never-rendered.pdf'
+        },
+        blocks: []
+      }
+    });
+    expect(result.pdfHtml).toBe('');
+    expect(result.pdfName).toBe('');
+  });
+  it('falls back toAddress.name to the rendered to_name when the address has none', async () => {
+    const result = await renderEmailContent({
+      attendee: fakeAttendee(),
+      mailName: 'welcome',
+      attendeeId: 'att-1',
+      linkOptions,
+      resolvePartial: notFoundPartial,
+      content: {
+        subject: {
+          type: 'text',
+          content: 'Hello'
+        },
+        to: {
+          type: 'text',
+          content: 'a@b.com'
+        },
+        to_name: {
+          type: 'text',
+          content: 'A B'
+        },
+        from: {
+          type: 'text',
+          content: 'sender@example.com'
+        },
+        cc: {
+          type: 'text',
+          content: ''
+        },
+        bcc: {
+          type: 'text',
+          content: ''
+        },
+        reply: {
+          type: 'text',
+          content: ''
+        },
+        pre: {
+          type: 'text',
+          content: ''
+        },
+        pdf: {
+          type: 'text',
+          content: ''
+        },
+        pdfname: {
+          type: 'text',
+          content: ''
+        },
+        blocks: []
+      }
+    });
+    expect(result.toAddress).toEqual({
+      name: 'A B',
+      email: 'a@b.com'
+    });
+  });
+  it('resolves handlebars partials via the injected resolvePartial callback', async () => {
+    const resolvePartial = vi.fn().mockResolvedValue('resolved partial text');
+    const result = await renderEmailContent({
+      attendee: fakeAttendee(),
+      mailName: 'welcome',
+      attendeeId: 'att-1',
+      linkOptions,
+      resolvePartial,
+      content: {
+        subject: {
+          type: 'text',
+          content: 'Hello'
+        },
+        to: {
+          type: 'text',
+          content: 'a@b.com'
+        },
+        to_name: {
+          type: 'text',
+          content: ''
+        },
+        from: {
+          type: 'text',
+          content: 'sender@example.com'
+        },
+        cc: {
+          type: 'text',
+          content: ''
+        },
+        bcc: {
+          type: 'text',
+          content: ''
+        },
+        reply: {
+          type: 'text',
+          content: ''
+        },
+        pre: {
+          type: 'text',
+          content: ''
+        },
+        pdf: {
+          type: 'text',
+          content: ''
+        },
+        pdfname: {
+          type: 'text',
+          content: ''
+        },
+        blocks: [{
+          key: 'body',
+          name: 'Body',
+          sort_order: 0,
+          value: {
+            type: 'handlebars',
+            content: '{{> footer}}'
+          }
+        }]
+      }
+    });
+    expect(resolvePartial).toHaveBeenCalledWith('footer');
+    expect(result.props.renderedBlocks).toEqual([{
+      key: 'body',
+      name: 'Body',
+      type: 'html',
+      html: 'resolved partial text'
+    }]);
+  });
+});

package/dist/lib/index.d.ts

@@ -9,3 +9,6 @@ export * from './csrf';
 export * from './tokens';
 export * from './email-links';
 export * from './email-handlebars';
+export * from './parse-address';
+export * from './mail-template-props';
+export * from './email-render';

package/dist/lib/index.js

@@ -8,4 +8,7 @@ export * from './headers';
 export * from './csrf';
 export * from './tokens';
 export * from './email-links';
-export * from './email-handlebars';
+export * from './email-handlebars';
+export * from './parse-address';
+export * from './mail-template-props';
+export * from './email-render';

package/dist/lib/mail-template-props.d.ts

@@ -0,0 +1,47 @@
+import { Attendee, PublicEmailContent } from '../models';
+import { EmailLinkContext } from './email-handlebars';
+import { LinkBuilderOptions } from './email-links';
+/**
+ * A block's rendered output, keeping the text/HTML distinction from its
+ * source `ContentValue.type` (see models/email-content.ts) instead of
+ * collapsing both to a plain HTML string -- lets a template render a
+ * `'text'` block through react-email's own (escaping) `<Text>` and reserve
+ * `dangerouslySetInnerHTML` for `'html'` blocks only.
+ */
+export type RenderedBlock = {
+    key: string;
+    name: string;
+    type: 'text';
+    content: string;
+} | {
+    key: string;
+    name: string;
+    type: 'html';
+    html: string;
+};
+/**
+ * Props every per-client `emails/{mail_name}.tsx` (and its `_default`
+ * fallback) receives from `renderHeadlessEmail`. `renderedFields`/
+ * `renderedBlocks` are already resolved/awaited -- a single ContentValue (a
+ * fixed field or a block's value) run through the Handlebars engine when its
+ * type is "handlebars", or the literal string for "text" -- since
+ * react-email components render synchronously.
+ */
+export type MailTemplateProps = {
+    instanceName: string;
+    attendee: Attendee;
+    content: PublicEmailContent;
+    linkOptions: LinkBuilderOptions;
+    linkContext: EmailLinkContext;
+    renderedFields: {
+        subject: string;
+        to: string;
+        toName: string;
+        from: string;
+        cc: string;
+        bcc: string;
+        reply: string;
+        pre: string;
+    };
+    renderedBlocks: RenderedBlock[];
+};

package/dist/lib/mail-template-props.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/parse-address.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A small subset of Python's email.utils.parseaddr, which is what the
+ * legacy renderer (app/emails.py) uses to split a rendered "to"/"from"
+ * field into a name + email pair. Handles the two shapes templates
+ * actually produce: "Name <email@x.com>" and a bare "email@x.com".
+ */
+export declare function parseAddress(raw: string): {
+    name: string;
+    email: string;
+};
+export declare function splitAddressList(raw: string): string[];

package/dist/lib/parse-address.js

@@ -0,0 +1,23 @@
+/**
+ * A small subset of Python's email.utils.parseaddr, which is what the
+ * legacy renderer (app/emails.py) uses to split a rendered "to"/"from"
+ * field into a name + email pair. Handles the two shapes templates
+ * actually produce: "Name <email@x.com>" and a bare "email@x.com".
+ */
+export function parseAddress(raw) {
+  const trimmed = raw.trim();
+  const match = /^(.*)<([^<>]+)>\s*$/.exec(trimmed);
+  if (match) {
+    return {
+      name: match[1].trim().replace(/^"|"$/g, ''),
+      email: match[2].trim()
+    };
+  }
+  return {
+    name: '',
+    email: trimmed
+  };
+}
+export function splitAddressList(raw) {
+  return raw.replace(/;/g, ',').split(',').map(s => s.trim()).filter(Boolean);
+}

package/dist/lib/parse-address.test.js

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { parseAddress, splitAddressList } from './parse-address';
+describe('parseAddress', () => {
+  it('splits a "Name <email>" address into name and email', () => {
+    expect(parseAddress('Max Mustermann <max@example.com>')).toEqual({
+      name: 'Max Mustermann',
+      email: 'max@example.com'
+    });
+  });
+  it('strips surrounding quotes from the name', () => {
+    expect(parseAddress('"Max Mustermann" <max@example.com>')).toEqual({
+      name: 'Max Mustermann',
+      email: 'max@example.com'
+    });
+  });
+  it('returns an empty name for a bare email address', () => {
+    expect(parseAddress('max@example.com')).toEqual({
+      name: '',
+      email: 'max@example.com'
+    });
+  });
+  it('trims surrounding whitespace', () => {
+    expect(parseAddress('  Max Mustermann <max@example.com>  ')).toEqual({
+      name: 'Max Mustermann',
+      email: 'max@example.com'
+    });
+  });
+});
+describe('splitAddressList', () => {
+  it('splits a comma-separated list and trims each entry', () => {
+    expect(splitAddressList('a@example.com, b@example.com')).toEqual(['a@example.com', 'b@example.com']);
+  });
+  it('treats semicolons as separators too', () => {
+    expect(splitAddressList('a@example.com; b@example.com')).toEqual(['a@example.com', 'b@example.com']);
+  });
+  it('drops empty entries', () => {
+    expect(splitAddressList('a@example.com,,b@example.com,')).toEqual(['a@example.com', 'b@example.com']);
+  });
+  it('returns an empty array for an empty string', () => {
+    expect(splitAddressList('')).toEqual([]);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-crew-berlin/enter-js-utils",
-  "version": "0.99.1",
+  "version": "0.99.3",
   "description": "utils such as vaildation and other helpers to work with data from the enter app",
   "files": [
     "dist",