@maravilla-labs/platform 0.3.11 → 0.4.1

package/dist/transforms-B3XZ8wYs.d.ts

@@ -0,0 +1,300 @@
+/**
+ * @fileoverview Media transforms — async ffmpeg / image / OCR jobs.
+ *
+ * Mirrors the Rust `platform.media.transforms` surface. All mutating
+ * methods (transcode/thumbnail/resize/ocr) return a {@link JobHandle}
+ * whose `outputKey` is content-addressed via {@link keyFor} and known
+ * up front — clients can render placeholder UI for the derived asset
+ * before the worker even starts the job.
+ *
+ * The runtime injects the live JS object as `platform.media.transforms`
+ * (see `crates/runtime/src/ops/platform/js_bindings/platform_js.rs`).
+ * The static helper {@link keyFor} is exported separately and runs
+ * client-side — it must produce byte-for-byte identical output to the
+ * Rust `derive_key`. The shared golden-vector fixture
+ * `crates/platform/tests/derive_key_vectors.json` is consumed from both
+ * the Rust integration test (`crates/platform/tests/derive_key_golden.rs`)
+ * and the TS test (`packages/platform/tests/derive-key.test.ts`) to keep
+ * the two in lockstep.
+ */
+/** Video container targets supported by v1. */
+type VideoFormat = 'mp4' | 'webm';
+/** Image output formats supported by v1. */
+type ImageFormat = 'jpg' | 'png' | 'webp';
+/** Lifecycle state of a transform job. */
+type JobStatus = 'pending' | 'running' | 'complete' | 'failed';
+/** Options for `transforms.transcode`. */
+interface TranscodeOpts {
+    format: VideoFormat;
+    codec?: string;
+    max_width?: number;
+    max_height?: number;
+    audio_codec?: string;
+    bitrate_kbps?: number;
+}
+/** Options for `transforms.thumbnail` — extract a single video frame. */
+interface ThumbnailOpts {
+    /** Offset into the source. Accepts `"00:00:01"`, `"1s"`, or a plain number-as-string. */
+    at: string;
+    width?: number;
+    height?: number;
+    /** Defaults to `"jpg"` server-side when omitted. */
+    format?: ImageFormat;
+    quality?: number;
+}
+/** Options for `transforms.resize`. */
+interface ResizeOpts {
+    width?: number;
+    height?: number;
+    format: ImageFormat;
+    quality?: number;
+    strip_metadata?: boolean;
+}
+/** Options for `transforms.ocr`. */
+interface OcrOpts {
+    /** Tesseract language code(s). Defaults to `"eng"` server-side when omitted. */
+    lang?: string;
+}
+/**
+ * LibreOffice-supported output container for `doc_convert`. Each value
+ * maps to a `--convert-to` filter and a derived-key extension.
+ */
+type DocFormat = 'pdf' | 'docx' | 'odt' | 'xlsx' | 'html' | 'txt' | 'rtf';
+/** Options for `transforms.docToPdf`. */
+interface DocToPdfOpts {
+}
+/** Options for `transforms.docThumbnail` — single-page raster of a document. */
+interface DocThumbnailOpts {
+    width?: number;
+    height?: number;
+    /** Defaults to `"png"` server-side when omitted. */
+    format?: ImageFormat;
+    /** 1-indexed page. Defaults to `1` server-side when omitted. */
+    page?: number;
+    quality?: number;
+}
+/** Options for `transforms.docConvert` — generic LibreOffice conversion. */
+interface DocConvertOpts {
+    to: DocFormat;
+}
+/** Options for `transforms.docToMarkdown` — RAG / LLM-friendly extraction. */
+interface DocToMarkdownOpts {
+    /** Keep GFM tables in the output. Defaults to `true` server-side when omitted. */
+    preserve_tables?: boolean;
+}
+/**
+ * Options for `transforms.docToHtml` — single-file HTML with images
+ * inlined as base64 `data:` URIs and CSS inlined as `<style>` blocks.
+ * The output is a self-contained `.html` the caller can email, embed
+ * in an `<iframe>`, or hand to an LLM as one string.
+ */
+interface DocToHtmlOpts {
+    /** Inline `<img>` references as base64 `data:` URIs. Defaults `true` server-side. */
+    inline_images?: boolean;
+    /** Inline CSS as a single `<style>` block. Defaults `true` server-side. */
+    inline_styles?: boolean;
+}
+/** Reference to a replacement image — its key in tenant `STORAGE`. */
+interface ImageRef {
+    src_key: string;
+}
+/**
+ * Options for `transforms.docReplaceImages` — substitute placeholder
+ * text-tags and/or named drawing objects with caller-supplied images.
+ *
+ * Keys in `placeholders` are the literal text the user types in their
+ * template (e.g. `"{{USER_LOGO}}"`). Keys in `named_objects` are
+ * LibreOffice draw-object Name properties (set in Word/Writer via
+ * Format → Anchor → Properties → Name) — named-object swap preserves
+ * the template's exact frame size, border, anchor, and wrap.
+ */
+interface DocReplaceImagesOpts {
+    /** Optional output format. When unset, the worker keeps the input format. */
+    output_format?: DocFormat;
+    /** `{{TAG}}` → image. The text is matched verbatim; missing tags are silently skipped. */
+    placeholders?: Record<string, ImageRef>;
+    /** `objectName` → image. */
+    named_objects?: Record<string, ImageRef>;
+    /** Pre-resize each image to the target frame's dimensions. Defaults `true` server-side. */
+    auto_resize?: boolean;
+}
+/** A single QR code to embed. Exactly one of `placeholder` or `named_object` must be set. */
+interface QrCodeSpec {
+    placeholder?: string;
+    named_object?: string;
+    /** Payload to encode — typically a URL. ≤ 1500 bytes; the server rejects larger. */
+    payload: string;
+    /** Output PNG width in pixels. QR codes are square. Defaults to 256 server-side. */
+    size?: number;
+}
+/**
+ * Options for `transforms.docInsertQrCode` — generate QR PNG(s)
+ * server-side and inject them via the same pipeline as
+ * `docReplaceImages`.
+ */
+interface DocInsertQrCodeOpts {
+    output_format?: DocFormat;
+    codes: QrCodeSpec[];
+}
+/** Inline QR-code spec for `DocTemplateMergeOpts.qr_codes`. The placeholder
+ *  is the map key, so we only carry payload + size here. */
+interface QrPayload {
+    payload: string;
+    /** Output PNG width in pixels (square). Defaults to 256 server-side. */
+    size?: number;
+}
+/**
+ * Options for `transforms.docTemplateMerge` — the unified single-call
+ * template-fill: text + images + QR codes in one render. The headline
+ * templating API; one call → one server-side render → one round-trip.
+ *
+ * `data` runs first (string find-and-replace), then `images` (text-tag →
+ * image insertion), then `named_objects` (preserves frame size/border),
+ * then `qr_codes` (server generates each PNG and injects via the same
+ * placeholder pipeline as `images`). All inside one document load.
+ */
+interface DocTemplateMergeOpts {
+    /** Output format. Defaults to keeping the input format. */
+    output_format?: DocFormat;
+    /** Text-tag → string. e.g. `{ '{{NAME}}': 'Senol Aktas' }`. */
+    data?: Record<string, string>;
+    /** Text-tag → image. Same semantics as `DocReplaceImagesOpts.placeholders`. */
+    images?: Record<string, ImageRef>;
+    /** Object-name → image. Preserves the template's frame size/border/wrap. */
+    named_objects?: Record<string, ImageRef>;
+    /** Text-tag → QR code spec. Server generates the PNG; ≤ 1500-byte payload. */
+    qr_codes?: Record<string, QrPayload>;
+    /** Pre-resize images / QR PNGs to anchor frames. Defaults `true`. */
+    auto_resize?: boolean;
+}
+/** Tagged union of all transform requests — matches the Rust `TransformSpec`. */
+type TransformSpec = ({
+    kind: 'transcode';
+} & TranscodeOpts) | ({
+    kind: 'thumbnail';
+} & ThumbnailOpts) | ({
+    kind: 'resize';
+} & ResizeOpts) | ({
+    kind: 'ocr';
+} & OcrOpts) | ({
+    kind: 'doc_to_pdf';
+} & DocToPdfOpts) | ({
+    kind: 'doc_thumbnail';
+} & DocThumbnailOpts) | ({
+    kind: 'doc_convert';
+} & DocConvertOpts) | ({
+    kind: 'doc_to_markdown';
+} & DocToMarkdownOpts) | ({
+    kind: 'doc_to_html';
+} & DocToHtmlOpts) | ({
+    kind: 'doc_replace_images';
+} & DocReplaceImagesOpts) | ({
+    kind: 'doc_insert_qr_code';
+} & DocInsertQrCodeOpts) | ({
+    kind: 'doc_template_merge';
+} & DocTemplateMergeOpts);
+/** Probe output. All fields optional — ffprobe doesn't fill every one for every input. */
+interface MediaInfo {
+    duration_secs?: number;
+    width?: number;
+    height?: number;
+    video_codec?: string;
+    audio_codec?: string;
+    bitrate_bps?: number;
+    container?: string;
+}
+/** Returned by every mutating transforms method. */
+interface JobHandle {
+    id: string;
+    src_key: string;
+    output_key: string;
+    status: JobStatus;
+}
+/** Returned by `transforms.job(id)`. */
+interface JobStatusResponse {
+    id: string;
+    status: JobStatus;
+}
+interface TransformsService {
+    transcode(srcKey: string, opts: TranscodeOpts): Promise<JobHandle>;
+    thumbnail(srcKey: string, opts: ThumbnailOpts): Promise<JobHandle>;
+    resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
+    probe(srcKey: string): Promise<MediaInfo>;
+    ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
+    /** Convert a LibreOffice-supported document to PDF. */
+    docToPdf(srcKey: string, opts?: DocToPdfOpts | null): Promise<JobHandle>;
+    /** Render a single page of a document as a raster thumbnail. */
+    docThumbnail(srcKey: string, opts: DocThumbnailOpts): Promise<JobHandle>;
+    /** Generic LibreOffice format conversion. */
+    docConvert(srcKey: string, opts: DocConvertOpts): Promise<JobHandle>;
+    /** Extract Markdown from a document (HTML → pandoc pipeline). */
+    docToMarkdown(srcKey: string, opts?: DocToMarkdownOpts | null): Promise<JobHandle>;
+    /** Convert to single-file HTML with base64-inlined images and inlined CSS. */
+    docToHtml(srcKey: string, opts?: DocToHtmlOpts | null): Promise<JobHandle>;
+    /** Swap placeholder text-tags and/or named drawing objects with caller-supplied images. */
+    docReplaceImages(srcKey: string, opts: DocReplaceImagesOpts): Promise<JobHandle>;
+    /** Generate QR codes server-side and inject them via the image-replace pipeline. */
+    docInsertQrCode(srcKey: string, opts: DocInsertQrCodeOpts): Promise<JobHandle>;
+    /** Unified template fill: text + images + QR codes in one render. The headline templating API. */
+    docTemplateMerge(srcKey: string, opts: DocTemplateMergeOpts): Promise<JobHandle>;
+    job(id: string): Promise<JobStatusResponse>;
+}
+/**
+ * Compute the canonical derived-asset key for `(srcKey, spec)`.
+ *
+ * Shape: `__derived/<srcHash>/<variantHash>.<ext>` where each hash is
+ * the first 16 hex chars (8 bytes / 64 bits) of `SHA-256(...)`.
+ *
+ * **MUST** match Rust `platform::media::transforms::derive_key` byte-for-byte.
+ * Cross-language golden vectors live at
+ * `crates/platform/tests/derive_key_vectors.json`.
+ */
+declare function keyFor(srcKey: string, spec: TransformSpec): string;
+/** Convenience namespace mirroring the Rust `transforms::keyFor` re-export. */
+declare const transforms: {
+    keyFor: typeof keyFor;
+};
+/**
+ * Per-pattern transforms declaration used inside the `transforms` block of
+ * `maravilla.config.ts`. Each field accepts a single opts object or an array.
+ *
+ * `variants` is sugar for `resize` arrays — convenient for the common
+ * "image → multiple resized renditions" case.
+ */
+interface TransformsPatternSpec {
+    transcode?: TranscodeOpts | TranscodeOpts[];
+    thumbnail?: ThumbnailOpts | ThumbnailOpts[];
+    resize?: ResizeOpts | ResizeOpts[];
+    /** Sugar for `resize` arrays — same shape, same semantics. */
+    variants?: ResizeOpts[];
+    ocr?: OcrOpts | OcrOpts[];
+}
+/**
+ * Top-level `transforms` block. Keys are glob path patterns matched against
+ * the storage key of every uploaded object. The adapter compiles each entry
+ * into a synthetic `storage.put` event handler that fans out the declared
+ * transforms via `Promise.all`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   transforms: {
+ *     'uploads/videos/**': {
+ *       transcode: [{ format: 'mp4' }, { format: 'webm' }],
+ *       thumbnail: { at: '1s', width: 640, format: 'jpg' },
+ *     },
+ *     'uploads/photos/**': {
+ *       variants: [
+ *         { width: 1600, format: 'webp', quality: 85 },
+ *         { width: 400,  format: 'webp', quality: 80 },
+ *       ],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+type TransformsConfig = Record<string, TransformsPatternSpec>;
+
+export { type DocConvertOpts as D, type ImageFormat as I, type JobHandle as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type DocFormat as b, type DocInsertQrCodeOpts as c, type DocReplaceImagesOpts as d, type DocTemplateMergeOpts as e, type DocThumbnailOpts as f, type DocToHtmlOpts as g, type DocToMarkdownOpts as h, type DocToPdfOpts as i, type ImageRef as j, type JobStatus as k, type JobStatusResponse as l, type QrPayload as m, type ThumbnailOpts as n, type TranscodeOpts as o, type TransformSpec as p, type TransformsService as q, keyFor as r, transforms as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.3.11",
+  "version": "0.4.1",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/remote-client.ts

@@ -1,5 +1,5 @@
 import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord } from './types.js';
-import type { TransformsService, TranscodeOpts, ThumbnailOpts, ResizeOpts, OcrOpts, JobHandle, JobStatusResponse, MediaInfo } from './transforms.js';
+import type { TransformsService, TranscodeOpts, ThumbnailOpts, ResizeOpts, OcrOpts, DocToPdfOpts, DocThumbnailOpts, DocConvertOpts, DocToMarkdownOpts, DocToHtmlOpts, DocReplaceImagesOpts, DocInsertQrCodeOpts, DocTemplateMergeOpts, JobHandle, JobStatusResponse, MediaInfo } from './transforms.js';
 import { RemoteMediaService } from './media.js';
 import { getRequestAuthHeader } from './request-scope.js';
 
@@ -1110,6 +1110,38 @@ class RemoteTransformsService implements TransformsService {
     return this.post<JobHandle>('/ocr', { srcKey, opts: opts ?? {} });
   }
 
+  docToPdf(srcKey: string, opts?: DocToPdfOpts | null): Promise<JobHandle> {
+    return this.post<JobHandle>('/doc_to_pdf', { srcKey, opts: opts ?? {} });
+  }
+
+  docThumbnail(srcKey: string, opts: DocThumbnailOpts): Promise<JobHandle> {
+    return this.post<JobHandle>('/doc_thumbnail', { srcKey, opts });
+  }
+
+  docConvert(srcKey: string, opts: DocConvertOpts): Promise<JobHandle> {
+    return this.post<JobHandle>('/doc_convert', { srcKey, opts });
+  }
+
+  docToMarkdown(srcKey: string, opts?: DocToMarkdownOpts | null): Promise<JobHandle> {
+    return this.post<JobHandle>('/doc_to_markdown', { srcKey, opts: opts ?? {} });
+  }
+
+  docToHtml(srcKey: string, opts?: DocToHtmlOpts | null): Promise<JobHandle> {
+    return this.post<JobHandle>('/doc_to_html', { srcKey, opts: opts ?? {} });
+  }
+
+  docReplaceImages(srcKey: string, opts: DocReplaceImagesOpts): Promise<JobHandle> {
+    return this.post<JobHandle>('/doc_replace_images', { srcKey, opts });
+  }
+
+  docInsertQrCode(srcKey: string, opts: DocInsertQrCodeOpts): Promise<JobHandle> {
+    return this.post<JobHandle>('/doc_insert_qr_code', { srcKey, opts });
+  }
+
+  docTemplateMerge(srcKey: string, opts: DocTemplateMergeOpts): Promise<JobHandle> {
+    return this.post<JobHandle>('/doc_template_merge', { srcKey, opts });
+  }
+
   probe(srcKey: string): Promise<MediaInfo> {
     return this.post<MediaInfo>('/probe', { srcKey });
   }

package/src/transforms.ts

@@ -71,12 +71,144 @@ export interface OcrOpts {
   lang?: string;
 }
 
+/**
+ * LibreOffice-supported output container for `doc_convert`. Each value
+ * maps to a `--convert-to` filter and a derived-key extension.
+ */
+export type DocFormat = 'pdf' | 'docx' | 'odt' | 'xlsx' | 'html' | 'txt' | 'rtf';
+
+/** Options for `transforms.docToPdf`. */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface DocToPdfOpts {}
+
+/** Options for `transforms.docThumbnail` — single-page raster of a document. */
+export interface DocThumbnailOpts {
+  width?: number;
+  height?: number;
+  /** Defaults to `"png"` server-side when omitted. */
+  format?: ImageFormat;
+  /** 1-indexed page. Defaults to `1` server-side when omitted. */
+  page?: number;
+  quality?: number;
+}
+
+/** Options for `transforms.docConvert` — generic LibreOffice conversion. */
+export interface DocConvertOpts {
+  to: DocFormat;
+}
+
+/** Options for `transforms.docToMarkdown` — RAG / LLM-friendly extraction. */
+export interface DocToMarkdownOpts {
+  /** Keep GFM tables in the output. Defaults to `true` server-side when omitted. */
+  preserve_tables?: boolean;
+}
+
+/**
+ * Options for `transforms.docToHtml` — single-file HTML with images
+ * inlined as base64 `data:` URIs and CSS inlined as `<style>` blocks.
+ * The output is a self-contained `.html` the caller can email, embed
+ * in an `<iframe>`, or hand to an LLM as one string.
+ */
+export interface DocToHtmlOpts {
+  /** Inline `<img>` references as base64 `data:` URIs. Defaults `true` server-side. */
+  inline_images?: boolean;
+  /** Inline CSS as a single `<style>` block. Defaults `true` server-side. */
+  inline_styles?: boolean;
+}
+
+/** Reference to a replacement image — its key in tenant `STORAGE`. */
+export interface ImageRef {
+  src_key: string;
+}
+
+/**
+ * Options for `transforms.docReplaceImages` — substitute placeholder
+ * text-tags and/or named drawing objects with caller-supplied images.
+ *
+ * Keys in `placeholders` are the literal text the user types in their
+ * template (e.g. `"{{USER_LOGO}}"`). Keys in `named_objects` are
+ * LibreOffice draw-object Name properties (set in Word/Writer via
+ * Format → Anchor → Properties → Name) — named-object swap preserves
+ * the template's exact frame size, border, anchor, and wrap.
+ */
+export interface DocReplaceImagesOpts {
+  /** Optional output format. When unset, the worker keeps the input format. */
+  output_format?: DocFormat;
+  /** `{{TAG}}` → image. The text is matched verbatim; missing tags are silently skipped. */
+  placeholders?: Record<string, ImageRef>;
+  /** `objectName` → image. */
+  named_objects?: Record<string, ImageRef>;
+  /** Pre-resize each image to the target frame's dimensions. Defaults `true` server-side. */
+  auto_resize?: boolean;
+}
+
+/** A single QR code to embed. Exactly one of `placeholder` or `named_object` must be set. */
+export interface QrCodeSpec {
+  placeholder?: string;
+  named_object?: string;
+  /** Payload to encode — typically a URL. ≤ 1500 bytes; the server rejects larger. */
+  payload: string;
+  /** Output PNG width in pixels. QR codes are square. Defaults to 256 server-side. */
+  size?: number;
+}
+
+/**
+ * Options for `transforms.docInsertQrCode` — generate QR PNG(s)
+ * server-side and inject them via the same pipeline as
+ * `docReplaceImages`.
+ */
+export interface DocInsertQrCodeOpts {
+  output_format?: DocFormat;
+  codes: QrCodeSpec[];
+}
+
+/** Inline QR-code spec for `DocTemplateMergeOpts.qr_codes`. The placeholder
+ *  is the map key, so we only carry payload + size here. */
+export interface QrPayload {
+  payload: string;
+  /** Output PNG width in pixels (square). Defaults to 256 server-side. */
+  size?: number;
+}
+
+/**
+ * Options for `transforms.docTemplateMerge` — the unified single-call
+ * template-fill: text + images + QR codes in one render. The headline
+ * templating API; one call → one server-side render → one round-trip.
+ *
+ * `data` runs first (string find-and-replace), then `images` (text-tag →
+ * image insertion), then `named_objects` (preserves frame size/border),
+ * then `qr_codes` (server generates each PNG and injects via the same
+ * placeholder pipeline as `images`). All inside one document load.
+ */
+export interface DocTemplateMergeOpts {
+  /** Output format. Defaults to keeping the input format. */
+  output_format?: DocFormat;
+  /** Text-tag → string. e.g. `{ '{{NAME}}': 'Senol Aktas' }`. */
+  data?: Record<string, string>;
+  /** Text-tag → image. Same semantics as `DocReplaceImagesOpts.placeholders`. */
+  images?: Record<string, ImageRef>;
+  /** Object-name → image. Preserves the template's frame size/border/wrap. */
+  named_objects?: Record<string, ImageRef>;
+  /** Text-tag → QR code spec. Server generates the PNG; ≤ 1500-byte payload. */
+  qr_codes?: Record<string, QrPayload>;
+  /** Pre-resize images / QR PNGs to anchor frames. Defaults `true`. */
+  auto_resize?: boolean;
+}
+
 /** Tagged union of all transform requests — matches the Rust `TransformSpec`. */
 export type TransformSpec =
   | ({ kind: 'transcode' } & TranscodeOpts)
   | ({ kind: 'thumbnail' } & ThumbnailOpts)
   | ({ kind: 'resize' } & ResizeOpts)
