@dev-crew-berlin/enter-js-utils 0.98.12 → 0.99.0

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

@@ -0,0 +1,339 @@
+import { describe, it, expect } from 'vitest';
+import { renderHandlebars } from './email-handlebars';
+
+/**
+ * Mirrors enter-core/tests/unittests/app/render_templates_test.py, which
+ * characterizes the *actual* pybars implementation these helpers are
+ * ported from -- same cases, same expected outputs (verified against real
+ * pybars/babel output there), so the two engines are checked to agree
+ * rather than silently drifting apart. Two documented, intentional
+ * deviations: `escape` does real HTML-escaping instead of reproducing a
+ * legacy bytes-repr bug, and date/shortdate/longdate/fulldate assume UTC
+ * input (see lib/email-handlebars.ts for why).
+ */
+
+const baseOptions = {
+  linkOptions: {
+    instanceName: 'test-instance',
+    jwtSecret: 'test-secret',
+    domain: 'test.frontend.example'
+  },
+  linkContext: {
+    attendeeId: 'att-1',
+    emailName: 'welcome',
+    trackingEnabled: true
+  },
+  resolvePartial: async () => {
+    throw new Error('unexpected partial lookup');
+  }
+};
+function renderEn(source, data = {}, extra = {}) {
+  return renderHandlebars(source, data, {
+    ...baseOptions,
+    lang: 'en',
+    languages: ['en', 'de'],
+    ...extra
+  });
+}
+function renderDe(source, data = {}) {
+  return renderHandlebars(source, data, {
+    ...baseOptions,
+    lang: 'de',
+    languages: ['en', 'de']
+  });
+}
+describe('translate helper (_)', () => {
+  it('picks the current language by default', async () => {
+    expect(await renderDe('{{_ label}}', {
+      label: {
+        en: 'Hello',
+        de: 'Hallo'
+      }
+    })).toBe('Hallo');
+  });
+  it('an explicit language argument overrides the current one', async () => {
+    expect(await renderDe('{{_ label "en"}}', {
+      label: {
+        en: 'Hello',
+        de: 'Hallo'
+      }
+    })).toBe('Hello');
+  });
+  it('passes non-object values through unchanged', async () => {
+    expect(await renderEn('{{_ label}}', {
+      label: 'plain string'
+    })).toBe('plain string');
+  });
+});
+describe('upper/lower helpers', () => {
+  it('upper translates then uppercases', async () => {
+    expect(await renderEn('{{upper label}}', {
+      label: {
+        en: 'hello'
+      }
+    })).toBe('HELLO');
+  });
+  it('lower translates then lowercases', async () => {
+    expect(await renderEn('{{lower label}}', {
+      label: {
+        en: 'HELLO'
+      }
+    })).toBe('hello');
+  });
+});
+describe('language block helper', () => {
+  it('renders the block only for the matching language', async () => {
+    const template = '{{#en}}Hi{{/en}}{{#de}}Hallo{{/de}}';
+    expect(await renderEn(template, {})).toBe('Hi');
+    expect(await renderDe(template, {})).toBe('Hallo');
+  });
+  it('inline args translate and concatenate', async () => {
+    expect(await renderEn('{{en "Attendee management by"}}', {})).toBe('Attendee management by');
+    expect(await renderDe('{{en "Attendee management by"}}', {})).toBe('');
+  });
+});
+describe('eq helper', () => {
+  it('takes the true branch when equal', async () => {
+    expect(await renderEn('{{#eq a b}}yes{{else}}no{{/eq}}', {
+      a: 'x',
+      b: 'x'
+    })).toBe('yes');
+  });
+  it('takes the false branch when not equal', async () => {
+    expect(await renderEn('{{#eq a b}}yes{{else}}no{{/eq}}', {
+      a: 'x',
+      b: 'y'
+    })).toBe('no');
+  });
+});
+describe('custom if helper', () => {
+  it.each([['==', 5, 5, 'yes'], ['!=', 5, 5, 'yes'],
+  // mirrors the legacy bug: != behaves like ==
+  ['>', 5, 3, 'yes'], ['<', 3, 5, 'yes'], ['>=', 5, 5, 'yes'], ['<=', 5, 5, 'yes'], ['in', 'b', 'abc', 'yes']])('operator %s', async (operator, left, right, expected) => {
+    const template = `{{#if a "${operator}" b}}yes{{else}}no{{/if}}`;
+    expect(await renderEn(template, {
+      a: left,
+      b: right
+    })).toBe(expected);
+  });
+  it('falls back to else on a type mismatch', async () => {
+    expect(await renderEn('{{#if a ">" b}}yes{{else}}no{{/if}}', {
+      a: 'not-a-number',
+      b: 3
+    })).toBe('no');
+  });
+  it('single-argument truthiness', async () => {
+    expect(await renderEn('{{#if x}}Y{{else}}N{{/if}}', {
+      x: true
+    })).toBe('Y');
+    expect(await renderEn('{{#if x}}Y{{else}}N{{/if}}', {
+      x: false
+    })).toBe('N');
+  });
+});
+describe('if_in helper', () => {
+  it('true when the value is in the list', async () => {
+    expect(await renderEn('{{#if_in list "x"}}yes{{else}}no{{/if_in}}', {
+      list: ['x', 'y']
+    })).toBe('yes');
+  });
+  it('false when missing', async () => {
+    expect(await renderEn('{{#if_in list "z"}}yes{{else}}no{{/if_in}}', {
+      list: ['x', 'y']
+    })).toBe('no');
+  });
+});
+describe('join helper', () => {
+  it('joins a list with a separator', async () => {
+    expect(await renderEn('{{join list ", "}}', {
+      list: ['a', 'b', 'c']
+    })).toBe('a, b, c');
+  });
+  it('joins with a distinct last separator', async () => {
+    expect(await renderEn('{{join list ", " " and "}}', {
+      list: ['a', 'b', 'c']
+    })).toBe('a, b and c');
+  });
+  it('a single-item list is returned unchanged', async () => {
+    expect(await renderEn('{{join list ", " " and "}}', {
+      list: ['a']
+    })).toBe('a');
+  });
+});
+describe('calc helper', () => {
+  it('addition preserves max decimal precision', async () => {
+    expect(await renderEn('{{calc a "+" b}}', {
+      a: '1.5',
+      b: '2.25'
+    })).toBe('3.75');
+  });
+  it('division round-half-to-even on a whole-number result shows .0', async () => {
+    expect(await renderEn('{{calc a "/" b}}', {
+      a: '10',
+      b: '4'
+    })).toBe('2.0');
+  });
+  it('non-numeric input renders empty', async () => {
+    expect(await renderEn('{{calc a "+" b}}', {
+      a: 'abc',
+      b: '1'
+    })).toBe('');
+  });
+});
+describe('count helper', () => {
+  it('counts list length', async () => {
+    expect(await renderEn('{{count list}}', {
+      list: ['a', 'b', 'c']
+    })).toBe('3');
+  });
+  it('non-countable value renders empty', async () => {
+    expect(await renderEn('{{count x}}', {
+      x: 5
+    })).toBe('');
+  });
+});
+describe('get helper', () => {
+  it('returns an existing key', async () => {
+    expect(await renderEn('{{get obj "key"}}', {
+      obj: {
+        key: 'val'
+      }
+    })).toBe('val');
+  });
+  it('returns the provided default when missing', async () => {
+    expect(await renderEn('{{get obj "missing" "fallback"}}', {
+      obj: {
+        key: 'val'
+      }
+    })).toBe('fallback');
+  });
+  it('returns empty when missing and no default', async () => {
+    expect(await renderEn('{{get obj "missing"}}', {
+      obj: {
+        key: 'val'
+      }
+    })).toBe('');
+  });
+});
+describe('range helper', () => {
+  it('iterates a numeric range', async () => {
+    expect(await renderEn('{{#range 0 3}}{{this}},{{/range}}', {})).toBe('0,1,2,');
+  });
+});
+describe('escape helper (intentional deviation)', () => {
+  it('does real HTML-escaping, not the legacy bytes-repr quirk', async () => {
+    expect(await renderEn('{{escape s}}', {
+      s: '<b>&'
+    })).toBe('&lt;b&gt;&amp;');
+  });
+});
+describe('date/time helpers', () => {
+  const dt = new Date(Date.UTC(2024, 11, 25, 15, 30));
+  it('date', async () => {
+    expect(await renderEn('{{date d}}', {
+      d: dt
+    })).toBe('Dec 25, 2024');
+  });
+  it('shortdate', async () => {
+    expect(await renderEn('{{shortdate d}}', {
+      d: dt
+    })).toBe('12/25/24');
+  });
+  it('longdate', async () => {
+    expect(await renderEn('{{longdate d}}', {
+      d: dt
+    })).toBe('December 25, 2024');
+  });
+  it('fulldate', async () => {
+    expect(await renderEn('{{fulldate d}}', {
+      d: dt
+    })).toBe('Wednesday, December 25, 2024');
+  });
+  it('time (always Berlin local time)', async () => {
+    // Node/ICU version dependent: this may render with a regular space
+    // or a narrow no-break space (U+202F) before AM/PM depending on runtime
+    // before the AM/PM marker, not a regular space
+    expect(await renderEn('{{time d}}', {
+      d: dt
+    })).toBe('4:30 PM');
+  });
+  it('longdate uses the render language, not the data', async () => {
+    expect(await renderDe('{{longdate d}}', {
+      d: dt
+    })).toBe('25. Dezember 2024');
+  });
+  it('longdateUtc converts to Berlin timezone, which can cross a day boundary', async () => {
+    const lateUtc = new Date(Date.UTC(2024, 11, 25, 23, 30));
+    expect(await renderEn('{{longdateUtc d}}', {
+      d: lateUtc
+    })).toBe('December 26, 2024');
+  });
+});
+describe('before/after/between helpers', () => {
+  it('before is true for a future timestamp', async () => {
+    expect(await renderEn('{{#before d}}FUTURE{{else}}PAST{{/before}}', {
+      d: '31.12.2999 00:00'
+    })).toBe('FUTURE');
+  });
+  it('before is false for a past timestamp', async () => {
+    expect(await renderEn('{{#before d}}FUTURE{{else}}PAST{{/before}}', {
+      d: '01.01.2000 00:00'
+    })).toBe('PAST');
+  });
+  it('between is true when now is inside the range', async () => {
+    const template = '{{#between a b}}INSIDE{{else}}OUTSIDE{{/between}}';
+    expect(await renderEn(template, {
+      a: '01.01.2000 00:00',
+      b: '31.12.2999 00:00'
+    })).toBe('INSIDE');
+  });
+  it('a truthy forced flag always takes the fn branch', async () => {
+    expect(await renderEn('{{#before d true}}FUTURE{{else}}PAST{{/before}}', {
+      d: '01.01.2000 00:00'
+    })).toBe('FUTURE');
+  });
+});
+describe('partial resolution', () => {
+  it('resolves a referenced partial through resolvePartial, recursively', async () => {
+    const html = await renderHandlebars('{{> footer}}', {}, {
+      ...baseOptions,
+      lang: 'en',
+      languages: ['en'],
+      resolvePartial: async name => name === 'footer' ? 'FOOTER-{{x}}' : 'Template not found'
+    });
+    expect(html).toBe('FOOTER-');
+  });
+  it('an unresolvable partial renders as a literal placeholder, matching get_template()', async () => {
+    const html = await renderHandlebars('{{> does_not_exist}}', {}, {
+      ...baseOptions,
+      lang: 'en',
+      languages: ['en'],
+      resolvePartial: async () => {
+        throw new Error('not found');
+      }
+    });
+    expect(html).toBe('Template not found');
+  });
+});
+describe('link helpers', () => {
+  it('unsubscribe_link embeds the attendee id and email name in a signed token', async () => {
+    const html = await renderEn('{{unsubscribe_link "a@b.com"}}', {});
+    expect(html.startsWith('https://test.frontend.example/unsubscribe?token=')).toBe(true);
+  });
+  it('link builds a tracked link when tracking is enabled', async () => {
+    const html = await renderEn('{{link "/home"}}', {});
+    expect(html.startsWith('https://test.frontend.example/link/')).toBe(true);
+  });
+  it('link returns the raw url when tracking is disabled', async () => {
+    const html = await renderHandlebars('{{link "/home"}}', {}, {
+      ...baseOptions,
+      lang: 'en',
+      languages: ['en'],
+      linkContext: {
+        ...baseOptions.linkContext,
+        trackingEnabled: false
+      }
+    });
+    expect(html).toBe('https://test.frontend.example/home');
+  });
+});

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

