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

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

@@ -0,0 +1,31 @@
+import { LinkBuilderOptions } from './email-links';
+/**
+ * A from-scratch TS port of the pybars helper set registered in
+ * app/templates.py (enter-core) -- the "mechanical, data-only" ones the
+ * plan calls out for reuse, plus the link builders (wired to the shared
+ * TS builders in email-links.ts instead of a backend round trip, since
+ * 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).
+ *
+ * Each helper's behaviour is checked against a characterization test of
+ * the *actual* pybars implementation in
+ * enter-core/tests/unittests/app/render_templates_test.py -- see
+ * email-handlebars.test.ts for the mirrored cases, including two
+ * intentional divergences documented inline below (`escape`, `if`'s `!=`).
+ */
+export type EmailLinkContext = {
+    attendeeId: string;
+    emailName: string;
+    mailingId?: string;
+    trackingEnabled: boolean;
+};
+export type PartialResolver = (name: string) => Promise<string>;
+export type RenderHandlebarsOptions = {
+    lang: string;
+    languages: string[];
+    linkOptions: LinkBuilderOptions;
+    linkContext: EmailLinkContext;
+    resolvePartial: PartialResolver;
+};
+export declare function renderHandlebars(source: string, data: Record<string, unknown>, options: RenderHandlebarsOptions): Promise<string>;

package/dist/lib/email-handlebars.js

