@robodev-ai/runtime 0.4.2 → 0.5.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.4.2",
-  "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.1",
+  "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.1"
+    "@robodev-ai/sdk": "0.13.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/index.ts

@@ -3,7 +3,7 @@
  * 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, the offline `robodev dev` jobs engine,
- * and email template rendering.
+ * email template rendering, and the offline PDF hop client.
  */
 
 export {
@@ -323,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: {
@@ -420,6 +421,24 @@ test("missing handler is route_not_found", async () => {
   await waitUntil(() => store.jobs[0]?.last_error === "route_not_found");
 });
 
+test("handler receives clients.storage", async () => {
+  const store = memoryJobs();
+  const clients = mockClients();
+  const seen: unknown[] = [];
+  const engine = createLocalJobsEngine({
+    query: store.query,
+    getGeneration: () => ({
+      db: {} as RobodevDb,
+      jobs: [{ name: "digest", def: jobDef((ctx) => seen.push(ctx.storage)) }],
+    }),
+    clients: () => clients,
+  });
+  await engine.enqueue({ name: "digest" });
+  await engine.tickJobs();
+  await waitUntil(() => store.jobs[0]?.status === "succeeded");
+  assert.equal(seen[0], clients.storage);
+});
+
 test("hosted-only clients still throw in job handlers; email is real", async () => {
   const store = memoryJobs();
   const seen: string[] = [];

package/src/local-jobs.ts

@@ -304,6 +304,8 @@ export function createLocalJobsEngine(options: LocalJobsEngineOptions): LocalJob
           push: clients.push,
           jobs: clients.jobs,
           sockets: clients.sockets,
+          pdf: clients.pdf,
+          storage: clients.storage,
           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");
+    },
+  };
+}