qr-code-generator

# qr-code-generator Skill

## When to use

Use this skill when you need to:
- Generate a QR code for a URL, WiFi network, contact card, or arbitrary text
- Embed a brand logo into a QR code
- Generate dozens or hundreds of QR codes from a CSV in one batch
- Download QR codes as SVG (for print) or PNG (for digital)
- Integrate QR generation into a pipeline via the REST API

## Prerequisites

Server running at `http://localhost:3000`. Start with:
```
pnpm --filter server dev
```
Or via Docker:
```
docker compose up -d
```

Health check:
```
curl http://localhost:3000/api/health
```

## Quick start

Generate a URL QR code (SVG):
```bash
curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{"type":"url","data":{"url":"https://example.com"},"format":"svg"}' \
  | jq -r '.svg' > qrcode.svg
```

## Usage patterns

### URL QR code
```bash
curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "url",
    "data": { "url": "https://example.com" },
    "style": {
      "fgColor": "#000000",
      "bgColor": "#ffffff",
      "errorCorrection": "M",
      "margin": 4,
      "width": 400
    },
    "format": "svg"
  }' | jq -r '.svg' > url.svg
```

### WiFi QR code
```bash
curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "wifi",
    "data": {
      "ssid": "OfficeNetwork",
      "password": "supersecret",
      "security": "WPA",
      "hidden": false
    },
    "format": "svg"
  }' | jq -r '.svg' > wifi.svg
```

Encoded string produced: `WIFI:T:WPA;S:OfficeNetwork;P:supersecret;H:false;;`

### vCard QR code
```bash
curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "vcard",
    "data": {
      "firstName": "Jane",
      "lastName": "Smith",
      "org": "Acme Corp",
      "title": "Product Manager",
      "phone": "+1-555-0100",
      "email": "jane@acme.com",
      "url": "https://acme.com"
    },
    "style": { "errorCorrection": "Q" },
    "format": "svg"
  }' | jq -r '.svg' > vcard.svg
```

### PNG output
```bash
curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "url",
    "data": { "url": "https://example.com" },
    "style": { "width": 512 },
    "format": "png"
  }' | jq -r '.dataUrl' | sed 's/data:image\/png;base64,//' | base64 -d > qrcode.png
```

### Logo embedding
```bash
LOGO_B64=$(base64 -i logo.png)

curl -s -X POST http://localhost:3000/api/generate \
  -H 'Content-Type: application/json' \
  -d "{
    \"type\": \"url\",
    \"data\": { \"url\": \"https://example.com\" },
    \"style\": { \"errorCorrection\": \"H\" },
    \"logo\": \"data:image/png;base64,$LOGO_B64\",
    \"format\": \"svg\"
  }" | jq -r '.svg' > branded.svg
```

Logo is auto-centered at 20% of QR width. Error correction is forced to H when a logo is present.

### Bulk generation from CSV
```bash
# codes.csv:
# data,filename,fgColor
# https://example.com,homepage,#000000
# https://example.com/about,about,#1d4ed8

curl -X POST http://localhost:3000/api/bulk \
  -F "csv=@codes.csv" \
  --output qrcodes.zip

unzip qrcodes.zip -d ./qrcodes/
```

### Bulk generation from JSON
```bash
curl -X POST http://localhost:3000/api/bulk \
  -H 'Content-Type: application/json' \
  -d '{
    "codes": [
      {"data": "https://a.com", "filename": "a"},
      {"data": "https://b.com", "filename": "b", "fgColor": "#1d4ed8"}
    ],
    "format": "svg"
  }' --output qrcodes.zip
```

## API reference

| Method | Path | Description |
|---|---|---|
| POST | /api/generate | Generate a single QR code |
| POST | /api/bulk | Batch generate from CSV or JSON array, returns ZIP |
| GET | /api/templates | List saved style templates |
| POST | /api/templates | Save a style template |
| DELETE | /api/templates/:id | Delete a template |
| GET | /api/health | Server health check |

### POST /api/generate request body

| Field | Type | Default | Description |
|---|---|---|---|
| type | string | required | url, text, wifi, vcard |
| data | object | required | Type-specific payload |
| style.fgColor | string | #000000 | Foreground hex color |
| style.bgColor | string | #ffffff | Background hex color |
| style.errorCorrection | string | M | L, M, Q, or H |
| style.margin | number | 4 | Quiet zone in modules |
| style.width | number | 400 | Output size in pixels |
| logo | string|null | null | Base64 data URL of logo image |
| format | string | svg | svg or png |

### POST /api/generate response

| Field | Type | Description |
|---|---|---|
| svg | string | SVG markup (format=svg only) |
| dataUrl | string | data:image/... base64 URL |
| size | number | Rendered pixel size |

## Error correction guide

| Level | Recovery | When to use |
|---|---|---|
| L | 7% | Clean print environments, smallest code |
| M | 15% | Default, general purpose |
| Q | 25% | Outdoor/industrial, long URLs |
| H | 30% | Required when embedding a logo |

## Behavior notes

- Logo embedding always upgrades error correction to H, regardless of the style setting
- Transparent background is only supported in SVG output; PNG always has a background
- Bulk endpoint rejects requests over MAX_BULK_CODES (default 500)
- All hex colors must be in #rrggbb format
- vCard data over ~300 characters: use error correction Q or H for reliability
- History is stored in browser localStorage only; the server is stateless

## Troubleshooting

**QR code does not scan**
- Check foreground/background contrast (minimum 4:1 ratio recommended)
- With logo: ensure error correction is H and logo size is below 30%
- Inverted codes (light on dark) may not scan on all devices

**Bulk job returns 400**
- CSV has more than MAX_BULK_CODES rows
- Required columns `data` and `filename` are missing

**Logo not appearing in SVG**
- Logo must be provided as a base64 data URL (data:image/png;base64,... or data:image/svg+xml;base64,...)
- Maximum logo size: 500 KB before encoding