@robodev-ai/runtime 0.4.1 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.4.1",
-  "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth, the socket engine, and local file storage. Shared by hosted Starbase and `robodev dev`.",
+  "version": "0.5.0",
+  "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth, the socket engine, local file storage, and the offline PDF hop client. Shared by hosted Starbase and `robodev dev`.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "pg": "^8.16.3",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@robodev-ai/sdk": "0.11.0"
+    "@robodev-ai/sdk": "0.12.0"
   },
   "devDependencies": {
     "@types/busboy": "^1.5.4",

package/src/compile-invoke.test.ts

@@ -81,6 +81,7 @@ function stubClients(): RouteClients {
       destroy: missing,
     },
     storage: { upload: missing, get: missing, getUrl: missing, delete: missing, list: missing },
+    pdf: { fromHtml: missing },
     push: { send: missing },
     jobs: { enqueue: missing },
     sockets: { send: missing, broadcast: missing },

package/src/email-templates.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  escapeEmailHtml,
+  extractTemplateVars,
+  htmlToPlainText,
+  isCustomEmailSlug,
+  loadLocalEmailTemplate,
+  mergeCustomTemplateVariables,
+  renderEmailFields,
+  renderEmailTemplate,
+  resolveEmailSendInput,
+} from "./email-templates.js";
+
+test("renderEmailTemplate replaces whitespace-tolerant vars", () => {
+  assert.equal(renderEmailTemplate("Hi {{ name }}", { name: "Ada" }), "Hi Ada");
+  assert.equal(renderEmailTemplate("Hi {{name}}", { name: "Ada" }), "Hi Ada");
+  assert.equal(renderEmailTemplate("Hi {{ missing }}", {}), "Hi ");
+  assert.equal(renderEmailTemplate("Hi {{1bad}}", { "1bad": "x" }), "Hi {{1bad}}");
+});
+
+test("renderEmailTemplate HTML-escapes only in html mode", () => {
+  assert.equal(
+    renderEmailTemplate("<p>{{name}}</p>", { name: `<a>"'` }, { html: true }),
+    `<p>${escapeEmailHtml(`<a>"'`)}</p>`,
+  );
+  assert.equal(renderEmailTemplate("{{name}}", { name: "<x>" }), "<x>");
+});
+
+test("extractTemplateVars unions unique names in order", () => {
+  assert.deepEqual(extractTemplateVars("{{email}} {{name}}", "{{email}} {{link}}"), [
+    "email",
+    "name",
+    "link",
+  ]);
+});
+
+test("htmlToPlainText strips tags", () => {
+  assert.equal(htmlToPlainText("<p>Your reset code is <code>123</code>.</p>"), "Your reset code is 123 .");
+});
+
+test("resolveEmailSendInput renders catalog then applies overrides", () => {
+  const resolved = resolveEmailSendInput(
+    {
+      to: "a@b.com",
+      template: "welcome",
+      vars: { name: "Ada" },
+      subject: "Override",
+    },
+    { subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>", text: "Hello {{name}}" },
+  );
+  assert.equal(resolved.subject, "Override");
+  assert.equal(resolved.html, "<p>Hello Ada</p>");
+  assert.equal(resolved.text, "Hello Ada");
+});
+
+test("resolveEmailSendInput throws template_not_found without catalog or body", () => {
+  assert.throws(
+    () => resolveEmailSendInput({ to: "a@b.com", template: "missing" }, null),
+    (error: unknown) => error instanceof Error && error.message === "template_not_found",
+  );
+});
+
+test("loadLocalEmailTemplate reads html plus optional json", async () => {
+  const root = await mkdtemp(join(tmpdir(), "robodev-emails-"));
+  await mkdir(join(root, "robodev", "emails"), { recursive: true });
+  await writeFile(join(root, "robodev", "emails", "welcome.html"), "<p>Hi {{name}}</p>", "utf8");
+  await writeFile(
+    join(root, "robodev", "emails", "welcome.json"),
+    JSON.stringify({ subject: "Hello", text: "Hi {{name}}" }),
+    "utf8",
+  );
+  const loaded = await loadLocalEmailTemplate(root, "welcome");
+  assert.deepEqual(loaded, {
+    slug: "welcome",
+    subject: "Hello",
+    html: "<p>Hi {{name}}</p>",
+    text: "Hi {{name}}",
+  });
+  assert.equal(await loadLocalEmailTemplate(root, "missing"), null);
+});
+
+test("custom slug and variable merge rules", () => {
+  assert.equal(isCustomEmailSlug("welcome"), true);
+  assert.equal(isCustomEmailSlug("auth.welcome"), false);
+  assert.equal(isCustomEmailSlug("Welcome"), false);
+  assert.deepEqual(mergeCustomTemplateVariables(["email", "name"], ["extra", "email", "1bad"]), [
+    "email",
+    "name",
+    "extra",
+  ]);
+});
+
+test("renderEmailFields derives plaintext when text is empty", () => {
+  const rendered = renderEmailFields(
+    { subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>", text: "" },
+    { name: "Ada" },
+  );
+  assert.equal(rendered.subject, "Hi Ada");
+  assert.equal(rendered.html, "<p>Hello Ada</p>");
+  assert.equal(rendered.text, "Hello Ada");
+});

package/src/email-templates.ts

@@ -0,0 +1,169 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { EmailSendInput } from "@robodev-ai/sdk";
+
+export const EMAIL_TEMPLATE_VAR_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+export const EMAIL_TEMPLATE_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const EMAIL_TEMPLATE_MAX_VARS = 32;
+export const EMAIL_TEMPLATE_MAX_VAR_NAME = 40;
+export const EMAIL_TEMPLATE_MAX_BYTES = 200 * 1024;
+export const EMAIL_TEMPLATE_MAX_SUBJECT = 200;
+export const EMAIL_TEMPLATE_MAX_CUSTOM = 40;
+export const CUSTOM_EMAIL_SLUG_RE = /^[a-z][a-z0-9-]{0,62}$/;
+
+export const SYSTEM_EMAIL_SLUGS = ["auth.welcome", "auth.magic-link", "auth.forgot-password"] as const;
+export type SystemEmailSlug = (typeof SYSTEM_EMAIL_SLUGS)[number];
+
+export type EmailTemplateKind = "system" | "custom";
+
+export type LocalEmailTemplate = {
+  slug: string;
+  subject: string;
+  html: string;
+  text: string;
+};
+
+export type EmailTemplateVars = Record<string, string | number | boolean>;
+
+export function isSystemEmailSlug(slug: string): slug is SystemEmailSlug {
+  return (SYSTEM_EMAIL_SLUGS as readonly string[]).includes(slug);
+}
+
+export function isCustomEmailSlug(slug: string): boolean {
+  return CUSTOM_EMAIL_SLUG_RE.test(slug) && !slug.startsWith("auth.");
+}
+
+export function escapeEmailHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+export function htmlToPlainText(html: string): string {
+  return html
+    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, " ")
+    .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function extractTemplateVars(...parts: Array<string | null | undefined>): string[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const part of parts) {
+    if (!part) continue;
+    const re = new RegExp(EMAIL_TEMPLATE_VAR_RE.source, "g");
+    for (const match of part.matchAll(re)) {
+      const name = match[1] ?? "";
+      if (!name || seen.has(name)) continue;
+      seen.add(name);
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+export function renderEmailTemplate(
+  template: string,
+  vars: EmailTemplateVars = {},
+  options: { html?: boolean } = {},
+): string {
+  return template.replace(EMAIL_TEMPLATE_VAR_RE, (token, name: string) => {
+    if (!Object.prototype.hasOwnProperty.call(vars, name)) return "";
+    const raw = vars[name];
+    const value = raw == null ? "" : String(raw);
+    return options.html ? escapeEmailHtml(value) : value;
+  });
+}
+
+export function renderEmailFields(
+  input: { subject: string; html: string; text?: string },
+  vars: EmailTemplateVars = {},
+): { subject: string; html: string; text: string } {
+  const html = renderEmailTemplate(input.html, vars, { html: true });
+  const textSource = input.text?.trim()
+    ? renderEmailTemplate(input.text, vars)
+    : htmlToPlainText(html);
+  return {
+    subject: renderEmailTemplate(input.subject, vars),
+    html,
+    text: textSource,
+  };
+}
+
+export function localEmailTemplatePaths(slug: string): { html: string; json: string } {
+  return {
+    html: `robodev/emails/${slug}.html`,
+    json: `robodev/emails/${slug}.json`,
+  };
+}
+
+export async function loadLocalEmailTemplate(
+  projectRoot: string,
+  slug: string,
+): Promise<LocalEmailTemplate | null> {
+  const paths = localEmailTemplatePaths(slug);
+  let html: string;
+  try {
+    html = await readFile(join(projectRoot, paths.html), "utf8");
+  } catch {
+    return null;
+  }
+  let subject = "";
+  let text = "";
+  try {
+    const raw = await readFile(join(projectRoot, paths.json), "utf8");
+    const parsed = JSON.parse(raw) as { subject?: unknown; text?: unknown };
+    if (typeof parsed.subject === "string") subject = parsed.subject;
+    if (typeof parsed.text === "string") text = parsed.text;
+  } catch {
+    /* html-only catalog row */
+  }
+  return { slug, subject, html, text };
+}
+
+export function resolveEmailSendInput(
+  input: EmailSendInput,
+  catalog: { subject: string; html: string; text?: string } | null,
+): EmailSendInput {
+  if (!input.template) return input;
+  if (!catalog) {
+    if (input.html || input.text) return input;
+    throw Object.assign(new Error("template_not_found"), { code: "template_not_found" });
+  }
+  const rendered = renderEmailFields(catalog, input.vars ?? {});
+  return {
+    ...input,
+    subject: input.subject ?? rendered.subject,
+    html: input.html ?? rendered.html,
+    text: input.text ?? rendered.text,
+  };
+}
+
+export function mergeCustomTemplateVariables(
+  extracted: readonly string[],
+  extras: readonly string[] = [],
+): string[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const name of [...extracted, ...extras]) {
+    if (!EMAIL_TEMPLATE_VAR_NAME_RE.test(name) || name.length > EMAIL_TEMPLATE_MAX_VAR_NAME) {
+      continue;
+    }
+    if (seen.has(name)) continue;
+    seen.add(name);
+    names.push(name);
+    if (names.length >= EMAIL_TEMPLATE_MAX_VARS) break;
+  }
+  return names;
+}

package/src/index.ts

@@ -2,7 +2,8 @@
  * `@robodev-ai/runtime` — the project runtime shared by hosted Starbase deploys and the
  * offline `robodev dev` loop: deploy-file classification, the esbuild compile, module
  * loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth,
- * the socket engine, local file storage, and the offline `robodev dev` jobs engine.
+ * the socket engine, local file storage, the offline `robodev dev` jobs engine,
+ * email template rendering, and the offline PDF hop client.
  */
 
 export {
@@ -279,6 +280,33 @@ export {
   type StorageQueryable,
 } from "./local-storage.js";
 
+export {
+  CUSTOM_EMAIL_SLUG_RE,
+  EMAIL_TEMPLATE_MAX_BYTES,
+  EMAIL_TEMPLATE_MAX_CUSTOM,
+  EMAIL_TEMPLATE_MAX_SUBJECT,
+  EMAIL_TEMPLATE_MAX_VAR_NAME,
+  EMAIL_TEMPLATE_MAX_VARS,
+  EMAIL_TEMPLATE_VAR_NAME_RE,
+  EMAIL_TEMPLATE_VAR_RE,
+  SYSTEM_EMAIL_SLUGS,
+  escapeEmailHtml,
+  extractTemplateVars,
+  htmlToPlainText,
+  isCustomEmailSlug,
+  isSystemEmailSlug,
+  loadLocalEmailTemplate,
+  localEmailTemplatePaths,
+  mergeCustomTemplateVariables,
+  renderEmailFields,
+  renderEmailTemplate,
+  resolveEmailSendInput,
+  type EmailTemplateKind,
+  type EmailTemplateVars,
+  type LocalEmailTemplate,
+  type SystemEmailSlug,
+} from "./email-templates.js";
+
 export {
   LOCAL_DEV_IDENTITY_AUD,
   LOCAL_DEV_IDENTITY_TYP,
@@ -295,3 +323,22 @@ export {
   verifyLocalDevIdentityAssertion,
   verifyLocalGoogleState,
 } from "./local-google.js";
+
+export {
+  DEFAULT_STARBASE_URL,
+  PDF_DEFAULT_MARGIN_IN,
+  PDF_HOP_TIMEOUT_MS,
+  PDF_HTML_MAX_BYTES,
+  PDF_PAGE_FORMATS,
+  PDF_RESPONSE_MAX_BYTES,
+  brokerPdfUrl,
+  createHopPdfClient,
+  hopError,
+  hopPdfBodySchema,
+  hopStarbaseUrl,
+  isPdfBytes,
+  parsePdfHtml,
+  pdfFromHtmlOptionsSchema,
+  resolvePdfOptions,
+  type ResolvedPdfOptions,
+} from "./local-pdf.js";

package/src/invoke.ts

@@ -5,6 +5,7 @@ import type {
   EmailClient,
   JobsClient,
   LlmClient,
+  PdfClient,
   PushClient,
   RobodevDb,
   SocketsClient,
@@ -28,6 +29,7 @@ export type RouteClients = {
   llm: LlmClient;
   agent: AgentClient;
   storage: StorageClient;
+  pdf: PdfClient;
   push: PushClient;
   jobs: JobsClient;
   sockets: SocketsClient;
@@ -179,6 +181,7 @@ export async function runRoute(input: RunRouteInput): Promise<RouteOutcome> {
       llm: clients.llm,
       agent: clients.agent,
       storage: clients.storage,
+      pdf: clients.pdf,
       env: clients.env,
       params,
       query: query as never,

package/src/local-jobs.test.ts

@@ -68,6 +68,7 @@ function mockClients(): RouteClients {
         return { objects: [], total: 0 };
       },
     },
+    pdf: { fromHtml: async () => Buffer.from("%PDF-1.4") },
     push: { send: () => notConfigured("push_not_configured") },
     jobs: { enqueue: async () => ({ id: "nested" }) },
     sockets: {

package/src/local-jobs.ts

@@ -304,6 +304,7 @@ export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJob
           push: clients.push,
           jobs: clients.jobs,
           sockets: clients.sockets,
+          pdf: clients.pdf,
           payload,
         });
       }, clampTimeoutMs(job.def.timeoutMs));

package/src/local-pdf.test.ts

@@ -0,0 +1,167 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  DEFAULT_STARBASE_URL,
+  brokerPdfUrl,
+  createHopPdfClient,
+  hopStarbaseUrl,
+  parsePdfHtml,
+  resolvePdfOptions,
+} from "./local-pdf.js";
+
+function pdfResponse(body: Uint8Array | string = "%PDF-1.4 hop", status = 200): Response {
+  const bytes = typeof body === "string" ? Buffer.from(body) : Buffer.from(body);
+  return new Response(bytes, {
+    status,
+    headers: { "content-type": "application/pdf" },
+  });
+}
+
+test("brokerPdfUrl strips trailing slash", () => {
+  assert.equal(
+    brokerPdfUrl("https://robodev.povio.dev/"),
+    "https://robodev.povio.dev/internal/pdf",
+  );
+  assert.equal(brokerPdfUrl("http://localhost:4000"), "http://localhost:4000/internal/pdf");
+});
+
+test("hopStarbaseUrl defaults to production and honors STARBASE_URL", () => {
+  assert.equal(hopStarbaseUrl({}), DEFAULT_STARBASE_URL);
+  assert.equal(hopStarbaseUrl({ STARBASE_URL: "http://localhost:4000/" }), "http://localhost:4000");
+  assert.equal(hopStarbaseUrl({ STARBASE_URL: "" }), "");
+});
+
+test("parsePdfHtml rejects empty and oversized html", () => {
+  assert.throws(
+    () => parsePdfHtml(""),
+    (err: unknown) => {
+      return err instanceof Error && err.message === "invalid_request";
+    },
+  );
+  assert.throws(
+    () => parsePdfHtml("   "),
+    (err: unknown) => {
+      return err instanceof Error && err.message === "invalid_request";
+    },
+  );
+  assert.throws(
+    () => parsePdfHtml(1),
+    (err: unknown) => {
+      return err instanceof Error && err.message === "invalid_request";
+    },
+  );
+  const huge = "x".repeat(512 * 1024 + 1);
+  assert.throws(
+    () => parsePdfHtml(huge),
+    (err: unknown) => {
+      return err instanceof Error && err.message === "pdf_too_large";
+    },
+  );
+  assert.equal(parsePdfHtml("  <p>ok</p>  "), "<p>ok</p>");
+});
+
+test("resolvePdfOptions applies defaults and rejects bad values", () => {
+  assert.deepEqual(resolvePdfOptions(), {
+    format: "A4",
+    landscape: false,
+    margin: { top: 0.39, right: 0.39, bottom: 0.39, left: 0.39 },
+  });
+  assert.deepEqual(resolvePdfOptions({ format: "Letter", landscape: true, margin: 0.5 }), {
+    format: "Letter",
+    landscape: true,
+    margin: { top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 },
+  });
+  assert.deepEqual(resolvePdfOptions({ margin: { top: 0.1 } }), {
+    format: "A4",
+    landscape: false,
+    margin: { top: 0.1, right: 0.39, bottom: 0.39, left: 0.39 },
+  });
+  assert.throws(() => resolvePdfOptions({ format: "A3" as "A4" }), /invalid_request/);
+  assert.throws(
+    () => resolvePdfOptions({ landscape: "yes" as unknown as boolean }),
+    /invalid_request/,
+  );
+  assert.throws(() => resolvePdfOptions({ margin: 2.1 }), /invalid_request/);
+  assert.throws(() => resolvePdfOptions({ margin: { left: -1 } }), /invalid_request/);
+});
+
+test("createHopPdfClient uses process STARBASE_URL and maps hop error codes", async () => {
+  const previous = process.env.STARBASE_URL;
+  process.env.STARBASE_URL = "http://starbase.test:4000/";
+  let url = "";
+  const client = createHopPdfClient({
+    fetch: async (input) => {
+      url = String(input);
+      return new Response(JSON.stringify({ error: "pdf_rate_limited" }), {
+        status: 429,
+        headers: { "content-type": "application/json" },
+      });
+    },
+  });
+  await assert.rejects(
+    () => client.fromHtml("<html>hi</html>"),
+    (err: unknown) => {
+      return err instanceof Error && err.message === "pdf_rate_limited";
+    },
+  );
+  assert.equal(url, "http://starbase.test:4000/internal/pdf");
+  if (previous === undefined) delete process.env.STARBASE_URL;
+  else process.env.STARBASE_URL = previous;
+});
+
+test("createHopPdfClient defaults to production URL", async () => {
+  const previous = process.env.STARBASE_URL;
+  delete process.env.STARBASE_URL;
+  let url = "";
+  const client = createHopPdfClient({
+    fetch: async (input) => {
+      url = String(input);
+      return pdfResponse();
+    },
+  });
+  const pdf = await client.fromHtml("<html>ok</html>");
+  assert.equal(url, `${DEFAULT_STARBASE_URL}/internal/pdf`);
+  assert.ok(pdf.toString("utf8").startsWith("%PDF"));
+  if (previous === undefined) delete process.env.STARBASE_URL;
+  else process.env.STARBASE_URL = previous;
+});
+
+test("createHopPdfClient maps unconfigured blank STARBASE_URL and network failure", async () => {
+  const blank = createHopPdfClient({ baseUrl: "" });
+  await assert.rejects(() => blank.fromHtml("<p>x</p>"), /pdf_unconfigured/);
+
+  const down = createHopPdfClient({
+    baseUrl: "http://localhost:9",
+    fetch: async () => {
+      throw new Error("connect ECONNREFUSED");
+    },
+  });
+  await assert.rejects(() => down.fromHtml("<p>x</p>"), /pdf_failed/);
+});
+
+test("createHopPdfClient maps JSON hop codes and non-PDF 200", async () => {
+  const codes = ["invalid_request", "pdf_unconfigured", "pdf_too_large", "pdf_failed"] as const;
+  for (const code of codes) {
+    const client = createHopPdfClient({
+      baseUrl: "https://robodev.povio.dev",
+      fetch: async () =>
+        new Response(JSON.stringify({ error: code }), {
+          status: 400,
+          headers: { "content-type": "application/json" },
+        }),
+    });
+    await assert.rejects(
+      () => client.fromHtml("<p>x</p>"),
+      (err: unknown) => {
+        return err instanceof Error && err.message === code;
+      },
+    );
+  }
+
+  const notPdf = createHopPdfClient({
+    baseUrl: "https://robodev.povio.dev",
+    fetch: async () =>
+      new Response("not a pdf", { status: 200, headers: { "content-type": "text/html" } }),
+  });
+  await assert.rejects(() => notPdf.fromHtml("<p>x</p>"), /pdf_failed/);
+});

package/src/local-pdf.ts

@@ -0,0 +1,195 @@
+import { z } from "zod";
+import type { PdfClient, PdfFromHtmlOptions, PdfPageFormat } from "@robodev-ai/sdk";
+
+export const DEFAULT_STARBASE_URL = "https://robodev.povio.dev";
+export const PDF_HOP_TIMEOUT_MS = 15_000;
+export const PDF_HTML_MAX_BYTES = 512 * 1024;
+export const PDF_RESPONSE_MAX_BYTES = 8 * 1024 * 1024;
+export const PDF_DEFAULT_MARGIN_IN = 0.39;
+export const PDF_PAGE_FORMATS = ["A4", "Letter", "Legal"] as const;
+
+const pageFormatSchema = z.enum(PDF_PAGE_FORMATS);
+const marginSideSchema = z.number().finite().min(0).max(2);
+const marginBoxSchema = z.object({
+  top: marginSideSchema.optional(),
+  right: marginSideSchema.optional(),
+  bottom: marginSideSchema.optional(),
+  left: marginSideSchema.optional(),
+});
+
+export const pdfFromHtmlOptionsSchema = z.object({
+  format: pageFormatSchema.optional(),
+  landscape: z.boolean().optional(),
+  margin: z.union([marginSideSchema, marginBoxSchema]).optional(),
+});
+
+export const hopPdfBodySchema = z.object({
+  html: z.string(),
+  options: pdfFromHtmlOptionsSchema.optional(),
+});
+
+export type ResolvedPdfOptions = {
+  format: PdfPageFormat;
+  landscape: boolean;
+  margin: { top: number; right: number; bottom: number; left: number };
+};
+
+export function hopError(code: string): Error {
+  return Object.assign(new Error(code), { code });
+}
+
+export function hopStarbaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const raw = env.STARBASE_URL;
+  if (raw === undefined) return DEFAULT_STARBASE_URL;
+  return raw.replace(/\/$/, "");
+}
+
+export function brokerPdfUrl(base: string): string {
+  return `${base.replace(/\/$/, "")}/internal/pdf`;
+}
+
+export function resolvePdfOptions(options?: PdfFromHtmlOptions): ResolvedPdfOptions {
+  const parsed = pdfFromHtmlOptionsSchema.safeParse(options ?? {});
+  if (!parsed.success) {
+    throw hopError("invalid_request");
+  }
+  const margin = parsed.data.margin;
+  const sides =
+    typeof margin === "number"
+      ? { top: margin, right: margin, bottom: margin, left: margin }
+      : {
+          top: margin?.top ?? PDF_DEFAULT_MARGIN_IN,
+          right: margin?.right ?? PDF_DEFAULT_MARGIN_IN,
+          bottom: margin?.bottom ?? PDF_DEFAULT_MARGIN_IN,
+          left: margin?.left ?? PDF_DEFAULT_MARGIN_IN,
+        };
+  return {
+    format: parsed.data.format ?? "A4",
+    landscape: parsed.data.landscape ?? false,
+    margin: sides,
+  };
+}
+
+export function parsePdfHtml(html: unknown): string {
+  if (typeof html !== "string" || !html.trim()) {
+    throw hopError("invalid_request");
+  }
+  const trimmed = html.trim();
+  if (Buffer.byteLength(trimmed, "utf8") > PDF_HTML_MAX_BYTES) {
+    throw hopError("pdf_too_large");
+  }
+  return trimmed;
+}
+
+export function isPdfBytes(bytes: Uint8Array, contentType?: string | null): boolean {
+  const type = (contentType ?? "").split(";")[0]?.trim().toLowerCase();
+  if (type === "application/pdf") return true;
+  return (
+    bytes.length >= 4 &&
+    bytes[0] === 0x25 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x44 &&
+    bytes[3] === 0x46
+  );
+}
+
+async function readCappedBytes(response: Response, maxBytes: number): Promise<Buffer> {
+  const contentLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+    throw hopError("pdf_too_large");
+  }
+  if (!response.body) {
+    const buf = Buffer.from(await response.arrayBuffer());
+    if (buf.byteLength > maxBytes) throw hopError("pdf_too_large");
+    return buf;
+  }
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => undefined);
+      throw hopError("pdf_too_large");
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks);
+}
+
+function hopErrorFromBody(body: unknown): Error | null {
+  if (!body || typeof body !== "object") return null;
+  const error = (body as { error?: unknown }).error;
+  if (typeof error !== "string" || !error) return null;
+  return hopError(error);
+}
+
+export function createHopPdfClient(
+  options: {
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+  } = {},
+): PdfClient {
+  const fetchImpl = options.fetch ?? fetch;
+  const timeoutMs = options.timeoutMs ?? PDF_HOP_TIMEOUT_MS;
+
+  return {
+    async fromHtml(html, pdfOptions) {
+      const resolvedHtml = parsePdfHtml(html);
+      const resolved = resolvePdfOptions(pdfOptions);
+      const baseUrl = options.baseUrl ?? hopStarbaseUrl();
+      if (!baseUrl.trim()) {
+        throw hopError("pdf_unconfigured");
+      }
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      let response: Response;
+      try {
+        response = await fetchImpl(brokerPdfUrl(baseUrl), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            html: resolvedHtml,
+            options: {
+              format: resolved.format,
+              landscape: resolved.landscape,
+              margin: resolved.margin,
+            },
+          }),
+          signal: controller.signal,
+        });
+      } catch {
+        throw hopError("pdf_failed");
+      } finally {
+        clearTimeout(timer);
+      }
+
+      if (response.status === 200) {
+        let bytes: Buffer;
+        try {
+          bytes = await readCappedBytes(response, PDF_RESPONSE_MAX_BYTES);
+        } catch (error) {
+          if (error instanceof Error && (error as { code?: string }).code === "pdf_too_large") {
+            throw error;
+          }
+          throw hopError("pdf_failed");
+        }
+        if (!isPdfBytes(bytes, response.headers.get("content-type"))) {
+          throw hopError("pdf_failed");
+        }
+        return bytes;
+      }
+
+      let parsed: unknown = null;
+      try {
+        parsed = await response.json();
+      } catch {
+        throw hopError("pdf_failed");
+      }
+      throw hopErrorFromBody(parsed) ?? hopError("pdf_failed");
+    },
+  };
+}