@formfeed/engine 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Formfeed template engine (Jinja2, Liquid, Handlebars) for the browser and Node.",
   "license": "MIT",
   "type": "module",

package/types/index.d.cts

@@ -6,7 +6,13 @@ export { analyzeHandlebars, analyzeJinja2, analyzeLiquid, engineIds, engines, ge
 export { inferSchema, schemaPaths } from './lib/schema.cjs';
 export { mergeSampleData, snippets, snippetsFor } from './lib/snippets.cjs';
 export { importApitemplate, slugFromName } from './lib/import/apitemplate.cjs';
-export type { ApitemplateExport, ImportNote, ImportResult, } from './lib/import/apitemplate.cjs';
+export type { ApitemplateExport } from './lib/import/apitemplate.cjs';
+export type { ImportNote, ImportResult, ImportSource } from './lib/import/common.cjs';
+export { importPdfmonkey, strftimeToDateFns } from './lib/import/pdfmonkey.cjs';
+export type { PdfmonkeyImportOptions, PdfmonkeySettings, PdfmonkeyTemplate } from './lib/import/pdfmonkey.cjs';
+export { importJsreport, jsreportTemplates, readJsreportExport } from './lib/import/jsreport.cjs';
+export type { JsreportBundle, JsreportImportOptions, JsreportTemplate } from './lib/import/jsreport.cjs';
+export { convertScss, isScss } from './lib/import/scss.cjs';
 export type { Snippet } from './lib/snippets.cjs';
 export type { JsonSchema } from './lib/schema.cjs';
 export { assembleDocument, chartInitScript, defaultSettings, fontFaceCss, mergeSettings, pageSize, printReset, renderVersion, } from './lib/assemble.cjs';

package/types/index.d.ts

@@ -6,7 +6,13 @@ export { analyzeHandlebars, analyzeJinja2, analyzeLiquid, engineIds, engines, ge
 export { inferSchema, schemaPaths } from './lib/schema.js';
 export { mergeSampleData, snippets, snippetsFor } from './lib/snippets.js';
 export { importApitemplate, slugFromName } from './lib/import/apitemplate.js';
-export type { ApitemplateExport, ImportNote, ImportResult, } from './lib/import/apitemplate.js';
+export type { ApitemplateExport } from './lib/import/apitemplate.js';
+export type { ImportNote, ImportResult, ImportSource } from './lib/import/common.js';
+export { importPdfmonkey, strftimeToDateFns } from './lib/import/pdfmonkey.js';
+export type { PdfmonkeyImportOptions, PdfmonkeySettings, PdfmonkeyTemplate } from './lib/import/pdfmonkey.js';
+export { importJsreport, jsreportTemplates, readJsreportExport } from './lib/import/jsreport.js';
+export type { JsreportBundle, JsreportImportOptions, JsreportTemplate } from './lib/import/jsreport.js';
+export { convertScss, isScss } from './lib/import/scss.js';
 export type { Snippet } from './lib/snippets.js';
 export type { JsonSchema } from './lib/schema.js';
 export { assembleDocument, chartInitScript, defaultSettings, fontFaceCss, mergeSettings, pageSize, printReset, renderVersion, } from './lib/assemble.js';

package/types/lib/engines/python-format.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Python's `str.format` for the Jinja2 engine (spec 05 §8): templates from apitemplate.io format
+ * numbers with it, e.g. `"{:,.2f}".format(total)`, including nested fields in the spec
+ * (`"{:,.{}f}".format(value, places)`). Covers positional, numbered and named fields, attribute
+ * lookups (`{0.name}`), `{{`/`}}` escapes and the format mini-language: fill and alignment, sign,
+ * `#`, zero padding, width, `,`/`_` grouping, precision and the types `s d n b o x X e E f F g G %`.
+ */
+/** Formats one value with a format spec (the part after `:`). */
+export declare function formatValue(value: unknown, spec: string): string;
+/**
+ * `template.format(*positional, **named)`. Unknown fields format as empty text instead of raising,
+ * because a template should render rather than fail on a missing value.
+ */
+export declare function pythonFormat(template: string, positional: unknown[], named?: Record<string, unknown>): string;

package/types/lib/engines/python-format.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Python's `str.format` for the Jinja2 engine (spec 05 §8): templates from apitemplate.io format
+ * numbers with it, e.g. `"{:,.2f}".format(total)`, including nested fields in the spec
+ * (`"{:,.{}f}".format(value, places)`). Covers positional, numbered and named fields, attribute
+ * lookups (`{0.name}`), `{{`/`}}` escapes and the format mini-language: fill and alignment, sign,
+ * `#`, zero padding, width, `,`/`_` grouping, precision and the types `s d n b o x X e E f F g G %`.
+ */
+/** Formats one value with a format spec (the part after `:`). */
+export declare function formatValue(value: unknown, spec: string): string;
+/**
+ * `template.format(*positional, **named)`. Unknown fields format as empty text instead of raising,
+ * because a template should render rather than fail on a missing value.
+ */
+export declare function pythonFormat(template: string, positional: unknown[], named?: Record<string, unknown>): string;

package/types/lib/import/apitemplate.d.cts

@@ -1,4 +1,6 @@
-import type { TemplateSettings } from '../assemble.cjs';
+import { type ImportResult } from './common.cjs';
+export { slugFromName } from './common.cjs';
+export type { ImportNote, ImportResult } from './common.cjs';
 /**
  * apitemplate.io importer (spec 10 §4, spec 05 §8): turns an exported template (HTML body, CSS,
  * settings, sample JSON) into a Formfeed draft and a report of what needs attention. The Jinja2
@@ -16,30 +18,4 @@ export interface ApitemplateExport {
     /** Their template format; JPEG and PNG become image templates. */
     format?: string | null;
 }
-export interface ImportNote {
-    code: string;
-    message: string;
-    line?: number;
-    column?: number;
-    /** Path under docs.formfeed.dev with the details. */
-    docs?: string;
-}
-export interface ImportResult {
-    name: string;
-    slug: string;
-    kind: 'pdf' | 'image';
-    engine: 'jinja2';
-    html: string;
-    css: string;
-    head: string;
-    settings: TemplateSettings;
-    sampleData: unknown;
-    /** Compile or analysis errors: the draft is created, but it will not render as is. */
-    errors: ImportNote[];
-    /** Unknown filters, unsupported Python constructs, ignored settings. */
-    warnings: ImportNote[];
-    /** What the importer changed or mapped. */
-    changes: string[];
-}
-export declare function slugFromName(name: string): string;
 export declare function importApitemplate(input: ApitemplateExport): ImportResult;

package/types/lib/import/apitemplate.d.ts

@@ -1,4 +1,6 @@
-import type { TemplateSettings } from '../assemble.js';
+import { type ImportResult } from './common.js';
+export { slugFromName } from './common.js';
+export type { ImportNote, ImportResult } from './common.js';
 /**
  * apitemplate.io importer (spec 10 §4, spec 05 §8): turns an exported template (HTML body, CSS,
  * settings, sample JSON) into a Formfeed draft and a report of what needs attention. The Jinja2
@@ -16,30 +18,4 @@ export interface ApitemplateExport {
     /** Their template format; JPEG and PNG become image templates. */
     format?: string | null;
 }
