Gramota

@gramota/qr

QR-code rendering for EUDIW deep links — Strategy-pluggable renderer, lazy / memoised result class.

Install: pnpm add @gramota/qr

Source: github.com/gramota-org/gramota/tree/main/packages/qr

Classes

QrClient

Defined in: @gramota/qr/dist/client.d.ts:12

@gramota/qr public API.

Two patterns work — pick whichever fits:

  1. Default singleton (zero config):

    import { qr } from "@gramota/qr";
const code = qr.fromUrl("openid4vp://…");

  2. Custom client (custom renderer, default options):

    import { QrClient } from "@gramota/qr";
const qr = new QrClient({ errorCorrection: "H", width: 512 });
const code = qr.fromUrl("openid4vp://…");

Tree-shakers can also import the named factories directly (fromUrl, fromAuthorizationRequest, fromCredentialOffer) — they delegate to the singleton.

Constructors

Constructor
new QrClient(options?: QrClientOptions): QrClient;

Defined in: @gramota/qr/dist/client.d.ts:15

Parameters
options?

QrClientOptions

Returns

QrClient

Methods

fromUrl()
fromUrl(url: string, options?: QrOptions): QrCode;

Defined in: @gramota/qr/dist/client.d.ts:28

Render any URL as a QR code.

Parameters
url

string

options?

QrOptions

Returns

QrCode

Example
const code = qr.fromUrl("openid4vp://?client_id=…");
const dataUrl = await code.toDataUrl();
Throws

QrError with qr.invalid_url if the input isn't a non-empty string with a : prefix.

fromAuthorizationRequest()
fromAuthorizationRequest(request: AuthorizationRequest, options?: QrOptions & {
  scheme?: string;
}): QrCode;

Defined in: @gramota/qr/dist/client.d.ts:34

Render an OID4VP AuthorizationRequest as a QR code. Default scheme is openid4vp://. Override via { scheme } for HAIP / country-specific wallet schemes.

Parameters
request

AuthorizationRequest

options?

QrOptions & { scheme?: string; }

Returns

QrCode

fromCredentialOffer()
fromCredentialOffer(offer: CredentialOffer, options?: QrOptions & {
  scheme?: string;
}): QrCode;

Defined in: @gramota/qr/dist/client.d.ts:41

Render an OID4VCI CredentialOffer as a QR code. Default scheme is openid-credential-offer:// per OID4VCI §4.1.

Parameters
offer

CredentialOffer

options?

QrOptions & { scheme?: string; }

Returns

QrCode

QrCode

Defined in: @gramota/qr/dist/qr-code.d.ts:15

Constructors

Constructor
new QrCode(
   url: string, 
   renderer: QrRenderer, 
   options?: QrOptions): QrCode;

Defined in: @gramota/qr/dist/qr-code.d.ts:24

Internal

— construct via the qr factories, not directly.

Parameters
url

string

renderer

QrRenderer

options?

QrOptions

Returns

QrCode

Properties

url
readonly url: string;

Defined in: @gramota/qr/dist/qr-code.d.ts:17

The URL encoded in the QR matrix — exactly what scanners will read.

Methods

toDataUrl()
toDataUrl(): Promise<string>;

Defined in: @gramota/qr/dist/qr-code.d.ts:30

PNG as a data:image/png;base64,… URL — drop directly into an attribute. Best for fast inline rendering in HTML emails and dashboards.

Returns

Promise<string>

toSvg()
toSvg(): Promise<string>;

Defined in: @gramota/qr/dist/qr-code.d.ts:35

Raw SVG markup — drop into innerHTML (or Angular [innerHTML]). Scales without quality loss, good for print and high-DPI screens.

Returns

Promise<string>

toPng()
toPng(): Promise<Uint8Array<ArrayBuffer>>;

Defined in: @gramota/qr/dist/qr-code.d.ts:41

Raw PNG bytes — Uint8Array for portability (Node Buffer extends it). Use for fs.writeFile, multipart uploads, and binary-channel transports.

Returns

Promise<Uint8Array<ArrayBuffer>>

DefaultQrRenderer

Defined in: @gramota/qr/dist/renderer.d.ts:29

Default renderer — Adapter (GoF) over the qrcode npm package.

Maps our QrOptions shape onto qrcode's, dispatches based on format, and surfaces failures as QrError. Swappable via QrRenderer: anyone with stricter requirements (Trust-on-first-use logo embedding, brand-coloured QR with a styled data-pattern, etc.) writes their own implementation.

Implements

Constructors

Constructor
new DefaultQrRenderer(): DefaultQrRenderer;
Returns

DefaultQrRenderer

Methods

render()
render(
   url: string, 
   format: QrFormat, 
options: QrOptions): Promise<string | Uint8Array<ArrayBuffer>>;

Defined in: @gramota/qr/dist/renderer.d.ts:30

Render the given URL as a QR code in format.

Return type depends on format:

  • "dataUrl" → string (a data:image/png;base64,... URL)
  • "svg" → string (the raw ... markup)
  • "png" → Uint8Array (raw PNG bytes — Buffer in Node, but typed as Uint8Array so this is portable).

Throw QrError with qr.unsupported_format if the renderer can't produce the requested format, or qr.render_failed for any other failure.

Parameters
url

string

format

QrFormat

options

QrOptions

Returns

Promise<string | Uint8Array<ArrayBuffer>>

Implementation of

QrRenderer.render

QrError

Defined in: @gramota/qr/dist/types.d.ts:29

Errors thrown anywhere in @gramota/qr carry one of these codes plus a free-form message. Caught upstream, the code is stable across releases — log it in audit trails, branch on it in handlers.

Extends

  • GramotaError

Constructors

