@20syldev/api 4.2.0 → 4.4.0

package/src/modules/v4/convert.ts

@@ -1,38 +1,118 @@
-import { MIN_TEMPERATURE, MAX_TEMPERATURE } from '../../constants.js';
-
 type ConversionFn = (val: number) => number;
 
+const TEMPERATURE_UNITS = new Set(['celsius', 'fahrenheit', 'kelvin']);
+const ABSOLUTE_ZERO: Record<string, number> = { celsius: -273.15, fahrenheit: -459.67, kelvin: 0 };
+
 const conversions: Record<string, Record<string, ConversionFn>> = {
+    // Temperature
     celsius: {
-        fahrenheit: (val) => (val * 9) / 5 + 32,
-        kelvin: (val) => val + 273.15,
+        fahrenheit: (v) => (v * 9) / 5 + 32,
+        kelvin: (v) => v + 273.15,
     },
     fahrenheit: {
-        celsius: (val) => ((val - 32) * 5) / 9,
-        kelvin: (val) => ((val - 32) * 5) / 9 + 273.15,
+        celsius: (v) => ((v - 32) * 5) / 9,
+        kelvin: (v) => ((v - 32) * 5) / 9 + 273.15,
     },
     kelvin: {
-        celsius: (val) => val - 273.15,
-        fahrenheit: (val) => ((val - 273.15) * 9) / 5 + 32,
+        celsius: (v) => v - 273.15,
+        fahrenheit: (v) => ((v - 273.15) * 9) / 5 + 32,
+    },
+
+    // Length
+    km: {
+        mi: (v) => v * 0.621371,
+        m: (v) => v * 1000,
+        ft: (v) => v * 3280.84,
+        cm: (v) => v * 100000,
+        in: (v) => v * 39370.1,
+        yd: (v) => v * 1093.61,
+    },
+    mi: {
+        km: (v) => v * 1.60934,
+        m: (v) => v * 1609.34,
+        ft: (v) => v * 5280,
+        cm: (v) => v * 160934,
+        in: (v) => v * 63360,
+        yd: (v) => v * 1760,
+    },
+    m: {
+        km: (v) => v / 1000,
+        mi: (v) => v * 0.000621371,
+        ft: (v) => v * 3.28084,
+        cm: (v) => v * 100,
+        in: (v) => v * 39.3701,
+        yd: (v) => v * 1.09361,
+    },
+    ft: {
+        km: (v) => v * 0.0003048,
+        mi: (v) => v / 5280,
+        m: (v) => v * 0.3048,
+        cm: (v) => v * 30.48,
+        in: (v) => v * 12,
+        yd: (v) => v / 3,
+    },
+    cm: {
+        km: (v) => v / 100000,
+        mi: (v) => v / 160934,
+        m: (v) => v / 100,
+        ft: (v) => v / 30.48,
+        in: (v) => v / 2.54,
+        yd: (v) => v / 91.44,
     },
+    in: {
+        km: (v) => v / 39370.1,
+        mi: (v) => v / 63360,
+        m: (v) => v * 0.0254,
+        ft: (v) => v / 12,
+        cm: (v) => v * 2.54,
+        yd: (v) => v / 36,
+    },
+    yd: {
+        km: (v) => v * 0.0009144,
+        mi: (v) => v / 1760,
+        m: (v) => v * 0.9144,
+        ft: (v) => v * 3,
+        cm: (v) => v * 91.44,
+        in: (v) => v * 36,
+    },
+
+    // Weight
+    kg: { lb: (v) => v * 2.20462, oz: (v) => v * 35.274, g: (v) => v * 1000, ton: (v) => v / 1000 },
+    lb: { kg: (v) => v * 0.453592, oz: (v) => v * 16, g: (v) => v * 453.592, ton: (v) => v * 0.000453592 },
+    oz: { kg: (v) => v * 0.0283495, lb: (v) => v / 16, g: (v) => v * 28.3495, ton: (v) => v * 0.0000283495 },
+    g: { kg: (v) => v / 1000, lb: (v) => v * 0.00220462, oz: (v) => v * 0.035274, ton: (v) => v / 1000000 },
+    ton: { kg: (v) => v * 1000, lb: (v) => v * 2204.62, oz: (v) => v * 35274, g: (v) => v * 1000000 },
+
+    // Data
+    b: { kb: (v) => v / 1024, mb: (v) => v / 1048576, gb: (v) => v / 1073741824, tb: (v) => v / 1099511627776 },
+    kb: { b: (v) => v * 1024, mb: (v) => v / 1024, gb: (v) => v / 1048576, tb: (v) => v / 1073741824 },
+    mb: { b: (v) => v * 1048576, kb: (v) => v * 1024, gb: (v) => v / 1024, tb: (v) => v / 1048576 },
+    gb: { b: (v) => v * 1073741824, kb: (v) => v * 1048576, mb: (v) => v * 1024, tb: (v) => v / 1024 },
+    tb: { b: (v) => v * 1099511627776, kb: (v) => v * 1073741824, mb: (v) => v * 1048576, gb: (v) => v * 1024 },
+
+    // Speed
+    'km/h': { mph: (v) => v * 0.621371, 'm/s': (v) => v / 3.6, knots: (v) => v * 0.539957 },
+    mph: { 'km/h': (v) => v * 1.60934, 'm/s': (v) => v * 0.44704, knots: (v) => v * 0.868976 },
+    'm/s': { 'km/h': (v) => v * 3.6, mph: (v) => v * 2.23694, knots: (v) => v * 1.94384 },
+    knots: { 'km/h': (v) => v * 1.852, mph: (v) => v * 1.15078, 'm/s': (v) => v * 0.514444 },
 };
 
 export default function convert(
-    value: string | number,
+    value: number,
     from: string,
     to: string,
 ): { from: string; to: string; value: number; result: number } {
-    const convertFn = conversions[from.toLowerCase()]?.[to.toLowerCase()];
+    const fromKey = from.toLowerCase();
+    const toKey = to.toLowerCase();
+    const convertFn = conversions[fromKey]?.[toKey];
 
     if (!convertFn) throw new Error('Invalid conversion unit');
-    if (isNaN(Number(value))) throw new Error('Value must be a number');
-    if (Number(value) < MIN_TEMPERATURE) throw new Error('Value must be greater than absolute zero');
-    if (Number(value) > MAX_TEMPERATURE) throw new Error('Value must be less than 1,000,000');
-
-    return {
-        from,
-        to,
-        value: parseFloat(String(value)),
-        result: convertFn(parseFloat(String(value))),
-    };
+    if (isNaN(value)) throw new Error('Value must be a number');
+
+    if (TEMPERATURE_UNITS.has(fromKey)) {
+        const minValue = ABSOLUTE_ZERO[fromKey]!;
+        if (value < minValue) throw new Error('Value must be greater than absolute zero');
+    }
+
+    return { from, to, value, result: convertFn(value) };
 }