-export interface ImportNote {
-    code: string;
-    message: string;
-    line?: number;
-    column?: number;
-    /** Path under docs.formfeed.dev with the details. */
-    docs?: string;
-}
-export interface ImportResult {
-    name: string;
-    slug: string;
-    kind: 'pdf' | 'image';
-    engine: 'jinja2';
-    html: string;
-    css: string;
-    head: string;
-    settings: TemplateSettings;
-    sampleData: unknown;
-    /** Compile or analysis errors: the draft is created, but it will not render as is. */
-    errors: ImportNote[];
-    /** Unknown filters, unsupported Python constructs, ignored settings. */
-    warnings: ImportNote[];
-    /** What the importer changed or mapped. */
-    changes: string[];
-}
-export declare function slugFromName(name: string): string;
 export declare function importApitemplate(input: ApitemplateExport): ImportResult;

package/types/lib/import/common.d.cts

@@ -0,0 +1,67 @@
+import type { TemplateSettings } from '../assemble.cjs';
+import type { EngineId } from '../types.cjs';
+/**
+ * What every importer shares (spec 10 §4): the result shape the app and the CLI turn into a draft,
+ * the notes of the report, and the final check that compiles and analyses the converted template
+ * against its sample data, so the report shows exactly what the editor would.
+ */
+export type ImportSource = 'apitemplate' | 'pdfmonkey' | 'jsreport';
+export interface ImportNote {
+    code: string;
+    message: string;
+    line?: number;
+    column?: number;
+    /** Path under docs.formfeed.dev with the details. */
+    docs?: string;
+}
+export interface ImportResult {
+    source: ImportSource;
+    name: string;
+    slug: string;
+    kind: 'pdf' | 'image';
+    engine: EngineId;
+    html: string;
+    css: string;
+    head: string;
+    settings: TemplateSettings;
+    sampleData: unknown;
+    /** Compile or analysis errors: the draft is created, but it will not render as is. */
+    errors: ImportNote[];
+    /** Unknown filters, unsupported constructs, ignored settings. */
+    warnings: ImportNote[];
+    /** What the importer changed or mapped. */
+    changes: string[];
+}
+export declare function slugFromName(name: string): string;
+export declare function parseSample(value: unknown): {
+    data: unknown;
+    error?: string;
+};
+export declare function positionOf(source: string, index: number): {
+    line: number;
+    column: number;
+};
+/** Every match of `pattern` in `source` as a note with its position. */
+export declare function notesFor(source: string, pattern: RegExp, note: Omit<ImportNote, 'line' | 'column'>, { once }?: {
+    once?: boolean;
+}): ImportNote[];
+/** Docs pages the generic diagnostics point at, per importer. */
+export interface CheckDocs {
+    syntax: string;
+    filters: string;
+    sampleData: string;
+}
+/**
+ * Compiles and analyses the converted template with the engine it will run on. Errors stop the
+ * render (the draft is still created); everything else is a warning. Duplicates of one error at
+ * the same line are dropped, since compile and analyse often report the same syntax error.
+ */
+export declare function checkTemplate(engineId: EngineId, html: string, sampleData: unknown, name: string, docs: CheckDocs): {
+    errors: ImportNote[];
+    warnings: ImportNote[];
+};
+/** `210`, `210mm`, `8.5in` → a CSS length; bare numbers are millimetres. */
+export declare function lengthMm(value: unknown): string | undefined;
+/** A binary value as base64: a base64 string, a serialised Node Buffer, or a byte array. */
+export declare function toBase64(value: unknown): string | undefined;
+export declare function mimeOf(name: string): string;

