@struktur/sdk 2.1.1 → 2.2.0

package/src/parsers/pdf.test.ts

@@ -1,394 +0,0 @@
-import { test, expect, mock } from "bun:test";
-
-// ---------------------------------------------------------------------------
-// Stub for pdf-parse: we control what getText() and getImage() return so we
-// can test parsePdf without a real PDF file.
-// ---------------------------------------------------------------------------
-
-type TextPage = { num: number; text: string };
-type EmbeddedImageStub = { dataUrl: string; width: number; height: number };
-type PageImagesStub = { pageNumber: number; images: EmbeddedImageStub[] };
-type ScreenshotPageStub = { pageNumber: number; dataUrl: string; width: number; height: number };
-
-// Configurable stubs — tests update these before importing parsePdf.
-let stubTextPages: TextPage[] = [];
-let stubTextFull = "";
-let stubImagePages: PageImagesStub[] = [];
-let stubScreenshotPages: ScreenshotPageStub[] = [];
-let stubGetImageThrows = false;
-let stubGetScreenshotThrows = false;
-
-mock.module("pdf-parse", () => ({
-  PDFParse: class {
-    constructor(_opts: unknown) {}
-    async getText() {
-      return {
-        pages: stubTextPages,
-        text: stubTextFull,
-        total: stubTextPages.length || 1,
-      };
-    }
-    async getImage(_params?: unknown) {
-      if (stubGetImageThrows) throw new Error("image extraction failed");
-      return {
-        pages: stubImagePages,
-        total: stubImagePages.length,
-      };
-    }
-    async getScreenshot(_params?: unknown) {
-      if (stubGetScreenshotThrows) throw new Error("screenshot rendering failed");
-      return {
-        pages: stubScreenshotPages,
-        total: stubScreenshotPages.length,
-      };
-    }
-    async getInfo() {
-      return { Title: "Test PDF" };
-    }
-    async destroy() {}
-  },
-}));
-
-// Import after mock is registered
-const { parsePdf } = await import("./pdf");
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function makeBuffer() {
-  return Buffer.from("%PDF-1.4 fake");
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-test("parsePdf extracts per-page text when pages are present", async () => {
-  stubTextPages = [
-    { num: 1, text: "Hello page one" },
-    { num: 2, text: "Hello page two" },
-  ];
-  stubTextFull = "Hello page one\nHello page two";
-  stubImagePages = [];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.type).toBe("pdf");
-  expect(artifact.contents).toHaveLength(2);
-  expect(artifact.contents[0]).toEqual({ page: 1, text: "Hello page one" });
-  expect(artifact.contents[1]).toEqual({ page: 2, text: "Hello page two" });
-});
-
-test("parsePdf falls back to full text when no pages are returned", async () => {
-  stubTextPages = [];
-  stubTextFull = "entire document text";
-  stubImagePages = [];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.contents).toHaveLength(1);
-  expect(artifact.contents[0]?.text).toBe("entire document text");
-  expect(artifact.contents[0]?.page).toBeUndefined();
-});
-
-test("parsePdf attaches images to the matching page content entry", async () => {
-  stubTextPages = [
-    { num: 1, text: "Page with image" },
-    { num: 2, text: "Page without image" },
-  ];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 1,
-      images: [{ dataUrl: "data:image/png;base64,abc123", width: 100, height: 50 }],
-    },
-  ];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.contents).toHaveLength(2);
-
-  const page1 = artifact.contents[0]!;
-  expect(page1.page).toBe(1);
-  expect(page1.text).toBe("Page with image");
-  expect(page1.media).toHaveLength(1);
-  expect(page1.media![0]).toMatchObject({
-    type: "image",
-    base64: "abc123",
-    width: 100,
-    height: 50,
-  });
-
-  const page2 = artifact.contents[1]!;
-  expect(page2.page).toBe(2);
-  expect(page2.media).toBeUndefined();
-});
-
-test("parsePdf strips data URL prefix to produce raw base64", async () => {
-  stubTextPages = [{ num: 1, text: "text" }];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 1,
-      images: [{ dataUrl: "data:image/jpeg;base64,/9j/4AAQ==", width: 200, height: 200 }],
-    },
-  ];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-  const img = artifact.contents[0]?.media?.[0];
-  expect(img?.base64).toBe("/9j/4AAQ==");
-});
-
-test("parsePdf creates a content entry for pages that have only images (no text)", async () => {
-  stubTextPages = [{ num: 1, text: "text only page" }];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 2,
-      images: [{ dataUrl: "data:image/png;base64,img2", width: 80, height: 80 }],
-    },
-  ];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  // Should have page 1 (text) and page 2 (image-only)
-  expect(artifact.contents).toHaveLength(2);
-
-  const imagePage = artifact.contents.find((c) => c.page === 2);
-  expect(imagePage).toBeDefined();
-  expect(imagePage?.text).toBeUndefined();
-  expect(imagePage?.media).toHaveLength(1);
-  expect(imagePage?.media![0]?.base64).toBe("img2");
-});
-
-test("parsePdf continues without images when getImage() throws", async () => {
-  stubTextPages = [{ num: 1, text: "resilient page" }];
-  stubTextFull = "";
-  stubImagePages = [];
-  stubScreenshotPages = [];
-  stubGetImageThrows = true;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.contents).toHaveLength(1);
-  expect(artifact.contents[0]?.text).toBe("resilient page");
-  expect(artifact.contents[0]?.media).toBeUndefined();
-});
-
-test("parsePdf produces at least one content entry for empty documents", async () => {
-  stubTextPages = [];
-  stubTextFull = "";
-  stubImagePages = [];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.contents).toHaveLength(1);
-  expect(artifact.contents[0]?.text).toBe("");
-});
-
-test("parsePdf includes numpages in metadata", async () => {
-  stubTextPages = [{ num: 1, text: "one" }];
-  stubTextFull = "";
-  stubImagePages = [];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.metadata?.numpages).toBe(1);
-  expect((artifact.metadata?.info as Record<string, unknown>)?.Title).toBe("Test PDF");
-});
-
-test("parsePdf raw() returns the original buffer", async () => {
-  stubTextPages = [{ num: 1, text: "raw test" }];
-  stubTextFull = "";
-  stubImagePages = [];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const buf = makeBuffer();
-  const artifact = await parsePdf(buf);
-  const raw = await artifact.raw();
-  expect(raw).toBe(buf);
-});
-
-test("parsePdf with includeImages: false skips image extraction", async () => {
-  stubTextPages = [{ num: 1, text: "text only" }];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 1,
-      images: [{ dataUrl: "data:image/png;base64,abc123", width: 100, height: 50 }],
-    },
-  ];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  // Even though stubImagePages has data, passing includeImages: false should
-  // cause getImage() to not be called, so no media on the content entry.
-  const artifact = await parsePdf(makeBuffer(), { includeImages: false });
-
-  expect(artifact.contents).toHaveLength(1);
-  expect(artifact.contents[0]?.text).toBe("text only");
-  expect(artifact.contents[0]?.media).toBeUndefined();
-});
-
-test("parsePdf with includeImages: true behaves the same as the default", async () => {
-  stubTextPages = [{ num: 1, text: "with images" }];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 1,
-      images: [{ dataUrl: "data:image/png;base64,xyz456", width: 80, height: 80 }],
-    },
-  ];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer(), { includeImages: true });
-
-  expect(artifact.contents[0]?.media).toHaveLength(1);
-  expect(artifact.contents[0]?.media![0]?.base64).toBe("xyz456");
-});
-
-test("parsePdf with no options still includes images by default", async () => {
-  stubTextPages = [{ num: 1, text: "default" }];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 1,
-      images: [{ dataUrl: "data:image/png;base64,def789", width: 60, height: 60 }],
-    },
-  ];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.contents[0]?.media).toHaveLength(1);
-  expect(artifact.contents[0]?.media![0]?.base64).toBe("def789");
-});
-
-test("parsePdf marks embedded images with imageType: 'embedded'", async () => {
-  stubTextPages = [{ num: 1, text: "page with embedded image" }];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 1,
-      images: [{ dataUrl: "data:image/png;base64,embedded123", width: 100, height: 100 }],
-    },
-  ];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.contents[0]?.media).toHaveLength(1);
-  expect(artifact.contents[0]?.media![0]?.imageType).toBe("embedded");
-});
-
-test("parsePdf marks screenshots with imageType: 'screenshot'", async () => {
-  stubTextPages = [{ num: 1, text: "page with screenshot" }];
-  stubTextFull = "";
-  stubImagePages = [];
-  stubScreenshotPages = [
-    { pageNumber: 1, dataUrl: "data:image/png;base64,screenshot456", width: 800, height: 600 },
-  ];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer(), { screenshots: true });
-
-  expect(artifact.contents[0]?.media).toHaveLength(1);
-  expect(artifact.contents[0]?.media![0]?.imageType).toBe("screenshot");
-});
-
-test("parsePdf correctly differentiates embedded images and screenshots on the same page", async () => {
-  stubTextPages = [{ num: 1, text: "page with both" }];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 1,
-      images: [{ dataUrl: "data:image/png;base64,embedded789", width: 100, height: 100 }],
-    },
-  ];
-  stubScreenshotPages = [
-    { pageNumber: 1, dataUrl: "data:image/png;base64,screenshot012", width: 800, height: 600 },
-  ];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer(), { screenshots: true });
-
-  expect(artifact.contents[0]?.media).toHaveLength(2);
-  
-  const embeddedImage = artifact.contents[0]?.media?.find(img => img.imageType === "embedded");
-  const screenshotImage = artifact.contents[0]?.media?.find(img => img.imageType === "screenshot");
-  
-  expect(embeddedImage).toBeDefined();
-  expect(embeddedImage?.base64).toBe("embedded789");
-  expect(screenshotImage).toBeDefined();
-  expect(screenshotImage?.base64).toBe("screenshot012");
-});
-
-test("parsePdf without screenshots option does not include screenshot images", async () => {
-  stubTextPages = [{ num: 1, text: "page" }];
-  stubTextFull = "";
-  stubImagePages = [
-    {
-      pageNumber: 1,
-      images: [{ dataUrl: "data:image/png;base64,embedded345", width: 100, height: 100 }],
-    },
-  ];
-  stubScreenshotPages = [
-    { pageNumber: 1, dataUrl: "data:image/png;base64,screenshot678", width: 800, height: 600 },
-  ];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = false;
-
-  const artifact = await parsePdf(makeBuffer());
-
-  expect(artifact.contents[0]?.media).toHaveLength(1);
-  expect(artifact.contents[0]?.media![0]?.imageType).toBe("embedded");
-});
-
-test("parsePdf continues without screenshots when getScreenshot() throws", async () => {
-  stubTextPages = [{ num: 1, text: "resilient page" }];
-  stubTextFull = "";
-  stubImagePages = [];
-  stubScreenshotPages = [];
-  stubGetImageThrows = false;
-  stubGetScreenshotThrows = true;
-
-  const artifact = await parsePdf(makeBuffer(), { screenshots: true });
-
-  expect(artifact.contents).toHaveLength(1);
-  expect(artifact.contents[0]?.text).toBe("resilient page");
-  expect(artifact.contents[0]?.media).toBeUndefined();
-});

