sgqr

A cross-platform typesafe SGQR library for individuals and businesses.

Important

sgqr is still a work-in-progress and may undergo drastic API changes to maximise DX and performance. See the following discussion for more information.

Install

You can depend on sgqr from npm or via CDN.

Node

npm i sgqr

bun add sgqr

Browser

<script src="https://cdn.jsdelivr.net/npm/sgqr/dist/index.global.js"></script>

Usage

Generate SGQR

Minimally, sgqr allows you to generate the SGQR text.

import sgqr from 'sgqr'

const code = sgqr.generate({
  number: '+6591234567',
  amount: '1.69'
})

console.log(code)

Generate SGQR Code

sgqr provides an API capable of generating QR codes in webp, jpeg or png formats.

const data = await sgqr.generate_code({
  number: '+6591234567',
  amount: '1',
  type: 'image/webp'
})

if (!data) {
  throw new Error('Failed to generate QR code')
}

await Bun.write('qr.png', data)

Generate SGQR SVG

SVGs can be generated with the generate_svg API.

const data = await sgqr.generate_svg({
  number: '+6591234567',
  amount: '1.2',
  comments: 'This SGQR was made with sgqr!'
})

Generate SGQR with UEN

If you are a business, you can generate SGQR codes with your UEN.

const data = await sgqr.generate_code({
  number: '0123456789',
  number_type: 'UEN',
  merchant_name: 'Singapore Armed Forces',
  amount: '4.1',
  type: 'image/jpeg'
})

Generate SGQR with Expiry Date

You can specify an expiry date for the SGQR code. According to the SGQR specification, the expiry date must be in the format YYYYMMDD.

const data = await sgqr.generate_svg({
  number: '0123456789',
  number_type: 'UEN',
  amount: '1.00',
  expiry_date: '20251231'
})

if (!data) {
  throw new Error('Failed to generate QR code')
}

await Bun.write('qr.svg', data)

Command Line

sgqr can also be used as a command line tool. The binary can be found here.

sgqr --number +6591234567 --amount 420.69 --type image/svg+xml --output qr.svg

Options:
  --version             Show version number             [boolean]
  --number              mobile or unique entity number  [string] [required]
  --amount              payment amount as a string      [string] [required]
  --output              output file path                [string]
  --number_type         UEN or MOBILE                   [choices: "UEN", "MOBILE"]
  --merchant_name       merchant name                   [string]
  --comments            comments                        [string]
  --country_code        country code                    [string]
  --scale               scale of the image              [number]
  --expiry_date         expiry date as a string         [string]
  --merchant_city       merchant city                   [string]
  --currency_code       currency code                   [string]
  --type                type of image                   [choices: "image/webp", "image/jpeg", "image/svg+xml"]
  --editable            if the code is editable         [boolean]
  --help                Show help                       [boolean]

Development

Setup

Install all dependencies.

bun install

Build

Minify and bundle the library with tsup.

bun run build

Compile

Compile the library into a binary.

bun compile

Test

Run your tests with hot reloading.

bun run test

Run your tests without hot reloading. For testing in a CI pipeline.

bun test

winstxnhdw / sgqr