vintasend-liquidjs 0.0.0-stage → 1.0.0-alpha5

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# vintasend-liquidjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[LiquidJS](https://liquidjs.com/) email and SMS template renderers for VintaSend.
+
+Liquid templates cannot run arbitrary code, which makes them a good fit for templates edited
+outside the codebase, such as [managed templates](https://github.com/vintasoftware/vintasend-ts#managed-templates)
+stored in a database.
+
+## Installation
+
+```bash
+npm install vintasend-liquidjs
+```
+
+## Exports
+
+- `LiquidEmailTemplateRenderer` / `LiquidEmailTemplateRendererFactory`: renders template files.
+- `LiquidInlineEmailTemplateRenderer` / `LiquidInlineEmailTemplateRendererFactory`: renders
+  templates from an in-memory map.
+- `LiquidSmsTemplateRenderer` / `LiquidSmsTemplateRendererFactory`: renders plain-text SMS
+  messages, from files or an in-memory map.
+- `LiquidTemplateRendererOptions`: the renderer options (every `LiquidOptions` field plus
+  `configureEngine`).
+
+## Rendering template files
+
+`notification.bodyTemplate` and `notification.subjectTemplate` are paths that Liquid resolves
+against `root`. Lookups that leave the roots fail, so a template key cannot read an arbitrary file.
+
+```
+templates/
+  emails/
+    welcome.liquid
+    welcome-subject.liquid
+  partials/
+    footer.liquid
+```
+
+```liquid
+{%- comment -%} templates/emails/welcome.liquid {%- endcomment -%}
+<h1>Hello {{ firstName }}!</h1>
+<p>Your appointment is on {{ appointmentDate | date: "%B %-d, %Y" }}.</p>
+{% include "partials/footer.liquid" %}
+```
+
+```liquid
+{%- comment -%} templates/emails/welcome-subject.liquid {%- endcomment -%}
+Welcome, {{ firstName }}
+```
+
+```typescript
+import { LiquidEmailTemplateRendererFactory } from 'vintasend-liquidjs';
+
+const templateRenderer = new LiquidEmailTemplateRendererFactory<NotificationTypeConfig>().create({
+  root: './templates',
+});
+
+// Then create the notification with
+//   bodyTemplate: 'emails/welcome.liquid',
+//   subjectTemplate: 'emails/welcome-subject.liquid',
+```
+
+Any [LiquidJS option](https://liquidjs.com/tutorials/options.html) can be passed: `root`,
+`partials`, `layouts`, `extname`, `cache`, `strictVariables`, `strictFilters`, `globals`, and so
+on.
+
+### Escaping
+
+The **body** is rendered with `outputEscape: 'escape'`, so every `{{ value }}` is HTML-escaped and
+context values cannot inject markup into the email. Mark a value as trusted HTML with the `raw`
+filter: `{{ trustedHtml | raw }}`. To change this, pass your own `outputEscape`.
+
+The **subject** is plain text and is never escaped. Its whitespace, including the trailing newline
+most editors add to a template file and any line breaks coming from context values, is collapsed to
+single spaces.
+
+### Custom filters and tags
+
+The renderer creates one Liquid engine for the body and one for the subject. Register filters,
+tags or plugins on both with `configureEngine`:
+
+```typescript
+const templateRenderer = new LiquidEmailTemplateRendererFactory<NotificationTypeConfig>().create({
+  root: './templates',
+  configureEngine: (engine) => {
+    engine.registerFilter('initials', (name: string) =>
+      name.split(' ').map((part) => part[0]).join(''),
+    );
+  },
+});
+```
+
+### Untrusted templates
+
+When templates come from users rather than from your repository, set LiquidJS's
+[DoS limits](https://liquidjs.com/tutorials/dos.html) (`parseLimit`, `renderLimit`,
+`memoryLimit`) and consider `strictFilters`, so a template cannot run expensive loops.
+
+## Rendering templates from memory
+
+For environments that can only deploy a single bundle (for example Medplum bots), use the inline
+renderer with a map of template key to template source. `include`, `render` and `layout` resolve
+against the same map.
+
+```typescript
+import { LiquidInlineEmailTemplateRendererFactory } from 'vintasend-liquidjs';
+import templates from './compiled-templates.json';
+
+const templateRenderer = new LiquidInlineEmailTemplateRendererFactory<NotificationTypeConfig>().create(
+  templates,
+  { strictVariables: true },
+);
+```
+
+Rendering a key that is not in the map throws `Body template "<key>" not found in templates` (or
+the subject equivalent).
+
+### Template compilation script
+
+The `compile-liquid-templates` CLI writes every `.liquid` file in a directory to a JSON map keyed
+by POSIX relative path (`emails/welcome.liquid`), which is what the inline renderer expects:
+
+```bash
+compile-liquid-templates [input-directory] [output-file]
+```
+
+`input-directory` defaults to `./templates` and `output-file` to `compiled-templates.json`.
+
+```json
+{
+  "scripts": {
+    "compile-templates": "compile-liquid-templates ./templates ./src/compiled-templates.json"
+  }
+}
+```
+
+## Rendering SMS
+
+`LiquidSmsTemplateRenderer` works with SMS adapters such as
+[vintasend-ts-twilio](https://github.com/vintasoftware/vintasend-ts-twilio), which send the rendered
+`body`. Compared with the email renderers:
+
+- Output is **not** HTML-escaped, because an SMS is plain text: `Tom & Jerry` arrives as written.
+- The subject template is optional. Without one, `subject` is an empty string.
+- Leading and trailing whitespace is trimmed from the body, including the trailing newline of a
+  template file. Line breaks inside the message are kept.
+
+```liquid
+{%- comment -%} templates/sms/reminder.liquid {%- endcomment -%}
+Hi {{ firstName }}, your appointment is on {{ appointmentDate | date: "%b %-d" }}.
+Reply STOP to opt out.
+```
+
+```typescript
+import { TwilioSmsAdapterFactory } from 'vintasend-ts-twilio';
+import { LiquidSmsTemplateRendererFactory } from 'vintasend-liquidjs';
+
+const smsRenderer = new LiquidSmsTemplateRendererFactory<NotificationTypeConfig>().create({
+  root: './templates',
+});
+const smsAdapter = new TwilioSmsAdapterFactory<NotificationTypeConfig>().create(
+  smsRenderer,
+  false,
+  twilioConfig,
+);
+
+// Then create the notification with
+//   bodyTemplate: 'sms/reminder.liquid',
+//   subjectTemplate: null,
+```
+
+For templates held in memory (Medplum bots), pass the map as the `templates` option. Keys missing
+from the map fail with the same `not found in templates` error as the inline email renderer:
+
+```typescript
+import templates from './compiled-templates.json';
+
+const smsRenderer = new LiquidSmsTemplateRendererFactory<NotificationTypeConfig>().create({
+  templates,
+});
+```
+
+## Rendering stored template content
+
+Every renderer implements `renderFromTemplateContent`, which renders `{ subject, body }` strings
+directly. This is what `vintasend-managed-templates` calls, so any of them can render managed
+templates (the SMS renderer accepts a `null` subject). Includes in that content resolve against
+`root` or the template map.
+
+## Logging
+
+With a logger injected, the renderers log the notification id, the template key and, on failure,
+the error's name. They never log the context, the rendered output or the error message. LiquidJS
+errors quote the template source around the failure, and errors thrown by filters can quote
+context values.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run lint
+```

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { LiquidOptions } from 'liquidjs';
+export type { LiquidTemplateRendererOptions } from './liquid-email-template-renderer.js';
+export { LiquidEmailTemplateRenderer, LiquidEmailTemplateRendererFactory, } from './liquid-email-template-renderer.js';
+export { LiquidInlineEmailTemplateRenderer, LiquidInlineEmailTemplateRendererFactory, } from './liquid-inline-email-template-renderer.js';
+export { LiquidSmsTemplateRenderer, LiquidSmsTemplateRendererFactory, } from './liquid-sms-template-renderer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EAAE,6BAA6B,EAAE,MAAM,qCAAqC,CAAC;AACzF,OAAO,EACL,2BAA2B,EAC3B,kCAAkC,GACnC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,iCAAiC,EACjC,wCAAwC,GACzC,MAAM,4CAA4C,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,gCAAgC,GACjC,MAAM,mCAAmC,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { LiquidEmailTemplateRenderer, LiquidEmailTemplateRendererFactory, } from './liquid-email-template-renderer.js';
+export { LiquidInlineEmailTemplateRenderer, LiquidInlineEmailTemplateRendererFactory, } from './liquid-inline-email-template-renderer.js';
+export { LiquidSmsTemplateRenderer, LiquidSmsTemplateRendererFactory, } from './liquid-sms-template-renderer.js';

package/dist/liquid-email-template-renderer.d.ts

@@ -0,0 +1,51 @@
+import { Liquid, type LiquidOptions } from 'liquidjs';
+import type { AnyNotification, BaseEmailTemplateRenderer, BaseLogger, BaseNotificationTypeConfig, EmailTemplate, EmailTemplateContent, JsonObject } from 'vintasend';
+export type LiquidTemplateRendererOptions = LiquidOptions & {
+    /**
+     * Called once for each Liquid engine the renderer creates (body and subject), to register custom
+     * filters, tags or plugins.
+     */
+    configureEngine?: (engine: Liquid) => void;
+};
+/**
+ * Renders email notifications from Liquid template files.
+ *
+ * `notification.bodyTemplate` and `notification.subjectTemplate` are template paths resolved by
+ * Liquid against `options.root` (the working directory when unset). Liquid refuses lookups that
+ * escape the roots, so a template key can never read an arbitrary file. With `options.templates`
+ * they are keys into that map instead, and a key missing from it is rejected before rendering.
+ *
+ * The body is rendered with `outputEscape: 'escape'` unless `options.outputEscape` says otherwise,
+ * so context values cannot inject markup into an HTML email; use `{{ value | raw }}` for values
+ * that are trusted HTML. The subject is plain text and is never escaped; its whitespace, including
+ * the trailing newline of a template file, is collapsed to single spaces.
+ */
+export declare class LiquidEmailTemplateRenderer<Config extends BaseNotificationTypeConfig> implements BaseEmailTemplateRenderer<Config> {
+    protected readonly options: LiquidTemplateRendererOptions;
+    logger: BaseLogger | null;
+    protected readonly rendererName: string;
+    /** What this renderer produces, for log lines. */
+    protected readonly templateKind: string;
+    protected readonly subjectRequired: boolean;
+    private readonly bodyEngine;
+    private readonly subjectEngine;
+    constructor(options?: LiquidTemplateRendererOptions);
+    /**
+     * Inject logger (called by VintaSend when logger exists)
+     */
+    injectLogger(logger: BaseLogger): void;
+    render(notification: AnyNotification<Config>, context: JsonObject): Promise<EmailTemplate>;
+    renderFromTemplateContent(notification: AnyNotification<Config>, templateContent: EmailTemplateContent, context: JsonObject): Promise<EmailTemplate>;
+    protected normalizeBody(body: string): string;
+    private assertTemplateExists;
+    /**
+     * Runs one render, logging a failure by template key and error name only: Liquid's errors quote
+     * the template source around the failure, and an error thrown by a filter keeps its message,
+     * which can include context values.
+     */
+    private renderPart;
+}
+export declare class LiquidEmailTemplateRendererFactory<Config extends BaseNotificationTypeConfig> {
+    create(options?: LiquidTemplateRendererOptions): LiquidEmailTemplateRenderer<Config>;
+}
+//# sourceMappingURL=liquid-email-template-renderer.d.ts.map

package/dist/liquid-email-template-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquid-email-template-renderer.d.ts","sourceRoot":"","sources":["../src/liquid-email-template-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,KAAK,EACV,eAAe,EACf,yBAAyB,EACzB,UAAU,EACV,0BAA0B,EAC1B,aAAa,EACb,oBAAoB,EACpB,UAAU,EACX,MAAM,WAAW,CAAC;AAKnB,MAAM,MAAM,6BAA6B,GAAG,aAAa,GAAG;IAC1D;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,qBAAa,2BAA2B,CAAC,MAAM,SAAS,0BAA0B,CAChF,YAAW,yBAAyB,CAAC,MAAM,CAAC;IAUhC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,6BAA6B;IARrE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAQ;IACjC,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAiC;IACxE,kDAAkD;IAClD,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAW;IAClD,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAQ;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAER,OAAO,GAAE,6BAAkC;IAQ1E;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAIhC,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IA6B1F,yBAAyB,CAC7B,YAAY,EAAE,eAAe,CAAC,MAAM,CAAC,EACrC,eAAe,EAAE,oBAAoB,EACrC,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,aAAa,CAAC;IAsBzB,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI7C,OAAO,CAAC,oBAAoB;IAO5B;;;;OAIG;YACW,UAAU;CAiBzB;AAMD,qBAAa,kCAAkC,CAAC,MAAM,SAAS,0BAA0B;IACvF,MAAM,CAAC,OAAO,GAAE,6BAAkC,GAAG,2BAA2B,CAAC,MAAM,CAAC;CAGzF"}

package/dist/liquid-email-template-renderer.js

@@ -0,0 +1,100 @@
+import { Liquid } from 'liquidjs';
+import { log, logError, logId, logLabel } from 'vintasend';
+/**
+ * Renders email notifications from Liquid template files.
+ *
+ * `notification.bodyTemplate` and `notification.subjectTemplate` are template paths resolved by
+ * Liquid against `options.root` (the working directory when unset). Liquid refuses lookups that
+ * escape the roots, so a template key can never read an arbitrary file. With `options.templates`
+ * they are keys into that map instead, and a key missing from it is rejected before rendering.
+ *
+ * The body is rendered with `outputEscape: 'escape'` unless `options.outputEscape` says otherwise,
+ * so context values cannot inject markup into an HTML email; use `{{ value | raw }}` for values
+ * that are trusted HTML. The subject is plain text and is never escaped; its whitespace, including
+ * the trailing newline of a template file, is collapsed to single spaces.
+ */
+export class LiquidEmailTemplateRenderer {
+    constructor(options = {}) {
+        this.options = options;
+        this.logger = null;
+        this.rendererName = 'LiquidEmailTemplateRenderer';
+        /** What this renderer produces, for log lines. */
+        this.templateKind = 'email';
+        this.subjectRequired = true;
+        const { configureEngine, ...liquidOptions } = options;
+        this.bodyEngine = new Liquid({ outputEscape: 'escape', ...liquidOptions });
+        this.subjectEngine = new Liquid({ ...liquidOptions, outputEscape: undefined });
+        configureEngine?.(this.bodyEngine);
+        configureEngine?.(this.subjectEngine);
+    }
+    /**
+     * Inject logger (called by VintaSend when logger exists)
+     */
+    injectLogger(logger) {
+        this.logger = logger;
+    }
+    async render(notification, context) {
+        const { bodyTemplate, subjectTemplate } = notification;
+        if (!bodyTemplate) {
+            throw new Error('Body template is required');
+        }
+        if (!subjectTemplate && this.subjectRequired) {
+            throw new Error('Subject template is required');
+        }
+        this.assertTemplateExists('Body', bodyTemplate);
+        if (subjectTemplate) {
+            this.assertTemplateExists('Subject', subjectTemplate);
+        }
+        this.logger?.info(log `[${logLabel(this.rendererName)}] Rendering ${logLabel(this.templateKind)} template for notification ${logId(notification.id)}`);
+        const body = await this.renderPart('body', bodyTemplate, notification, () => this.bodyEngine.renderFile(bodyTemplate, context));
+        const subject = subjectTemplate
+            ? await this.renderPart('subject', subjectTemplate, notification, () => this.subjectEngine.renderFile(subjectTemplate, context))
+            : '';
+        return { subject: normalizeSubject(subject), body: this.normalizeBody(body) };
+    }
+    async renderFromTemplateContent(notification, templateContent, context) {
+        const { subject: subjectContent, body: bodyContent } = templateContent;
+        if (!subjectContent && this.subjectRequired) {
+            throw new Error('Subject template is required');
+        }
+        this.logger?.info(log `[${logLabel(this.rendererName)}] Rendering ${logLabel(this.templateKind)} template from content for notification ${logId(notification.id)}`);
+        const body = await this.renderPart('body', null, notification, () => this.bodyEngine.parseAndRender(bodyContent, context));
+        const subject = subjectContent
+            ? await this.renderPart('subject', null, notification, () => this.subjectEngine.parseAndRender(subjectContent, context))
+            : '';
+        return { subject: normalizeSubject(subject), body: this.normalizeBody(body) };
+    }
+    normalizeBody(body) {
+        return body;
+    }
+    assertTemplateExists(part, templateKey) {
+        const { templates } = this.options;
+        if (templates && !Object.hasOwn(templates, templateKey)) {
+            throw new Error(`${part} template "${templateKey}" not found in templates`);
+        }
+    }
+    /**
+     * Runs one render, logging a failure by template key and error name only: Liquid's errors quote
+     * the template source around the failure, and an error thrown by a filter keeps its message,
+     * which can include context values.
+     */
+    async renderPart(part, templateKey, notification, renderTemplate) {
+        try {
+            return await renderTemplate();
+        }
+        catch (error) {
+            this.logger?.error(templateKey === null
+                ? log `[${logLabel(this.rendererName)}] Error rendering ${logLabel(part)} template content for notification ${logId(notification.id)}: ${logError(error)}`
+                : log `[${logLabel(this.rendererName)}] Error rendering ${logLabel(part)} template ${logLabel(templateKey)} for notification ${logId(notification.id)}: ${logError(error)}`);
+            throw error;
+        }
+    }
+}
+function normalizeSubject(subject) {
+    return subject.replace(/\s+/g, ' ').trim();
+}
+export class LiquidEmailTemplateRendererFactory {
+    create(options = {}) {
+        return new LiquidEmailTemplateRenderer(options);
+    }
+}

package/dist/liquid-inline-email-template-renderer.d.ts

@@ -0,0 +1,20 @@
+import type { BaseNotificationTypeConfig } from 'vintasend';
+import { LiquidEmailTemplateRenderer, type LiquidTemplateRendererOptions } from './liquid-email-template-renderer.js';
+/**
+ * Renders email notifications from Liquid templates held in memory instead of on disk.
+ *
+ * `notification.bodyTemplate` and `notification.subjectTemplate` are keys into `templates`, which
+ * is typically the JSON written by `compile-liquid-templates`. Includes, renders and layouts
+ * resolve against the same map, so templates can share partials without a file system — useful in
+ * environments such as Medplum bots where templates ship embedded in the bundle.
+ *
+ * Escaping and subject handling are the same as `LiquidEmailTemplateRenderer`.
+ */
+export declare class LiquidInlineEmailTemplateRenderer<Config extends BaseNotificationTypeConfig> extends LiquidEmailTemplateRenderer<Config> {
+    protected readonly rendererName: string;
+    constructor(templates: Record<string, string>, options?: Omit<LiquidTemplateRendererOptions, 'templates'>);
+}
+export declare class LiquidInlineEmailTemplateRendererFactory<Config extends BaseNotificationTypeConfig> {
+    create(templates: Record<string, string>, options?: Omit<LiquidTemplateRendererOptions, 'templates'>): LiquidInlineEmailTemplateRenderer<Config>;
+}
+//# sourceMappingURL=liquid-inline-email-template-renderer.d.ts.map

package/dist/liquid-inline-email-template-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquid-inline-email-template-renderer.d.ts","sourceRoot":"","sources":["../src/liquid-inline-email-template-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EACL,2BAA2B,EAC3B,KAAK,6BAA6B,EACnC,MAAM,qCAAqC,CAAC;AAE7C;;;;;;;;;GASG;AACH,qBAAa,iCAAiC,CAC5C,MAAM,SAAS,0BAA0B,CACzC,SAAQ,2BAA2B,CAAC,MAAM,CAAC;IAC3C,mBAA4B,YAAY,EAAE,MAAM,CAAuC;gBAGrF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,OAAO,GAAE,IAAI,CAAC,6BAA6B,EAAE,WAAW,CAAM;CAIjE;AAED,qBAAa,wCAAwC,CAAC,MAAM,SAAS,0BAA0B;IAC7F,MAAM,CACJ,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,OAAO,GAAE,IAAI,CAAC,6BAA6B,EAAE,WAAW,CAAM,GAC7D,iCAAiC,CAAC,MAAM,CAAC;CAG7C"}

package/dist/liquid-inline-email-template-renderer.js

@@ -0,0 +1,22 @@
+import { LiquidEmailTemplateRenderer, } from './liquid-email-template-renderer.js';
+/**
+ * Renders email notifications from Liquid templates held in memory instead of on disk.
+ *
+ * `notification.bodyTemplate` and `notification.subjectTemplate` are keys into `templates`, which
+ * is typically the JSON written by `compile-liquid-templates`. Includes, renders and layouts
+ * resolve against the same map, so templates can share partials without a file system — useful in
+ * environments such as Medplum bots where templates ship embedded in the bundle.
+ *
+ * Escaping and subject handling are the same as `LiquidEmailTemplateRenderer`.
+ */
+export class LiquidInlineEmailTemplateRenderer extends LiquidEmailTemplateRenderer {
+    constructor(templates, options = {}) {
+        super({ ...options, templates });
+        this.rendererName = 'LiquidInlineEmailTemplateRenderer';
+    }
+}
+export class LiquidInlineEmailTemplateRendererFactory {
+    create(templates, options = {}) {
+        return new LiquidInlineEmailTemplateRenderer(templates, options);
+    }
+}

package/dist/liquid-sms-template-renderer.d.ts

@@ -0,0 +1,27 @@
+import type { BaseNotificationTypeConfig } from 'vintasend';
+import { LiquidEmailTemplateRenderer, type LiquidTemplateRendererOptions } from './liquid-email-template-renderer.js';
+/**
+ * Renders SMS notifications from Liquid templates, for SMS adapters such as
+ * `vintasend-ts-twilio`, which send the rendered `body`.
+ *
+ * Templates resolve the same way as in `LiquidEmailTemplateRenderer`: paths under `options.root`,
+ * or keys into `options.templates` for templates held in memory (e.g. in Medplum bots).
+ *
+ * Differences from the email renderer:
+ * - Output is not HTML-escaped, since an SMS is plain text (`Tom & Jerry` stays as is). Passing
+ *   `outputEscape` still overrides this.
+ * - The subject template is optional; without one, `subject` is an empty string.
+ * - Leading and trailing whitespace is trimmed from the body, including the trailing newline of a
+ *   template file. Line breaks inside the message are kept.
+ */
+export declare class LiquidSmsTemplateRenderer<Config extends BaseNotificationTypeConfig> extends LiquidEmailTemplateRenderer<Config> {
+    protected readonly rendererName: string;
+    protected readonly templateKind: string;
+    protected readonly subjectRequired: boolean;
+    constructor(options?: LiquidTemplateRendererOptions);
+    protected normalizeBody(body: string): string;
+}
+export declare class LiquidSmsTemplateRendererFactory<Config extends BaseNotificationTypeConfig> {
+    create(options?: LiquidTemplateRendererOptions): LiquidSmsTemplateRenderer<Config>;
+}
+//# sourceMappingURL=liquid-sms-template-renderer.d.ts.map

package/dist/liquid-sms-template-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liquid-sms-template-renderer.d.ts","sourceRoot":"","sources":["../src/liquid-sms-template-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EACL,2BAA2B,EAC3B,KAAK,6BAA6B,EACnC,MAAM,qCAAqC,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAAyB,CACpC,MAAM,SAAS,0BAA0B,CACzC,SAAQ,2BAA2B,CAAC,MAAM,CAAC;IAC3C,mBAA4B,YAAY,EAAE,MAAM,CAA+B;IAC/E,mBAA4B,YAAY,EAAE,MAAM,CAAS;IACzD,mBAA4B,eAAe,EAAE,OAAO,CAAS;gBAEjD,OAAO,GAAE,6BAAkC;cAIpC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAGvD;AAED,qBAAa,gCAAgC,CAAC,MAAM,SAAS,0BAA0B;IACrF,MAAM,CAAC,OAAO,GAAE,6BAAkC,GAAG,yBAAyB,CAAC,MAAM,CAAC;CAGvF"}

package/dist/liquid-sms-template-renderer.js

@@ -0,0 +1,31 @@
+import { LiquidEmailTemplateRenderer, } from './liquid-email-template-renderer.js';
+/**
+ * Renders SMS notifications from Liquid templates, for SMS adapters such as
+ * `vintasend-ts-twilio`, which send the rendered `body`.
+ *
+ * Templates resolve the same way as in `LiquidEmailTemplateRenderer`: paths under `options.root`,
+ * or keys into `options.templates` for templates held in memory (e.g. in Medplum bots).
+ *
+ * Differences from the email renderer:
+ * - Output is not HTML-escaped, since an SMS is plain text (`Tom & Jerry` stays as is). Passing
+ *   `outputEscape` still overrides this.
+ * - The subject template is optional; without one, `subject` is an empty string.
+ * - Leading and trailing whitespace is trimmed from the body, including the trailing newline of a
+ *   template file. Line breaks inside the message are kept.
+ */
+export class LiquidSmsTemplateRenderer extends LiquidEmailTemplateRenderer {
+    constructor(options = {}) {
+        super({ outputEscape: undefined, ...options });
+        this.rendererName = 'LiquidSmsTemplateRenderer';
+        this.templateKind = 'SMS';
+        this.subjectRequired = false;
+    }
+    normalizeBody(body) {
+        return body.trim();
+    }
+}
+export class LiquidSmsTemplateRendererFactory {
+    create(options = {}) {
+        return new LiquidSmsTemplateRenderer(options);
+    }
+}

package/dist/scripts/compile-liquid-templates.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Main function to compile liquid templates to JSON
+ */
+export declare function compileLiquidTemplates(inputDir?: string, outputFile?: string): void;
+export declare function runCli(args?: string[]): void;
+//# sourceMappingURL=compile-liquid-templates.d.ts.map

package/dist/scripts/compile-liquid-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-liquid-templates.d.ts","sourceRoot":"","sources":["../../src/scripts/compile-liquid-templates.ts"],"names":[],"mappings":";AAoCA;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,GAAE,MAAsB,EAChC,UAAU,GAAE,MAAkC,GAC7C,IAAI,CAwBN;AAeD,wBAAgB,MAAM,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,IAAI,CAenE"}

package/dist/scripts/compile-liquid-templates.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Recursively finds all .liquid files in a directory
+ */
+function findLiquidFiles(dir, baseDir, files = new Map()) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            findLiquidFiles(fullPath, baseDir, files);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.liquid')) {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            // Keys are POSIX-style paths relative to the base directory, so includes such as
+            // {% include "partials/footer.liquid" %} resolve the same way they do on disk.
+            const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+            files.set(relativePath, content);
+        }
+    }
+    return files;
+}
+/**
+ * Main function to compile liquid templates to JSON
+ */
+export function compileLiquidTemplates(inputDir = './templates', outputFile = 'compiled-templates.json') {
+    if (!fs.existsSync(inputDir)) {
+        throw new Error(`Directory "${inputDir}" does not exist.`);
+    }
+    if (!fs.statSync(inputDir).isDirectory()) {
+        throw new Error(`"${inputDir}" is not a directory.`);
+    }
+    console.log(`Searching for .liquid files in: ${inputDir}`);
+    const liquidFiles = findLiquidFiles(inputDir, inputDir);
+    console.log(`Found ${liquidFiles.size} .liquid file(s)`);
+    const result = {};
+    for (const [filePath, content] of liquidFiles.entries()) {
+        result[filePath] = content;
+        console.log(`  - ${filePath}`);
+    }
+    fs.writeFileSync(outputFile, JSON.stringify(result, null, 2), 'utf-8');
+    console.log(`\nSuccessfully compiled templates to: ${outputFile}`);
+}
+function printHelp() {
+    console.log('Usage: compile-liquid-templates [input-directory] [output-file]');
+    console.log('');
+    console.log('Arguments:');
+    console.log('  input-directory  Directory containing .liquid templates (default: ./templates)');
+    console.log('  output-file      Output JSON file path (default: compiled-templates.json)');
+    console.log('');
+    console.log('Examples:');
+    console.log('  compile-liquid-templates');
+    console.log('  compile-liquid-templates ./templates');
+    console.log('  compile-liquid-templates ./templates ./compiled-templates.json');
+}
+export function runCli(args = process.argv.slice(2)) {
+    if (args.includes('--help') || args.includes('-h')) {
+        printHelp();
+        return;
+    }
+    const [inputDir, outputFile] = args;
+    try {
+        compileLiquidTemplates(inputDir, outputFile);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        process.exit(1);
+    }
+}
+// Compare against the real path so the bin also runs when invoked through the
+// node_modules/.bin symlink.
+const isExecutedDirectly = process.argv[1] !== undefined &&
+    fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1]);
+if (isExecutedDirectly) {
+    runCli(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "vintasend-liquidjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-alpha5",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vintasoftware/vintasend-liquidjs.git"
+  },
+  "description": "LiquidJS email and SMS template renderers for VintaSend",
+  "keywords": [
+    "vintasend",
+    "liquid",
+    "liquidjs",
+    "email",
+    "sms",
+    "templates",
+    "notifications"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "prepare": "husky",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "compile-liquid-templates": "dist/scripts/compile-liquid-templates.js"
+  },
+  "author": "Hugo Bessa",
+  "license": "MIT",
+  "dependencies": {
+    "liquidjs": "^10.29.0",
+    "vintasend": "^1.0.0-alpha5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.10",
+    "@types/node": "25.3.3",
+    "@vitest/coverage-v8": "4.0.18",
+    "husky": "^9.1.7",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.18"
+  }
+}