@qr-platform/qr-code.js 0.9.0 → 0.9.1

package/lib/node/license/LicenseManager.d.ts

@@ -0,0 +1,69 @@
+import { type DecodedLicenseToken } from '../utils/token-validator';
+export declare const STORAGE_KEY = "QRCodeJsLicense";
+export type LicenseReasonCode = // Export the type
+'DOMAIN_MISMATCH' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID' | 'FETCH_FAILED' | 'KEY_INVALID';
+export interface ValidationResult {
+    isValid: boolean;
+    token: string | null;
+    license: DecodedLicenseToken | null;
+    reason?: LicenseReasonCode;
+}
+export declare class LicenseManager {
+    private static _instance;
+    private static _defaultLicenseApiUrl;
+    private static _currentHostname;
+    private _hls;
+    private _decodedToken;
+    private _licenseKey;
+    private _isInitialized;
+    private _initPromise;
+    private _licenseFetcher;
+    private constructor();
+    /**
+     * Gets the singleton instance of LicenseManager.
+     */
+    static get instance(): LicenseManager;
+    /**
+     * Sets the default URL used by the built-in license fetcher.
+     * Call this *before* activating with a key if you are not providing a custom fetcher.
+     * @param url The new default URL for fetching license tokens.
+     */
+    static setDefaultLicenseApiUrl(url: string): void;
+    get hls(): boolean;
+    get isInitialized(): boolean;
+    getLicenseDetails(): DecodedLicenseToken | null;
+    get licenseKey(): string | null;
+    /**
+     * Configures the function used to fetch a license token from a key.
+     * @param fetcher A function that accepts a license key string and returns a Promise<string> (the token).
+     */
+    configureLicenseFetcher(fetcher: (licenseKey: string) => Promise<string>): void;
+    initialize(): Promise<boolean>;
+    private _performInitialization;
+    /**
+     * Resets the initialization state, forcing re-initialization on the next call to initialize().
+     */
+    resetInitialization(): void;
+    /**
+     * Resets the current license state (hls, decodedToken, licenseKey).
+     */
+    resetLicenseState(): void;
+    /**
+     * Activates the license using a pre-fetched JWT token.
+     * Pass `null` to explicitly clear the current license state.
+     * @param token The JWT token string, or null to clear the license.
+     * @returns {Promise<ValidationResult>} The result of the validation.
+     */
+    activateWithToken(token: string | null): Promise<ValidationResult>;
+    /**
+     * Activates the license using a license key, fetching a token if necessary.
+     * @param licenseKey The license key string.
+     * @returns {Promise<ValidationResult>} The result of the validation.
+     */
+    activateWithKey(licenseKey: string): Promise<ValidationResult>;
+    private _checkDomain;
+    private _logValidationWarning;
+    private _getStoredLicenseData;
+    private _setStoredLicenseData;
+    private _validateAndStoreToken;
+}

package/lib/node/license/LicenseManagerNode.d.ts

@@ -0,0 +1,64 @@
+import { type DecodedLicenseToken } from '../utils/token-validator';
+export interface ValidationResult {
+    isValid: boolean;
+    token: string | null;
+    license: DecodedLicenseToken | null;
+}
+export declare class LicenseManagerNode {
+    private static _instance;
+    private static _defaultLicenseApiUrl;
+    private _hls;
+    private _decodedToken;
+    private _licenseKey;
+    private _storedToken;
+    private _storedKey;
+    private _isInitialized;
+    private _initPromise;
+    private _licenseFetcher;
+    private constructor();
+    /**
+     * Gets the singleton instance of LicenseManagerNode.
+     */
+    static get instance(): LicenseManagerNode;
+    /**
+     * Sets the default absolute URL used by the built-in license fetcher.
+     * MUST be called before activating with a key if not providing a custom fetcher.
+     * @param url The new default absolute URL for fetching license tokens.
+     */
+    static setDefaultLicenseApiUrl(url: string): void;
+    get hls(): boolean;
+    get isInitialized(): boolean;
+    getLicenseDetails(): DecodedLicenseToken | null;
+    get licenseKey(): string | null;
+    /**
+     * Configures the function used to fetch a license token from a key.
+     * @param fetcher A function that accepts a license key string and returns a Promise<string> (the token).
+     */
+    configureLicenseFetcher(fetcher: (licenseKey: string) => Promise<string>): void;
+    initialize(): Promise<boolean>;
+    private _performInitialization;
+    /**
+     * Resets the initialization state, forcing re-initialization on the next call to initialize().
+     */
+    resetInitialization(): void;
+    /**
+     * Resets the current license state (hls, decodedToken, licenseKey).
+     */
+    resetLicenseState(): void;
+    /**
+     * Activates the license using a pre-fetched JWT token.
+     * Pass `null` to explicitly clear the current license state.
+     * @param token The JWT token string, or null to clear the license.
+     * @returns {Promise<ValidationResult>} The result of the validation.
+     */
+    activateWithToken(token: string | null): Promise<ValidationResult>;
+    /**
+     * Activates the license using a license key, fetching a token if necessary.
+     * @param licenseKey The license key string.
+     * @returns {Promise<ValidationResult>} The result of the validation.
+     */
+    activateWithKey(licenseKey: string): Promise<ValidationResult>;
+    private _getStoredLicenseData;
+    private _setStoredLicenseData;
+    private _validateAndStoreToken;
+}

