@validpay/node-sdk 0.6.0 → 0.7.0

package/README.md

@@ -62,6 +62,62 @@ const verifyUrl = `https://validpay.com/verify/${retrievalId}#key=${toBase64Url(
 
 `toBase64Url` matters because phone QR scanners + browser share-sheets mangle `+`, `/`, and `=` in URL fragments. The `/verify` page accepts both standard base64 and base64url for backward compatibility, but new links should always emit base64url.
 
+### Placing the QR on a document (`embedQr`)
+
+For a PDF, `embedQr` builds the verify QR and stamps it onto the page for you — so you don't have to wire up a QR library, base64url the key, or wrestle with PDF coordinates (PDFs use a bottom-left origin; everything else uses top-left).
+
+`embedQr` needs two **optional** peer dependencies — the core client stays dependency-free, so install them only if you use it:
+
+```bash
+npm i pdf-lib qrcode
+```
+
+```ts
+import { ValidPayClient, embedQr } from "@validpay/node-sdk";
+import { readFile, writeFile } from "node:fs/promises";
+
+const client = new ValidPayClient({ apiKey: process.env.VALIDPAY_API_KEY! });
+
+const original = await readFile("invoice.pdf");
+const { retrievalId, key } = await client.createFileIntent({
+  documentType: "invoice",
+  file: original,
+  fileContentType: "application/pdf",
+});
+
+const sealed = await embedQr(original, {
+  retrievalId,
+  key,
+  // 90pt (1.25in) QR, 36pt in from the bottom-right corner.
+  placement: { anchor: "bottom-right", x: 36, y: 36, width: 90 },
+});
+await writeFile("invoice-sealed.pdf", sealed);
+```
+
+#### The placement contract
+
+Coordinates read the way you think about a page, and are identical to what the **"Try it" placement tool** in the developer console emits — so position once in the UI, copy the call, and it lands in the same spot.
+
+| field    | meaning | default |
+| -------- | ------- | ------- |
+| `anchor` | which page **corner** the insets are measured from (`top-left` \| `top-right` \| `bottom-left` \| `bottom-right`) | `top-left` |
+| `x`      | horizontal inset from that corner's vertical edge | — |
+| `y`      | vertical inset from that corner's horizontal edge | — |
+| `width`  | QR side length (it's square) | — |
+| `units`  | `pt` (1/72in) \| `mm` \| `in` | `pt` |
+| `page`   | 1-based page number | `1` |
+
+`{ anchor: "bottom-right", x: 36, y: 36, width: 90 }` sits 36pt in from the bottom and right edges — and stays bottom-right on any page size. Keep the QR **≥ ~72pt (1in)** so it scans reliably once printed; `embedQr` warns below that and throws if the placement runs off the page.
+
+If you render PDFs with a different library, the two pure helpers are exported too:
+
+```ts
+import { buildVerifyUrl, resolveQrRect } from "@validpay/node-sdk";
+
+const url  = buildVerifyUrl(retrievalId, key);               // base64url key in the fragment
+const rect = resolveQrRect(placement, pageWidthPt, pageHeightPt); // → { x, y, size } in pdf bottom-left points
+```
+
 ## How it works
 
 1. `createIntent` generates a fresh 256-bit key, encrypts your payload locally with AES-256-GCM, computes a SHA-256 commitment hash of the plaintext, and POSTs only the ciphertext + hash to `POST /v1/intent`.

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export { ValidPayClient } from "./client.js";
 export { generateKey, encrypt, encryptBytes, decrypt, decryptBytes, commitmentHash, splitKey, combineKeyShares, encryptFields, buildKeyMap, decryptFields, } from "./crypto.js";
 export { ValidPayError, type ValidPayClientOptions, type CreateIntentParams, type CreateFileIntentParams, type BatchIntentItem, type SelectiveIntentParams, type CreateIntentResult, type VerifyIntentResult, type TimeLockStatus, type RevocationResult, type RevocationEvent, type RawIntentResponse, type RawCreateIntentResponse, } from "./types.js";
 export { verifyWebhookSignature, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type VerifyWebhookOptions, type WebhookVerifyResult, type WebhookVerifyFailureReason, } from "./webhookSignature.js";
+export { buildVerifyUrl, resolveQrRect, embedQr, MIN_RECOMMENDED_QR_PT, type QrAnchor, type QrUnit, type QrPlacement, type VerifyUrlOptions, type ResolvedQrRect, type QrRenderOptions, type EmbedQrOptions, } from "./pdf.js";
 //# 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,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,OAAO,EACP,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,EACb,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,OAAO,EACP,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,EACb,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,aAAa,EACb,OAAO,EACP,qBAAqB,EACrB,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -2,4 +2,5 @@ export { ValidPayClient } from "./client.js";
 export { generateKey, encrypt, encryptBytes, decrypt, decryptBytes, commitmentHash, splitKey, combineKeyShares, encryptFields, buildKeyMap, decryptFields, } from "./crypto.js";
 export { ValidPayError, } from "./types.js";
 export { verifyWebhookSignature, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, } from "./webhookSignature.js";
+export { buildVerifyUrl, resolveQrRect, embedQr, MIN_RECOMMENDED_QR_PT, } from "./pdf.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,OAAO,EACP,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,GAad,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,iCAAiC,GAIlC,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,OAAO,EACP,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,GAad,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,iCAAiC,GAIlC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,aAAa,EACb,OAAO,EACP,qBAAqB,GAQtB,MAAM,UAAU,CAAC"}

package/dist/pdf.d.ts

@@ -0,0 +1,116 @@
+/** Which page corner the (x, y) inset is measured from. */
+export type QrAnchor = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** Units for placement values. 1pt = 1/72 inch (PDF's native unit). */
+export type QrUnit = "pt" | "mm" | "in";
+/**
+ * Where to place the QR on a page, in a coordinate system that matches how
+ * people actually think about documents:
+ *
+ *   - `anchor` names a page CORNER.
+ *   - `x` is the horizontal inset from that corner's vertical edge.
+ *   - `y` is the vertical inset from that corner's horizontal edge.
+ *   - The QR's matching corner is pinned at that inset.
+ *
+ * So `{ anchor: "bottom-right", x: 36, y: 36, width: 90 }` is a 90pt QR sitting
+ * 36pt in from the bottom and right edges — and it stays bottom-right on any
+ * page size. The default `top-left` anchor reads like screen coordinates.
+ */
+export interface QrPlacement {
+    /** 1-based page number. Default `1`. */
+    page?: number;
+    /** Page corner the insets are measured from. Default `"top-left"`. */
+    anchor?: QrAnchor;
+    /** Horizontal inset from the anchor's vertical edge, in `units`. */
+    x: number;
+    /** Vertical inset from the anchor's horizontal edge, in `units`. */
+    y: number;
+    /** QR side length (it is square), in `units`. */
+    width: number;
+    /** Units for `x` / `y` / `width`. Default `"pt"`. */
+    units?: QrUnit;
+}
+/**
+ * Smallest QR side we consider reliably scannable from a printed page at
+ * arm's length (~72pt ≈ 1in ≈ 2.54cm). Below this, {@link embedQr} emits a
+ * one-time console warning. Advisory only — not enforced.
+ */
+export declare const MIN_RECOMMENDED_QR_PT = 72;
+export interface VerifyUrlOptions {
+    /** Web origin that serves `/verify`. Default `"https://validpay.com"`. */
+    baseUrl?: string;
+}
+/**
+ * Build the canonical verify URL the QR encodes:
+ *
+ *     <baseUrl>/verify/<retrievalId>#key=<base64url(key)>
+ *
+ * The key is placed in the URL FRAGMENT (`#key=`), which browsers never send
+ * to any server — so the decryption share rides along with the scan without
+ * ever touching ValidPay's logs. The key is converted to base64url so phone
+ * scanners don't mangle it.
+ */
+export declare function buildVerifyUrl(retrievalId: string, key: string, opts?: VerifyUrlOptions): string;
+/** A QR rectangle in pdf-lib's bottom-left-origin point space. */
+export interface ResolvedQrRect {
+    /** Distance from the page's LEFT edge to the QR's left edge, in points. */
+    x: number;
+    /** Distance from the page's BOTTOM edge to the QR's bottom edge, in points. */
+    y: number;
+    /** QR side length, in points. */
+    size: number;
+}
+/**
+ * Convert a canonical {@link QrPlacement} (top-left-friendly, anchor-relative
+ * insets, arbitrary units) into pdf-lib's bottom-left-origin point rectangle
+ * for a page of the given size.
+ *
+ * This is the EXACT conversion the website "Try it" tool uses, so coordinates
+ * you copy from the tool land in the same place here. Pure and
+ * dependency-free.
+ */
+export declare function resolveQrRect(placement: QrPlacement, pageWidthPt: number, pageHeightPt: number): ResolvedQrRect;
+export interface QrRenderOptions {
+    /**
+     * Error-correction level. Higher tolerates more print damage/smudging at
+     * the cost of density. Default `"M"` (15%); use `"Q"` (25%) for documents
+     * that get printed and re-scanned in the wild.
+     */
+    errorCorrectionLevel?: "L" | "M" | "Q" | "H";
+    /** Quiet-zone width in modules. Default `2`. Don't go below 1 or scanners struggle. */
+    margin?: number;
+    /** Foreground (module) color. Default `"#0A0F1E"`. */
+    darkColor?: string;
+    /** Background color. Default `"#FFFFFF"` — keep it opaque for contrast. */
+    lightColor?: string;
+    /** Raster resolution in px for the embedded image. Default `1024`. */
+    renderPx?: number;
+}
+export interface EmbedQrOptions {
+    /** From `createIntent` / `createFileIntent`. */
+    retrievalId: string;
+    /** Share A from `createIntent` / `createFileIntent`. */
+    key: string;
+    /** Where to stamp the QR. */
+    placement: QrPlacement;
+    /** Verify URL base. Default `"https://validpay.com"`. */
+    baseUrl?: string;
+    /** QR rendering tweaks. */
+    qr?: QrRenderOptions;
+}
+/**
+ * Stamp a scannable verify QR onto an existing PDF and return the new PDF
+ * bytes. The input is not mutated.
+ *
+ * Requires the optional peer deps `pdf-lib` and `qrcode` (`npm i pdf-lib
+ * qrcode`); it throws a `missing_dependency` ValidPayError if either is
+ * absent. Works in Node and the browser (both libs are isomorphic).
+ *
+ * @example
+ * const { retrievalId, key } = await client.createFileIntent({ documentType: "invoice", file });
+ * const sealed = await embedQr(originalPdfBytes, {
+ *   retrievalId, key,
+ *   placement: { anchor: "bottom-right", x: 36, y: 36, width: 90 },
+ * });
+ */
+export declare function embedQr(pdf: Uint8Array, opts: EmbedQrOptions): Promise<Uint8Array>;
+//# sourceMappingURL=pdf.d.ts.map