package/types/lib/import/common.d.ts

@@ -0,0 +1,67 @@
+import type { TemplateSettings } from '../assemble.js';
+import type { EngineId } from '../types.js';
+/**
+ * What every importer shares (spec 10 §4): the result shape the app and the CLI turn into a draft,
+ * the notes of the report, and the final check that compiles and analyses the converted template
+ * against its sample data, so the report shows exactly what the editor would.
+ */
+export type ImportSource = 'apitemplate' | 'pdfmonkey' | 'jsreport';
+export interface ImportNote {
+    code: string;
+    message: string;
+    line?: number;
+    column?: number;
+    /** Path under docs.formfeed.dev with the details. */
+    docs?: string;
+}
+export interface ImportResult {
+    source: ImportSource;
+    name: string;
+    slug: string;
+    kind: 'pdf' | 'image';
+    engine: EngineId;
+    html: string;
+    css: string;
+    head: string;
+    settings: TemplateSettings;
+    sampleData: unknown;
+    /** Compile or analysis errors: the draft is created, but it will not render as is. */
+    errors: ImportNote[];
+    /** Unknown filters, unsupported constructs, ignored settings. */
+    warnings: ImportNote[];
+    /** What the importer changed or mapped. */
+    changes: string[];
+}
+export declare function slugFromName(name: string): string;
+export declare function parseSample(value: unknown): {
+    data: unknown;
+    error?: string;
+};
+export declare function positionOf(source: string, index: number): {
+    line: number;
+    column: number;
+};
+/** Every match of `pattern` in `source` as a note with its position. */
+export declare function notesFor(source: string, pattern: RegExp, note: Omit<ImportNote, 'line' | 'column'>, { once }?: {
+    once?: boolean;
+}): ImportNote[];
+/** Docs pages the generic diagnostics point at, per importer. */
+export interface CheckDocs {
+    syntax: string;
+    filters: string;
+    sampleData: string;
+}
+/**
+ * Compiles and analyses the converted template with the engine it will run on. Errors stop the
+ * render (the draft is still created); everything else is a warning. Duplicates of one error at
+ * the same line are dropped, since compile and analyse often report the same syntax error.
+ */
+export declare function checkTemplate(engineId: EngineId, html: string, sampleData: unknown, name: string, docs: CheckDocs): {
+    errors: ImportNote[];
+    warnings: ImportNote[];
+};
+/** `210`, `210mm`, `8.5in` → a CSS length; bare numbers are millimetres. */
+export declare function lengthMm(value: unknown): string | undefined;
+/** A binary value as base64: a base64 string, a serialised Node Buffer, or a byte array. */
+export declare function toBase64(value: unknown): string | undefined;
+export declare function mimeOf(name: string): string;