package/lib/node/node.d.ts

@@ -0,0 +1,88 @@
+import { QRCodeJs as _QRCodeJs } from './core/qr-code-js';
+import { type ValidationResult } from './license/LicenseManagerNode';
+import type * as _browserUtils from './tools/browser-utils';
+import { RecursivePartial } from './types/helper';
+import { StyleOptions } from './types/style-options';
+import { Options } from './utils/options';
+import { ScanValidatorResponse } from './utils/scan-validators/abstract-scan-validator';
+import { type DecodedLicenseToken } from './utils/token-validator';
+export { ErrorCorrectionLevel, Mode, TypeNumber } from '~/lib/qrcode/QRCodeMinimal';
+export { type ExtensionFunction } from './core/qr-code-js';
+export { FileExtension } from './tools/browser-utils';
+export { type RecursivePartial } from './types/helper';
+export { type CanvasOptions } from './utils/canvas-options';
+export { GradientType, type Gradient } from './utils/gradient';
+export { CornerDotType, CornerSquareType, DotType, ImageMode, ShapeType, type Options } from './utils/options';
+export { ErrorCorrectionPercents } from './utils/qrcode';
+export declare const browserUtils: typeof _browserUtils | undefined;
+export declare class QRCodeJs extends _QRCodeJs {
+    static initializeIfNeeded(): Promise<boolean>;
+    static get hls(): boolean;
+    protected _hls(): boolean;
+    static getLicenseDetails(): DecodedLicenseToken | null;
+    static configureLicenseFetcher(fetcher: (licenseKey: string) => Promise<string>): void;
+    static token(token: string | null): Promise<ValidationResult>;
+    static license(licenseKey: string): Promise<ValidationResult>;
+    /**
+     * Sets the absolute URL used by the built-in license fetcher.
+     * MUST be called before using .license('key') if not providing a custom fetcher.
+     * @param url The absolute URL for fetching license tokens (e.g., https://api.example.com/get-token).
+     */
+    static setLicenseUrl(url: string): typeof QRCodeJs;
+    static _xmldomSync: any;
+    static _initPromise: Promise<void> | null;
+    static initXmldom(): Promise<void>;
+    constructor(options: RecursivePartial<Options>, _?: boolean);
+    validateScanning(): Promise<ScanValidatorResponse>;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific template.
+     * Allows for fluent configuration chaining. We need it here to avoid circular dependency
+     * @param templateName - The name of the template to start with.
+     * @param templateNameOrOptions - The name of the template or a partial options object to start with.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): QRCodeBuilder;
+    /**
+     * Creates a QRCodeBuilder instance initialized with a specific style.
+     * Allows for fluent configuration chaining.
+     * @param styleNameOrOptions - The name of the predefined style or a StyleOptions object.
+     * @returns A new QRCodeBuilder instance.
+     */
+    static useStyle(styleNameOrOptions: string | StyleOptions): QRCodeBuilder;
+}
+declare class QRCodeBuilder {
+    protected config: RecursivePartial<Options>;
+    /**
+     * Creates a new QRCodeBuilder instance.
+     * @param templateNameOrOptions - Optional name of a predefined template or a partial options object to start with.
+     */
+    constructor(templateNameOrOptions?: string | RecursivePartial<Options>);
+    /**
+     * Applies a template to the builder's configuration. Template options
+     * will be overridden by subsequently chained .style() or .options() calls.
+     * @param templateNameOrOptions - The name of the template or a partial options object to apply.
+     * @returns The builder instance for chaining.
+     */
+    useTemplate(templateNameOrOptions: string | RecursivePartial<Options>): this;
+    /**
+     * Applies style options to the builder's configuration.
+     * @param styleNameOrOptions - Name of a predefined style or Style options object to apply.
+     * @returns The builder instance for chaining.
+     */
+    useStyle(styleNameOrOptions: string | StyleOptions): this;
+    /**
+     * Merges the provided options into the builder's configuration.
+     * @param options - A partial options object to merge.
+     * @returns The builder instance for chaining.
+     */
+    options(options: RecursivePartial<Options>): QRCodeJs;
+    /**
+     * Builds the QRCodeJs instance with the accumulated configuration.
+     * @returns The created QRCodeJs instance.
+     */
+    build(): QRCodeJs;
+}
+export declare class _ extends QRCodeJs {
+    protected _hls(): boolean;
+    constructor(options: RecursivePartial<Options>);
+}

