@f-o-t/e-signature 1.0.7 → 1.2.0

package/README.md

@@ -19,7 +19,7 @@ bun add @f-o-t/e-signature
 
 ## API
 
-### `signPdf(pdf: Uint8Array, options: PdfSignOptions): Promise<Uint8Array>`
+### `signPdf(pdf: Uint8Array | ReadableStream<Uint8Array>, options: PdfSignOptions): Promise<Uint8Array>`
 
 Sign a PDF document with a digital certificate. Supports PAdES-BES and PAdES with ICP-Brasil compliance (signing-certificate-v2 and signature-policy attributes).
 
@@ -46,6 +46,52 @@ const signedPdf = await signPdf(pdfBytes, {
 await Bun.write("signed.pdf", signedPdf);
 ```
 
+To stamp multiple pages with the same visual appearance:
+
+```ts
+const signedPdf = await signPdf(pdfBytes, {
+  certificate: { p12, password: "secret" },
+  reason: "Document approval",
+  appearances: [
+    { x: 50, y: 730, width: 200, height: 80, page: 0, showCertInfo: true },
+    { x: 50, y: 730, width: 200, height: 80, page: 1, showCertInfo: true },
+    { x: 50, y: 730, width: 200, height: 80, page: 2, showCertInfo: true },
+  ],
+  qrCode: { data: "https://validar.iti.gov.br", size: 128 },
+});
+```
+
+`appearance` and `appearances` can be used simultaneously — both stamps are rendered. An empty `appearances: []` is a no-op.
+
+#### TSA Resilience
+
+Control timeout, retry, and fallback behavior for timestamp requests:
+
+```ts
+const signedPdf = await signPdf(pdfBytes, {
+  certificate: { p12, password: "secret" },
+  timestamp: true,
+  tsaUrl: TIMESTAMP_SERVERS.VALID,
+  tsaTimeout: 5000,           // 5s per attempt (default: 10000)
+  tsaRetries: 2,              // 2 attempts on primary (default: 1)
+  tsaFallbackUrls: [          // tried in order after primary fails
+    TIMESTAMP_SERVERS.SAFEWEB,
+    TIMESTAMP_SERVERS.CERTISIGN,
+  ],
+});
+```
+
+If all servers fail, a `TimestampError` is thrown with a descriptive message identifying which servers were tried and the last error.
+
+#### Signing from a ReadableStream
+
+```ts
+const stream: ReadableStream<Uint8Array> = getFileStream("document.pdf");
+const signedPdf = await signPdf(stream, {
+  certificate: { p12, password: "secret" },
+});
+```
+
 ### `buildSigningCertificateV2(certDer: Uint8Array): Uint8Array`
 
 Build the `id-aa-signingCertificateV2` attribute value (RFC 5035). Links the signature to the specific certificate used, preventing substitution attacks.
@@ -58,7 +104,7 @@ Build the `id-aa-ets-sigPolicyId` attribute value. Downloads the ICP-Brasil PAdE
 
 Clear the cached signature policy data, forcing a re-download on the next call.
 
-### `requestTimestamp(data: Uint8Array, tsaUrl: string, hashAlgorithm?: "sha256" | "sha384" | "sha512"): Promise<Uint8Array>`
+### `requestTimestamp(data: Uint8Array, tsaUrl: string, hashAlgorithm?: "sha256" | "sha384" | "sha512", options?: { tsaTimeout?: number; tsaRetries?: number; tsaFallbackUrls?: string[] }): Promise<Uint8Array>`
 
 Request an RFC 3161 timestamp from a TSA server. Returns the DER-encoded TimeStampToken.
 
@@ -68,6 +114,50 @@ import { requestTimestamp, TIMESTAMP_SERVERS } from "@f-o-t/e-signature";
 const token = await requestTimestamp(signatureBytes, TIMESTAMP_SERVERS.VALID);
 ```
 
+### `signPdfBatch(files: BatchSignInput[], options: PdfSignOptions): AsyncGenerator<BatchSignEvent>`
+
+Sign multiple PDFs sequentially, yielding progress events. Yields control between each signing to prevent blocking the event loop.
+
+```ts
+import { signPdfBatch, signPdfBatchToArray, TIMESTAMP_SERVERS } from "@f-o-t/e-signature";
+
+for await (const event of signPdfBatch(
+  [
+    { filename: "doc1.pdf", pdf: pdf1Bytes },
+    { filename: "doc2.pdf", pdf: pdf2Bytes, options: { reason: "Custom reason" } },
+  ],
+  { certificate: { p12, password: "secret" } },
+)) {
+  switch (event.type) {
+    case "file_start": console.log(`Signing ${event.filename}...`); break;
+    case "file_complete": console.log(`Signed ${event.filename}`); break;
+    case "file_error": console.error(`Failed ${event.filename}: ${event.error}`); break;
+    case "batch_complete": console.log(`Done: ${event.totalFiles} files, ${event.errorCount} errors`); break;
+  }
+}
+```
+
+Per-file `options` are merged with the base options (per-file takes priority). Error in one file emits a `file_error` event and continues with the next file.
+
+### `signPdfBatchToArray(files: BatchSignInput[], options: PdfSignOptions): Promise<...[]>`
+
+Convenience wrapper that collects all results:
+
+```ts
+const results = await signPdfBatchToArray(
+  [
+    { filename: "doc1.pdf", pdf: pdf1Bytes },
+    { filename: "doc2.pdf", pdf: pdf2Bytes },
+  ],
+  { certificate: { p12, password: "secret" } },
+);
+
+for (const r of results) {
+  if (r.signed) await Bun.write(r.filename, r.signed);
+  else console.error(`${r.filename}: ${r.error}`);
+}
+```
+
 ## Constants
 
 ### `ICP_BRASIL_OIDS`
@@ -102,7 +192,16 @@ type PdfSignOptions = {
   policy?: "pades-ades" | "pades-icp-brasil";
   timestamp?: boolean;
   tsaUrl?: string;
+  /** Timeout in ms per TSA attempt (default: 10000) */
+  tsaTimeout?: number;
+  /** Number of retry attempts on primary TSA server before trying fallbacks (default: 1) */
+  tsaRetries?: number;
+  /** Fallback TSA server URLs tried in order after primary is exhausted */
+  tsaFallbackUrls?: string[];
+  /** Single visual stamp (false to disable) */
   appearance?: SignatureAppearance | false;
+  /** Multiple visual stamps — renders one per entry, useful for multi-page documents */
+  appearances?: SignatureAppearance[];
   qrCode?: QrCodeConfig;
   docMdpPermission?: 1 | 2 | 3;
 };
@@ -121,6 +220,21 @@ type QrCodeConfig = {
   data?: string;
   size?: number;
 };
+
+type BatchSignInput = {
+  /** Filename for identification in events */
+  filename: string;
+  /** PDF content as Uint8Array or ReadableStream */
+  pdf: Uint8Array | ReadableStream<Uint8Array>;
+  /** Per-file option overrides merged with base options */
+  options?: Partial<PdfSignOptions>;
+};
+
+type BatchSignEvent =
+  | { type: "file_start"; fileIndex: number; filename: string }
+  | { type: "file_complete"; fileIndex: number; filename: string; signed: Uint8Array }
+  | { type: "file_error"; fileIndex: number; filename: string; error: string }
+  | { type: "batch_complete"; totalFiles: number; errorCount: number };
 ```
 
 ## Error Classes

package/dist/appearance.d.ts

@@ -5,8 +5,8 @@
  * for visible digital signatures.
  */
 import type { CertificateInfo } from "@f-o-t/digital-certificate";
-import type { PdfPage, PdfDocument } from "@f-o-t/pdf/plugins/editing";
-import type { SignatureAppearance, QrCodeConfig } from "./types.ts";
+import type { PdfDocument, PdfPage } from "@f-o-t/pdf/plugins/editing";
+import type { QrCodeConfig, SignatureAppearance } from "./types.ts";
 /**
  * Draw the visual signature appearance on a PDF page.
  *

package/dist/appearance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../src/appearance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAGvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,EAAE,eAAe,GAAG,IAAI,EAChC,OAAO,EAAE;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,UAAU,CAAC;CACpB,GACC,IAAI,CA6CN"}
+{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../src/appearance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAEvE,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,uBAAuB,CACpC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,EAAE,eAAe,GAAG,IAAI,EAChC,OAAO,EAAE;IACN,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,UAAU,CAAC;CACtB,GACD,IAAI,CA6CN"}

package/dist/batch.d.ts

@@ -0,0 +1,61 @@
+import type { PdfSignOptions } from "./types.ts";
+/**
+ * Input for a single PDF in a batch signing operation.
+ */
+export type BatchSignInput = {
+    /** Filename for identification in events */
+    filename: string;
+    /** PDF content as Uint8Array or ReadableStream */
+    pdf: Uint8Array | ReadableStream<Uint8Array>;
+    /** Per-file option overrides merged with base options */
+    options?: Partial<PdfSignOptions>;
+};
+/**
+ * Events emitted during batch signing.
+ */
+export type BatchSignEvent = {
+    type: "file_start";
+    fileIndex: number;
+    filename: string;
+} | {
+    type: "file_complete";
+    fileIndex: number;
+    filename: string;
+    signed: Uint8Array;
+} | {
+    type: "file_error";
+    fileIndex: number;
+    filename: string;
+    error: string;
+} | {
+    type: "batch_complete";
+    totalFiles: number;
+    errorCount: number;
+};
+/**
+ * Sign multiple PDFs sequentially, yielding progress events.
+ *
+ * Yields control between each signing operation to prevent blocking
+ * the event loop under bulk load.
+ *
+ * @param files - Array of PDFs with filename and optional per-file options
+ * @param options - Base signing options (per-file options override these)
+ * @yields BatchSignEvent for each file start, completion, error, and batch complete
+ */
+export declare function signPdfBatch(files: BatchSignInput[], options: PdfSignOptions): AsyncGenerator<BatchSignEvent>;
+/**
+ * Sign multiple PDFs sequentially, collecting all results.
+ *
+ * Convenience wrapper around {@link signPdfBatch} that collects all events
+ * into an array of results.
+ *
+ * @param files - Array of PDFs with filename and optional per-file options
+ * @param options - Base signing options
+ * @returns Array of results with signed PDF bytes or error per file
+ */
+export declare function signPdfBatchToArray(files: BatchSignInput[], options: PdfSignOptions): Promise<{
+    filename: string;
+    signed?: Uint8Array;
+    error?: string;
+}[]>;
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,GAAG,EAAE,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAC7C,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACnC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAClF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;;;;;GASG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,cAAc,GACtB,cAAc,CAAC,cAAc,CAAC,CA+BhC;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAoBtE"}

package/dist/icp-brasil.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"icp-brasil.d.ts","sourceRoot":"","sources":["../src/icp-brasil.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8CH;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAuCzE;AA2ED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,UAAU,CAAC,CA8BhE;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAMX,qBAAa,oBAAqB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI3B"}
+{"version":3,"file":"icp-brasil.d.ts","sourceRoot":"","sources":["../src/icp-brasil.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8CH;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAuCzE;AAyED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,UAAU,CAAC,CA8BhE;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAMX,qBAAa,oBAAqB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI7B"}

package/dist/index.d.ts

@@ -6,9 +6,11 @@
  *
  * @packageDocumentation
  */
-export { signPdf, PdfSignError } from "./sign-pdf.ts";
-export { buildSigningCertificateV2, buildSignaturePolicy, clearPolicyCache, SignaturePolicyError, ICP_BRASIL_OIDS, } from "./icp-brasil.ts";
-export { requestTimestamp, TimestampError, TIMESTAMP_SERVERS, TIMESTAMP_TOKEN_OID, } from "./timestamp.ts";
-export type { PdfSignOptions, SignatureAppearance, QrCodeConfig } from "./types.ts";
+export { signPdfBatch, signPdfBatchToArray } from "./batch.ts";
+export type { BatchSignEvent, BatchSignInput } from "./batch.ts";
+export { buildSignaturePolicy, buildSigningCertificateV2, clearPolicyCache, ICP_BRASIL_OIDS, SignaturePolicyError, } from "./icp-brasil.ts";
 export { pdfSignOptionsSchema } from "./schemas.ts";
+export { PdfSignError, signPdf } from "./sign-pdf.ts";
+export { requestTimestamp, TIMESTAMP_SERVERS, TIMESTAMP_TOKEN_OID, TimestampError, } from "./timestamp.ts";
+export type { PdfSignOptions, QrCodeConfig, SignatureAppearance, } from "./types.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EACN,yBAAyB,EACzB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EACJ,oBAAoB,EACpB,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EACJ,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,GAChB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,GACrB,MAAM,YAAY,CAAC"}