package/src/modules/v4/domain.ts

@@ -1,4 +1,4 @@
-import { random, genIP } from './utils.js';
+import { random, genIP } from '../../utils/helpers.js';
 
 export default function domain(): Record<string, unknown> {
     const subdomains = [

package/src/modules/v4/geo.ts

@@ -0,0 +1,53 @@
+export interface GeoResult {
+    distance: { km: number; miles: number; nauticalMiles: number };
+    bearing: { degrees: number; cardinal: string };
+    from: { lat: number; lon: number };
+    to: { lat: number; lon: number };
+}
+
+const EARTH_RADIUS_KM = 6371;
+const CARDINALS = ['N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW'];
+
+function toRad(deg: number): number {
+    return (deg * Math.PI) / 180;
+}
+
+function toDeg(rad: number): number {
+    return (rad * 180) / Math.PI;
+}
+
+function parseCoord(value: string, name: string, min: number, max: number): number {
+    const n = Number(value);
+    if (isNaN(n)) throw new Error(`${name} must be a number`);
+    if (n < min || n > max) throw new Error(`${name} must be between ${min} and ${max}`);
+    return n;
+}
+
+export default function geo(lat1: string, lon1: string, lat2: string, lon2: string): GeoResult {
+    const a = parseCoord(lat1, 'lat1', -90, 90);
+    const b = parseCoord(lon1, 'lon1', -180, 180);
+    const c = parseCoord(lat2, 'lat2', -90, 90);
+    const d = parseCoord(lon2, 'lon2', -180, 180);
+
+    const dLat = toRad(c - a);
+    const dLon = toRad(d - b);
+    const sa = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(a)) * Math.cos(toRad(c)) * Math.sin(dLon / 2) ** 2;
+    const distance = 2 * EARTH_RADIUS_KM * Math.asin(Math.sqrt(sa));
+
+    const y = Math.sin(toRad(d - b)) * Math.cos(toRad(c));
+    const x =
+        Math.cos(toRad(a)) * Math.sin(toRad(c)) - Math.sin(toRad(a)) * Math.cos(toRad(c)) * Math.cos(toRad(d - b));
+    const bearing = (toDeg(Math.atan2(y, x)) + 360) % 360;
+    const cardinal = CARDINALS[Math.round(bearing / 22.5) % 16]!;
+
+    return {
+        distance: {
+            km: +distance.toFixed(3),
+            miles: +(distance * 0.621371).toFixed(3),
+            nauticalMiles: +(distance * 0.539957).toFixed(3),
+        },
+        bearing: { degrees: +bearing.toFixed(2), cardinal },
+        from: { lat: a, lon: b },
+        to: { lat: c, lon: d },
+    };
+}

package/src/modules/v4/hash.ts

@@ -1,9 +1,23 @@
 import { getHashes, createHash } from 'crypto';
 
-export default function hash(text: string, method: string): { method: string; hash: string } | { error: string } {
+export interface HashResult {
+    method: string;
+    hash: string;
+    encoding: string;
+}
+
+const ENCODINGS = new Set(['hex', 'base64']);
+
+export default function hash(text: string, method: string, encoding: string = 'hex'): HashResult {
+    if (!text) throw new Error('Text is required');
+
     const methods = getHashes();
-    if (!methods.includes(method)) return { error: `Unsupported method. Use one of: ${methods.join(', ')}` };
+    if (!methods.includes(method)) throw new Error(`Unsupported method. Use one of: ${methods.join(', ')}`);
+
+    if (!ENCODINGS.has(encoding)) throw new Error('Encoding must be one of: hex, base64');
 
-    const result = createHash(method).update(text).digest('hex');
-    return { method, hash: result };
+    const result = createHash(method)
+        .update(text)
+        .digest(encoding as 'hex' | 'base64');
+    return { method, hash: result, encoding };
 }

package/src/modules/v4/hyperplanning.ts

@@ -1,4 +1,4 @@
-import { formatDate } from './utils.js';
+import { formatDate } from '../../utils/helpers.js';
 import ical from 'ical.js';
 
 interface CalendarEvent {

package/src/modules/v4/palette.ts

@@ -0,0 +1,63 @@
+import { hexToRgb, rgbToHsl, hslToRgb, rgbToHex } from '../../utils/colors.js';
+
+export interface PaletteColor {
+    hex: string;
+    rgb: string;
+    hsl: string;
+}
+
+export interface PaletteResult {
+    base: PaletteColor;
+    type: string;
+    colors: PaletteColor[];
+}
+
+function format(r: number, g: number, b: number): PaletteColor {
+    const [h, s, l] = rgbToHsl(r, g, b);
+    return {
+        hex: rgbToHex(r, g, b),
+        rgb: `rgb(${r}, ${g}, ${b})`,
+        hsl: `hsl(${h.toFixed(1)}, ${(s * 100).toFixed(1)}%, ${(l * 100).toFixed(1)}%)`,
+    };
+}
+
+function fromHueShifts(base: [number, number, number], shifts: number[]): PaletteColor[] {
+    const [h, s, l] = base;
+    return shifts.map((shift) => {
+        const newH = (h + shift + 360) % 360;
+        const [r, g, b] = hslToRgb(newH, s, l);
+        return format(r, g, b);
+    });
+}
+
+export default function palette(color: string, type: string): PaletteResult {
+    if (!color) throw new Error('A base color is required');
+    if (!type) throw new Error('A palette type is required');
+
+    const [r, g, b] = hexToRgb(color);
+    const base = format(r, g, b);
+    const hsl = rgbToHsl(r, g, b);
+
+    let colors: PaletteColor[];
+    switch (type) {
+        case 'complementary':
+            colors = fromHueShifts(hsl, [0, 180]);
+            break;
+        case 'triadic':
+            colors = fromHueShifts(hsl, [0, 120, 240]);
+            break;
+        case 'analogous':
+            colors = fromHueShifts(hsl, [-60, -30, 0, 30, 60]);
+            break;
+        case 'tetradic':
+            colors = fromHueShifts(hsl, [0, 90, 180, 270]);
+            break;
+        case 'split-complementary':
+            colors = fromHueShifts(hsl, [0, 150, 210]);
+            break;
+        default:
+            throw new Error('Type must be one of: complementary, triadic, analogous, tetradic, split-complementary');
+    }
+
+    return { base, type, colors };
+}

package/src/modules/v4/personal.ts

@@ -1,4 +1,4 @@
-import { random, randomNumber } from './utils.js';
+import { random, randomNumber } from '../../utils/helpers.js';
 
 interface Person {
     name: string;

package/src/modules/v4/placeholder.ts

@@ -0,0 +1,189 @@
+import { normalizeColor } from '../../utils/colors.js';
+
+type AvatarShape = 'circle' | 'rounded' | 'square';
+type AnimateMode = 'shimmer' | 'pulse' | 'none';
+
+export interface PlaceholderOptions {
+    width: number;
+    height: number;
+    bg?: string;
+    color?: string;
+    text?: string;
+    rows?: number;
+    avatar?: AvatarShape;
+    lines?: number;
+    animate?: AnimateMode;
+    speed?: number;
+    radius?: number;
+}
+
+function parseSize(value: string | undefined, name: string, def: number): number {
+    if (value === undefined) return def;
+    const n = Number(value);
+    if (isNaN(n)) throw new Error(`${name} must be a number`);
+    if (n < 1 || n > 4000) throw new Error(`${name} must be between 1 and 4000`);
+    return Math.floor(n);
+}
+
+function escapeXml(str: string): string {
+    return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function generateImage(opts: PlaceholderOptions): string {
+    const { width, height } = opts;
+    const bg = normalizeColor(opts.bg, '#cccccc');
+    const color = normalizeColor(opts.color, '#333333');
+    const text = escapeXml(opts.text ?? `${width}\u00d7${height}`);
+    const fontSize = Math.max(12, Math.min(width, height) / 8);
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+  <rect width="${width}" height="${height}" fill="${bg}" rx="4" />
+  <text x="50%" y="50%" dominant-baseline="central" text-anchor="middle" font-family="system-ui,-apple-system,sans-serif" font-weight="600" font-size="${fontSize}" fill="${color}">${text}</text>
+</svg>`;
+}
+
+function avatarShape(shape: AvatarShape, x: number, y: number, size: number): string {
+    const r = size / 2;
+    switch (shape) {
+        case 'circle':
+            return `<circle cx="${x + r}" cy="${y + r}" r="${r}" />`;
+        case 'rounded':
+            return `<rect x="${x}" y="${y}" width="${size}" height="${size}" rx="${Math.round(size * 0.25)}" />`;
+        case 'square':
+            return `<rect x="${x}" y="${y}" width="${size}" height="${size}" rx="2" />`;
+    }
+}
+
+function animationDefs(mode: AnimateMode, bg: string, highlight: string, speed: number): string {
+    if (mode === 'none') return '';
+
+    if (mode === 'pulse') {
+        return `<style>
+      @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
+      .sk { animation: pulse ${speed}s cubic-bezier(0.4, 0, 0.6, 1) infinite; }
+    </style>`;
+    }
+
+    return `<linearGradient id="g">
+      <stop offset="0.1" stop-color="${bg}" />
+      <stop offset="0.5" stop-color="${highlight}" />
+      <stop offset="0.9" stop-color="${bg}" />
+      <animateTransform attributeName="gradientTransform" type="translate" values="-2 0; 2 0" dur="${speed}s" repeatCount="indefinite" />
+    </linearGradient>`;
+}
+
+function generateSkeleton(opts: PlaceholderOptions): string {
+    const { width, height } = opts;
+    const bg = normalizeColor(opts.bg, '#e5e5e5');
+    const highlight = normalizeColor(opts.color, '#f5f5f5');
+    const rows = Math.max(0, Math.min(20, opts.rows ?? 3));
+    const avatar = opts.avatar;
+    const animate = opts.animate ?? 'shimmer';
+    const speed = opts.speed ?? 1.5;
+    const rx = opts.radius ?? 4;
+
+    const pad = Math.round(width * 0.06);
+    const slots = rows + (avatar ? 4 : 0);
+    const available = height - pad * 2;
+    const lineH = Math.round(Math.max(8, (available / Math.max(1, slots)) * 0.65));
+    const gap = Math.round(Math.max(6, (available / Math.max(1, slots)) * 0.35));
+
+    const shapes: string[] = [];
+    let y = pad;
+
+    if (avatar) {
+        const size = Math.round(Math.min(width * 0.14, height * 0.24, 48));
+        shapes.push(avatarShape(avatar, pad, y, size));
+
+        const lx = pad + size + gap;
+        const lw = width - lx - pad;
+        const count = Math.max(0, Math.min(2, opts.lines ?? 2));
+
+        if (count === 2) {
+            const nameY = Math.max(pad, Math.round(y + size / 2 - (lineH * 2 + gap) / 2));
+            shapes.push(`<rect x="${lx}" y="${nameY}" width="${lw * 0.55}" height="${lineH}" rx="${rx}" />`);
+            shapes.push(
+                `<rect x="${lx}" y="${nameY + lineH + gap}" width="${lw * 0.35}" height="${lineH}" rx="${rx}" />`,
+            );
+        } else if (count === 1) {
+            const nameY = Math.max(pad, Math.round(y + size / 2 - lineH / 2));
+            shapes.push(`<rect x="${lx}" y="${nameY}" width="${lw * 0.55}" height="${lineH}" rx="${rx}" />`);
+        }
+
+        y += size + gap * 2;
+    }
+
+    for (let i = 0; i < rows; i++) {
+        const ratio = i === rows - 1 && rows > 1 ? 0.55 : i % 2 === 0 ? 0.92 : 0.78;
+        const w = Math.round((width - pad * 2) * ratio);
+        shapes.push(`<rect x="${pad}" y="${y}" width="${w}" height="${lineH}" rx="${rx}" />`);
+        y += lineH + gap;
+    }
+
+    const defs = animationDefs(animate, bg, highlight, speed);
+    const fill = animate === 'shimmer' ? 'url(#g)' : bg;
+    const cls = animate === 'pulse' ? ' class="sk"' : '';
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+  <defs>
+    <clipPath id="c">
+      ${shapes.join('\n      ')}
+    </clipPath>
+    ${defs}
+  </defs>
+  <rect width="${width}" height="${height}" clip-path="url(#c)" fill="${fill}"${cls} />
+</svg>`;
+}
+
+export interface PlaceholderResult {
+    type: string;
+    contentType: string;
+    body: string;
+}
+
+const AVATAR_SHAPES = new Set(['circle', 'rounded', 'square']);
+const ANIMATE_MODES = new Set(['shimmer', 'pulse', 'none']);
+
+function parseAvatar(value: string | undefined): AvatarShape | undefined {
+    if (!value) return undefined;
+    if (value === 'true' || value === '1') return 'circle';
+    if (AVATAR_SHAPES.has(value)) return value as AvatarShape;
+    throw new Error('avatar must be one of: circle, rounded, square');
+}
+
+function parseAnimate(value: string | undefined): AnimateMode {
+    if (!value) return 'shimmer';
+    if (ANIMATE_MODES.has(value)) return value as AnimateMode;
+    throw new Error('animate must be one of: shimmer, pulse, none');
+}
+
+export default function placeholder(type: string, query: Record<string, string | undefined>): PlaceholderResult {
+    const speed = query.speed ? parseFloat(query.speed) : 1.5;
+    if (isNaN(speed) || speed < 0.1 || speed > 10) throw new Error('speed must be between 0.1 and 10');
+
+    const radius = query.radius ? parseInt(query.radius, 10) : 4;
+    if (isNaN(radius) || radius < 0 || radius > 50) throw new Error('radius must be between 0 and 50');
+
+    const opts: PlaceholderOptions = {
+        width: parseSize(query.width, 'width', 800),
+        height: parseSize(query.height, 'height', 600),
+        bg: query.bg,
+        color: query.color,
+        text: query.text,
+        rows: query.rows ? parseInt(query.rows, 10) : undefined,
+        avatar: parseAvatar(query.avatar),
+        lines: query.lines ? parseInt(query.lines, 10) : 2,
+        animate: parseAnimate(query.animate),
+        speed,
+        radius,
+    };
+
+    switch (type) {
+        case 'image':
+            return { type, contentType: 'image/svg+xml', body: generateImage(opts) };
+        case 'skeleton':
+            return { type, contentType: 'image/svg+xml', body: generateSkeleton(opts) };
+        default:
+            throw new Error('Type must be one of: image, skeleton');
+    }
+}

package/src/modules/v4/qrcode.ts

@@ -1,11 +1,113 @@
-import { toDataURL } from 'qrcode';
+import { toBuffer, toDataURL, toCanvas as qrToCanvas } from 'qrcode';
+import { createCanvas, loadImage } from 'canvas';
+import { normalizeColor } from '../../utils/colors.js';
 
-export default async function qrcode(url: string): Promise<string> {
+export interface QRCodeOptions {
+    url: string;
+    size?: number;
+    margin?: number;
+    correction?: 'L' | 'M' | 'Q' | 'H';
+    dark?: string;
+    light?: string;
+    icon?: string;
+    iconSize?: number;
+    iconPadding?: number;
+    iconRadius?: number;
+    format?: 'png' | 'base64';
+}
+
+export interface QRCodeResult {
+    contentType: string;
+    body: Buffer | string;
+}
+
+const CORRECTIONS = new Set(['L', 'M', 'Q', 'H']);
+const FORMATS = new Set(['png', 'base64']);
+const MAX_LOGO_BYTES = 2 * 1024 * 1024;
+
+function clamp(value: number | undefined, name: string, def: number, min: number, max: number): number {
+    if (value === undefined) return def;
+    if (isNaN(value)) throw new Error(`${name} must be a number`);
+    if (value < min || value > max) throw new Error(`${name} must be between ${min} and ${max}`);
+    return Math.floor(value);
+}
+
+async function fetchIcon(url: string): Promise<Buffer> {
+    if (!/^https:\/\//i.test(url)) throw new Error('Icon URL must use HTTPS');
+
+    const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
+
+    if (!response.ok) throw new Error(`Failed to fetch icon: HTTP ${response.status}`);
+
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!contentType.startsWith('image/')) throw new Error('Icon URL must point to an image');
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length > MAX_LOGO_BYTES) throw new Error('Icon must be under 2MB');
+
+    return buffer;
+}
+
+export default async function qrcode(options: QRCodeOptions): Promise<QRCodeResult> {
+    const { url } = options;
     if (!url || typeof url !== 'string') throw new Error('Please provide a valid URL');
 
-    try {
-        return await toDataURL(url);
-    } catch (error) {
-        throw new Error(`Failed to generate QR code: ${(error as Error).message}`);
+    const format = options.format ?? 'png';
+    if (!FORMATS.has(format)) throw new Error('format must be one of: png, base64');
+
+    const size = clamp(options.size, 'size', 200, 50, 2000);
+    const margin = clamp(options.margin, 'margin', 4, 0, 10);
+    const dark = normalizeColor(options.dark, '#000000');
+    const light = normalizeColor(options.light, '#ffffff');
+
+    let correction = options.correction ?? 'M';
+    if (!CORRECTIONS.has(correction)) throw new Error('correction must be one of: L, M, Q, H');
+    if (options.icon) correction = 'H';
+
+    const qrOpts = {
+        width: size,
+        margin,
+        errorCorrectionLevel: correction as 'L' | 'M' | 'Q' | 'H',
+        color: { dark, light },
+    };
+
+    if (!options.icon) {
+        if (format === 'base64') {
+            return { contentType: 'application/json', body: await toDataURL(url, qrOpts) };
+        }
+        return { contentType: 'image/png', body: await toBuffer(url, qrOpts) };
+    }
+
+    const canvas = createCanvas(size, size);
+    await qrToCanvas(canvas as unknown as HTMLCanvasElement, url, qrOpts);
+
+    const iconBuffer = await fetchIcon(options.icon);
+    const iconImg = await loadImage(iconBuffer);
+
+    const iconSize = clamp(options.iconSize, 'iconSize', Math.round(size * 0.2), 10, Math.round(size * 0.4));
+    const iconPadding = clamp(options.iconPadding, 'iconPadding', 5, 0, 50);
+    const maxRadius = Math.floor((iconSize + iconPadding * 2) / 2);
+    const iconRadius = clamp(options.iconRadius, 'iconRadius', 0, 0, maxRadius);
+
+    const ctx = canvas.getContext('2d');
+    const totalSize = iconSize + iconPadding * 2;
+    const x = (canvas.width - totalSize) / 2;
+    const y = (canvas.height - totalSize) / 2;
+
+    ctx.beginPath();
+    ctx.roundRect(x, y, totalSize, totalSize, iconRadius);
+    ctx.fillStyle = light;
+    ctx.fill();
+
+    ctx.save();
+    ctx.beginPath();
+    ctx.roundRect(x + iconPadding, y + iconPadding, iconSize, iconSize, Math.max(0, iconRadius - iconPadding));
+    ctx.clip();
+    ctx.drawImage(iconImg, x + iconPadding, y + iconPadding, iconSize, iconSize);
+    ctx.restore();
+
+    if (format === 'base64') {
+        return { contentType: 'application/json', body: canvas.toDataURL('image/png') };
     }
+    return { contentType: 'image/png', body: canvas.toBuffer('image/png') };
 }

package/src/modules/v4/tic_tac_toe.ts

@@ -44,11 +44,43 @@ export default function tic_tac_toe(action: string, params: TicTacToeParams): Re
         return playMove(params, games, sessions, u, now);
     } else if (action === 'fetch') {
         return fetchGame(params, games, u);
+    } else if (action === 'forfeit') {
+        return forfeitGame(params, games, sessions);
     } else {
-        throw new Error('Invalid action. Use "play", "fetch", or "list"');
+        throw new Error('Invalid action. Use "play", "fetch", "list", or "forfeit"');
     }
 }
 
+function forfeitGame(
+    params: TicTacToeParams,
+    games: Record<string, TicTacToeGame>,
+    sessions: Record<string, { user: string; last: number }>,
+): Record<string, unknown> {
+    const { game, session } = params;
+
+    if (!game) throw new Error('Please provide a valid game ID');
+    if (!session) throw new Error('Please provide a valid session ID');
+    if (!games[game]) throw new Error('Game not found');
+
+    const u = params.username!.toLowerCase();
+    if (sessions[u] && sessions[u].user !== session) {
+        throw new Error('Session ID mismatch');
+    }
+
+    const players = games[game]!.players;
+    if (!players.includes(u)) throw new Error('You are not a player in this game');
+
+    const winner = players.find((p) => p !== u) ?? null;
+    delete games[game];
+    delete sessions[u];
+
+    return {
+        message: `${params.username} forfeited the game.${winner ? ` ${winner} wins.` : ''}`,
+        winner,
+        loser: params.username,
+    };
+}
+
 function playMove(
     params: TicTacToeParams,
     games: Record<string, TicTacToeGame>,

package/src/modules/v4/username.ts

@@ -1,4 +1,4 @@
-import { random, randomNumber } from './utils.js';
+import { random, randomNumber } from '../../utils/helpers.js';
 
 export default function username(): Record<string, unknown> {
     const adj = [