@juspay/neurolink 12.19.2 → 12.20.0

package/CHANGELOG.md

@@ -1,8 +1,12 @@
-## [12.19.2](https://github.com/juspay/neurolink/compare/v12.19.1...v12.19.2) (2026-09-22)
+## [12.20.0](https://github.com/juspay/neurolink/compare/v12.19.2...v12.20.0) (2026-09-22)
+
+### Features
+
+- **(images):** let a caller choose the transcode output format ([f536fd0](https://github.com/juspay/neurolink/commit/f536fd0916f9e688c723cf679e05f8d995d12e9f))
 
 ### Bug Fixes
 
-- **(proxy):** convert the system turns Vertex refuses so the fallback survives ([a7fd9bf](https://github.com/juspay/neurolink/commit/a7fd9bf0410f81d3efee5e35d3457d74f750f409))
+- **(rag):** keep SVG out of the raster image path and scope the sanitized-markup claim ([0716f94](https://github.com/juspay/neurolink/commit/0716f944d097b2a8944e4036a72fccf3f7c636b6))
 
 ## [11.2.3](https://github.com/juspay/neurolink/compare/v11.2.2...v11.2.3) (2026-08-19)
 

package/dist/adapters/imageFormatSupport.d.ts

@@ -19,7 +19,7 @@
  *
  * @module adapters/imageFormatSupport
  */
-import type { ImageWithAltText, VisionImageConversion } from "../types/index.js";
+import type { ImageWithAltText, VisionImageConversion, VisionImageOutputFormat } from "../types/index.js";
 /**
  * MIME types every vision-capable provider accepts as-is.
  *
@@ -57,8 +57,11 @@ export declare function needsVisionTranscode(mimeType: string): boolean;
  *
  * @param buffer - Raw image bytes.
  * @param mimeType - Detected MIME type of `buffer`.
+ * @param outputFormat - Transcode target. Defaults to `"png"` — see the
+ *   module header for why that stays the default for every caller who
+ *   doesn't opt into `"jpeg"` explicitly.
  */
-export declare function toVisionCompatibleImage(buffer: Buffer, mimeType: string): Promise<VisionImageConversion>;
+export declare function toVisionCompatibleImage(buffer: Buffer, mimeType: string, outputFormat?: VisionImageOutputFormat): Promise<VisionImageConversion>;
 /**
  * Unwrap an `input.images` entry to its payload.
  *

package/dist/adapters/imageFormatSupport.js

@@ -23,7 +23,12 @@ import { extensionForMimeType } from "../processors/config/fileTypeRegistry.js";
 import { withTimeout } from "../utils/errorHandling.js";
 import { logger } from "../utils/logger.js";
 import { tryImport } from "../utils/tryImport.js";
-import { getFfmpegPath, runFfmpeg } from "./video/ffmpegAdapter.js";
+import { getFfmpegPath, JPEG_QUALITY, runFfmpeg, } from "./video/ffmpegAdapter.js";
+/**
+ * Default transcode target, and the one every existing caller keeps getting:
+ * see the module header for why PNG rather than JPEG is the right default.
+ */
+const DEFAULT_VISION_IMAGE_OUTPUT_FORMAT = "png";
 /**
  * Per-backend ceiling for one image conversion.
  *
@@ -106,7 +111,7 @@ export function needsVisionTranscode(mimeType) {
  * only — actual HEVC-coded HEIC fails inside libheif, and BMP, ICO and
  * JPEG 2000 are not compiled in at all. Those fall through to ffmpeg below.
  */
-async function transcodeWithSharp(buffer) {
+async function transcodeWithSharp(buffer, outputFormat) {
     const sharpModule = await tryImport("sharp", "Image format conversion for vision providers");
     // A shape guard, not a crash guard: an absent or malformed sharp already
     // fails safely, because `tryImport` throws a named install error and any
@@ -115,9 +120,9 @@ async function transcodeWithSharp(buffer) {
     // failure list instead of "sharpModule.default is not a function".
     //
     // It deliberately throws rather than returning `buffer`: returning the input
-    // would report a successful conversion and relabel the original bytes as PNG,
-    // and would also skip the ffmpeg backend — the one that actually handles
-    // HEIC, BMP, ICO and JPEG 2000.
+    // would report a successful conversion and relabel the original bytes under
+    // the requested format, and would also skip the ffmpeg backend — the one
+    // that actually handles HEIC, BMP, ICO and JPEG 2000.
     if (typeof sharpModule?.default !== "function") {
         throw new Error("the installed sharp package does not expose a callable default export");
     }
@@ -125,9 +130,15 @@ async function transcodeWithSharp(buffer) {
     // a multi-page TIFF) from being flattened into one tall strip — the first
     // frame is what a vision model should receive.
     const pipeline = sharpModule.default(buffer, { pages: 1 });
-    // The instance shape is checked as well as the factory: a build that exports
-    // a callable but returns something without `.png()` would otherwise fail as
-    // an opaque TypeError inside the backend loop.
+    if (outputFormat === "jpeg") {
+        // The instance shape is checked as well as the factory: a build that
+        // exports a callable but returns something without `.jpeg()` would
+        // otherwise fail as an opaque TypeError inside the backend loop.
+        if (typeof pipeline?.jpeg !== "function") {
+            throw new Error("the installed sharp package returned a pipeline without a jpeg() encoder");
+        }
+        return pipeline.jpeg().toBuffer();
+    }
     if (typeof pipeline?.png !== "function") {
         throw new Error("the installed sharp package returned a pipeline without a png() encoder");
     }
@@ -151,7 +162,7 @@ async function transcodeWithSharp(buffer) {
  * `mkdtemp`. This whole path is server-only — nothing in a browser is going to
  * spawn ffmpeg — so the import belongs where it is used.
  */
-async function transcodeWithFfmpeg(buffer, extension, binaryPath) {
+async function transcodeWithFfmpeg(buffer, extension, outputFormat, binaryPath) {
     const [{ randomUUID }, { mkdtemp, readFile, rm, writeFile }, { tmpdir }, { join },] = await Promise.all([
         import("node:crypto"),
         import("node:fs/promises"),
@@ -160,7 +171,13 @@ async function transcodeWithFfmpeg(buffer, extension, binaryPath) {
     ]);
     const workDir = await mkdtemp(join(tmpdir(), "neurolink-img-"));
     const inputPath = join(workDir, `${randomUUID()}${extension}`);
-    const outputPath = join(workDir, `${randomUUID()}.png`);
+    // "mjpeg" is ffmpeg's codec name for a JPEG image2 stream; "png" doubles as
+    // both the codec name and the output extension.
+    const outputExtension = outputFormat === "jpeg" ? ".jpg" : ".png";
+    const codecArgs = outputFormat === "jpeg"
+        ? ["-c:v", "mjpeg", "-q:v", JPEG_QUALITY]
+        : ["-c:v", "png"];
+    const outputPath = join(workDir, `${randomUUID()}${outputExtension}`);
     try {
         await writeFile(inputPath, buffer);
         await runFfmpeg([
@@ -169,14 +186,13 @@ async function transcodeWithFfmpeg(buffer, extension, binaryPath) {
             "error",
             "-i",
             inputPath,
-            // Take a single frame so a multi-image container yields one PNG rather
-            // than ffmpeg erroring on a missing output-sequence pattern.
+            // Take a single frame so a multi-image container yields one output
+            // image rather than ffmpeg erroring on a missing sequence pattern.
             "-frames:v",
             "1",
             "-f",
             "image2",
-            "-c:v",
-            "png",
+            ...codecArgs,
             outputPath,
         ], binaryPath ? { binaryPath } : {});
         return await readFile(outputPath);
@@ -194,17 +210,20 @@ async function transcodeWithFfmpeg(buffer, extension, binaryPath) {
  * so when the resolved binary is not already the system one it is retried
  * explicitly rather than reporting a photo as unsupported.
  */
-async function* transcodeBackends(buffer, extension) {
-    yield { name: "sharp", run: () => transcodeWithSharp(buffer) };
+async function* transcodeBackends(buffer, extension, outputFormat) {
+    yield {
+        name: "sharp",
+        run: () => transcodeWithSharp(buffer, outputFormat),
+    };
     const resolved = await getFfmpegPath().catch(() => "ffmpeg");
     yield {
         name: "ffmpeg",
-        run: () => transcodeWithFfmpeg(buffer, extension),
+        run: () => transcodeWithFfmpeg(buffer, extension, outputFormat),
     };
     if (resolved !== "ffmpeg") {
         yield {
             name: "system ffmpeg",
-            run: () => transcodeWithFfmpeg(buffer, extension, "ffmpeg"),
+            run: () => transcodeWithFfmpeg(buffer, extension, outputFormat, "ffmpeg"),
         };
     }
 }
@@ -220,15 +239,19 @@ async function* transcodeBackends(buffer, extension) {
  *
  * @param buffer - Raw image bytes.
  * @param mimeType - Detected MIME type of `buffer`.
+ * @param outputFormat - Transcode target. Defaults to `"png"` — see the
+ *   module header for why that stays the default for every caller who
+ *   doesn't opt into `"jpeg"` explicitly.
  */
-export async function toVisionCompatibleImage(buffer, mimeType) {
+export async function toVisionCompatibleImage(buffer, mimeType, outputFormat = DEFAULT_VISION_IMAGE_OUTPUT_FORMAT) {
     if (!needsVisionTranscode(mimeType)) {
         return { buffer, mimeType, converted: false };
     }
     const normalized = mimeType.split(";")[0].trim().toLowerCase();
     const extension = extensionForMimeType(normalized) ?? ".bin";
+    const targetMimeType = outputFormat === "jpeg" ? "image/jpeg" : "image/png";
     const failures = [];
-    for await (const backend of transcodeBackends(buffer, extension)) {
+    for await (const backend of transcodeBackends(buffer, extension, outputFormat)) {
         try {
             // Both backends can stall — sharp on a malformed stream, ffmpeg on a
             // container it half-understands — and this runs inline on the request
@@ -238,16 +261,16 @@ export async function toVisionCompatibleImage(buffer, mimeType) {
             if (converted.length === 0) {
                 throw new Error("produced an empty image");
             }
-            logger.debug(`[imageFormatSupport] Transcoded ${normalized} → image/png via ${backend.name} ` +
+            logger.debug(`[imageFormatSupport] Transcoded ${normalized} → ${targetMimeType} via ${backend.name} ` +
                 `(${buffer.length} → ${converted.length} bytes) for vision compatibility`);
-            return { buffer: converted, mimeType: "image/png", converted: true };
+            return { buffer: converted, mimeType: targetMimeType, converted: true };
         }
         catch (error) {
             failures.push(`${backend.name}: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`);
         }
     }
-    logger.warn(`[imageFormatSupport] Could not transcode ${normalized} to PNG — sending the ` +
-        `original bytes, which most vision providers will reject. Install a full ` +
+    logger.warn(`[imageFormatSupport] Could not transcode ${normalized} to ${targetMimeType} — sending ` +
+        `the original bytes, which most vision providers will reject. Install a full ` +
         `ffmpeg build (or set FFMPEG_PATH to one) to enable this format. ` +
         `Tried ${failures.join("; ")}`);
     return { buffer, mimeType, converted: false };