package/lib/node/options-demo.d.ts

@@ -0,0 +1,239 @@
+import { ShapeType } from './utils/options';
+export declare const options2: {
+    shape: ShapeType;
+    verticalOffset: number;
+    isResponive: string;
+    margin: number;
+    scale: number;
+    data: string;
+    image: string;
+    dotsOptions: {
+        type: string;
+        color: string;
+        size: number;
+    };
+    backgroundOptions: {
+        color: string;
+    };
+    cornersDotOptions: {
+        type: string;
+        color: string;
+    };
+    cornersSquareOptions: {
+        type: string;
+        color: string;
+    };
+    imageOptions: {
+        crossOrigin: string;
+        imageSize: number;
+        margin: number;
+    };
+    borderOptions: {
+        hasBorder: boolean;
+        radius: string;
+        thickness: number;
+        inner: {
+            radius: string;
+            scale: number;
+            horizontalOffset: number;
+            verticalOffset: number;
+        };
+        color: string;
+        decorations: {
+            top: {
+                disabled: boolean;
+                enableText: boolean;
+                offset: number;
+                curveAdjustment: number;
+                curveDisabled: boolean;
+                curveRadius: string;
+                type: string;
+                value: string;
+                style: {
+                    fontFace: string;
+                    fontSize: number;
+                    fontColor: string;
+                    letterSpacing: number;
+                    fontWeight: string;
+                };
+            };
+            bottom: {
+                disabled: boolean;
+                enableText: boolean;
+                offset: number;
+                curveAdjustment: number;
+                curveRadius: string;
+                curveDisabled: boolean;
+                type: string;
+                value: string;
+                style: {
+                    fontFace: string;
+                    fontSize: number;
+                    fontColor: string;
+                    letterSpacing: number;
+                    fontWeight: string;
+                };
+            };
+            left: {
+                disabled: boolean;
+                enableText: boolean;
+                offset: number;
+                curveAdjustment: number;
+                curveRadius: string;
+                curveDisabled: boolean;
+                type: string;
+                value: string;
+                style: {
+                    fontFace: string;
+                    fontSize: number;
+                    fontColor: string;
+                    letterSpacing: number;
+                    fontWeight: string;
+                };
+            };
+            right: {
+                disabled: boolean;
+                enableText: boolean;
+                offset: number;
+                curveAdjustment: number;
+                curveDisabled: boolean;
+                curveRadius: string;
+                type: string;
+                value: string;
+                style: {
+                    fontFace: string;
+                    fontSize: number;
+                    fontColor: string;
+                    letterSpacing: number;
+                    fontWeight: string;
+                };
+            };
+        };
+        borderOuter: {
+            color: string;
+            thickness: number;
+        };
+        borderInner: {
+            color: string;
+            thickness: number;
+        };
+    };
+};
+export declare const options: {
+    name: string;
+    description: string;
+    data: string;
+    image: string;
+    margin: number;
+    verticalOffset: number;
+    scale: number;
+    shape: string;
+    qrOptions: {};
+    imageOptions: {
+        imageSize: number;
+        margin: number;
+        roundedValue: number;
+    };
+    dotsOptions: {
+        type: string;
+        color: string;
+    };
+    cornersSquareOptions: {
+        type: string;
+        color: string;
+    };
+    cornersDotOptions: {
+        type: string;
+        color: string;
+    };
+    backgroundOptions: {
+        color: string;
+        gradient: {
+            type: string;
+            colorStops: {
+                offset: number;
+                color: string;
+            }[];
+        };
+    };
+    borderOptions: {
+        hasBorder: boolean;
+        radius: string;
+        innerRadius: string;
+        thickness: number;
+        color: string;
+        isTopBorderOnly: boolean;
+        isBottomBorderOnly: boolean;
+        isTopBottomBorderOnly: boolean;
+        decorations: {
+            top: {
+                enableText: boolean;
+                verticalOffset: number;
+                curveAdjustment: number;
+                disableCurve: boolean;
+                type: string;
+                value: string;
+                style: {
+                    fontFace: string;
+                    fontSize: number;
+                    fontColor: string;
+                    letterSpacing: number;
+                    fontWeight: string;
+                };
+            };
+            bottom: {
+                enableText: boolean;
+                verticalOffset: number;
+                curveAdjustment: number;
+                disableCurve: boolean;
+                type: string;
+                value: string;
+                style: {
+                    fontFace: string;
+                    fontSize: number;
+                    fontColor: string;
+                    letterSpacing: number;
+                    fontWeight: string;
+                };
+            };
+            left: {
+                enableText: boolean;
+                verticalOffset: number;
+                curveAdjustment: number;
+                disableCurve: boolean;
+                type: string;
+                value: string;
+                style: {
+                    fontFace: string;
+                    fontSize: number;
+                    fontColor: string;
+                    letterSpacing: number;
+                    fontWeight: string;
+                };
+            };
+            right: {
+                enableText: boolean;
+                verticalOffset: number;
+                curveAdjustment: number;
+                disableCurve: boolean;
+                type: string;
+                value: string;
+                style: {
+                    fontFace: string;
+                    fontSize: number;
+                    fontColor: string;
+                    letterSpacing: number;
+                    fontWeight: string;
+                };
+            };
+        };
+        borderOuter: {
+            color: string;
+            thickness: number;
+        };
+        borderInner: {
+            color: string;
+            thickness: number;
+        };
+    };
+};