@@ -0,0 +1,46 @@
+import { TokenOptions } from './tokens';
+/**
+ * Mirrors the link-building methods on FrontendConfig
+ * (common/models/frontend_config.py) on the backend, using the same
+ * shared FRONTEND_JWT_SECRET. These exist so a headless email's
+ * Handlebars-typed content can build tracking/unsubscribe/registration/
+ * wallet/QR links locally, without a backend round trip per link --
+ * tracking links in particular are template-dependent (an author can
+ * wrap an arbitrary one-off URL anywhere in a block), so the set of
+ * links needing signing can't be enumerated ahead of render time.
+ */
+export type LinkBuilderOptions = TokenOptions & {
+    domain: string;
+};
+export declare function makeTrackingLink(options: LinkBuilderOptions, args: {
+    attendeeId: string;
+    emailName: string;
+    mailingId?: string | null;
+    urlLink: string;
+    trackingEnabled: boolean;
+}): string;
+export declare function makeUnsubscribeLink(options: LinkBuilderOptions, args: {
+    attendeeId: string;
+    emailName: string;
+    emailAddress: string;
+}): string;
+export declare function makeRegistrationLink(options: LinkBuilderOptions, args: {
+    attendeeId: string;
+    sessionType?: string;
+    flags?: Record<string, unknown>;
+    expiresInSeconds?: number;
+    email?: {
+        name: string;
+        mailingId: string;
+    };
+}): string;
+export declare function makeWalletLink(options: LinkBuilderOptions, attendeeId: string): string;
+export declare function makeGoogleWalletLink(options: LinkBuilderOptions, attendeeId: string): string;
+export declare function makeQrCodeLink(options: LinkBuilderOptions, args: {
+    content: string;
+    size?: number;
+    background?: string;
+    body?: string;
+    corners?: string;
+    fancy?: 0 | 1;
+}): string;