package/dist/pdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf.d.ts","sourceRoot":"","sources":["../src/pdf.ts"],"names":[],"mappings":"AA4BA,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,cAAc,CAAC;AAEjF,uEAAuE;AACvE,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,oEAAoE;IACpE,CAAC,EAAE,MAAM,CAAC;IACV,oEAAoE;IACpE,CAAC,EAAE,MAAM,CAAC;IACV,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAIxC,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,gBAAqB,GAC1B,MAAM,CASR;AAID,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,CAAC,EAAE,MAAM,CAAC;IACV,+EAA+E;IAC/E,CAAC,EAAE,MAAM,CAAC;IACV,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,WAAW,EACtB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,cAAc,CAiBhB;AAID,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC7C,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,SAAS,EAAE,WAAW,CAAC;IACvB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,EAAE,CAAC,EAAE,eAAe,CAAC;CACtB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,OAAO,CAC3B,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,UAAU,CAAC,CAuDrB"}

package/dist/pdf.js

@@ -0,0 +1,172 @@
+/**
+ * QR placement helpers (file mode add-on).
+ *
+ * `createFileIntent` / `createIntent` seal a document and return
+ * `{ retrievalId, key }`. To actually verify it, a scannable QR encoding the
+ * verify URL must appear ON the document. WHERE that QR goes is the
+ * integrator's call — but historically they were on their own to render it
+ * and to guess coordinates, which is fiddly and error-prone (PDFs use a
+ * bottom-left origin; every screen uses top-left).
+ *
+ * This module fixes that with one canonical placement contract used by the
+ * SDK, the website "Try it" tool, and the docs, so a position you pick once
+ * (e.g. in the tool) maps to the exact same spot here.
+ *
+ * `pdf-lib` and `qrcode` are OPTIONAL peer dependencies — the core
+ * `ValidPayClient` stays zero-dependency. They're loaded lazily, so you only
+ * need them installed if you call {@link embedQr}:
+ *
+ *     npm i pdf-lib qrcode
+ *
+ * The coordinate math ({@link resolveQrRect}) and {@link buildVerifyUrl} are
+ * pure and dependency-free — use them directly if you render PDFs with a
+ * different library.
+ */
+import { ValidPayError } from "./types.js";
+const UNIT_TO_PT = { pt: 1, mm: 72 / 25.4, in: 72 };
+/**
+ * Smallest QR side we consider reliably scannable from a printed page at
+ * arm's length (~72pt ≈ 1in ≈ 2.54cm). Below this, {@link embedQr} emits a
+ * one-time console warning. Advisory only — not enforced.
+ */
+export const MIN_RECOMMENDED_QR_PT = 72;
+/** base64 → base64url. Phone QR scanners and share-sheets mangle `+`, `/`,
+ *  and `=` inside URL fragments, so keys must be base64url in a QR. Idempotent
+ *  on already-base64url input; the `/verify` page accepts both. */
+function toBase64Url(b64) {
+    return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Build the canonical verify URL the QR encodes:
+ *
+ *     <baseUrl>/verify/<retrievalId>#key=<base64url(key)>
+ *
+ * The key is placed in the URL FRAGMENT (`#key=`), which browsers never send
+ * to any server — so the decryption share rides along with the scan without
+ * ever touching ValidPay's logs. The key is converted to base64url so phone
+ * scanners don't mangle it.
+ */
+export function buildVerifyUrl(retrievalId, key, opts = {}) {
+    if (!retrievalId) {
+        throw new ValidPayError("invalid_argument", "retrievalId is required");
+    }
+    if (!key) {
+        throw new ValidPayError("invalid_argument", "key is required");
+    }
+    const base = (opts.baseUrl ?? "https://validpay.com").replace(/\/+$/, "");
+    return `${base}/verify/${encodeURIComponent(retrievalId)}#key=${toBase64Url(key)}`;
+}
+/**
+ * Convert a canonical {@link QrPlacement} (top-left-friendly, anchor-relative
+ * insets, arbitrary units) into pdf-lib's bottom-left-origin point rectangle
+ * for a page of the given size.
+ *
+ * This is the EXACT conversion the website "Try it" tool uses, so coordinates
+ * you copy from the tool land in the same place here. Pure and
+ * dependency-free.
+ */
+export function resolveQrRect(placement, pageWidthPt, pageHeightPt) {
+    const unit = UNIT_TO_PT[placement.units ?? "pt"];
+    const size = placement.width * unit;
+    const insetX = placement.x * unit;
+    const insetY = placement.y * unit;
+    const anchor = placement.anchor ?? "top-left";
+    const leftAnchored = anchor === "top-left" || anchor === "bottom-left";
+    const topAnchored = anchor === "top-left" || anchor === "top-right";
+    // Horizontal: inset measured from the left or right edge to the QR's left.
+    const x = leftAnchored ? insetX : pageWidthPt - insetX - size;
+    // Vertical: pdf-lib y is the QR's BOTTOM edge from the page bottom. A top
+    // inset measures from the page top down to the QR's top edge.
+    const y = topAnchored ? pageHeightPt - insetY - size : insetY;
+    return { x, y, size };
+}
+let smallQrWarned = false;
+/**
+ * Stamp a scannable verify QR onto an existing PDF and return the new PDF
+ * bytes. The input is not mutated.
+ *
+ * Requires the optional peer deps `pdf-lib` and `qrcode` (`npm i pdf-lib
+ * qrcode`); it throws a `missing_dependency` ValidPayError if either is
+ * absent. Works in Node and the browser (both libs are isomorphic).
+ *
+ * @example
+ * const { retrievalId, key } = await client.createFileIntent({ documentType: "invoice", file });
+ * const sealed = await embedQr(originalPdfBytes, {
+ *   retrievalId, key,
+ *   placement: { anchor: "bottom-right", x: 36, y: 36, width: 90 },
+ * });
+ */
+export async function embedQr(pdf, opts) {
+    if (!(pdf instanceof Uint8Array) || pdf.length === 0) {
+        throw new ValidPayError("invalid_argument", "pdf must be non-empty Uint8Array/Buffer bytes");
+    }
+    if (!opts?.placement) {
+        throw new ValidPayError("invalid_argument", "placement is required");
+    }
+    if (!(opts.placement.width > 0)) {
+        throw new ValidPayError("invalid_argument", "placement.width must be > 0");
+    }
+    const { PDFDocument } = await loadPdfLib();
+    const qrcode = await loadQrcode();
+    const url = buildVerifyUrl(opts.retrievalId, opts.key, { baseUrl: opts.baseUrl });
+    const q = opts.qr ?? {};
+    const dataUrl = await qrcode.toDataURL(url, {
+        errorCorrectionLevel: q.errorCorrectionLevel ?? "M",
+        margin: q.margin ?? 2,
+        width: q.renderPx ?? 1024,
+        color: { dark: q.darkColor ?? "#0A0F1E", light: q.lightColor ?? "#FFFFFF" },
+    });
+    const pngBytes = dataUrlToBytes(dataUrl);
+    const doc = await PDFDocument.load(pdf);
+    const pages = doc.getPages();
+    const pageIndex = (opts.placement.page ?? 1) - 1;
+    if (pageIndex < 0 || pageIndex >= pages.length) {
+        throw new ValidPayError("invalid_argument", `placement.page ${opts.placement.page ?? 1} is out of range (document has ${pages.length} page(s))`);
+    }
+    const page = pages[pageIndex];
+    const { width, height } = page.getSize();
+    const rect = resolveQrRect(opts.placement, width, height);
+    if (rect.size < MIN_RECOMMENDED_QR_PT && !smallQrWarned) {
+        smallQrWarned = true;
+        // eslint-disable-next-line no-console
+        console.warn(`[validpay] QR is ${rect.size.toFixed(0)}pt wide — below the ~${MIN_RECOMMENDED_QR_PT}pt ` +
+            "(1in) recommended minimum; it may be hard to scan once printed.");
+    }
+    if (rect.x < 0 || rect.y < 0 || rect.x + rect.size > width || rect.y + rect.size > height) {
+        throw new ValidPayError("invalid_argument", "placement puts the QR (partly) off the page — check x/y/width against the page size");
+    }
+    const png = await doc.embedPng(pngBytes);
+    page.drawImage(png, { x: rect.x, y: rect.y, width: rect.size, height: rect.size });
+    return doc.save();
+}
+// ── internals ───────────────────────────────────────────────────────────────
+/** Decode a `data:image/png;base64,...` URL to raw bytes (Node or browser). */
+function dataUrlToBytes(dataUrl) {
+    const b64 = dataUrl.replace(/^data:[^,]*,/, "");
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(b64, "base64"));
+    }
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+async function loadPdfLib() {
+    try {
+        return (await import("pdf-lib"));
+    }
+    catch {
+        throw new ValidPayError("missing_dependency", "embedQr requires the optional peer dependency 'pdf-lib'. Install it: npm i pdf-lib");
+    }
+}
+async function loadQrcode() {
+    try {
+        const mod = (await import("qrcode"));
+        return (mod.default ?? mod);
+    }
+    catch {
+        throw new ValidPayError("missing_dependency", "embedQr requires the optional peer dependency 'qrcode'. Install it: npm i qrcode");
+    }
+}
+//# sourceMappingURL=pdf.js.map

package/dist/pdf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf.js","sourceRoot":"","sources":["../src/pdf.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@validpay/node-sdk",
-  "version": "0.6.0",
-  "description": "Official ValidPay Node.js SDK — client-side AES-256-GCM encryption + commitment hashing + split-key + selective disclosure + revocation. Zero production dependencies.",
+  "version": "0.7.0",
+  "description": "Official ValidPay Node.js SDK — client-side AES-256-GCM encryption + commitment hashing + split-key + selective disclosure + revocation + QR placement. Zero required production dependencies.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -47,8 +47,19 @@
   },
   "license": "MIT",
   "author": "ValidPay",
+  "peerDependencies": {
+    "pdf-lib": ">=1.17.0",
+    "qrcode": ">=1.5.0"
+  },
+  "peerDependenciesMeta": {
+    "pdf-lib": { "optional": true },
+    "qrcode": { "optional": true }
+  },
   "devDependencies": {
     "@types/node": "^20.11.0",
+    "@types/qrcode": "^1.5.5",
+    "pdf-lib": "^1.17.1",
+    "qrcode": "^1.5.4",
     "typescript": "^5.4.0",
     "vitest": "^1.6.0"
   }