package/lib/node/plugins/QRBorderHelpers.d.ts

@@ -0,0 +1,32 @@
+export type Position = 'top' | 'bottom' | 'left' | 'right';
+export type DecorationType = 'text' | 'image';
+export declare const Positions: Record<Position, Position>;
+export interface BorderOffsets {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+}
+export declare function computeBorderOffsets(thickness: number, noBorderThickness: number, enabledBorders: {
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+    left: boolean;
+}): BorderOffsets;
+export declare const buildTransform: (rotate: number, flip: boolean, width: number, height: number) => string;
+export declare function computeTextPathOffset(position: Position, // 'top' | 'bottom' | 'left' | 'right'
+thickness: number, // main border thickness
+noBorderThickness: number, // fallback thickness if side is disabled
+enabledBorders: {
+    [key in Position]: boolean;
+}): {
+    x: number;
+    y: number;
+};
+export declare const calculatePathDimensions: (size: number, thickness: number, outerBorderPadding: number, offset: number, borderOffsets?: BorderOffsets) => {
+    startX: number;
+    startY: number;
+    pathWidth: number;
+};
+export declare const getRoundValue: (round: string | number) => number;
+export declare const addProcentageToRadius: (radius: string | undefined, defaultRadius?: string | number) => string | number;

package/lib/node/plugins/QRBorderPlugin.d.ts