package/types/lib/import/jsreport.d.cts

@@ -0,0 +1,90 @@
+import { type ImportResult } from './common.cjs';
+/**
+ * jsreport importer (spec 10 §4). jsreport is the open-source report server many teams run
+ * themselves; its export (`.jsrexport`, a zip with one JSON file per entity) carries templates,
+ * sample data, assets, components and scripts. Templates with the Handlebars engine and the
+ * chrome-pdf or chrome-image recipe map almost one to one onto Formfeed: the header and footer are
+ * Chromium header templates in both, and the chrome options are Formfeed's settings.
+ *
+ * - `{{asset}}` calls are resolved from the export: small files become data URIs or inline text.
+ *   A larger one keeps its `{{asset}}` call and a warning: the helper resolves against the
+ *   workspace file library, so the file has to be uploaded there under the same name.
+ * - Child templates and components are inlined (stored partials do not take part in API renders).
+ * - Custom helpers are JavaScript, which Formfeed does not run: each one is reported, and the
+ *   engine's analysis marks every call to it.
+ * - jsrender, EJS and Pug templates, scripts, pdf-utils operations and non-PDF recipes are reported.
+ *
+ * The caller unzips the export (`readJsreportExport` takes the file map), so the engine stays free
+ * of a zip library.
+ */
+export interface JsreportEntity {
+    _id?: string;
+    shortid?: string;
+    name?: string;
+    folder?: {
+        shortid?: string;
+    } | null;
+    [key: string]: unknown;
+}
+export interface JsreportTemplate extends JsreportEntity {
+    content?: string;
+    engine?: string;
+    recipe?: string;
+    helpers?: string;
+    chrome?: Record<string, unknown> | null;
+    chromeImage?: Record<string, unknown> | null;
+    data?: {
+        shortid?: string;
+    } | null;
+    scripts?: Array<{
+        shortid?: string;
+    }> | null;
+    pdfOperations?: unknown[] | null;
+    pdfMeta?: Record<string, unknown> | null;
+    pdfPassword?: Record<string, unknown> | null;
+    localization?: {
+        language?: string;
+    } | null;
+}
+export interface JsreportBundle {
+    templates: JsreportTemplate[];
+    data: Array<JsreportEntity & {
+        dataJson?: string;
+    }>;
+    assets: Array<JsreportEntity & {
+        content?: unknown;
+        link?: string;
+        isSharedHelper?: boolean;
+    }>;
+    components: Array<JsreportEntity & {
+        content?: string;
+        helpers?: string;
+        engine?: string;
+    }>;
+    scripts: Array<JsreportEntity & {
+        content?: string;
+    }>;
+    folders: JsreportEntity[];
+    /** jsreport version from metadata.json. */
+    version?: string;
+}
+export interface JsreportImportOptions {
+    /** Assets up to this size are inlined as data URIs (default 256 KB); larger ones become `{{asset}}`. */
+    inlineAssetBytes?: number;
+}
+/**
+ * The entities of an unzipped `.jsrexport`: file path → file text. Entity files are
+ * `<collection>/<name>-<id>.json`; everything else (metadata, versions, settings) is ignored.
+ */
+export declare function readJsreportExport(files: Record<string, string>): JsreportBundle;
+/** The templates of an export for a picker: name, folder path, engine and recipe. */
+export declare function jsreportTemplates(bundle: JsreportBundle): Array<{
+    ref: string;
+    name: string;
+    path: string;
+    engine: string;
+    recipe: string;
+}>;
+/** Names of the functions a jsreport helpers script defines. */
+export declare function helperNames(script: string): string[];
+export declare function importJsreport(bundle: JsreportBundle, ref: string, options?: JsreportImportOptions): ImportResult;

package/types/lib/import/jsreport.d.ts

