av6-pdf-engine 1.0.4 → 1.0.6

package/dist/index.d.mts

@@ -293,7 +293,26 @@ interface RenderEnv {
     allowPageBreak: boolean;
 }
 
+declare enum PdfEngineErrorCode {
+    PDF_ERROR_DEF_INVALID = "PDF_ERROR_DEF_INVALID",
+    PDF_ERROR_BLOCK_UNSUPPORTED = "PDF_ERROR_BLOCK_UNSUPPORTED",
+    PDF_ERROR_LAYOUT_INVALID = "PDF_ERROR_LAYOUT_INVALID",
+    PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW = "PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW",
+    PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN = "PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN",
+    PDF_ERROR_SIGNATURE_MISSING_BLOCKS = "PDF_ERROR_SIGNATURE_MISSING_BLOCKS",
+    PDF_ERROR_QR_GENERATION_FAILED = "PDF_ERROR_QR_GENERATION_FAILED",
+    PDF_ERROR_BARCODE_GENERATION_FAILED = "PDF_ERROR_BARCODE_GENERATION_FAILED",
+    PDF_ERROR_BARCODE_TYPE_UNSUPPORTED = "PDF_ERROR_BARCODE_TYPE_UNSUPPORTED",
+    PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH = "PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH",
+    PDF_ERROR_IMAGE_SRC_INVALID = "PDF_ERROR_IMAGE_SRC_INVALID",
+    PDF_ERROR_IMAGE_FETCH_FAILED = "PDF_ERROR_IMAGE_FETCH_FAILED",
+    PDF_ERROR_FONT_REGISTER_FAILED = "PDF_ERROR_FONT_REGISTER_FAILED",
+    PDF_ERROR_OUTPUT_STREAM_ERROR = "PDF_ERROR_OUTPUT_STREAM_ERROR",
+    PDF_ERROR_RENDER_FAILED = "PDF_ERROR_RENDER_FAILED",
+    PDF_ERROR_PDFKIT_ERROR = "PDF_ERROR_PDFKIT_ERROR"
+}
+
 declare function renderCustomPdf(def: CustomDocDefinition, outputPath: string): Promise<void>;
 declare function renderCustomPdfToBuffer(def: CustomDocDefinition): Promise<Buffer>;
 
-export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderEnv, type SignatureBlock, type StyleDef, type StyleRef, type TableBlock, type TableCell, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, renderCustomPdf, renderCustomPdfToBuffer };
+export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, PdfEngineErrorCode, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderEnv, type SignatureBlock, type StyleDef, type StyleRef, type TableBlock, type TableCell, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, renderCustomPdf, renderCustomPdfToBuffer };

package/dist/index.d.ts

@@ -293,7 +293,26 @@ interface RenderEnv {
     allowPageBreak: boolean;
 }
 
+declare enum PdfEngineErrorCode {
+    PDF_ERROR_DEF_INVALID = "PDF_ERROR_DEF_INVALID",
+    PDF_ERROR_BLOCK_UNSUPPORTED = "PDF_ERROR_BLOCK_UNSUPPORTED",
+    PDF_ERROR_LAYOUT_INVALID = "PDF_ERROR_LAYOUT_INVALID",
+    PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW = "PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW",
+    PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN = "PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN",
+    PDF_ERROR_SIGNATURE_MISSING_BLOCKS = "PDF_ERROR_SIGNATURE_MISSING_BLOCKS",
+    PDF_ERROR_QR_GENERATION_FAILED = "PDF_ERROR_QR_GENERATION_FAILED",
+    PDF_ERROR_BARCODE_GENERATION_FAILED = "PDF_ERROR_BARCODE_GENERATION_FAILED",
+    PDF_ERROR_BARCODE_TYPE_UNSUPPORTED = "PDF_ERROR_BARCODE_TYPE_UNSUPPORTED",
+    PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH = "PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH",
+    PDF_ERROR_IMAGE_SRC_INVALID = "PDF_ERROR_IMAGE_SRC_INVALID",
+    PDF_ERROR_IMAGE_FETCH_FAILED = "PDF_ERROR_IMAGE_FETCH_FAILED",
+    PDF_ERROR_FONT_REGISTER_FAILED = "PDF_ERROR_FONT_REGISTER_FAILED",
+    PDF_ERROR_OUTPUT_STREAM_ERROR = "PDF_ERROR_OUTPUT_STREAM_ERROR",
+    PDF_ERROR_RENDER_FAILED = "PDF_ERROR_RENDER_FAILED",
+    PDF_ERROR_PDFKIT_ERROR = "PDF_ERROR_PDFKIT_ERROR"
+}
+
 declare function renderCustomPdf(def: CustomDocDefinition, outputPath: string): Promise<void>;
 declare function renderCustomPdfToBuffer(def: CustomDocDefinition): Promise<Buffer>;
 