@@ -0,0 +1,35 @@
+import { Gradient } from '../utils/gradient';
+import { BorderOptions } from '../utils/options.js';
+import { Position } from './QRBorderHelpers.js';
+export interface QRBorderPluginStyleOptions {
+    fontFace?: string;
+    fontSize?: number;
+    fontColor?: string;
+    letterSpacing?: number;
+    fontWeight?: string;
+}
+interface QRPluginSettings {
+    width?: number;
+    height?: number;
+    document: Document;
+    instanceId: number;
+    backgroundOptions?: {
+        /** Background roundnes, from 0 (square) to 1 (circle) */
+        round?: number;
+        /** Background color */
+        color?: string;
+        /** Background Gradient */
+        gradient?: Gradient;
+    } | false;
+}
+type QRBorderPluginFn = (options: BorderOptions) => (svgElement: SVGElement, settings: QRPluginSettings, svgSize: number, drawBackgroundForBorder: (padding: number, baseRadius: number) => SVGElement | undefined, bordersMain: {
+    [key in Position]: number;
+}, bordersOuter: {
+    [key in Position]: number;
+}, bordersInner: {
+    [key in Position]: number;
+}, noBorderThickness: number, hs: () => boolean) => void;
+export declare const isBorderSideEnabled: (options: BorderOptions, position: Position) => boolean;
+export declare const isBorderSideEnabledBottom: (options: BorderOptions, position: Position, _hls: boolean) => boolean;
+declare const QRBorderPlugin: QRBorderPluginFn;
+export { QRBorderPlugin };

package/lib/node/plugins/QRValidatorZbar.d.ts

@@ -0,0 +1,38 @@
+export default QRValidatorZbar;
+declare class QRValidatorZbar {
+    constructor(options?: {});
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D | null;
+    maxRetries: any;
+    retryInterval: any;
+    /**
+     * Validate and decode a QR code from an image
+     * @param {HTMLImageElement|File|Blob|String} input - Input image (can be an image element, file, blob or data URL)
+     * @returns {Promise<Object>} - Validation results with decoded data if successful
+     */
+    validate(input: HTMLImageElement | File | Blob | string, width: any, height: any): Promise<Object>;
+    /**
+     * Load image from various sources
+     * @param {HTMLImageElement|File|Blob|String} input - Input image
+     * @returns {Promise<HTMLImageElement>} - Loaded image
+     */
+    loadImage(input: HTMLImageElement | File | Blob | string): Promise<HTMLImageElement>;
+    /**
+     * Sleep function to wait between retry attempts
+     * @param {number} ms - Milliseconds to wait
+     * @returns {Promise<void>}
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Decode QR code with automatic retry
+     * @param {ImageData} imageData - Raw image data
+     * @returns {Promise<Object>} - Validation result after retries
+     */
+    decodeQRWithRetry(imageData: ImageData): Promise<Object>;
+    /**
+     * Decode QR code from image data using zbar-wasm
+     * @param {ImageData} imageData - Raw image data
+     * @returns {Promise<Object>} - Validation result
+     */
+    decodeQR(imageData: ImageData): Promise<Object>;
+}

package/lib/node/plugins/QRValidatorZbarNode.d.ts

@@ -0,0 +1,60 @@
+/**
+ * QRValidatorZbar Validation Library for Node.js
+ *
+ * This server-side class uses zbar-wasm to decode QR codes and other barcodes,
+ * with Jimp (and Resvg for SVG conversion) for image processing.
+ */
+interface QRValidatorOptions {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Time to wait between retries in milliseconds */
+    retryInterval?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+interface QRValidationResult {
+    /** Whether the validation was successful */
+    isValid: boolean;
+    /** Decoded data from the QR code (if successful) */
+    data?: string;
+    /** Format of the detected barcode */
+    format?: string;
+    /** Number of retry attempts made */
+    attempts?: number;
+    /** Whether the successful decode came from an inverted image */
+    isInverted?: boolean;
+    /** Error message if validation failed */
+    error?: string;
+    /** Error code if validation failed */
+    errorCode?: string;
+}
+declare class QRValidatorZbarNode {
+    private maxRetries;
+    private retryInterval;
+    private debug;
+    constructor(options?: QRValidatorOptions);
+    private log;
+    /**
+     * Validate and decode a QR code from an SVG string (or file path)
+     */
+    validate(input: string, isInverted?: boolean): Promise<QRValidationResult>;
+    private sleep;
+    /**
+     * Process image using Sharp and get raw pixel data
+     * @param input Input image
+     * @param width Optional width for resizing
+     * @param height Optional height for resizing
+     * @returns Processed image data compatible with zbar-wasm
+     */
+    private processImageResvg;
+    private validateWithRetry;
+    /**
+     * Save a debug image using Jimp. The raw image data is used to reconstruct an image.
+     */
+    private saveDebugImage;
+    /**
+     * Decode the QR code from image data using zbar-wasm.
+     */
+    private decodeQR;
+}
+export default QRValidatorZbarNode;