@@ -0,0 +1,90 @@
+import { type ImportResult } from './common.js';
+/**
+ * jsreport importer (spec 10 §4). jsreport is the open-source report server many teams run
+ * themselves; its export (`.jsrexport`, a zip with one JSON file per entity) carries templates,
+ * sample data, assets, components and scripts. Templates with the Handlebars engine and the
+ * chrome-pdf or chrome-image recipe map almost one to one onto Formfeed: the header and footer are
+ * Chromium header templates in both, and the chrome options are Formfeed's settings.
+ *
+ * - `{{asset}}` calls are resolved from the export: small files become data URIs or inline text.
+ *   A larger one keeps its `{{asset}}` call and a warning: the helper resolves against the
+ *   workspace file library, so the file has to be uploaded there under the same name.
+ * - Child templates and components are inlined (stored partials do not take part in API renders).
+ * - Custom helpers are JavaScript, which Formfeed does not run: each one is reported, and the
+ *   engine's analysis marks every call to it.
+ * - jsrender, EJS and Pug templates, scripts, pdf-utils operations and non-PDF recipes are reported.
+ *
+ * The caller unzips the export (`readJsreportExport` takes the file map), so the engine stays free
+ * of a zip library.
+ */
+export interface JsreportEntity {
+    _id?: string;
+    shortid?: string;
+    name?: string;
+    folder?: {
+        shortid?: string;
+    } | null;
+    [key: string]: unknown;
+}
+export interface JsreportTemplate extends JsreportEntity {
+    content?: string;
+    engine?: string;
+    recipe?: string;
+    helpers?: string;
+    chrome?: Record<string, unknown> | null;
+    chromeImage?: Record<string, unknown> | null;
+    data?: {
+        shortid?: string;
+    } | null;
+    scripts?: Array<{
+        shortid?: string;
+    }> | null;
+    pdfOperations?: unknown[] | null;
+    pdfMeta?: Record<string, unknown> | null;
+    pdfPassword?: Record<string, unknown> | null;
+    localization?: {
+        language?: string;
+    } | null;
+}
+export interface JsreportBundle {
+    templates: JsreportTemplate[];
+    data: Array<JsreportEntity & {
+        dataJson?: string;
+    }>;
+    assets: Array<JsreportEntity & {
+        content?: unknown;
+        link?: string;
+        isSharedHelper?: boolean;
+    }>;
+    components: Array<JsreportEntity & {
+        content?: string;
+        helpers?: string;
+        engine?: string;
+    }>;
+    scripts: Array<JsreportEntity & {
+        content?: string;
+    }>;
+    folders: JsreportEntity[];
+    /** jsreport version from metadata.json. */
+    version?: string;
+}
+export interface JsreportImportOptions {
+    /** Assets up to this size are inlined as data URIs (default 256 KB); larger ones become `{{asset}}`. */
+    inlineAssetBytes?: number;
+}
+/**
+ * The entities of an unzipped `.jsrexport`: file path → file text. Entity files are
+ * `<collection>/<name>-<id>.json`; everything else (metadata, versions, settings) is ignored.
+ */
+export declare function readJsreportExport(files: Record<string, string>): JsreportBundle;
+/** The templates of an export for a picker: name, folder path, engine and recipe. */
+export declare function jsreportTemplates(bundle: JsreportBundle): Array<{
+    ref: string;
+    name: string;
+    path: string;
+    engine: string;
+    recipe: string;
+}>;
+/** Names of the functions a jsreport helpers script defines. */
+export declare function helperNames(script: string): string[];
+export declare function importJsreport(bundle: JsreportBundle, ref: string, options?: JsreportImportOptions): ImportResult;

package/types/lib/import/pdfmonkey.d.cts