-export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderEnv, type SignatureBlock, type StyleDef, type StyleRef, type TableBlock, type TableCell, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, renderCustomPdf, renderCustomPdfToBuffer };
+export { type Alignment, BARCODE_TYPES, type BarcodeBlock, type BarcodeType, type BaseBlock, type Block, type BuiltInFont, type ColumnsBlock, type CustomDocDefinition, type FontName, type FontRegistration, type FooterDef, type FooterInput, type HeaderDef, type ImageBlock, type InlineTextStyle, type KeyValueGridBlock, type KeyValueItem, type LineBlock, type Orientation, type PDFDoc, type PageBackgroundDef, type PageBreakBlock, type PageContext, type PageMargins, PdfEngineErrorCode, type QRErrorLevel, QR_ERROR_LEVEL, type QrCodeBlock, type RenderEnv, type SignatureBlock, type StyleDef, type StyleRef, type TableBlock, type TableCell, type TextBlock, type WatermarkDef, type WatermarkMode, type Width, renderCustomPdf, renderCustomPdfToBuffer };

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BARCODE_TYPES: () => BARCODE_TYPES,
+  PdfEngineErrorCode: () => PdfEngineErrorCode,
   QR_ERROR_LEVEL: () => QR_ERROR_LEVEL,
   renderCustomPdf: () => renderCustomPdf,
   renderCustomPdfToBuffer: () => renderCustomPdfToBuffer
@@ -41,6 +42,44 @@ module.exports = __toCommonJS(index_exports);
 var import_fs = __toESM(require("fs"));
 var import_pdfkit = __toESM(require("pdfkit"));
 
