Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/winstxnhdw/sgqr

A cross-platform typesafe SGQR library for individuals and businesses.
https://github.com/winstxnhdw/sgqr

bun paylah paynow sgpay sgqr

Last synced: 25 days ago
JSON representation

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

Awesome Lists containing this project

README

        

# sgqr

[![npm version](https://badge.fury.io/js/sgqr.svg)](https://www.npmjs.com/package/sgqr)
[![main.yml](https://github.com/winstxnhdw/sgqr/actions/workflows/main.yml/badge.svg)](https://github.com/winstxnhdw/sgqr/actions/workflows/main.yml)
[![publish.yml](https://github.com/winstxnhdw/sgqr/actions/workflows/publish.yml/badge.svg)](https://github.com/winstxnhdw/sgqr/actions/workflows/publish.yml)
[![formatter.yml](https://github.com/winstxnhdw/sgqr/actions/workflows/formatter.yml/badge.svg)](https://github.com/winstxnhdw/sgqr/actions/workflows/formatter.yml)

A cross-platform typesafe [SGQR](https://www.mas.gov.sg/development/e-payments/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](https://github.com/winstxnhdw/sgqr/discussions/28) for more information.

## Install

You can depend on `sgqr` from `npm` or via CDN.

### Node

```bash
npm i sgqr
```

```bash
bun add sgqr
```

### Browser

```html

```

## Usage

### Generate SGQR

Minimally, `sgqr` allows you to generate the SGQR text.

```ts
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.

```ts
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.

```ts
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.

```ts
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`.

```ts
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](https://github.com/winstxnhdw/sgqr/releases).

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

```yml
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.

```bash
bun install
```

### Build

Minify and bundle the library with [tsup](https://github.com/egoist/tsup).

```bash
bun run build
```

### Compile

Compile the library into a binary.

```bash
bun compile
```

### Test

Run your tests with hot reloading.

```bash
bun run test
```

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

```bash
bun test
```