Constructor
new QrError(
   code: QrErrorCode, 
   message: string, 
   options?: {
  cause?: unknown;
}): QrError;

Defined in: @gramota/qr/dist/types.d.ts:31

Parameters
code

QrErrorCode

message

string

options?
cause?

unknown

Returns

QrError

Overrides
GramotaError.constructor

Properties

cause?
readonly optional cause?: unknown;

Defined in: .pnpm/@gramota+core@0.2.1/node_modules/@gramota/core/dist/error.d.ts:44

Optional original error that caused this one. Always set when the Gramota package is wrapping a thrown exception from a dependency (Web Crypto, JOSE, fetch). Survives JSON.stringify(err) only via the cause property — Node 16.9+ logs it natively.

Inherited from
GramotaError.cause
code
readonly code: QrErrorCode;

Defined in: @gramota/qr/dist/types.d.ts:30

Stable string that identifies the failure mode. Subclasses narrow the type; at runtime it's always a string. Use for branching, logs, and metrics labels — never serialize GramotaError.message for that purpose, message strings drift across versions.

Overrides
GramotaError.code
name
name: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from
GramotaError.name
message
message: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from
GramotaError.message
stack?
optional stack?: string;

Defined in: .pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from
GramotaError.stack

Interfaces

QrClientOptions

Defined in: @gramota/qr/dist/client.d.ts:7

Construction-time options for QrClient.

Extends

Properties

renderer?
readonly optional renderer?: QrRenderer;

Defined in: @gramota/qr/dist/client.d.ts:10

Override the rendering Strategy. Defaults to a singleton DefaultQrRenderer backed by the qrcode npm package.

width?
readonly optional width?: number;

Defined in: @gramota/qr/dist/types.d.ts:44

Pixel width of the rendered QR. PNG uses this directly; SVG scales to fit. Default: 300.

Inherited from

QrOptions.width

margin?
readonly optional margin?: number;

Defined in: @gramota/qr/dist/types.d.ts:46

Quiet-zone modules around the matrix. Default: 1.

Inherited from

QrOptions.margin

colors?
readonly optional colors?: {
  dark?: string;
  light?: string;
};

Defined in: @gramota/qr/dist/types.d.ts:49

Foreground / background colours. CSS colour strings (e.g. "#0b1220"). Default: black on white.

dark?
readonly optional dark?: string;
light?
readonly optional light?: string;
Inherited from

QrOptions.colors

errorCorrection?
readonly optional errorCorrection?: "L" | "M" | "Q" | "H";

Defined in: @gramota/qr/dist/types.d.ts:57

Reed-Solomon error-correction level. Higher = more redundant data, larger matrix, more tolerant of dirt / partial occlusion. Default: "M" (15% recovery — the QR-spec recommendation for general use).

Inherited from

QrOptions.errorCorrection

QrRenderer

Defined in: @gramota/qr/dist/renderer.d.ts:4

Strategy interface. Implementations decide HOW to render; the orchestrator decides WHEN.

Methods

render()
render(
   url: string, 
   format: QrFormat, 
options: QrOptions): Promise<string | Uint8Array<ArrayBuffer>>;

Defined in: @gramota/qr/dist/renderer.d.ts:18

Render the given URL as a QR code in format.

Return type depends on format:

  • "dataUrl" → string (a data:image/png;base64,... URL)
  • "svg" → string (the raw ... markup)
  • "png" → Uint8Array (raw PNG bytes — Buffer in Node, but typed as Uint8Array so this is portable).

Throw QrError with qr.unsupported_format if the renderer can't produce the requested format, or qr.render_failed for any other failure.

Parameters
url

string

format

QrFormat

options

QrOptions

Returns

Promise<string | Uint8Array<ArrayBuffer>>

QrOptions

Defined in: @gramota/qr/dist/types.d.ts:41

Layout options forwarded to the renderer. Specific renderers may accept additional knobs (logo embedding, custom corner shapes, …) via their own constructor options — these four are the universal subset every renderer is expected to honour.

Extended by

Properties

width?
readonly optional width?: number;

Defined in: @gramota/qr/dist/types.d.ts:44

Pixel width of the rendered QR. PNG uses this directly; SVG scales to fit. Default: 300.

margin?
readonly optional margin?: number;

Defined in: @gramota/qr/dist/types.d.ts:46

Quiet-zone modules around the matrix. Default: 1.

colors?
readonly optional colors?: {
  dark?: string;
  light?: string;
};

Defined in: @gramota/qr/dist/types.d.ts:49

Foreground / background colours. CSS colour strings (e.g. "#0b1220"). Default: black on white.

dark?
readonly optional dark?: string;
light?
readonly optional light?: string;
errorCorrection?
readonly optional errorCorrection?: "L" | "M" | "Q" | "H";

Defined in: @gramota/qr/dist/types.d.ts:57

Reed-Solomon error-correction level. Higher = more redundant data, larger matrix, more tolerant of dirt / partial occlusion. Default: "M" (15% recovery — the QR-spec recommendation for general use).

Type Aliases

QrFormat

type QrFormat = "dataUrl" | "svg" | "png";

Defined in: @gramota/qr/dist/types.d.ts:12

Output formats a QrRenderer may be asked to produce.

QrErrorCode

type QrErrorCode = "qr.invalid_url" | "qr.render_failed" | "qr.unsupported_format";

Defined in: @gramota/qr/dist/types.d.ts:17

Stable error codes for QrError. Pinned strings (not descriptions) so callers can branch on them in switch statements.

Variables

qr

const qr: QrClient;

Defined in: @gramota/qr/dist/client.d.ts:53

Default singleton QrClient with the default renderer.

Most consumers want this — no construction, no options, just qr.fromUrl(deepLink). Pass a custom renderer or default options by constructing your own new QrClient({...}).