package/dist/lib/email-links.js

@@ -0,0 +1,68 @@
+import { encodeJWS } from './tokens';
+
+/**
+ * Mirrors the link-building methods on FrontendConfig
+ * (common/models/frontend_config.py) on the backend, using the same
+ * shared FRONTEND_JWT_SECRET. These exist so a headless email's
+ * Handlebars-typed content can build tracking/unsubscribe/registration/
+ * wallet/QR links locally, without a backend round trip per link --
+ * tracking links in particular are template-dependent (an author can
+ * wrap an arbitrary one-off URL anywhere in a block), so the set of
+ * links needing signing can't be enumerated ahead of render time.
+ */
+
+export function makeTrackingLink(options, args) {
+  const target = new URL(args.urlLink, `https://${options.domain}`).toString();
+  if (!args.trackingEnabled) return target;
+  const token = encodeJWS({
+    instance_name: options.instanceName,
+    attendee_id: args.attendeeId,
+    target,
+    email_name: args.emailName,
+    mailing_id: args.mailingId ?? null
+  }, options.jwtSecret);
+  return `https://${options.domain}/link/${token}`;
+}
+export function makeUnsubscribeLink(options, args) {
+  const token = encodeJWS({
+    instance_name: options.instanceName,
+    attendee_id: args.attendeeId,
+    email_address: args.emailAddress,
+    email_name: args.emailName
+  }, options.jwtSecret);
+  return `https://${options.domain}/unsubscribe?token=${token}`;
+}
+const REGISTRATION_TOKEN_DEFAULT_EXPIRY_SECONDS = 15 * 24 * 60 * 60;
+export function makeRegistrationLink(options, args) {
+  const payload = {
+    attendee_id: args.attendeeId,
+    instance_name: options.instanceName,
+    session_type: args.sessionType ?? 'register',
+    flags: args.flags ?? {}
+  };
+  if (args.email) {
+    payload.email = {
+      name: args.email.name,
+      mailing_id: args.email.mailingId
+    };
+  }
+  const token = encodeJWS(payload, options.jwtSecret, args.expiresInSeconds ?? REGISTRATION_TOKEN_DEFAULT_EXPIRY_SECONDS);
+  return `https://${options.domain}/register/${token}`;
+}
+export function makeWalletLink(options, attendeeId) {
+  return `https://${options.domain}/wallet/${attendeeId}`;
+}
+export function makeGoogleWalletLink(options, attendeeId) {
+  return `https://${options.domain}/google-wallet/${attendeeId}`;
+}
+export function makeQrCodeLink(options, args) {
+  const params = new URLSearchParams({
+    content: args.content,
+    size: String(args.size ?? 600),
+    background: args.background ?? 'white',
+    body: args.body ?? 'black',
+    corners: args.corners ?? 'black',
+    fancy: String(args.fancy ?? 0)
+  });
+  return `https://${options.domain}/qr/?${params.toString()}`;
+}