-  | ({ kind: 'ocr' } & OcrOpts);
+  | ({ kind: 'ocr' } & OcrOpts)
+  | ({ kind: 'doc_to_pdf' } & DocToPdfOpts)
+  | ({ kind: 'doc_thumbnail' } & DocThumbnailOpts)
+  | ({ kind: 'doc_convert' } & DocConvertOpts)
+  | ({ kind: 'doc_to_markdown' } & DocToMarkdownOpts)
+  | ({ kind: 'doc_to_html' } & DocToHtmlOpts)
+  | ({ kind: 'doc_replace_images' } & DocReplaceImagesOpts)
+  | ({ kind: 'doc_insert_qr_code' } & DocInsertQrCodeOpts)
+  | ({ kind: 'doc_template_merge' } & DocTemplateMergeOpts);
 
 /** Probe output. All fields optional — ffprobe doesn't fill every one for every input. */
 export interface MediaInfo {
@@ -111,6 +243,22 @@ export interface TransformsService {
   resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
   probe(srcKey: string): Promise<MediaInfo>;
   ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
+  /** Convert a LibreOffice-supported document to PDF. */
+  docToPdf(srcKey: string, opts?: DocToPdfOpts | null): Promise<JobHandle>;
+  /** Render a single page of a document as a raster thumbnail. */
+  docThumbnail(srcKey: string, opts: DocThumbnailOpts): Promise<JobHandle>;
+  /** Generic LibreOffice format conversion. */
+  docConvert(srcKey: string, opts: DocConvertOpts): Promise<JobHandle>;
+  /** Extract Markdown from a document (HTML → pandoc pipeline). */
+  docToMarkdown(srcKey: string, opts?: DocToMarkdownOpts | null): Promise<JobHandle>;
+  /** Convert to single-file HTML with base64-inlined images and inlined CSS. */
+  docToHtml(srcKey: string, opts?: DocToHtmlOpts | null): Promise<JobHandle>;
+  /** Swap placeholder text-tags and/or named drawing objects with caller-supplied images. */
+  docReplaceImages(srcKey: string, opts: DocReplaceImagesOpts): Promise<JobHandle>;
+  /** Generate QR codes server-side and inject them via the image-replace pipeline. */
+  docInsertQrCode(srcKey: string, opts: DocInsertQrCodeOpts): Promise<JobHandle>;
+  /** Unified template fill: text + images + QR codes in one render. The headline templating API. */
+  docTemplateMerge(srcKey: string, opts: DocTemplateMergeOpts): Promise<JobHandle>;
   job(id: string): Promise<JobStatusResponse>;
 }
 
@@ -164,6 +312,29 @@ function outputExtension(spec: TransformSpec): string {
     }
     case 'ocr':
       return 'txt';
+    case 'doc_to_pdf':
+      return 'pdf';
+    case 'doc_thumbnail': {
+      // `format` defaults to png server-side — mirror so the canonical
+      // JSON the Rust impl hashes matches the JS one for default-shape
+      // requests.
+      const fmt = (spec as { format?: ImageFormat }).format ?? 'png';
+      return fmt;
+    }
+    case 'doc_convert':
+      return spec.to;
+    case 'doc_to_markdown':
+      return 'md';
+    case 'doc_to_html':
+      return 'html';
+    case 'doc_replace_images':
+    case 'doc_insert_qr_code':
+    case 'doc_template_merge':
+      // Mirror the Rust fallback: when output_format is omitted the
+      // result preserves the input format, which we don't know without
+      // inspecting bytes — fall back to docx (the dominant template
+      // format).
+      return spec.output_format ?? 'docx';
     default: {
       const _exhaust: never = spec;
       throw new Error(`unknown transform kind: ${(_exhaust as { kind: string }).kind}`);