package/src/parsers/pdf.ts

@@ -1,194 +0,0 @@
-import type { Artifact, ArtifactContent, ArtifactImage } from "../types";
-import { collectStream } from "./collect";
-
-export type ParsePdfOptions = {
-  /**
-   * Whether to extract embedded images from each page and include them as
-   * base64-encoded ArtifactImage entries in the media field.
-   * Defaults to true. Pass false to skip image extraction entirely.
-   */
-  includeImages?: boolean;
-  /**
-   * Whether to render page screenshots and include them as ArtifactImage entries.
-   * When true, each page is rendered to a PNG image and added to the media field.
-   * Defaults to false.
-   */
-  screenshots?: boolean;
-  /**
-   * Scale factor for screenshots. Higher values produce larger, higher-quality images.
-   * Defaults to 1.5.
-   */
-  screenshotScale?: number;
-  /**
-   * Target width in pixels for screenshots. If specified, takes precedence over screenshotScale.
-   * Height is calculated to maintain aspect ratio.
-   */
-  screenshotWidth?: number;
-};
-
-/**
- * Built-in PDF parser using pdf-parse.
- *
- * Accepts a Buffer or ReadableStream<Uint8Array> and extracts text per-page
- * into ArtifactContent[] with page numbers set. Embedded images on each page
- * are extracted and included as base64-encoded ArtifactImage entries in the
- * media field of the corresponding content block (unless includeImages is
- * false). Returns an Artifact with type: "pdf".
- */
-export async function parsePdf(
-  input: Buffer | ReadableStream<Uint8Array>,
-  options?: ParsePdfOptions,
-): Promise<Artifact> {
-  const buffer = Buffer.isBuffer(input) ? input : await collectStream(input);
-
-  // Dynamic import to avoid bundling issues
-  const { PDFParse } = await import("pdf-parse");
-
-  const parser = new PDFParse({ data: buffer });
-  const textResult = await parser.getText();
-
-  // Build a page-number → text map from per-page results
-  const pageTextMap = new Map<number, string>();
-  if (textResult.pages.length > 0) {
-    for (const page of textResult.pages) {
-      if (page.text && page.text.trim().length > 0) {
-        pageTextMap.set(page.num, page.text);
-      }
-    }
-  }
-
-  // Extract embedded images unless the caller opted out.
-  // imageBuffer=false saves memory (we only need the data URL).
-  let imageResult;
-  if (options?.includeImages !== false) {
-    try {
-      imageResult = await parser.getImage({ imageBuffer: false, imageDataUrl: true });
-    } catch {
-      // Image extraction is optional — continue without images if it fails
-    }
-  }
-
-  // Render page screenshots if requested
-  let screenshotResult;
-  if (options?.screenshots === true) {
-    try {
-      const screenshotParams: {
-        imageBuffer: boolean;
-        imageDataUrl: boolean;
-        scale?: number;
-        desiredWidth?: number;
-      } = { imageBuffer: false, imageDataUrl: true };
-      
-      if (options.screenshotWidth !== undefined) {
-        screenshotParams.desiredWidth = options.screenshotWidth;
-      } else {
-        screenshotParams.scale = options.screenshotScale ?? 1.5;
-      }
-      
-      screenshotResult = await parser.getScreenshot(screenshotParams);
-    } catch {
-      // Screenshot rendering is optional — continue without screenshots if it fails
-    }
-  }
-
-  // Build a page-number → ArtifactImage[] map from extracted images
-  const pageImageMap = new Map<number, ArtifactImage[]>();
-  if (imageResult) {
-    for (const pageImages of imageResult.pages) {
-      const artifactImages: ArtifactImage[] = pageImages.images
-        .filter((img) => img.dataUrl)
-        .map((img) => {
-          // Strip the "data:<mime>;base64," prefix to get the raw base64 string
-          const base64 = img.dataUrl.replace(/^data:[^;]+;base64,/, "");
-          const artifactImage: ArtifactImage = {
-            type: "image",
-            base64,
-            width: img.width,
-            height: img.height,
-            imageType: "embedded",
-          };
-          return artifactImage;
-        });
-      if (artifactImages.length > 0) {
-        pageImageMap.set(pageImages.pageNumber, artifactImages);
-      }
-    }
-  }
-
-  // Add screenshots to the pageImageMap
-  if (screenshotResult) {
-    for (const screenshot of screenshotResult.pages) {
-      if (screenshot.dataUrl) {
-        // Strip the "data:<mime>;base64," prefix to get the raw base64 string
-        const base64 = screenshot.dataUrl.replace(/^data:[^;]+;base64,/, "");
-        const artifactImage: ArtifactImage = {
-          type: "image",
-          base64,
-          width: screenshot.width,
-          height: screenshot.height,
-          imageType: "screenshot",
-        };
-        // Append to existing images for this page, or create new entry
-        const existing = pageImageMap.get(screenshot.pageNumber) ?? [];
-        pageImageMap.set(screenshot.pageNumber, [...existing, artifactImage]);
-      }
-    }
-  }
-
-  let contents: ArtifactContent[];
-
-  if (textResult.pages.length > 0) {
-    // Collect all page numbers that have text or images
-    const allPageNums = new Set<number>([
-      ...pageTextMap.keys(),
-      ...pageImageMap.keys(),
-    ]);
-
-    contents = Array.from(allPageNums)
-      .sort((a, b) => a - b)
-      .map((pageNum) => {
-        const entry: ArtifactContent = { page: pageNum };
-        const text = pageTextMap.get(pageNum);
-        if (text) entry.text = text;
-        const media = pageImageMap.get(pageNum);
-        if (media) entry.media = media;
-        return entry;
-      });
-  } else {
-    // Fallback: no per-page info — use full concatenated text
-    const entry: ArtifactContent = { text: textResult.text };
-    // Attach any images from the first page if available
-    const firstPageImages = pageImageMap.size > 0
-      ? pageImageMap.values().next().value
-      : undefined;
-    if (firstPageImages) entry.media = firstPageImages;
-    contents = [entry];
-  }
-
-  // Ensure we have at least one content entry
-  if (contents.length === 0) {
-    contents = [{ text: "" }];
-  }
-
-  let infoResult;
-  try {
-    infoResult = await parser.getInfo();
-  } catch {
-    // Info extraction is optional
-  }
-
-  await parser.destroy();
-
-  return {
-    id: `artifact-${crypto.randomUUID()}`,
-    type: "pdf",
-    raw: async () => buffer,
-    contents,
-    metadata: infoResult
-      ? {
-          numpages: textResult.total,
-          info: infoResult,
-        }
-      : { numpages: textResult.total },
-  };
-}