@@ -0,0 +1,77 @@
+import { type ImportResult } from './common.cjs';
+/**
+ * PDFMonkey importer (spec 10 §4). A PDFMonkey code template is HTML with Ruby Liquid 4, a CSS or
+ * SCSS stylesheet, sample data as a JSON string and settings, all returned by
+ * `GET /api/v1/document_templates/{id}`. Formfeed's Liquid engine is LiquidJS with the shared
+ * helpers, so the converter rewrites what differs:
+ *
+ * - `date` takes date-fns tokens here, strftime there; `in_time_zone` becomes `date`'s timezone.
+ * - PDFMonkey's own filters map to helpers (`slice_by` → `chunk`, `with_delimiter` → `number`
+ *   with a locale that has the same separators) or are reported: the engine runs with strict
+ *   filters, so an unmapped one would fail the render.
+ * - Ruby's lax parser accepts `| filter, key: value`; LiquidJS needs `| filter: key: value`.
+ * - Snippets (`load_snippets` + `include`) and inline `{% partial %}` blocks are inlined, because
+ *   stored partials do not take part in API renders.
+ * - Settings: paper, orientation, margins (PDFMonkey's default is 10 mm), the simple
+ *   left/center/right header and footer with `[page]`/`[topage]`, or the advanced HTML one.
+ *
+ * Builder templates (their visual builder) have an undocumented format and are not supported.
+ */
+export interface PdfmonkeyMargin {
+    top?: number | string | null;
+    right?: number | string | null;
+    bottom?: number | string | null;
+    left?: number | string | null;
+}
+export interface PdfmonkeyHeaderFooter {
+    left?: string | null;
+    center?: string | null;
+    right?: string | null;
+    /** "Advanced mode": full-width HTML with Liquid; overrides left/center/right. */
+    content?: string | null;
+}
+export interface PdfmonkeySettings {
+    paper_format?: string | null;
+    paper_width?: number | string | null;
+    paper_height?: number | string | null;
+    orientation?: string | null;
+    margin?: PdfmonkeyMargin | null;
+    header?: PdfmonkeyHeaderFooter | null;
+    footer?: PdfmonkeyHeaderFooter | null;
+    inject_javascript?: boolean | null;
+    use_emojis?: boolean | null;
+    transparent_background?: boolean | null;
+    use_paged?: boolean | null;
+    use_forms?: boolean | null;
+    [key: string]: unknown;
+}
+export interface PdfmonkeyTemplate {
+    id?: string;
+    identifier?: string | null;
+    edition_mode?: string | null;
+    output_type?: string | null;
+    body?: string | null;
+    body_draft?: string | null;
+    scss_style?: string | null;
+    scss_style_draft?: string | null;
+    sample_data?: unknown;
+    sample_data_draft?: unknown;
+    settings?: PdfmonkeySettings | null;
+    settings_draft?: PdfmonkeySettings | null;
+}
+export interface PdfmonkeyImportOptions {
+    /** Import the unpublished draft instead of the published version. */
+    draft?: boolean;
+    /** Snippet code by name, for templates that `load_snippets`; PDFMonkey's API does not return it. */
+    snippets?: Record<string, string>;
+    /** A Sass compiler; without one, SCSS is converted as far as that works without (see scss.ts). */
+    compileScss?: (source: string) => string;
+}
+/** A strftime format as date-fns tokens; `unmapped` lists the directives without an equivalent. */
+export declare function strftimeToDateFns(format: string): {
+    format: string;
+    unmapped: string[];
+};
+export declare function importPdfmonkey(input: PdfmonkeyTemplate | {
+    document_template: PdfmonkeyTemplate;
+}, options?: PdfmonkeyImportOptions): ImportResult;

package/types/lib/import/pdfmonkey.d.ts

