@20syldev/api 4.5.0 → 4.7.0

package/src/modules/v4/text.ts

@@ -142,6 +142,13 @@ export interface TextStats {
     mostFrequentChar: string;
 }
 
+/**
+ * Analyzes a text string and returns character, word, sentence, and reading time statistics.
+ *
+ * @param value - The text to analyze
+ * @returns Object containing character counts, word/sentence/paragraph counts, reading time, and most frequent character
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function stats(value: string): TextStats {
     checkText(value);
 
@@ -168,6 +175,13 @@ export function stats(value: string): TextStats {
     return { characters, charactersNoSpaces, words, sentences, paragraphs, readingTime, mostFrequentChar };
 }
 
+/**
+ * Converts a string to a URL-friendly slug.
+ *
+ * @param value - The string to slugify
+ * @returns Lowercase hyphenated slug with diacritics and special characters removed
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function slug(value: string): string {
     checkText(value);
     return value
@@ -179,6 +193,14 @@ export function slug(value: string): string {
         .replace(/[\s-]+/g, '-');
 }
 
+/**
+ * Generates Lorem Ipsum placeholder text.
+ *
+ * @param type - Content type: "words", "sentences", or "paragraphs"
+ * @param count - Number of words, sentences, or paragraphs to generate
+ * @returns Generated Lorem Ipsum text
+ * @throws Error if count is out of range or type is not one of the accepted values
+ */
 export function lorem(type: string, count: string): string {
     const n = Number(count) || 5;
     if (n < 1 || n > 500) throw new Error('Count must be between 1 and 500');
@@ -283,6 +305,14 @@ function numberToEnglish(n: number): string {
     throw new Error('Number must be less than 1 billion');
 }
 
+/**
+ * Converts an integer to its written-out word form in French or English.
+ *
+ * @param value - The integer to convert (must be less than 1 billion)
+ * @param lang - Language: "fr" for French or "en" for English
+ * @returns The number written out in words
+ * @throws Error if value is not an integer, exceeds the maximum, or lang is not supported
+ */
 export function number(value: string, lang: string): string {
     const n = Number(value);
     if (isNaN(n)) throw new Error('Value must be a number');

package/src/modules/v4/tic_tac_toe.ts

@@ -1,6 +1,7 @@
 import { randomBytes } from 'crypto';
-import { SESSION_TTL, GAME_CLEANUP_TTL, RATE_LIMIT_WINDOW, RATE_LIMIT_MAX } from '../../constants.js';
-import type { TicTacToeStorage, TicTacToeMove, TicTacToeGame } from '../../types/storage.js';
+
+import { GAME_CLEANUP_TTL, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW, SESSION_TTL } from '../../constants.js';
+import type { TicTacToeGame, TicTacToeMove, TicTacToeStorage } from '../../types/storage.js';
 
 interface TicTacToeParams {
     username?: string;
@@ -17,6 +18,14 @@ interface GameResult {
     tie?: boolean;
 }
 
+/**
+ * Handles Tic-Tac-Toe game actions including playing a move, fetching game state, listing games, and forfeiting.
+ *
+ * @param action - The action to perform: "play", "fetch", "list", or "forfeit"
+ * @param params - Game parameters including username, move, session, game ID, and shared storage
+ * @returns Game state or action result depending on the action
+ * @throws Error if a required parameter is missing, the action is invalid, or a rate limit is exceeded
+ */
 export default function tic_tac_toe(action: string, params: TicTacToeParams): Record<string, unknown> {
     const storage = params.storage;
 

package/src/modules/v4/time.ts

@@ -24,6 +24,17 @@ const validTimezones = ['UTC', 'America/New_York', 'Europe/Paris', 'Asia/Tokyo',
 type TimeFormat = (typeof validFormats)[number];
 type Timezone = (typeof validTimezones)[number];
 
+/**
+ * Returns the current or a random date/time in various formats and timezones.
+ *
+ * @param type - "live" for the current time or "random" for a random date within a range
+ * @param start - Optional start date for random mode (YYYY-MM-DD)
+ * @param end - Optional end date for random mode (YYYY-MM-DD)
+ * @param format - Optional specific format to return (e.g. "iso", "timestamp", "year")
+ * @param timezone - Optional timezone (e.g. "UTC", "Europe/Paris")
+ * @returns Object containing all time formats, or a single format if specified
+ * @throws Error if type, format, or timezone is invalid
+ */
 export default function time(
     type: string = 'live',
     start?: string,

package/src/modules/v4/token.ts

@@ -1,7 +1,16 @@
-import { randomBytes } from 'crypto';
+import { randomBytes, randomInt } from 'crypto';
 import { v4 } from 'uuid';
-import { MIN_TOKEN_LENGTH, MAX_TOKEN_LENGTH } from '../../constants.js';
 
+import { MAX_TOKEN_LENGTH, MIN_TOKEN_LENGTH } from '../../constants.js';
+
+/**
+ * Generates a cryptographically random token of the specified length and type.
+ *
+ * @param len - Token length (must be between 12 and 4096)
+ * @param type - Character set to use: "alpha", "alphanum", "base64", "hex", "num", "punct", "urlsafe", or "uuid"
+ * @returns The generated token string
+ * @throws Error if length is out of range or the type is not valid
+ */
 export default function token(len: number, type: string = 'alphanum'): string {
     if (isNaN(len) || len < MIN_TOKEN_LENGTH) {
         throw new Error('Length must be a number greater than or equal to 12');
@@ -11,11 +20,8 @@ export default function token(len: number, type: string = 'alphanum'): string {
         throw new Error('Length cannot exceed 4096');
     }
 
-    const genToken = (chars: string, length: number): string => {
-        return Array.from({ length }, () => {
-            return chars[Math.floor(Math.random() * chars.length)];
-        }).join('');
-    };
+    const genToken = (chars: string, length: number): string =>
+        Array.from({ length }, () => chars[randomInt(chars.length)]).join('');
 
     const tokenTypes: Record<string, () => string> = {
         alpha: () => genToken('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', len),
@@ -31,7 +37,11 @@ export default function token(len: number, type: string = 'alphanum'): string {
         num: () => genToken('0123456789', len),
         punct: () => genToken('!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~', len),
         urlsafe: () => genToken('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_', len),
-        uuid: () => v4().replace(/-/g, '').slice(0, len),
+        uuid: () => {
+            let result = '';
+            while (result.length < len) result += v4().replace(/-/g, '');
+            return result.slice(0, len);
+        },
     };
 
     const lowerType = type.toLowerCase();

package/src/modules/v4/username.ts

@@ -1,5 +1,10 @@
 import { random, randomNumber } from '../../utils/helpers.js';
 
+/**
+ * Generates a random username combining adjectives, animals, and job titles.
+ *
+ * @returns Object containing the generated username, the number used, and the components (adjective, animal, job)
+ */
 export default function username(): Record<string, unknown> {
     const adj = [
         'Happy',

package/src/modules/v4/validate.ts

@@ -7,6 +7,13 @@ function checkValue(value: string): void {
         throw new Error(`Value must be less than ${MAX_STRING_LENGTH} characters long`);
 }
 
+/**
+ * Validates a credit/debit card number using the Luhn algorithm.
+ *
+ * @param value - Card number string (digits, spaces, or dashes allowed)
+ * @returns Object containing the validity result and the sanitized digit string
+ * @throws Error if value is missing, contains non-digit characters, or has an invalid length
+ */
 export function luhn(value: string): { valid: boolean; value: string } {
     checkValue(value);
     const digits = value.replace(/\s|-/g, '');
@@ -28,6 +35,13 @@ export function luhn(value: string): { valid: boolean; value: string } {
     return { valid: sum % 10 === 0, value: digits };
 }
 
+/**
+ * Validates an IBAN using the mod-97 checksum algorithm.
+ *
+ * @param value - IBAN string (spaces allowed)
+ * @returns Object containing the validity result, sanitized IBAN, and country code
+ * @throws Error if value is missing, has an invalid format, or is out of length bounds
+ */
 export function iban(value: string): { valid: boolean; value: string; country?: string } {
     checkValue(value);
     const cleaned = value.replace(/\s/g, '').toUpperCase();
@@ -48,6 +62,13 @@ export function iban(value: string): { valid: boolean; value: string; country?:
     return { valid: remainder === 1, value: cleaned, country: cleaned.slice(0, 2) };
 }
 
+/**
+ * Validates an email address against a basic format check.
+ *
+ * @param value - The email address string to validate
+ * @returns Object containing the validity result and the original value
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function email(value: string): { valid: boolean; value: string } {
     checkValue(value);
     const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

package/src/modules/v4.ts

@@ -1,6 +1,8 @@
+export { default as address } from './v4/address.js';
+export { default as agent } from './v4/agent.js';
 export * as algorithms from './v4/algorithms.js';
-export { default as chat } from './v4/chat.js';
 export { default as captcha } from './v4/captcha.js';
+export { default as chat } from './v4/chat.js';
 export { default as color } from './v4/color.js';
 export { default as convert } from './v4/convert.js';
 export { default as dice } from './v4/dice.js';
@@ -9,8 +11,10 @@ export * as encode from './v4/encode.js';
 export { default as geo } from './v4/geo.js';
 export { default as hash } from './v4/hash.js';
 export { default as hyperplanning } from './v4/hyperplanning.js';
+export { default as ip } from './v4/ip.js';
 export { default as levenshtein } from './v4/levenshtein.js';
 export { default as palette } from './v4/palette.js';
+export { default as password } from './v4/password.js';
 export { default as personal } from './v4/personal.js';
 export { default as placeholder } from './v4/placeholder.js';
 export { default as qrcode } from './v4/qrcode.js';

package/src/routes/delete.ts

@@ -1,4 +1,5 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
 import { chatStorage, ticTacToeStorage } from '../storage/index.js';
 import { error } from '../utils/response.js';
 

package/src/routes/get.ts

@@ -1,14 +1,18 @@
-import { Router, type Request, type Response } from 'express';
-import { versions } from '../config/versions.js';
+import { type Request, type Response, Router } from 'express';
+
 import { env } from '../config/env.js';
-import { ipLimits } from '../storage/index.js';
-import { chatStorage } from '../storage/index.js';
+import { versions } from '../config/versions.js';
 import { DOCS_URL, GITHUB_CACHE_TTL } from '../constants.js';
-import { error } from '../utils/response.js';
-import { since } from '../utils/helpers.js';
-import type { QRCodeOptions, QRCodeResult } from '../modules/v4/qrcode.js';
+import type { AddressResult } from '../modules/v4/address.js';
+import type { UserAgentResult } from '../modules/v4/agent.js';
 import type { CaptchaOptions, CaptchaResult } from '../modules/v4/captcha.js';
 import type { ColorResult } from '../modules/v4/color.js';
+import type { IpResult } from '../modules/v4/ip.js';
+import type { PasswordResult } from '../modules/v4/password.js';
+import type { QRCodeOptions, QRCodeResult } from '../modules/v4/qrcode.js';
+import { chatStorage, ipLimits } from '../storage/index.js';
+import { since } from '../utils/helpers.js';
+import { error } from '../utils/response.js';
 
 const router = Router();
 
@@ -174,6 +178,75 @@ router.get('/:version/convert', (req: Request, res: Response) => {
     }
 });
 
+// Generate a fictional postal address
+router.get('/:version/address', (req: Request, res: Response) => {
+    const { country, count } = req.query;
+    const { version } = req.params;
+
+    const addressFn = (req.module as { address?: (c?: string, n?: number) => AddressResult }).address;
+    if (!addressFn) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/address`);
+        return;
+    }
+
+    const parsedCount = count !== undefined ? parseInt(count as string, 10) : 1;
+
+    try {
+        const result = addressFn(country as string | undefined, parsedCount);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/address`);
+    }
+});
+
+// Echo request headers
+router.get('/:version/headers', (req: Request, res: Response) => {
+    const redacted = new Set(['authorization', 'cookie', 'set-cookie', 'proxy-authorization']);
+    let headers: Record<string, unknown> = {};
+
+    for (const [k, v] of Object.entries(req.headers)) {
+        headers[k] = redacted.has(k) ? '[redacted]' : v;
+    }
+
+    const filter = req.query.filter as string | undefined;
+    if (filter) {
+        const keys = new Set(filter.split(',').map((k) => k.trim().toLowerCase()));
+        headers = Object.fromEntries(Object.entries(headers).filter(([k]) => keys.has(k)));
+    }
+
+    res.jsonResponse({
+        count: Object.keys(headers).length,
+        headers,
+        ip: req.ip,
+        method: req.method,
+        url: req.originalUrl,
+    });
+});
+
+// Analyze an IP address
+router.get('/:version/ip', (req: Request, res: Response) => {
+    const address = (req.query.address as string | undefined) ?? req.ip ?? '';
+    try {
+        const ipFn = (req.module as Record<string, unknown>).ip as (a: string) => IpResult;
+        const result = ipFn(address);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/ip`);
+    }
+});
+
+// Parse a User-Agent string
+router.get('/:version/agent', (req: Request, res: Response) => {
+    const ua = (req.query.ua as string | undefined) ?? (req.headers['user-agent'] as string) ?? '';
+    try {
+        const agentFn = (req.module as Record<string, unknown>).agent as (ua: string) => UserAgentResult;
+        const result = agentFn(ua);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/agent`);
+    }
+});
+
 // Generate domain informations
 router.get('/:version/domain', (req: Request, res: Response) => {
     try {
@@ -326,6 +399,41 @@ router.get('/:version/palette', (req: Request, res: Response) => {
     }
 });
 
+// Generate a password or passphrase
+router.get('/:version/password', (req: Request, res: Response) => {
+    const { type, length, uppercase, lowercase, digits, symbols, exclude, count, separator } = req.query;
+    const { version } = req.params;
+
+    const passwordFn = (
+        req.module as { password?: (t: string, l: number, o: Record<string, unknown>) => PasswordResult }
+    ).password;
+    if (!passwordFn) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/password`);
+        return;
+    }
+
+    const parseBool = (v: unknown, def: boolean): boolean => (v === undefined ? def : v !== 'false');
+
+    try {
+        const result = passwordFn(
+            (type as string) ?? 'random',
+            length !== undefined ? parseInt(length as string, 10) : 16,
+            {
+                uppercase: parseBool(uppercase, true),
+                lowercase: parseBool(lowercase, true),
+                digits: parseBool(digits, true),
+                symbols: parseBool(symbols, false),
+                exclude: (exclude as string) ?? '',
+                count: count !== undefined ? parseInt(count as string, 10) : 1,
+                separator: (separator as string) ?? '-',
+            },
+        );
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/password`);
+    }
+});
+
 // Generate personal data
 router.get('/:version/personal', (req: Request, res: Response) => {
     try {

package/src/routes/index.ts

@@ -1,8 +1,9 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
 import { versions } from '../config/versions.js';
-import { ipLimits } from '../storage/index.js';
-import { logger } from '../middleware/logger.js';
 import { APP_VERSION, DOCS_URL, START_TIME } from '../constants.js';
+import { logger } from '../middleware/logger.js';
+import { ipLimits } from '../storage/index.js';
 
 const router = Router();
 

package/src/routes/patch.ts

@@ -1,4 +1,5 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
 import { ticTacToeStorage } from '../storage/index.js';
 import { error } from '../utils/response.js';
 

package/src/routes/post.ts

@@ -1,9 +1,10 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
+import { MAX_TOKEN_LENGTH, MIN_TOKEN_LENGTH } from '../constants.js';
+import type { HashResult } from '../modules/v4/hash.js';
 import { chatStorage, ticTacToeStorage } from '../storage/index.js';
-import { MIN_TOKEN_LENGTH, MAX_TOKEN_LENGTH } from '../constants.js';
-import { error } from '../utils/response.js';
 import { since } from '../utils/helpers.js';
-import type { HashResult } from '../modules/v4/hash.js';
+import { error } from '../utils/response.js';
 
 const router = Router();
 

package/src/storage/index.ts

@@ -1,4 +1,4 @@
-import type { ChatStorage, TicTacToeStorage, IpLimits } from '../types/storage.js';
+import type { ChatStorage, IpLimits, TicTacToeStorage } from '../types/storage.js';
 
 export const ipLimits: IpLimits = {};
 

package/src/utils/response.ts

@@ -1,4 +1,5 @@
 import type { Response } from 'express';
+
 import { DOCS_URL, STATUS_MESSAGES } from '../constants.js';
 
 /**

package/tests/integration/api.test.ts

@@ -1,7 +1,8 @@
-import { test, describe, before, after } from 'node:test';
 import { strict as assert } from 'node:assert';
-import type { AddressInfo } from 'node:net';
 import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { after, before, describe, test } from 'node:test';
+
 import app from '../../src/app.js';
 
 let server: Server;
@@ -558,6 +559,145 @@ describe('Payload size limit', () => {
     });
 });
 
+describe('GET /v4/headers', () => {
+    test('returns headers object with count, ip, method, url', async () => {
+        const { status, body } = await getJson('/v4/headers');
+        assert.equal(status, 200);
+        assert.ok(typeof body.count === 'number');
+        assert.ok(typeof body.headers === 'object');
+        assert.ok('method' in body);
+        assert.equal(body.method, 'GET');
+        assert.ok((body.url as string).includes('/v4/headers'));
+    });
+
+    test('filter param returns only matching headers', async () => {
+        const { body } = await getJson('/v4/headers?filter=host');
+        const headers = body.headers as Record<string, unknown>;
+        assert.ok('host' in headers);
+        assert.equal(body.count, 1);
+    });
+
+    test('cookie header is redacted', async () => {
+        const res = await fetch(`${baseUrl}/v4/headers`, {
+            headers: { Cookie: 'session=secret123' },
+        });
+        const body = (await res.json()) as Record<string, unknown>;
+        const headers = body.headers as Record<string, unknown>;
+        assert.equal(headers['cookie'], '[redacted]');
+    });
+});
+
+describe('GET /v4/ip', () => {
+    test('returns valid ip result with no address param', async () => {
+        const { status, body } = await getJson('/v4/ip');
+        assert.equal(status, 200);
+        assert.ok(['IPv4', 'IPv6'].includes(body.version as string));
+        assert.ok(typeof body.binary === 'string');
+        assert.ok(typeof body.reverse === 'string');
+    });
+
+    test('loopback 127.0.0.1', async () => {
+        const { status, body } = await getJson('/v4/ip?address=127.0.0.1');
+        assert.equal(status, 200);
+        assert.equal(body.type, 'loopback');
+        assert.equal(body.version, 'IPv4');
+    });
+
+    test('private 192.168.1.1', async () => {
+        const { body } = await getJson('/v4/ip?address=192.168.1.1');
+        assert.equal(body.type, 'private');
+        assert.equal(body.decimal, 3232235777);
+    });
+
+    test('invalid address returns 400', async () => {
+        const { status } = await getJson('/v4/ip?address=notanip');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/agent', () => {
+    test('returns parsed result with browser, os, device, engine, bot', async () => {
+        const { status, body } = await getJson('/v4/agent');
+        assert.equal(status, 200);
+        assert.ok(typeof body.browser === 'object');
+        assert.ok(typeof body.os === 'object');
+        assert.ok(typeof body.device === 'object');
+        assert.ok(typeof body.engine === 'object');
+        assert.ok(typeof body.bot === 'boolean');
+    });
+
+    test('custom ua param is parsed', async () => {
+        const ua = encodeURIComponent(
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+        );
+        const { body } = await getJson(`/v4/agent?ua=${ua}`);
+        const browser = body.browser as Record<string, string>;
+        assert.equal(browser.name, 'Firefox');
+        assert.equal(browser.major, '121');
+    });
+
+    test('bot ua detected', async () => {
+        const ua = encodeURIComponent('Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)');
+        const { body } = await getJson(`/v4/agent?ua=${ua}`);
+        assert.equal(body.bot, true);
+    });
+});
+
+describe('GET /v4/address', () => {
+    test('returns one address by default', async () => {
+        const { status, body } = await getJson('/v4/address');
+        assert.equal(status, 200);
+        assert.equal((body.addresses as unknown[]).length, 1);
+    });
+
+    test('country=fr returns a French address', async () => {
+        const { body } = await getJson('/v4/address?country=fr');
+        const a = (body.addresses as Record<string, string>[])[0]!;
+        assert.equal(a.countryCode, 'FR');
+    });
+
+    test('count=3 returns 3 addresses', async () => {
+        const { body } = await getJson('/v4/address?count=3');
+        assert.equal((body.addresses as unknown[]).length, 3);
+    });
+
+    test('unknown country returns 400', async () => {
+        const { status } = await getJson('/v4/address?country=xx');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/password', () => {
+    test('returns one password by default', async () => {
+        const { status, body } = await getJson('/v4/password');
+        assert.equal(status, 200);
+        assert.equal((body.passwords as string[]).length, 1);
+        assert.equal((body.passwords as string[])[0]!.length, 16);
+    });
+
+    test('length param is respected', async () => {
+        const { body } = await getJson('/v4/password?length=32');
+        assert.equal((body.passwords as string[])[0]!.length, 32);
+    });
+
+    test('passphrase mode returns words', async () => {
+        const { body } = await getJson('/v4/password?type=passphrase&length=4');
+        assert.equal(body.type, 'passphrase');
+        assert.equal((body.passwords as string[])[0]!.split('-').length, 4);
+    });
+
+    test('count=5 returns 5 passwords', async () => {
+        const { body } = await getJson('/v4/password?count=5');
+        assert.equal((body.passwords as string[]).length, 5);
+    });
+
+    test('no charset active returns 400', async () => {
+        const { status } = await getJson('/v4/password?uppercase=false&lowercase=false&digits=false&symbols=false');
+        assert.equal(status, 400);
+    });
+});
+
+
 describe('Prototype access on dynamic endpoints', () => {
     test('algorithms?method=toString returns 400', async () => {
         const { status } = await getJson('/v4/algorithms?method=toString');

package/tests/unit/address.test.ts

@@ -0,0 +1,84 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
+import address from '../../src/modules/v4/address.js';
+
+describe('address', () => {
+    describe('default behavior', () => {
+        test('returns an addresses array with one entry by default', () => {
+            const r = address();
+            assert.equal(r.addresses.length, 1);
+        });
+
+        test('each address has required fields', () => {
+            const r = address();
+            const a = r.addresses[0]!;
+            assert.ok(a.street);
+            assert.ok(a.city);
+            assert.ok(a.zip);
+            assert.ok(a.state);
+            assert.ok(a.country);
+            assert.ok(a.countryCode);
+        });
+    });
+
+    describe('country filtering', () => {
+        test('fr returns a French address', () => {
+            const r = address('fr');
+            assert.equal(r.addresses[0]!.countryCode, 'FR');
+            assert.equal(r.addresses[0]!.country, 'France');
+        });
+
+        test('us returns a US address', () => {
+            const r = address('us');
+            assert.equal(r.addresses[0]!.countryCode, 'US');
+            assert.equal(r.addresses[0]!.country, 'United States');
+        });
+
+        test('uk returns a UK address', () => {
+            const r = address('uk');
+            assert.equal(r.addresses[0]!.countryCode, 'UK');
+        });
+
+        test('de returns a German address', () => {
+            const r = address('de');
+            assert.equal(r.addresses[0]!.countryCode, 'DE');
+        });
+
+        test('es returns a Spanish address', () => {
+            const r = address('es');
+            assert.equal(r.addresses[0]!.countryCode, 'ES');
+        });
+
+        test('country code is case-insensitive', () => {
+            const r = address('FR');
+            assert.equal(r.addresses[0]!.countryCode, 'FR');
+        });
+    });
+
+    describe('count', () => {
+        test('count=5 returns 5 addresses', () => {
+            const r = address('fr', 5);
+            assert.equal(r.addresses.length, 5);
+        });
+
+        test('count=10 returns 10 addresses', () => {
+            const r = address('us', 10);
+            assert.equal(r.addresses.length, 10);
+        });
+    });
+
+    describe('errors', () => {
+        test('unknown country throws', () => {
+            assert.throws(() => address('xx'), /Unknown country code/);
+        });
+
+        test('count=0 throws', () => {
+            assert.throws(() => address('fr', 0), /Count must be between/);
+        });
+
+        test('count=11 throws', () => {
+            assert.throws(() => address('fr', 11), /Count must be between/);
+        });
+    });
+});