package/src/parsers/runner.test.ts

@@ -1,95 +0,0 @@
-import { test, expect } from "bun:test";
-import { runParser } from "./runner";
-import type { ParserDef, ParserInput } from "./types";
-import path from "node:path";
-import os from "node:os";
-import { rm, writeFile } from "node:fs/promises";
-
-// command-file: echo a serialized artifact JSON
-const makeArtifactJson = () => {
-  const artifact = JSON.stringify([{
-    id: "test-1",
-    type: "text",
-    contents: [{ text: "parsed text" }],
-  }]);
-  return artifact;
-};
-
-test("command-stdin runner pipes buffer to stdin and parses output", async () => {
-  // Use a command that outputs valid artifact JSON ignoring stdin
-  const artifactJson = makeArtifactJson();
-  const def: ParserDef = {
-    type: "command-stdin",
-    command: `echo ${JSON.stringify(artifactJson)}`,
-  };
-  const input: ParserInput = {
-    kind: "buffer",
-    buffer: Buffer.from("irrelevant input"),
-  };
-
-  const artifacts = await runParser(def, input, "text/plain");
-  expect(artifacts).toHaveLength(1);
-  expect(artifacts[0]?.id).toBe("test-1");
-  expect(artifacts[0]?.contents[0]?.text).toBe("parsed text");
-});
-
-test("command-file runner interpolates FILE_PATH and parses output", async () => {
-  const artifactJson = makeArtifactJson();
-  // Write a script that outputs the artifact JSON
-  const tmpScript = path.join(os.tmpdir(), `struktur-test-${Math.random().toString(16).slice(2)}.sh`);
-  await writeFile(tmpScript, `#!/bin/sh\necho '${artifactJson}'`, { mode: 0o755 });
-
-  try {
-    const def: ParserDef = {
-      type: "command-file",
-      command: `${tmpScript} FILE_PATH`,
-    };
-    const input: ParserInput = {
-      kind: "file",
-      path: tmpScript,
-    };
-
-    const artifacts = await runParser(def, input, "text/plain");
-    expect(artifacts).toHaveLength(1);
-    expect(artifacts[0]?.id).toBe("test-1");
-  } finally {
-    await rm(tmpScript, { force: true });
-  }
-});
-
-test("command-file runner writes temp file for buffer input", async () => {
-  const artifactJson = makeArtifactJson();
-  const tmpScript = path.join(os.tmpdir(), `struktur-test-${Math.random().toString(16).slice(2)}.sh`);
-  await writeFile(tmpScript, `#!/bin/sh\necho '${artifactJson}'`, { mode: 0o755 });
-
-  try {
-    const def: ParserDef = {
-      type: "command-file",
-      command: `${tmpScript} FILE_PATH`,
-    };
-    const input: ParserInput = {
-      kind: "buffer",
-      buffer: Buffer.from("some buffer data"),
-    };
-
-    const artifacts = await runParser(def, input, "text/plain");
-    expect(artifacts).toHaveLength(1);
-    expect(artifacts[0]?.id).toBe("test-1");
-  } finally {
-    await rm(tmpScript, { force: true });
-  }
-});
-
-test("npm runner errors when package exports neither function", async () => {
-  // This will fail to import, but we test that the error is thrown
-  const def: ParserDef = {
-    type: "npm",
-    package: "this-package-does-not-exist-xyz-abc-123",
-  };
-  const input: ParserInput = {
-    kind: "buffer",
-    buffer: Buffer.from("data"),
-  };
-
-  await expect(runParser(def, input, "text/plain")).rejects.toThrow();
-});