quadqr-js 1.0.2 → 1.2.0

package/types/index.d.ts

@@ -1,5 +1,7 @@
 export type EccLevel = "L" | "M" | "Q" | "H";
 export type RenderStyle = "classic" | "depth" | "soft" | "inset";
+export type RenderMode = "screen" | "print";
+export type CompressionMode = "none" | "auto" | "lz";
 export type SecurityMode = "password" | "raw-key";
 
 export interface Palette {
@@ -11,12 +13,28 @@ export interface Palette {
 }
 
 export interface EncodeOptions {
-  version?: number;
+  version?: number | "auto";
+  minVersion?: number;
+  maxVersion?: number;
   ecc?: EccLevel;
   maskId?: number;
   text?: boolean;
+  compression?: CompressionMode;
 }
 
+export interface SigningOptions {
+  /** Private Ed25519 key used to create the signature. Never embed or distribute it. */
+  privateKey: CryptoKey | Uint8Array | ArrayBuffer;
+  /** Optional compact identifier stored with the signature so a verifier can select a trusted public key. */
+  keyId?: string;
+  /** Optional public key used only when embedPublicKey is explicitly enabled. */
+  publicKey?: CryptoKey | Uint8Array | ArrayBuffer;
+  /** Embed the public key for self-contained integrity checks. Default: false. */
+  embedPublicKey?: boolean;
+}
+
+export interface SignedEncodeOptions extends EncodeOptions, SigningOptions {}
+
 export interface PasswordSecurity {
   mode: "password";
   password: string;
@@ -32,6 +50,7 @@ export interface RawKeySecurity {
 
 export interface SecureEncodeOptions extends EncodeOptions {
   security: PasswordSecurity | RawKeySecurity;
+  signing?: SigningOptions;
 }
 
 export interface QuadQRCode {
@@ -43,6 +62,9 @@ export interface QuadQRCode {
   payloadBytes: number;
   capacityBytes: number;
   secure?: boolean;
+  compressed?: boolean;
+  compression?: "none" | "lz";
+  signed?: boolean;
   security?: SecurityMetadata | null;
   [key: string]: unknown;
 }
@@ -61,6 +83,22 @@ export interface SecurityMetadata {
   [key: string]: unknown;
 }
 
+export interface ScanDiagnostics {
+  confidence: number;
+  cellConfidence: number;
+  structureConfidence: number;
+  geometryConfidence: number;
+  calibrationConfidence: number;
+  eccUtilization: number;
+  correctedErrors: number;
+  erasureSymbols: number;
+  stages?: Record<string, boolean>;
+  failedStage?: string | null;
+  geometryCandidates?: unknown[];
+  sampled?: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+
 export interface DecodeResult {
   payload: Uint8Array;
   text: string | null;
@@ -73,6 +111,24 @@ export interface DecodeResult {
   decrypted?: boolean;
   security?: SecurityMetadata | null;
   encryptedPayload?: Uint8Array;
+  protectedPayload?: Uint8Array;
+  compressed?: boolean;
+  compression?: "none" | "lz";
+  signed?: boolean;
+  /** Legacy v1 signer label, if decoding an older signed symbol. */
+  signer?: string | null;
+  signingKeyId?: string | null;
+  hasEmbeddedPublicKey?: boolean;
+  signatureVerified?: boolean | null;
+  signatureTrusted?: boolean | null;
+  signatureTrustSource?: "external" | "embedded" | null;
+  confidence?: number;
+  geometryConfidence?: number;
+  calibrationConfidence?: number;
+  structureConfidence?: number;
+  correctedErrors?: number;
+  eccUtilization?: number;
+  diagnostics?: ScanDiagnostics;
   [key: string]: unknown;
 }
 
@@ -82,6 +138,21 @@ export interface ImageDataLike {
   data: Uint8ClampedArray | Uint8Array;
 }
 
+export interface LogoRenderOptions {
+  /** Loaded CanvasImageSource in canvas rendering, ImageDataLike in pixel rendering, or URL/data URL in SVG rendering. */
+  source: CanvasImageSource | ImageDataLike | string;
+  /** Logo width/height as a fraction of the symbol area. Clamped to 0.05..0.30. Default: 0.18. */
+  size?: number | "auto";
+  /** Clear the modules behind the logo with a solid background before drawing it. */
+  clearBackground?: boolean;
+  /** Background padding around the logo in modules. Default: 0.65. */
+  padding?: number;
+  /** Rounded background corner radius in modules. Default: 0.8. */
+  radius?: number;
+  /** Background color used when clearBackground is enabled. Default: palette white. */
+  backgroundColor?: string;
+}
+
 export interface CameraFinderDiagnostic {
   x: number;
   y: number;
@@ -128,14 +199,30 @@ export interface CameraDiagnosticEvent {
 }
 
 export interface RenderOptions {
+  /** Exact square output size in pixels. If neither imageSize nor moduleSize is supplied, defaults to 720. */
+  imageSize?: number;
+  /** Legacy/low-level pixels per module sizing. Used when imageSize is not supplied. */
   moduleSize?: number;
   quietZone?: number;
   palette?: Palette;
   style?: RenderStyle;
+  /** Screen defaults or print-safe palette/quiet-zone/classic-style behavior. */
+  mode?: RenderMode;
+  renderMode?: RenderMode;
+  allowStyledPrint?: boolean;
+  allowUnsafePrintQuietZone?: boolean;
+  logo?: CanvasImageSource | ImageDataLike | string | LogoRenderOptions;
+  logoSize?: number;
+  logoClearBackground?: boolean;
+  logoPadding?: number;
+  logoRadius?: number;
+  logoBackgroundColor?: string;
   [key: string]: unknown;
 }
 
 export interface ScanOptions {
+  debug?: boolean;
+  debugMatrices?: boolean;
   minVersion?: number;
   maxVersion?: number;
   perspective?: boolean;
@@ -224,6 +311,10 @@ export const FORMAT_VERSION: number;
 export const MIN_VERSION: number;
 export const MAX_VERSION: number;
 export const DEFAULT_ECC_LEVEL: EccLevel;
+export const RENDER_MODES: Readonly<{ SCREEN: "screen"; PRINT: "print" }>;
+export const PRINT_PALETTE: Readonly<Required<Palette>>;
+export const COMPRESSION_MODES: Readonly<Record<string, CompressionMode>>;
+export const SIGNATURE_ALGORITHMS: Readonly<{ ED25519: "Ed25519" }>;
 export const CELL: Readonly<{ BLACK: -1; RED: 0; GREEN: 1; BLUE: 2; WHITE: 3 }>;
 export const DEFAULT_PALETTE: Readonly<Required<Palette>>;
 export const RENDER_STYLES: Readonly<Record<string, RenderStyle>>;
@@ -235,16 +326,39 @@ export const DEFAULT_PBKDF2_ITERATIONS: number;
 
 export function encodeText(text: string, options?: EncodeOptions): QuadQRCode;
 export function encodeBytes(input: Uint8Array | ArrayBuffer | ArrayLike<number>, options?: EncodeOptions): QuadQRCode;
+export function encodeUint8Array(input: Uint8Array | ArrayBuffer | ArrayLike<number>, options?: EncodeOptions): QuadQRCode;
+export function encodeSignedText(text: string, options: SignedEncodeOptions): Promise<QuadQRCode>;
+export function encodeSignedBytes(input: Uint8Array | ArrayBuffer | ArrayLike<number>, options: SignedEncodeOptions): Promise<QuadQRCode>;
 export function encodeSecureText(text: string, options: SecureEncodeOptions): Promise<QuadQRCode>;
 export function encodeSecureBytes(input: Uint8Array | ArrayBuffer | ArrayLike<number>, options: SecureEncodeOptions): Promise<QuadQRCode>;
+export function compressPayload(input: Uint8Array | ArrayBuffer | ArrayLike<number>): Uint8Array;
+export function decompressPayload(input: Uint8Array | ArrayBuffer | ArrayLike<number>, expectedLength?: number | null): Uint8Array;
+export function deriveSigningKeyId(publicKey: CryptoKey | Uint8Array | ArrayBuffer, bytes?: number): Promise<string>;
+export function generateSigningKeyPair(): Promise<{ privateKey: CryptoKey; publicKey: CryptoKey; privateKeyPkcs8: Uint8Array; publicKeyBytes: Uint8Array; keyId: string; algorithm: "Ed25519" }>;
 export function decodeMatrix(matrix: number[][], options?: Record<string, unknown>): DecodeResult;
+export function decodeUint8Array(matrix: number[][], options?: Record<string, unknown>): Uint8Array;
 export function decryptDecoded(result: DecodeResult, credentials: { password: string } | { key: string | Uint8Array | ArrayBuffer }): Promise<DecodeResult>;
+export function verifyDecodedSignature(result: DecodeResult, options?: {
+  publicKey?: CryptoKey | Uint8Array | ArrayBuffer;
+  trustedPublicKey?: CryptoKey | Uint8Array | ArrayBuffer;
+  trustedKeys?: Record<string, CryptoKey | Uint8Array | ArrayBuffer> | Map<string, CryptoKey | Uint8Array | ArrayBuffer>;
+  allowEmbeddedKey?: boolean;
+}): Promise<DecodeResult>;
 export function renderToCanvas(codeOrMatrix: QuadQRCode | number[][], canvas: HTMLCanvasElement, options?: RenderOptions): HTMLCanvasElement;
 export function renderToImageData(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions): ImageDataLike;
+export function renderToSVG(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions): string;
+export function estimateSafeLogoSize(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions & { ecc?: EccLevel; utilization?: number }): number;
+export function findMaxSafeLogoSize(code: QuadQRCode, options: RenderOptions & { minSize?: number; maxSize?: number; iterations?: number }): { safeSize: number; testedMax: number; iterations: number; empirical: boolean };
+export function getPrintGuidance(codeOrMatrix: QuadQRCode | number[][], options?: { quietZone?: number; physicalSizeMm?: number; dpi?: number; minimumModuleMm?: number }): Record<string, unknown>;
 export function scanImageData(imageData: ImageDataLike, options?: ScanOptions): DecodeResult;
+export function debugScanImageData(imageData: ImageDataLike, options?: ScanOptions): { ok: boolean; result?: DecodeResult; error?: string; debug?: ScanDiagnostics | null };
 export function scanFile(file: Blob, options?: ScanOptions): Promise<DecodeResult>;
 export function scanVideoFrame(video: HTMLVideoElement, options?: ScanOptions): DecodeResult;
 export function startCameraScanner(video: HTMLVideoElement, options?: CameraScanOptions): Promise<{ stop(): void; scanNow(): DecodeResult; stream: MediaStream; video: HTMLVideoElement }>;
+export function applyStressDistortion(imageData: ImageDataLike, type: string, severity?: number, options?: Record<string, unknown>): ImageDataLike;
+export const STRESS_PROFILES: readonly Readonly<{ id: string; label: string; type: string; severity: number; weight: number }>[];
+export function runImageStressTest(imageData: ImageDataLike, expected?: { version?: number; crc32?: number }, options?: Record<string, unknown>): Record<string, unknown>;
+export function assessScanability(code: QuadQRCode, renderOptions?: RenderOptions, options?: Record<string, unknown>): Record<string, unknown>;
 export function rectifyDetectedCode(imageData: ImageDataLike, options?: Record<string, unknown>): ImageDataLike;
 export function rotateMatrix(matrix: number[][], quarterTurns?: number): number[][];
 export function getVersionInfo(version: number, options?: { ecc?: EccLevel }): Record<string, unknown>;

package/types/node.d.ts

@@ -5,5 +5,7 @@ export function decodePNG(input: Uint8Array | ArrayBuffer): ImageDataLike;
 export function encodePNG(imageData: ImageDataLike, options?: { compressionLevel?: number }): Buffer;
 export function toPNG(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions & { compressionLevel?: number }): Buffer;
 export function savePNG(codeOrMatrix: QuadQRCode | number[][], filename: string | URL, options?: RenderOptions & { compressionLevel?: number }): Promise<{ filename: string | URL; bytes: number }>;
+export function toSVG(codeOrMatrix: QuadQRCode | number[][], options?: RenderOptions): string;
+export function saveSVG(codeOrMatrix: QuadQRCode | number[][], filename: string | URL, options?: RenderOptions): Promise<{ filename: string | URL; bytes: number }>;
 export function scanBuffer(input: Uint8Array | ArrayBuffer, options?: ScanOptions): Promise<DecodeResult>;
 export function scanFile(filename: string | URL, options?: ScanOptions): Promise<DecodeResult>;