@@ -0,0 +1,77 @@
+import { type ImportResult } from './common.js';
+/**
+ * PDFMonkey importer (spec 10 §4). A PDFMonkey code template is HTML with Ruby Liquid 4, a CSS or
+ * SCSS stylesheet, sample data as a JSON string and settings, all returned by
+ * `GET /api/v1/document_templates/{id}`. Formfeed's Liquid engine is LiquidJS with the shared
+ * helpers, so the converter rewrites what differs:
+ *
+ * - `date` takes date-fns tokens here, strftime there; `in_time_zone` becomes `date`'s timezone.
+ * - PDFMonkey's own filters map to helpers (`slice_by` → `chunk`, `with_delimiter` → `number`
+ *   with a locale that has the same separators) or are reported: the engine runs with strict
+ *   filters, so an unmapped one would fail the render.
+ * - Ruby's lax parser accepts `| filter, key: value`; LiquidJS needs `| filter: key: value`.
+ * - Snippets (`load_snippets` + `include`) and inline `{% partial %}` blocks are inlined, because
+ *   stored partials do not take part in API renders.
+ * - Settings: paper, orientation, margins (PDFMonkey's default is 10 mm), the simple
+ *   left/center/right header and footer with `[page]`/`[topage]`, or the advanced HTML one.
+ *
+ * Builder templates (their visual builder) have an undocumented format and are not supported.
+ */
+export interface PdfmonkeyMargin {
+    top?: number | string | null;
+    right?: number | string | null;
+    bottom?: number | string | null;
+    left?: number | string | null;
+}
+export interface PdfmonkeyHeaderFooter {
+    left?: string | null;
+    center?: string | null;
+    right?: string | null;
+    /** "Advanced mode": full-width HTML with Liquid; overrides left/center/right. */
+    content?: string | null;
+}
+export interface PdfmonkeySettings {
+    paper_format?: string | null;
+    paper_width?: number | string | null;
+    paper_height?: number | string | null;
+    orientation?: string | null;
+    margin?: PdfmonkeyMargin | null;
+    header?: PdfmonkeyHeaderFooter | null;
+    footer?: PdfmonkeyHeaderFooter | null;
+    inject_javascript?: boolean | null;
+    use_emojis?: boolean | null;
+    transparent_background?: boolean | null;
+    use_paged?: boolean | null;
+    use_forms?: boolean | null;
+    [key: string]: unknown;
+}
+export interface PdfmonkeyTemplate {
+    id?: string;
+    identifier?: string | null;
+    edition_mode?: string | null;
+    output_type?: string | null;
+    body?: string | null;
+    body_draft?: string | null;
+    scss_style?: string | null;
+    scss_style_draft?: string | null;
+    sample_data?: unknown;
+    sample_data_draft?: unknown;
+    settings?: PdfmonkeySettings | null;
+    settings_draft?: PdfmonkeySettings | null;
+}
+export interface PdfmonkeyImportOptions {
+    /** Import the unpublished draft instead of the published version. */
+    draft?: boolean;
+    /** Snippet code by name, for templates that `load_snippets`; PDFMonkey's API does not return it. */
+    snippets?: Record<string, string>;
+    /** A Sass compiler; without one, SCSS is converted as far as that works without (see scss.ts). */
+    compileScss?: (source: string) => string;
+}
+/** A strftime format as date-fns tokens; `unmapped` lists the directives without an equivalent. */
+export declare function strftimeToDateFns(format: string): {
+    format: string;
+    unmapped: string[];
+};
+export declare function importPdfmonkey(input: PdfmonkeyTemplate | {
+    document_template: PdfmonkeyTemplate;
+}, options?: PdfmonkeyImportOptions): ImportResult;

package/types/lib/import/scss.d.cts

@@ -0,0 +1,17 @@
+import { type ImportNote } from './common.cjs';
+/**
+ * SCSS → CSS for imported stylesheets (PDFMonkey stores "CSS or SCSS"). Formfeed styles are CSS,
+ * and the engine must stay free of a Sass compiler, so the caller may pass one (`compile`): the app
+ * loads `sass` on demand, the CLI when it is installed. Without it, the plain-CSS subset that most
+ * stylesheets use is converted here: `//` comment lines go, top-level `$variables` are substituted,
+ * and everything that needs a real compiler (mixins, functions, control flow) is reported with its
+ * line. Nested rules are left as they are: Chromium renders CSS nesting natively.
+ */
+export interface ScssResult {
+    css: string;
+    warnings: ImportNote[];
+    changes: string[];
+}
+/** True when the stylesheet uses anything beyond CSS (nesting aside, which CSS has too). */
+export declare function isScss(source: string): boolean;
+export declare function convertScss(source: string, compile?: (source: string) => string): ScssResult;

package/types/lib/import/scss.d.ts

@@ -0,0 +1,17 @@
+import { type ImportNote } from './common.js';
+/**
+ * SCSS → CSS for imported stylesheets (PDFMonkey stores "CSS or SCSS"). Formfeed styles are CSS,
+ * and the engine must stay free of a Sass compiler, so the caller may pass one (`compile`): the app
+ * loads `sass` on demand, the CLI when it is installed. Without it, the plain-CSS subset that most
+ * stylesheets use is converted here: `//` comment lines go, top-level `$variables` are substituted,
+ * and everything that needs a real compiler (mixins, functions, control flow) is reported with its
+ * line. Nested rules are left as they are: Chromium renders CSS nesting natively.
+ */
+export interface ScssResult {
+    css: string;
+    warnings: ImportNote[];
+    changes: string[];
+}
+/** True when the stylesheet uses anything beyond CSS (nesting aside, which CSS has too). */
+export declare function isScss(source: string): boolean;
+export declare function convertScss(source: string, compile?: (source: string) => string): ScssResult;