+// src/types/barcode.ts
+var BARCODE_TYPES = {
+  CODE128: "CODE128",
+  EAN13: "EAN13",
+  CODE39: "CODE39",
+  ITF: "ITF",
+  CODE93: "CODE93"
+};
+
+// src/types/error.ts
+var PdfEngineErrorCode = /* @__PURE__ */ ((PdfEngineErrorCode2) => {
+  PdfEngineErrorCode2["PDF_ERROR_DEF_INVALID"] = "PDF_ERROR_DEF_INVALID";
+  PdfEngineErrorCode2["PDF_ERROR_BLOCK_UNSUPPORTED"] = "PDF_ERROR_BLOCK_UNSUPPORTED";
+  PdfEngineErrorCode2["PDF_ERROR_LAYOUT_INVALID"] = "PDF_ERROR_LAYOUT_INVALID";
+  PdfEngineErrorCode2["PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW"] = "PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW";
+  PdfEngineErrorCode2["PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN"] = "PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN";
+  PdfEngineErrorCode2["PDF_ERROR_SIGNATURE_MISSING_BLOCKS"] = "PDF_ERROR_SIGNATURE_MISSING_BLOCKS";
+  PdfEngineErrorCode2["PDF_ERROR_QR_GENERATION_FAILED"] = "PDF_ERROR_QR_GENERATION_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_BARCODE_GENERATION_FAILED"] = "PDF_ERROR_BARCODE_GENERATION_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_BARCODE_TYPE_UNSUPPORTED"] = "PDF_ERROR_BARCODE_TYPE_UNSUPPORTED";
+  PdfEngineErrorCode2["PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH"] = "PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH";
+  PdfEngineErrorCode2["PDF_ERROR_IMAGE_SRC_INVALID"] = "PDF_ERROR_IMAGE_SRC_INVALID";
+  PdfEngineErrorCode2["PDF_ERROR_IMAGE_FETCH_FAILED"] = "PDF_ERROR_IMAGE_FETCH_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_FONT_REGISTER_FAILED"] = "PDF_ERROR_FONT_REGISTER_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_OUTPUT_STREAM_ERROR"] = "PDF_ERROR_OUTPUT_STREAM_ERROR";
+  PdfEngineErrorCode2["PDF_ERROR_RENDER_FAILED"] = "PDF_ERROR_RENDER_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_PDFKIT_ERROR"] = "PDF_ERROR_PDFKIT_ERROR";
+  return PdfEngineErrorCode2;
+})(PdfEngineErrorCode || {});
+
+// src/types/qr.ts
+var QR_ERROR_LEVEL = {
+  LOW: "L",
+  MEDIUM: "M",
+  QUARTILE: "Q",
+  HIGH: "H"
+};
+
 // src/renderer-engine/blocks/barcode.ts
 var processBarcodeBlock = (doc, ctx, block, y, env, ensureSpaceFor) => {
   const imgSource = block.src;
@@ -711,10 +750,20 @@ function createBlockRenderer(deps) {
         );
       case "signature":
         if (!env.allowPageBreak) {
-          throw new Error("Signature block is only allowed in main content flow.");
+          throw new PdfEngineError({
+            code: "PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW" /* PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW */,
+            message: "Signature block is only allowed in main content flow.",
+            statusCode: 400,
+            details: { blockType: "signature" }
+          });
         }
         if (y !== null) {
-          throw new Error("Signature block must be part of main flow, not drawn at explicit Y.");
+          throw new PdfEngineError({
+            code: "PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN" /* PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN */,
+            message: "Signature block must be part of main flow, not drawn at explicit Y.",
+            statusCode: 400,
+            details: { blockType: "signature", y }
+          });
         }
         processSignatureBlock(block);
         return ctx.currentY;
@@ -776,6 +825,35 @@ var contentEnv = (doc) => ({
   allowPageBreak: true
 });
 
+// src/renderer-engine/utils/error.ts
+var PdfEngineError = class extends Error {
+  code;
+  statusCode;
+  details;
+  retryable;
+  cause;
+  constructor(args) {
+    super(args.message);
+    this.name = "PdfEngineError";
+    this.code = args.code;
+    this.statusCode = args.statusCode ?? 400;
+    this.details = args.details;
+    this.retryable = args.retryable ?? false;
+    this.cause = args.cause;
+  }
+};
+function toPdfEngineError(cause, fallback) {
+  if (cause instanceof PdfEngineError) return cause;
+  return new PdfEngineError({
+    code: fallback.code,
+    message: fallback.message,
+    statusCode: fallback.statusCode,
+    details: fallback.details,
+    retryable: fallback.retryable,
+    cause
+  });
+}
+
 // src/renderer-engine/utils/finish-page.ts
 function finishPage({
   addNewPage,
@@ -922,10 +1000,18 @@ async function normalizeImageSrc(src) {
   if (!src) return src;
   if (Buffer.isBuffer(src)) return src;
   if (src.startsWith("http://") || src.startsWith("https://")) {
-    const res = await import_axios.default.get(src, {
-      responseType: "arraybuffer"
-    });
-    return Buffer.from(res.data);
+    try {
+      const res = await import_axios.default.get(src, { responseType: "arraybuffer" });
+      return Buffer.from(res.data);
+    } catch (e) {
+      throw toPdfEngineError(e, {
+        code: "PDF_ERROR_IMAGE_FETCH_FAILED" /* PDF_ERROR_IMAGE_FETCH_FAILED */,
+        message: "Failed to fetch remote image for PDF.",
+        statusCode: 422,
+        details: { url: src },
+        retryable: false
+      });
+    }
   }
   return src;
 }
@@ -939,9 +1025,7 @@ async function materializeImagesInBlocks(blocks) {
     } else if (block.type === "columns") {
       out.push({
         ...block,
-        columns: await Promise.all(
-          block.columns.map((col) => materializeImagesInBlocks(col))
-        )
+        columns: await Promise.all(block.columns.map((col) => materializeImagesInBlocks(col)))
       });
     } else if (block.type === "signature" && block.blocks) {
       out.push({
@@ -1290,7 +1374,15 @@ function generateQrBuffer(value, size, version, errorCorrectionLevel) {
   return new Promise((resolve, reject) => {
     import_qrcode.default.toBuffer(value, options, (err, buffer) => {
       if (err) {
-        return reject(err);
+        return reject(
+          toPdfEngineError(err, {
+            code: "PDF_ERROR_QR_GENERATION_FAILED" /* PDF_ERROR_QR_GENERATION_FAILED */,
+            message: "Failed to generate QR code.",
+            statusCode: 500,
+            details: { valuePreview: String(value).slice(0, 60), size },
+            retryable: false
+          })
+        );
       }
       resolve(buffer);
     });
@@ -1312,13 +1404,7 @@ function mapBarcodeTypeToBcid(bcType) {
   }
 }
 function generateBarcodeBuffer(value, options = {}) {
-  const {
-    bcType,
-    scale = 3,
-    barHeight = 10,
-    includetext = false,
-    textalign = "center"
-  } = options;
+  const { bcType, scale = 3, barHeight = 10, includetext = false, textalign = "center" } = options;
   const bcid = mapBarcodeTypeToBcid(bcType);
   return new Promise((resolve, reject) => {
     let textValue = value;
@@ -1327,12 +1413,16 @@ function generateBarcodeBuffer(value, options = {}) {
       if (digitsOnly.length === 13) {
         textValue = digitsOnly.slice(0, 12);
       } else if (digitsOnly.length === 12) {
-        textValue = textValue;
+        textValue = digitsOnly;
       } else {
         return reject(
-          new Error(
-            `EAN13 barcode value must have 12 or 13 digits, got "${value}"`
-          )
+          new PdfEngineError({
+            code: "PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH" /* PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH */,
+            message: `EAN13 barcode value must have 12 or 13 digits, got "${value}"`,
+            statusCode: 422,
+            details: { value },
+            retryable: false
+          })
         );
       }
     }
@@ -1346,7 +1436,15 @@ function generateBarcodeBuffer(value, options = {}) {
     bwipOptions.textxalign = textalign;
     import_bwip_js.default.toBuffer(bwipOptions, (err, png) => {
       if (err) {
-        return reject(err);
+        return reject(
+          toPdfEngineError(err, {
+            code: "PDF_ERROR_BARCODE_GENERATION_FAILED" /* PDF_ERROR_BARCODE_GENERATION_FAILED */,
+            message: "Failed to generate barcode.",
+            statusCode: 500,
+            details: { bcType, valuePreview: String(value).slice(0, 60) },
+            retryable: false
+          })
+        );
       }
       resolve(png);
     });
@@ -1380,12 +1478,7 @@ async function materializeQrAndBarcodesInBlocks(blocks) {
       const qb = { ...block };
       if (!qb.src && qb.value) {
         const size = qb.size ?? 80;
-        const buf = await generateQrBuffer(
-          qb.value,
-          size,
-          qb.qrVersion,
-          qb.errorCorrectionLevel
-        );
+        const buf = await generateQrBuffer(qb.value, size, qb.qrVersion, qb.errorCorrectionLevel);
         qb.src = buf;
       }
       out.push(qb);
@@ -1659,9 +1752,7 @@ function drawWatermarkForPage(doc, watermark, pageNumber, isLast) {
 // src/renderer-engine/index.ts
 async function renderCustomPdf(def, outputPath) {
   if (def.header) {
-    def.header.blocks = await materializeQrAndBarcodesInBlocks(
-      def.header.blocks
-    );
+    def.header.blocks = await materializeQrAndBarcodesInBlocks(def.header.blocks);
     def.header.blocks = await materializeImagesInBlocks(def.header.blocks);
   }
   def.content = await materializeQrAndBarcodesInBlocks(def.content);
@@ -1670,9 +1761,7 @@ async function renderCustomPdf(def, outputPath) {
     def.pageBackground.src = await normalizeImageSrc(def.pageBackground.src);
   }
   if (def.header?.backgroundImage) {
-    def.header.backgroundImage = await normalizeImageSrc(
-      def.header.backgroundImage
-    );
+    def.header.backgroundImage = await normalizeImageSrc(def.header.backgroundImage);
   }
   if (def.footer && typeof def.footer !== "function") {
     const footer = def.footer;
@@ -1751,14 +1840,23 @@ async function renderCustomPdf(def, outputPath) {
     finishPage2(false);
     doc.end();
     stream.on("finish", () => resolve());
-    stream.on("error", (err) => reject(err));
+    stream.on(
+      "error",
+      (err) => reject(
+        toPdfEngineError(err, {
+          code: "PDF_ERROR_OUTPUT_STREAM_ERROR" /* PDF_ERROR_OUTPUT_STREAM_ERROR */,
+          message: "Failed while writing PDF to output stream.",
+          statusCode: 500,
+          details: { outputPath },
+          retryable: true
+        })
+      )
+    );
   });
 }
 async function renderCustomPdfToBuffer(def) {
   if (def.header) {
-    def.header.blocks = await materializeQrAndBarcodesInBlocks(
-      def.header.blocks
-    );
+    def.header.blocks = await materializeQrAndBarcodesInBlocks(def.header.blocks);
     def.header.blocks = await materializeImagesInBlocks(def.header.blocks);
   }
   def.content = await materializeQrAndBarcodesInBlocks(def.content);
@@ -1767,9 +1865,7 @@ async function renderCustomPdfToBuffer(def) {
     def.pageBackground.src = await normalizeImageSrc(def.pageBackground.src);
   }
   if (def.header?.backgroundImage) {
-    def.header.backgroundImage = await normalizeImageSrc(
-      def.header.backgroundImage
-    );
+    def.header.backgroundImage = await normalizeImageSrc(def.header.backgroundImage);
   }
   if (def.footer && typeof def.footer !== "function") {
     const footer = def.footer;
@@ -1797,7 +1893,14 @@ async function renderCustomPdfToBuffer(def) {
       resolve(Buffer.concat(chunks));
     });
     doc.on("error", (err) => {
-      reject(err);
+      reject(
+        toPdfEngineError(err, {
+          code: "PDF_ERROR_PDFKIT_ERROR" /* PDF_ERROR_PDFKIT_ERROR */,
+          message: "PDFKit emitted an error while rendering.",
+          statusCode: 500,
+          retryable: true
+        })
+      );
     });
     if (def.fonts && def.fonts.length) {
       for (const f of def.fonts) {
@@ -1857,26 +1960,10 @@ async function renderCustomPdfToBuffer(def) {
     doc.end();
   });
 }
-
-// src/types/barcode.ts
-var BARCODE_TYPES = {
-  CODE128: "CODE128",
-  EAN13: "EAN13",
-  CODE39: "CODE39",
-  ITF: "ITF",
-  CODE93: "CODE93"
-};
-
-// src/types/qr.ts
-var QR_ERROR_LEVEL = {
-  LOW: "L",
-  MEDIUM: "M",
-  QUARTILE: "Q",
-  HIGH: "H"
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BARCODE_TYPES,
+  PdfEngineErrorCode,
   QR_ERROR_LEVEL,
   renderCustomPdf,
   renderCustomPdfToBuffer

package/dist/index.mjs

@@ -2,6 +2,44 @@
 import fs from "fs";
 import PDFDocument from "pdfkit";
 
+// src/types/barcode.ts
+var BARCODE_TYPES = {
+  CODE128: "CODE128",
+  EAN13: "EAN13",
+  CODE39: "CODE39",
+  ITF: "ITF",
+  CODE93: "CODE93"
+};
+
+// src/types/error.ts
+var PdfEngineErrorCode = /* @__PURE__ */ ((PdfEngineErrorCode2) => {
+  PdfEngineErrorCode2["PDF_ERROR_DEF_INVALID"] = "PDF_ERROR_DEF_INVALID";
+  PdfEngineErrorCode2["PDF_ERROR_BLOCK_UNSUPPORTED"] = "PDF_ERROR_BLOCK_UNSUPPORTED";
+  PdfEngineErrorCode2["PDF_ERROR_LAYOUT_INVALID"] = "PDF_ERROR_LAYOUT_INVALID";
+  PdfEngineErrorCode2["PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW"] = "PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW";
+  PdfEngineErrorCode2["PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN"] = "PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN";
+  PdfEngineErrorCode2["PDF_ERROR_SIGNATURE_MISSING_BLOCKS"] = "PDF_ERROR_SIGNATURE_MISSING_BLOCKS";
+  PdfEngineErrorCode2["PDF_ERROR_QR_GENERATION_FAILED"] = "PDF_ERROR_QR_GENERATION_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_BARCODE_GENERATION_FAILED"] = "PDF_ERROR_BARCODE_GENERATION_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_BARCODE_TYPE_UNSUPPORTED"] = "PDF_ERROR_BARCODE_TYPE_UNSUPPORTED";
+  PdfEngineErrorCode2["PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH"] = "PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH";
+  PdfEngineErrorCode2["PDF_ERROR_IMAGE_SRC_INVALID"] = "PDF_ERROR_IMAGE_SRC_INVALID";
+  PdfEngineErrorCode2["PDF_ERROR_IMAGE_FETCH_FAILED"] = "PDF_ERROR_IMAGE_FETCH_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_FONT_REGISTER_FAILED"] = "PDF_ERROR_FONT_REGISTER_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_OUTPUT_STREAM_ERROR"] = "PDF_ERROR_OUTPUT_STREAM_ERROR";
+  PdfEngineErrorCode2["PDF_ERROR_RENDER_FAILED"] = "PDF_ERROR_RENDER_FAILED";
+  PdfEngineErrorCode2["PDF_ERROR_PDFKIT_ERROR"] = "PDF_ERROR_PDFKIT_ERROR";
+  return PdfEngineErrorCode2;
+})(PdfEngineErrorCode || {});
+
+// src/types/qr.ts
+var QR_ERROR_LEVEL = {
+  LOW: "L",
+  MEDIUM: "M",
+  QUARTILE: "Q",
+  HIGH: "H"
+};
+
 // src/renderer-engine/blocks/barcode.ts
 var processBarcodeBlock = (doc, ctx, block, y, env, ensureSpaceFor) => {
   const imgSource = block.src;
@@ -672,10 +710,20 @@ function createBlockRenderer(deps) {
         );
       case "signature":
         if (!env.allowPageBreak) {
-          throw new Error("Signature block is only allowed in main content flow.");
+          throw new PdfEngineError({
+            code: "PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW" /* PDF_ERROR_SIGNATURE_NOT_IN_MAIN_FLOW */,
+            message: "Signature block is only allowed in main content flow.",
+            statusCode: 400,
+            details: { blockType: "signature" }
+          });
         }
         if (y !== null) {
-          throw new Error("Signature block must be part of main flow, not drawn at explicit Y.");
+          throw new PdfEngineError({
+            code: "PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN" /* PDF_ERROR_SIGNATURE_EXPLICIT_Y_FORBIDDEN */,
+            message: "Signature block must be part of main flow, not drawn at explicit Y.",
+            statusCode: 400,
+            details: { blockType: "signature", y }
+          });
         }
         processSignatureBlock(block);
         return ctx.currentY;
@@ -737,6 +785,35 @@ var contentEnv = (doc) => ({
   allowPageBreak: true
 });
 
+// src/renderer-engine/utils/error.ts
+var PdfEngineError = class extends Error {
+  code;
+  statusCode;
+  details;
+  retryable;
+  cause;
+  constructor(args) {
+    super(args.message);
+    this.name = "PdfEngineError";
+    this.code = args.code;
+    this.statusCode = args.statusCode ?? 400;
+    this.details = args.details;
+    this.retryable = args.retryable ?? false;
+    this.cause = args.cause;
+  }
+};
+function toPdfEngineError(cause, fallback) {
+  if (cause instanceof PdfEngineError) return cause;
+  return new PdfEngineError({
+    code: fallback.code,
+    message: fallback.message,
+    statusCode: fallback.statusCode,
+    details: fallback.details,
+    retryable: fallback.retryable,
+    cause
+  });
+}
+
 // src/renderer-engine/utils/finish-page.ts
 function finishPage({
   addNewPage,
@@ -883,10 +960,18 @@ async function normalizeImageSrc(src) {
   if (!src) return src;
   if (Buffer.isBuffer(src)) return src;
   if (src.startsWith("http://") || src.startsWith("https://")) {
-    const res = await axios.get(src, {
-      responseType: "arraybuffer"
-    });
-    return Buffer.from(res.data);
+    try {
+      const res = await axios.get(src, { responseType: "arraybuffer" });
+      return Buffer.from(res.data);
+    } catch (e) {
+      throw toPdfEngineError(e, {
+        code: "PDF_ERROR_IMAGE_FETCH_FAILED" /* PDF_ERROR_IMAGE_FETCH_FAILED */,
+        message: "Failed to fetch remote image for PDF.",
+        statusCode: 422,
+        details: { url: src },
+        retryable: false
+      });
+    }
   }
   return src;
 }
@@ -900,9 +985,7 @@ async function materializeImagesInBlocks(blocks) {
     } else if (block.type === "columns") {
       out.push({
         ...block,
-        columns: await Promise.all(
-          block.columns.map((col) => materializeImagesInBlocks(col))
-        )
+        columns: await Promise.all(block.columns.map((col) => materializeImagesInBlocks(col)))
       });
     } else if (block.type === "signature" && block.blocks) {
       out.push({
@@ -1251,7 +1334,15 @@ function generateQrBuffer(value, size, version, errorCorrectionLevel) {
   return new Promise((resolve, reject) => {
     QRCode.toBuffer(value, options, (err, buffer) => {
       if (err) {
-        return reject(err);
+        return reject(
+          toPdfEngineError(err, {
+            code: "PDF_ERROR_QR_GENERATION_FAILED" /* PDF_ERROR_QR_GENERATION_FAILED */,
+            message: "Failed to generate QR code.",
+            statusCode: 500,
+            details: { valuePreview: String(value).slice(0, 60), size },
+            retryable: false
+          })
+        );
       }
       resolve(buffer);
     });
@@ -1273,13 +1364,7 @@ function mapBarcodeTypeToBcid(bcType) {
   }
 }
 function generateBarcodeBuffer(value, options = {}) {
-  const {
-    bcType,
-    scale = 3,
-    barHeight = 10,
-    includetext = false,
-    textalign = "center"
-  } = options;
+  const { bcType, scale = 3, barHeight = 10, includetext = false, textalign = "center" } = options;
   const bcid = mapBarcodeTypeToBcid(bcType);
   return new Promise((resolve, reject) => {
     let textValue = value;
@@ -1288,12 +1373,16 @@ function generateBarcodeBuffer(value, options = {}) {
       if (digitsOnly.length === 13) {
         textValue = digitsOnly.slice(0, 12);
       } else if (digitsOnly.length === 12) {
-        textValue = textValue;
+        textValue = digitsOnly;
       } else {
         return reject(
-          new Error(
-            `EAN13 barcode value must have 12 or 13 digits, got "${value}"`
-          )
+          new PdfEngineError({
+            code: "PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH" /* PDF_ERROR_BARCODE_EAN13_INVALID_LENGTH */,
+            message: `EAN13 barcode value must have 12 or 13 digits, got "${value}"`,
+            statusCode: 422,
+            details: { value },
+            retryable: false
+          })
         );
       }
     }
@@ -1307,7 +1396,15 @@ function generateBarcodeBuffer(value, options = {}) {
     bwipOptions.textxalign = textalign;
     bwipjs.toBuffer(bwipOptions, (err, png) => {
       if (err) {
-        return reject(err);
+        return reject(
+          toPdfEngineError(err, {
+            code: "PDF_ERROR_BARCODE_GENERATION_FAILED" /* PDF_ERROR_BARCODE_GENERATION_FAILED */,
+            message: "Failed to generate barcode.",
+            statusCode: 500,
+            details: { bcType, valuePreview: String(value).slice(0, 60) },
+            retryable: false
+          })
+        );
       }
       resolve(png);
     });
@@ -1341,12 +1438,7 @@ async function materializeQrAndBarcodesInBlocks(blocks) {
       const qb = { ...block };
       if (!qb.src && qb.value) {
         const size = qb.size ?? 80;
-        const buf = await generateQrBuffer(
-          qb.value,
-          size,
-          qb.qrVersion,
-          qb.errorCorrectionLevel
-        );
+        const buf = await generateQrBuffer(qb.value, size, qb.qrVersion, qb.errorCorrectionLevel);
         qb.src = buf;
       }
       out.push(qb);
@@ -1620,9 +1712,7 @@ function drawWatermarkForPage(doc, watermark, pageNumber, isLast) {
 // src/renderer-engine/index.ts
 async function renderCustomPdf(def, outputPath) {
   if (def.header) {
-    def.header.blocks = await materializeQrAndBarcodesInBlocks(
-      def.header.blocks
-    );
+    def.header.blocks = await materializeQrAndBarcodesInBlocks(def.header.blocks);
     def.header.blocks = await materializeImagesInBlocks(def.header.blocks);
   }
   def.content = await materializeQrAndBarcodesInBlocks(def.content);
@@ -1631,9 +1721,7 @@ async function renderCustomPdf(def, outputPath) {
     def.pageBackground.src = await normalizeImageSrc(def.pageBackground.src);
   }
   if (def.header?.backgroundImage) {
-    def.header.backgroundImage = await normalizeImageSrc(
-      def.header.backgroundImage
-    );
+    def.header.backgroundImage = await normalizeImageSrc(def.header.backgroundImage);
   }
   if (def.footer && typeof def.footer !== "function") {
     const footer = def.footer;
@@ -1712,14 +1800,23 @@ async function renderCustomPdf(def, outputPath) {
     finishPage2(false);
     doc.end();
     stream.on("finish", () => resolve());
-    stream.on("error", (err) => reject(err));
+    stream.on(
+      "error",
+      (err) => reject(
+        toPdfEngineError(err, {
+          code: "PDF_ERROR_OUTPUT_STREAM_ERROR" /* PDF_ERROR_OUTPUT_STREAM_ERROR */,
+          message: "Failed while writing PDF to output stream.",
+          statusCode: 500,
+          details: { outputPath },
+          retryable: true
+        })
+      )
+    );
   });
 }
 async function renderCustomPdfToBuffer(def) {
   if (def.header) {
-    def.header.blocks = await materializeQrAndBarcodesInBlocks(
-      def.header.blocks
-    );
+    def.header.blocks = await materializeQrAndBarcodesInBlocks(def.header.blocks);
     def.header.blocks = await materializeImagesInBlocks(def.header.blocks);
   }
   def.content = await materializeQrAndBarcodesInBlocks(def.content);
@@ -1728,9 +1825,7 @@ async function renderCustomPdfToBuffer(def) {
     def.pageBackground.src = await normalizeImageSrc(def.pageBackground.src);
   }
   if (def.header?.backgroundImage) {
-    def.header.backgroundImage = await normalizeImageSrc(
-      def.header.backgroundImage
-    );
+    def.header.backgroundImage = await normalizeImageSrc(def.header.backgroundImage);
   }
   if (def.footer && typeof def.footer !== "function") {
     const footer = def.footer;
@@ -1758,7 +1853,14 @@ async function renderCustomPdfToBuffer(def) {
       resolve(Buffer.concat(chunks));
     });
     doc.on("error", (err) => {
-      reject(err);
+      reject(
+        toPdfEngineError(err, {
+          code: "PDF_ERROR_PDFKIT_ERROR" /* PDF_ERROR_PDFKIT_ERROR */,
+          message: "PDFKit emitted an error while rendering.",
+          statusCode: 500,
+          retryable: true
+        })
+      );
     });
     if (def.fonts && def.fonts.length) {
       for (const f of def.fonts) {
@@ -1818,25 +1920,9 @@ async function renderCustomPdfToBuffer(def) {
     doc.end();
   });
 }
-
-// src/types/barcode.ts
-var BARCODE_TYPES = {
-  CODE128: "CODE128",
-  EAN13: "EAN13",
-  CODE39: "CODE39",
-  ITF: "ITF",
-  CODE93: "CODE93"
-};
-
-// src/types/qr.ts
-var QR_ERROR_LEVEL = {
-  LOW: "L",
-  MEDIUM: "M",
-  QUARTILE: "Q",
-  HIGH: "H"
-};
 export {
   BARCODE_TYPES,
+  PdfEngineErrorCode,
   QR_ERROR_LEVEL,
   renderCustomPdf,
   renderCustomPdfToBuffer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "av6-pdf-engine",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.mjs",
@@ -14,6 +14,7 @@
     "format": "prettier --write **/*.ts"
   },
   "dependencies": {
+    "@types/pdfkit": "^0.13.6",
     "axios": "^1.13.2",
     "bwip-js": "^4.8.0",
     "pdfkit": "^0.15.0",
@@ -22,9 +23,10 @@
   },
   "devDependencies": {
     "@types/bwip-js": "^3.2.3",
-    "@types/pdfkit": "^0.13.6",
+    "@types/node": "^24.10.1",
     "@types/qrcode": "^1.5.6",
-    "typescript": "^5.4.0",
-    "prettier": "^3.6.2"
-  }
+    "prettier": "^3.6.2",
+    "typescript": "^5.4.0"
+  },
+  "packageManager": "pnpm@10.8.1+sha512.c50088ba998c67b8ca8c99df8a5e02fd2ae2e2b29aaf238feaa9e124248d3f48f9fb6db2424949ff901cffbb5e0f0cc1ad6aedb602cd29450751d11c35023677"
 }