@@ -0,0 +1,436 @@
+import Handlebars from 'handlebars';
+import { makeGoogleWalletLink, makeQrCodeLink, makeRegistrationLink, makeTrackingLink, makeUnsubscribeLink, makeWalletLink } from './email-links';
+
+/**
+ * A from-scratch TS port of the pybars helper set registered in
+ * app/templates.py (enter-core) -- the "mechanical, data-only" ones the
+ * plan calls out for reuse, plus the link builders (wired to the shared
+ * TS builders in email-links.ts instead of a backend round trip, since
+ * 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).
+ *
+ * Each helper's behaviour is checked against a characterization test of
+ * the *actual* pybars implementation in
+ * enter-core/tests/unittests/app/render_templates_test.py -- see
+ * email-handlebars.test.ts for the mirrored cases, including two
+ * intentional divergences documented inline below (`escape`, `if`'s `!=`).
+ */
+
+function translate(item, lang) {
+  if (typeof item === 'string') return item;
+  if (item && typeof item === 'object' && !Array.isArray(item)) {
+    return item[lang];
+  }
+  return item;
+}
+function stringifyTranslated(item, lang) {
+  const value = translate(item, lang);
+  return value == null ? '' : String(value);
+}
+function helperArgs(args) {
+  return {
+    options: args[args.length - 1],
+    explicit: args.slice(0, -1)
+  };
+}
+function compareValues(op, left, right) {
+  try {
+    switch (op) {
+      case '==':
+        return left === right;
+      // mirrors a bug in the legacy pybars `if` helper where != behaves
+      // exactly like == -- documented, not "fixed", so templates ported
+      // from the legacy renderer keep behaving the same way here
+      case '!=':
+        return left === right;
+      case '>':
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return left > right;
+      case '<':
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return left < right;
+      case '>=':
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return left >= right;
+      case '<=':
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return left <= right;
+      case 'in':
+        if (typeof right === 'string' || Array.isArray(right)) {
+          return right.includes(left);
+        }
+        return false;
+      default:
+        return false;
+    }
+  } catch {
+    return false;
+  }
+}
+function decimalPlaces(value) {
+  const s = String(value);
+  return s.includes('.') ? s.split('.')[1].length : 0;
+}
+function roundHalfToEven(value, decimals) {
+  const factor = 10 ** decimals;
+  const scaled = value * factor;
+  if (Math.abs(scaled - Math.trunc(scaled) - 0.5) < 1e-9) {
+    const floor = Math.floor(scaled);
+    return (floor % 2 === 0 ? floor : floor + 1) / factor;
+  }
+  return Math.round(scaled) / factor;
+}
+function formatCalcResult(value) {
+  // Python's round() always returns a float, and str(float) always shows
+  // at least one decimal digit (2.0, not 2) -- JS's default number ->
+  // string conversion drops it, so whole numbers need it added back.
+  return Number.isInteger(value) ? `${value}.0` : String(value);
+}
+function parseDayFirst(value) {
+  if (value instanceof Date) return value;
+  const s = String(value);
+  // "DD.MM.YYYY HH:mm" -- the format legacy templates author literal
+  // comparison timestamps in; anything else is handed to Date() as-is
+  // (covers ISO strings, which is what real attendee/event data uses).
+  const match = /^(\d{1,2})\.(\d{1,2})\.(\d{4})(?:\s+(\d{1,2}):(\d{2}))?/.exec(s);
+  if (match) {
+    const [, day, month, year, hour, minute] = match;
+    return new Date(Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour ?? 0), Number(minute ?? 0)));
+  }
+  return new Date(s);
+}
+function sizeofFmt(value) {
+  let num = Number(value);
+  if (!Number.isFinite(num)) num = 0;
+  if (num < 1024) return `${Math.trunc(num)} B`;
+  for (const unit of ['KB', 'MB', 'GB']) {
+    num /= 1024;
+    if (Math.abs(num) < 100) return `${num.toFixed(1)} ${unit}`;
+    if (Math.abs(num) < 1024) return `${Math.trunc(num)} ${unit}`;
+  }
+  return `${num.toFixed(1)} TB`;
+}
+function registerDataHelpers(hb, lang, languages) {
+  hb.registerHelper('_', function (value, ...rest) {
+    const explicit = rest.slice(0, -1);
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const key = explicit.length > 0 ? String(explicit[0]) : lang;
+      return value[key];
+    }
+    return value;
+  });
+  hb.registerHelper('upper', function (value, ...rest) {
+    const explicit = rest.slice(0, -1);
+    const key = explicit.length > 0 ? String(explicit[0]) : lang;
+    const translated = value && typeof value === 'object' && !Array.isArray(value) ? value[key] : value;
+    return translated == null ? '' : String(translated).toUpperCase();
+  });
+  hb.registerHelper('lower', function (value, ...rest) {
+    const explicit = rest.slice(0, -1);
+    const key = explicit.length > 0 ? String(explicit[0]) : lang;
+    const translated = value && typeof value === 'object' && !Array.isArray(value) ? value[key] : value;
+    return translated == null ? '' : String(translated).toLowerCase();
+  });
+  for (const targetLang of languages) {
+    hb.registerHelper(targetLang, function (...args) {
+      const {
+        options,
+        explicit
+      } = helperArgs(args);
+      const matches = targetLang === lang;
+      if (typeof options.fn === 'function') {
+        return matches ? options.fn(this) : options.inverse(this);
+      }
+      if (!matches) return undefined;
+      return explicit.map(a => stringifyTranslated(a, lang)).join('');
+    });
+  }
+  hb.registerHelper('eq', function (...args) {
+    const {
+      options,
+      explicit
+    } = helperArgs(args);
+    if (explicit.length >= 2) {
+      const left = translate(explicit[0], lang);
+      for (const arg of explicit.slice(1)) {
+        if (left === translate(arg, lang)) return options.fn(this);
+      }
+    }
+    return options.inverse(this);
+  });
+  hb.registerHelper('if', function (...args) {
+    const {
+      options,
+      explicit
+    } = helperArgs(args);
+    if (explicit.length >= 3) {
+      const operator = String(explicit[1]);
+      const left = translate(explicit[0], lang);
+      for (const arg of explicit.slice(2)) {
+        if (compareValues(operator, left, translate(arg, lang))) return options.fn(this);
+      }
+    } else if (explicit.length === 1) {
+      if (explicit[0]) return options.fn(this);
+    }
+    return options.inverse(this);
+  });
+  hb.registerHelper('if_in', function (...args) {
+    const {
+      options,
+      explicit
+    } = helperArgs(args);
+    const haystack = explicit[0];
+    if (explicit.length >= 2 && (Array.isArray(haystack) || typeof haystack === 'string')) {
+      for (const arg of explicit.slice(1)) {
+        const needle = translate(arg, lang);
+        if (haystack.includes(needle)) return options.fn(this);
+      }
+    }
+    return options.inverse(this);
+  });
+  hb.registerHelper('join', function (...args) {
+    const {
+      explicit
+    } = helperArgs(args);
+    const list = explicit[0];
+    if (!Array.isArray(list)) return '';
+    if (explicit.length === 2) {
+      return list.join(stringifyTranslated(explicit[1], lang));
+    }
+    if (explicit.length === 3 && list.length) {
+      if (list.length === 1) return list[0];
+      const joiner = stringifyTranslated(explicit[1], lang);
+      return list.slice(0, -1).join(joiner) + String(explicit[2]) + list[list.length - 1];
+    }
+    return '';
+  });
+  hb.registerHelper('calc', function (...args) {
+    const {
+      explicit
+    } = helperArgs(args);
+    if (explicit.length !== 3) return '';
+    const a = Number(explicit[0]);
+    const b = Number(explicit[2]);
+    if (Number.isNaN(a) || Number.isNaN(b)) return '';
+    const maxDecimals = Math.max(decimalPlaces(explicit[0]), decimalPlaces(explicit[2]));
+    let result = null;
+    switch (explicit[1]) {
+      case '+':
+        result = a + b;
+        break;
+      case '-':
+        result = a - b;
+        break;
+      case '*':
+        result = a * b;
+        break;
+      case '/':
+        result = a / b;
+        break;
+    }
+    if (result === null) return '';
+    return formatCalcResult(roundHalfToEven(result, maxDecimals));
+  });
+  hb.registerHelper('count', function (value) {
+    if (Array.isArray(value) || typeof value === 'string') return value.length;
+    if (value && typeof value === 'object') return Object.keys(value).length;
+    return '';
+  });
+  hb.registerHelper('get', function (...args) {
+    const {
+      options,
+      explicit
+    } = helperArgs(args);
+    const obj = explicit[0];
+    const key = explicit[1];
+    const value = obj != null ? obj[key] : undefined;
+    const fallback = explicit.length > 2 ? explicit[2] : '';
+    if (typeof options.fn === 'function') {
+      return options.fn(value !== undefined ? value : fallback);
+    }
+    return value !== undefined ? value : fallback;
+  });
+  hb.registerHelper('range', function (...args) {
+    const {
+      options,
+      explicit
+    } = helperArgs(args);
+    const nums = explicit.map(Number);
+    const [start, stop, step] = nums.length === 1 ? [0, nums[0], 1] : nums.length === 2 ? [nums[0], nums[1], 1] : nums;
+    let result = '';
+    for (let x = start; step > 0 ? x < stop : x > stop; x += step) {
+      result += options.fn(x);
+    }
+    return result;
+  });
+  hb.registerHelper('size', function (value) {
+    return sizeofFmt(value);
+  });
+  hb.registerHelper('escape', function (value) {
+    // Deliberate deviation from the legacy pybars `escape` helper, which
+    // returns str(x).encode(...) -- a bytes object -- and ends up
+    // rendering its own Python repr (e.g. "b'&lt;b&gt;'") once pybars
+    // stringifies it. That's almost certainly an unintentional bug no
+    // template actually relies on; this does the HTML-escaping the
+    // helper's name promises instead of reproducing the bug.
+    return new Handlebars.SafeString(Handlebars.escapeExpression(String(value ?? '')));
+  });
+  function dateComparisonHelper(mode) {
+    return function (...args) {
+      const {
+        options,
+        explicit
+      } = helperArgs(args);
+      const forcedIndex = mode === 'between' ? 2 : 1;
+      if (explicit.length > forcedIndex && explicit[forcedIndex]) return options.fn(this);
+      if (mode === 'between') {
+        if (explicit.length < 2) return options.inverse(this);
+        const a = parseDayFirst(explicit[0]).getTime();
+        const b = parseDayFirst(explicit[1]).getTime();
+        const now = Date.now();
+        const inside = a < now && now < b || b < now && now < a;
+        return inside ? options.fn(this) : options.inverse(this);
+      }
+      if (explicit.length === 0) return options.inverse(this);
+      const timestamp = parseDayFirst(explicit[0]).getTime();
+      const now = Date.now();
+      const passed = mode === 'before' ? now < timestamp : now > timestamp;
+      return passed ? options.fn(this) : options.inverse(this);
+    };
+  }
+  hb.registerHelper('before', dateComparisonHelper('before'));
+  hb.registerHelper('after', dateComparisonHelper('after'));
+  hb.registerHelper('between', dateComparisonHelper('between'));
+}
+function registerDateHelpers(hb, lang) {
+  const dateFormat = (style, timeZone = 'UTC') => function (value) {
+    const date = value instanceof Date ? value : new Date(String(value));
+    return new Intl.DateTimeFormat(lang, {
+      dateStyle: style,
+      timeZone
+    }).format(date);
+  };
+  hb.registerHelper('shortdate', dateFormat('short'));
+  hb.registerHelper('date', dateFormat('medium'));
+  hb.registerHelper('longdate', dateFormat('long'));
+  hb.registerHelper('fulldate', dateFormat('full'));
+  hb.registerHelper('time', function (value) {
+    const date = value instanceof Date ? value : new Date(String(value));
+    return new Intl.DateTimeFormat(lang, {
+      timeStyle: 'short',
+      timeZone: 'Europe/Berlin'
+    }).format(date);
+  });
+  hb.registerHelper('longdateUtc', function (value) {
+    const date = value instanceof Date ? value : new Date(String(value));
+    return new Intl.DateTimeFormat(lang, {
+      dateStyle: 'long',
+      timeZone: 'Europe/Berlin'
+    }).format(date);
+  });
+}
+
+// Handlebars.js HTML-escapes every helper return value by default (e.g. "="
+// becomes "&#x3D;"), which corrupts any URL with a query string --
+// "?token=..." becomes "?token&#x3D;...". pybars does not do this to
+// helper-produced strings, so every link helper below needs to opt out via
+// SafeString to match legacy template behaviour (confirmed against a real
+// pybars render in enter-core/tests/unittests/app/render_templates_test.py).
+function safe(value) {
+  return new Handlebars.SafeString(value);
+}
+function registerLinkHelpers(hb, linkOptions, ctx) {
+  hb.registerHelper('link', function (path) {
+    return safe(makeTrackingLink(linkOptions, {
+      attendeeId: ctx.attendeeId,
+      emailName: ctx.emailName,
+      mailingId: ctx.mailingId,
+      urlLink: path,
+      trackingEnabled: ctx.trackingEnabled
+    }));
+  });
+  hb.registerHelper('unsubscribe_link', function (emailAddress) {
+    return safe(makeUnsubscribeLink(linkOptions, {
+      attendeeId: ctx.attendeeId,
+      emailName: ctx.emailName,
+      emailAddress
+    }));
+  });
+  hb.registerHelper('registration_link', function (...args) {
+    const {
+      explicit
+    } = helperArgs(args);
+    const id = explicit[0] ?? ctx.attendeeId;
+    const sessionType = explicit[1] ?? 'register';
+    const daysValid = explicit[2] != null ? Number(explicit[2]) : 15;
+    return safe(makeRegistrationLink(linkOptions, {
+      attendeeId: id,
+      sessionType,
+      expiresInSeconds: daysValid * 24 * 60 * 60,
+      email: ctx.mailingId ? {
+        name: ctx.emailName,
+        mailingId: ctx.mailingId
+      } : undefined
+    }));
+  });
+  hb.registerHelper('wallet_link', function (id) {
+    const link = makeWalletLink(linkOptions, id ?? ctx.attendeeId);
+    // mirrors the legacy helper: the wallet link itself is wrapped in a
+    // tracked link, unlike google_wallet_link below
+    return safe(makeTrackingLink(linkOptions, {
+      attendeeId: ctx.attendeeId,
+      emailName: ctx.emailName,
+      mailingId: ctx.mailingId,
+      urlLink: link,
+      trackingEnabled: ctx.trackingEnabled
+    }));
+  });
+  hb.registerHelper('google_wallet_link', function (id) {
+    return safe(makeGoogleWalletLink(linkOptions, id ?? ctx.attendeeId));
+  });
+  hb.registerHelper('qr_code_link', function (...args) {
+    const {
+      explicit
+    } = helperArgs(args);
+    return safe(makeQrCodeLink(linkOptions, {
+      content: String(explicit[0]),
+      size: explicit[1] != null ? Number(explicit[1]) : undefined,
+      background: explicit[2],
+      body: explicit[3],
+      corners: explicit[4],
+      fancy: explicit[5] != null ? Number(explicit[5]) : undefined
+    }));
+  });
+}
+const PARTIAL_REFERENCE_PATTERN = /\{\{>\s*([a-zA-Z0-9_-]+)/g;
+const MAX_PARTIAL_DEPTH = 10;
+function extractPartialNames(source) {
+  return [...source.matchAll(PARTIAL_REFERENCE_PATTERN)].map(m => m[1]);
+}
+async function resolvePartialsRecursively(hb, source, resolvePartial, seen, depth) {
+  if (depth > MAX_PARTIAL_DEPTH) return;
+  for (const name of extractPartialNames(source)) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    let partialSource;
+    try {
+      partialSource = await resolvePartial(name);
+    } catch {
+      // mirrors get_template()'s behaviour of never raising -- an
+      // unresolvable partial silently becomes a literal placeholder
+      partialSource = 'Template not found';
+    }
+    hb.registerPartial(name, partialSource);
+    await resolvePartialsRecursively(hb, partialSource, resolvePartial, seen, depth + 1);
+  }
+}
+export async function renderHandlebars(source, data, options) {
+  const hb = Handlebars.create();
+  registerDataHelpers(hb, options.lang, options.languages);
+  registerDateHelpers(hb, options.lang);
+  registerLinkHelpers(hb, options.linkOptions, options.linkContext);
+  await resolvePartialsRecursively(hb, source, options.resolvePartial, new Set(), 0);
+  const template = hb.compile(source);
+  return template(data);
+}