@ccgenerator/test-cards 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package
+follows [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] — 2026-08-23
+
+First public release.
+
+### Added
+
+- `generate(network?, options?)` — one synthetic, Luhn-valid card with CVV and
+  expiry; `formatted`, `length` and `expiryYearsAhead` options.
+- `generateMany(count, network?, options?)` — batches, deliberately without
+  deduplication.
+- `validate(pan)` — structural validation with stable error codes
+  (`not_a_string`, `empty`, `non_digit`, `unknown_network`, `bad_length`,
+  `luhn_failed`).
+- `detectBrand(pan)` — network detection that works on partial input.
+- `luhnCheckDigit(payload)` / `isLuhnValid(pan)` — the checksum primitives.
+- `networks` / `networkKeys` — the rule table itself: IIN prefixes, lengths,
+  CVV length and display grouping per network.
+- Nine networks: Visa, Mastercard (including the 2-series), American Express,
+  Discover, JCB, Diners Club (14-digit), Maestro (16/19), UnionPay (16/19),
+  Troy.
+- Hand-written TypeScript declarations (`index.d.ts`).
+- Test suite on `node:test` — no framework, no dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CC Generator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# @ccgenerator/test-cards
+
+[![npm version](https://img.shields.io/npm/v/%40ccgenerator%2Ftest-cards)](https://www.npmjs.com/package/@ccgenerator/test-cards)
+[![CI](https://github.com/ccgeneratororg/ccgenerator-npm/actions/workflows/test.yml/badge.svg)](https://github.com/ccgeneratororg/ccgenerator-npm/actions/workflows/test.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](./package.json)
+
+Synthetic, Luhn-valid payment card numbers for testing card input.
+
+Zero dependencies. No network calls. Works in Node and the browser.
+
+```js
+import { generate, validate, detectBrand } from '@ccgenerator/test-cards';
+
+generate('mastercard');
+// { network: 'mastercard', networkName: 'Mastercard', pan: '5312448763449521',
+//   cvv: '204', expiryMonth: '09', expiryYear: '2029' }
+
+detectBrand('2223 0031 2200 3222');  // 'mastercard'
+validate('4111111111111112').errors; // ['luhn_failed']
+```
+
+## What this is for
+
+Exercising the card field. Does the input mask group digits correctly? Does the
+brand icon switch on the right prefix? Does a 19-digit Maestro number survive the
+form, and does a 15-digit Amex number get an Amex-length CVV field?
+
+Those are the questions this package answers, and it is deliberately not useful
+for anything else.
+
+## What it is not
+
+**The numbers are not real cards.** They satisfy the Luhn checksum and sit inside
+published issuer identification ranges, which is exactly what a card field checks
+— and that is where the resemblance stops. They correspond to no account at any
+issuer, carry no balance, and cannot authorise a transaction. A payment gateway
+declines them at the first hop.
+
+**They are not gateway test cards either.** Stripe, PayPal, Adyen and the rest
+publish their own fixed numbers that trigger specific sandbox behaviour, such as
+a decline for insufficient funds or a 3-D Secure challenge. This package cannot
+produce those, because they are assigned by the gateway, not derived. Use the
+provider's own list for that: [ccgenerator.org/test-card-numbers](https://ccgenerator.org/test-card-numbers/)
+collects them per gateway.
+
+## Install
+
+```sh
+npm install --save-dev @ccgenerator/test-cards
+```
+
+Node 18 or newer. ESM only.
+
+## Recipes
+
+### Table-driven form tests
+
+The output shape is stable, so a batch drops straight into a parameterised
+suite. With `node:test` (works the same in Vitest or Jest):
+
+```js
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { generateMany } from '@ccgenerator/test-cards';
+import { formatCardInput } from '../src/card-field.js'; // your code
+
+for (const { networkName, pan } of generateMany(100)) {
+  test(`${networkName} ${pan} survives the input mask`, () => {
+    assert.equal(formatCardInput(pan).replaceAll(' ', ''), pan);
+  });
+}
+```
+
+One hundred fresh numbers per run costs nothing and finds the seams a single
+hard-coded `4111 1111 1111 1111` never will — the 15-digit Amex, the 14-digit
+Diners, the 19-digit Maestro.
+
+### Negative cases
+
+A number that is *almost* right is the most useful test input there is. Break
+the check digit deliberately:
+
+```js
+import { generate, validate } from '@ccgenerator/test-cards';
+
+const good = generate('visa').pan;
+const bad = good.slice(0, -1) + String((Number(good.at(-1)) + 1) % 10);
+
+validate(bad).errors; // ['luhn_failed'] — your form should reject it too
+```
+
+### End-to-end (Playwright, Cypress, …)
+
+```js
+import { generate } from '@ccgenerator/test-cards';
+
+test('checkout accepts a 19-digit Maestro', async ({ page }) => {
+  const card = generate('maestro', { length: 19 });
+
+  await page.goto('/checkout');
+  await page.fill('[name=cardnumber]', card.pan);
+  await page.fill('[name=expiry]', `${card.expiryMonth}/${card.expiryYear.slice(2)}`);
+  await page.fill('[name=cvc]', card.cvv);
+
+  await expect(page.locator('.brand-icon')).toHaveClass(/maestro/);
+});
+```
+
+This exercises *your* form, not a payment. If the page ends at a real gateway,
+use that gateway's own sandbox numbers instead — see
+[What it is not](#what-it-is-not).
+
+### In the browser, no build step
+
+```html
+<script type="module">
+  import { generate } from 'https://cdn.jsdelivr.net/npm/@ccgenerator/test-cards@1/+esm';
+
+  console.log(generate('visa', { formatted: true }).formatted);
+</script>
+```
+
+### TypeScript
+
+Types ship with the package — no `@types/…` install, no build step on our side:
+
+```ts
+import { generate, networks, type NetworkKey } from '@ccgenerator/test-cards';
+
+function cvvFieldSize(key: NetworkKey): number {
+  return networks[key].cvvLength;
+}
+
+cvvFieldSize(generate().network); // 3 or 4
+```
+
+## API
+
+### `generate(network?, options?)`
+
+Returns one `TestCard`. `network` is a key from the table below, or `'random'`
+(the default).
+
+```js
+generate('amex');
+generate('visa', { formatted: true });   // adds `formatted: '4539 8776 1234 5678'`
+generate('maestro', { length: 19 });     // pick one of the network's lengths
+generate('visa', { expiryYearsAhead: 2 });
+```
+
+Throws `RangeError` on an unknown network, or on a length that network does not
+issue — `generate('amex', { length: 16 })` is a mistake worth failing loudly.
+
+### `generateMany(count, network?, options?)`
+
+An array of `count` cards. Numbers are not deduplicated; collisions are
+vanishingly unlikely at realistic counts, and discarding draws would bias the
+output.
+
+### `validate(pan)`
+
+Structural validation. Separators are ignored.
+
+```js
+validate('4111 1111 1111 1111');
+// { valid: true, network: 'visa', pan: '4111111111111111',
+//   length: 16, luhn: true, errors: [] }
+```
+
+`errors` holds stable string codes rather than sentences, so you can map them to
+your own copy: `not_a_string`, `empty`, `non_digit`, `unknown_network`,
+`bad_length`, `luhn_failed`.
+
+A number that passes Luhn but matches no known IIN range comes back with
+`unknown_network` rather than being rejected outright. New ranges get allocated,
+and any table like this one goes stale before the standard does.
+
+### `detectBrand(pan)`
+
+The network key, or `null`. Works on partial input, so it can drive a brand
+indicator while the user is still typing:
+
+```js
+detectBrand('4');    // 'visa'
+detectBrand('22');   // 'mastercard'
+detectBrand('');     // null
+```
+
+### `luhnCheckDigit(payload)`
+
+The digit that completes `payload` into a Luhn-valid number. `payload` is the
+number *without* its final check digit.
+
+```js
+luhnCheckDigit('411111111111111'); // '1'
+```
+
+### `isLuhnValid(pan)`
+
+Whether a number satisfies the checksum. Ignores spaces and hyphens; returns
+`false` for anything else non-numeric rather than silently stripping it.
+
+### `networks`, `networkKeys`
+
+The rule table itself, if you need the lengths or CVV length for a network.
+
+```js
+networks.amex.cvvLength; // 4
+networks.amex.lengths;   // [15]
+```
+
+## Supported networks
+
+Each network name links to a browser version of the generator, for when you
+want a number without opening a REPL.
+
+| Key | Network | Lengths | CVV |
+|---|---|---|---|
+| `visa` | [Visa](https://ccgenerator.org/visa-card-generator/) | 16 | 3 |
+| `mastercard` | [Mastercard](https://ccgenerator.org/mastercard-generator/) | 16 | 3 |
+| `amex` | [American Express](https://ccgenerator.org/american-express-card-generator/) | 15 | 4 |
+| `discover` | [Discover](https://ccgenerator.org/discover-card-generator/) | 16 | 3 |
+| `jcb` | [JCB](https://ccgenerator.org/jcb-card-generator/) | 16 | 3 |
+| `diners` | [Diners Club](https://ccgenerator.org/diners-club-card-generator/) | 14 | 3 |
+| `maestro` | [Maestro](https://ccgenerator.org/maestro-card-generator/) | 16, 19 | 3 |
+| `unionpay` | [UnionPay](https://ccgenerator.org/unionpay-card-generator/) | 16, 19 | 3 |
+| `troy` | [Troy](https://ccgenerator.org/troy-card-generator/) | 16 | 3 |
+
+## Why the ranges are what they are
+
+The rule table is where hand-rolled card fixtures usually go wrong, so the three
+most common mistakes are worth spelling out:
+
+- **Mastercard's 2-series** (222100–272099) has been live since 2017. Code that
+  only checks 51–55 rejects a real, in-issue Mastercard.
+- **Maestro is not "50, 56–69".** That approximation swallows Discover's 6011,
+  65 and 644–649 and UnionPay's 62, so a generator built on it emits numbers
+  that are not Maestro at all. This package uses the allocations Maestro
+  actually issues on.
+- **Not every network is 16 digits.** Amex is 15, classic Diners Club is 14, and
+  Maestro and UnionPay issue at 19 as well as 16 — the full picture is in
+  [card number length by network](https://ccgenerator.org/guides/card-number-length-by-network/).
+  A form that hard-codes 16 truncates real cards.
+
+## Randomness
+
+Card numbers are drawn from `crypto.getRandomValues()` with rejection sampling,
+not `% range`. This is not a security property — nothing here protects anything.
+It is a correctness one: a biased generator under-samples part of the range,
+which is precisely the gap a test corpus exists to close.
+
+## Tests
+
+```sh
+npm test
+```
+
+No test framework, no dependencies — `node:test` and `node:assert`. The suite
+includes an exhaustive check that Luhn catches every single-digit error, and one
+that pins its documented blind spot: a transposed `09` ↔ `90` passes, and any
+claim that Luhn catches *all* transpositions is wrong.
+
+## Related tools
+
+The same rule table runs in two other places, for when you want the numbers
+without writing code:
+
+- **[Browser generator](https://ccgenerator.org/credit-card-number-generator/)** —
+  generate and copy test numbers for any of the nine networks, no install.
+- **[Chrome extension](https://chromewebstore.google.com/detail/credit-card-generator-tes/jmjdiinigjlchmnjkccoljpcnbgbikfd)** —
+  generates test numbers, validates BINs, and fills checkout forms in one click
+  while you develop.
+- **[Card validator](https://ccgenerator.org/credit-card-validator/)** — paste a
+  number, see the same structural checks `validate()` runs, with the failure
+  explained.
+- **[Bulk generator](https://ccgenerator.org/bulk-credit-card-generator/)** — up
+  to 10,000 cards with reproducible seeds, exported as CSV, JSON, JSONL, SQL or
+  TSV, for fixtures that live outside JavaScript.
+
+## Background
+
+Longer write-ups of the mechanics behind this package:
+
+- [The Luhn algorithm](https://ccgenerator.org/guides/luhn-algorithm/) — worked
+  example, reference implementation, and what it misses
+- [Luhn algorithm code examples](https://ccgenerator.org/guides/luhn-algorithm-code-examples/) —
+  the check digit routine in JavaScript, TypeScript, Python, PHP and Ruby
+- [Card number structure](https://ccgenerator.org/guides/credit-card-number-structure/) —
+  IIN, account identifier, check digit
+- [Card brand detection regex](https://ccgenerator.org/guides/card-brand-detection-regex/)
+- [Why test cards fail on real payment systems](https://ccgenerator.org/guides/why-test-cards-fail-on-real-payment-systems/)
+
+## Contributing and security
+
+Corrections to the IIN table are welcome — with a source; the bar is described
+in [CONTRIBUTING.md](CONTRIBUTING.md). The package's security posture (no
+dependencies, no scripts, no network, no real card data) is spelled out in
+[SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Type definitions for @ccgenerator/test-cards.
+ *
+ * Hand-written rather than emitted by tsc: the package is plain ESM with no
+ * build step, and a 90-line declaration file is cheaper to maintain than a
+ * toolchain. Keep this in step with src/index.js.
+ */
+
+/** A network key accepted by `generate` and returned by `detectBrand`. */
+export type NetworkKey =
+  | 'visa'
+  | 'mastercard'
+  | 'amex'
+  | 'discover'
+  | 'jcb'
+  | 'diners'
+  | 'maestro'
+  | 'unionpay'
+  | 'troy';
+
+/** An inclusive numeric IIN range whose bounds have the same digit count. */
+export interface PrefixRange {
+  from: number;
+  to: number;
+}
+
+export type Prefix = string | PrefixRange;
+
+export interface NetworkRule {
+  /** Display name, e.g. "American Express". */
+  name: string;
+  /** Published IIN prefixes and ranges. */
+  prefixes: readonly Prefix[];
+  /** Digit counts this network issues. */
+  lengths: readonly number[];
+  /** CVV/CVC/CID length. */
+  cvvLength: number;
+  /** Digit grouping used by `format`. */
+  groups: readonly number[];
+}
+
+export interface GenerateOptions {
+  /** Force one of the network's accepted lengths. */
+  length?: number;
+  /** Also return the number grouped for display. */
+  formatted?: boolean;
+  /** Upper bound for the generated expiry year. Default 5. */
+  expiryYearsAhead?: number;
+}
+
+export interface TestCard {
+  network: NetworkKey;
+  networkName: string;
+  /** Digits only. */
+  pan: string;
+  /** Present only when `formatted: true` was passed. */
+  formatted?: string;
+  cvv: string;
+  /** Zero-padded, "01"–"12". */
+  expiryMonth: string;
+  /** Four digits. */
+  expiryYear: string;
+}
+
+/** Stable, machine-readable reasons a PAN failed validation. */
+export type ValidationError =
+  | 'not_a_string'
+  | 'empty'
+  | 'non_digit'
+  | 'unknown_network'
+  | 'bad_length'
+  | 'luhn_failed';
+
+export interface ValidationResult {
+  /** True only when every structural check passed. */
+  valid: boolean;
+  network: NetworkKey | null;
+  /** The PAN with separators removed. */
+  pan: string;
+  length: number;
+  luhn: boolean;
+  errors: ValidationError[];
+}
+
+export declare function generate(
+  network?: NetworkKey | 'random',
+  options?: GenerateOptions
+): TestCard;
+
+export declare function generateMany(
+  count: number,
+  network?: NetworkKey | 'random',
+  options?: GenerateOptions
+): TestCard[];
+
+export declare function format(pan: string, groups: readonly number[]): string;
+
+export declare function validate(pan: string): ValidationResult;
+
+export declare function detectBrand(pan: string): NetworkKey | null;
+
+export declare function luhnCheckDigit(payload: string): string;
+
+export declare function isLuhnValid(pan: string): boolean;
+
+export declare const networks: Readonly<Record<NetworkKey, NetworkRule>>;
+
+export declare const networkKeys: readonly NetworkKey[];

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ccgenerator/test-cards",
+  "version": "1.0.0",
+  "description": "Synthetic, Luhn-valid payment card numbers for testing card input. Zero dependencies, no network calls, works in Node and the browser.",
+  "keywords": [
+    "test-card",
+    "credit-card",
+    "luhn",
+    "payment",
+    "testing",
+    "qa",
+    "fixtures",
+    "test-data",
+    "card-validation",
+    "iin",
+    "bin",
+    "pan",
+    "card-number",
+    "sandbox",
+    "pci"
+  ],
+  "license": "MIT",
+  "author": "CC Generator Editorial Team <hello@ccgenerator.org>",
+  "homepage": "https://ccgenerator.org/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ccgeneratororg/ccgenerator-npm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ccgeneratororg/ccgenerator-npm/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "index.d.ts",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/detect.js

@@ -0,0 +1,58 @@
+/**
+ * Network detection from an IIN prefix.
+ */
+
+import { networks, matchesPrefix, prefixWidth } from './networks.js';
+
+/**
+ * Score a matching prefix so the most specific rule wins.
+ *
+ * Two components, in order: how many prefix digits are pinned down, then
+ * whether the rule is an exact prefix rather than a range. The second matters
+ * where two networks are allocated at the same depth — "62" is UnionPay's own
+ * two-digit allocation, so it beats a two-digit range that merely spans it.
+ *
+ * @param {import('./networks.js').Prefix} prefix
+ * @returns {number}
+ */
+function specificity(prefix) {
+  return prefixWidth(prefix) * 2 + (typeof prefix === 'string' ? 1 : 0);
+}
+
+/**
+ * Identify the card network from a PAN or a partial one.
+ *
+ * A number starting 6011 is Discover, not something matched by a shorter rule,
+ * because the four pinned digits outrank two. Ties beyond that fall to
+ * declaration order in the network table.
+ *
+ * Returns `null` for input that matches nothing — including empty input, which
+ * is the normal state of a card field before the first keystroke and not an
+ * error.
+ *
+ * @param {string} pan Full or partial PAN. Spaces and hyphens are ignored.
+ * @returns {string | null} A network key such as "visa", or null.
+ */
+export function detectBrand(pan) {
+  if (typeof pan !== 'string') return null;
+
+  const digits = pan.replace(/[ -]/g, '');
+  if (!/^\d+$/.test(digits)) return null;
+
+  let best = null;
+  let bestScore = -1;
+
+  for (const [key, rule] of Object.entries(networks)) {
+    for (const prefix of rule.prefixes) {
+      if (!matchesPrefix(digits, prefix)) continue;
+
+      const score = specificity(prefix);
+      if (score > bestScore) {
+        best = key;
+        bestScore = score;
+      }
+    }
+  }
+
+  return best;
+}

package/src/generate.js

@@ -0,0 +1,135 @@
+/**
+ * Synthetic card generation.
+ *
+ * Everything produced here is structurally valid and financially inert: the
+ * numbers satisfy the Luhn checksum and sit inside published IIN ranges, and
+ * they correspond to no account at any issuer. That is the point — they are for
+ * exercising a card field, not for buying anything.
+ */
+
+import { networks, networkKeys } from './networks.js';
+import { luhnCheckDigit } from './luhn.js';
+import { randomInt, randomDigits, choose } from './random.js';
+
+/**
+ * @typedef {object} GenerateOptions
+ * @property {number} [length] Force one of the network's accepted lengths.
+ * @property {boolean} [formatted] Also return the number grouped for display.
+ * @property {number} [expiryYearsAhead] Upper bound for the expiry year, default 5.
+ */
+
+/**
+ * @typedef {object} TestCard
+ * @property {string} network Network key, e.g. "mastercard".
+ * @property {string} networkName Display name, e.g. "Mastercard".
+ * @property {string} pan Digits only.
+ * @property {string} [formatted] Grouped PAN, when `formatted` was requested.
+ * @property {string} cvv 3 or 4 digits, per network.
+ * @property {string} expiryMonth Zero-padded, "01"–"12".
+ * @property {string} expiryYear Four digits.
+ */
+
+/**
+ * Pick a concrete prefix from a network's rules.
+ *
+ * @param {import('./networks.js').Prefix[]} prefixes
+ * @returns {string}
+ */
+function choosePrefix(prefixes) {
+  const prefix = choose(prefixes);
+  if (typeof prefix === 'string') return prefix;
+
+  // Preserve the digit count: 300–305 must yield "300", never "3".
+  return String(randomInt(prefix.from, prefix.to)).padStart(String(prefix.to).length, '0');
+}
+
+/**
+ * Group a PAN for display, e.g. "4111 1111 1111 1111".
+ *
+ * @param {string} pan
+ * @param {readonly number[]} groups
+ * @returns {string}
+ */
+export function format(pan, groups) {
+  const chunks = [];
+  let at = 0;
+
+  for (const size of groups) {
+    if (at >= pan.length) break;
+    chunks.push(pan.slice(at, at + size));
+    at += size;
+  }
+
+  if (at < pan.length) chunks.push(pan.slice(at));
+
+  return chunks.join(' ');
+}
+
+/**
+ * Generate one synthetic card.
+ *
+ * @param {string} [network] Network key. Omitted or "random" picks one.
+ * @param {GenerateOptions} [options]
+ * @returns {TestCard}
+ * @throws {RangeError} On an unknown network or a length that network never issues.
+ */
+export function generate(network = 'random', options = {}) {
+  const key = network === 'random' ? choose(networkKeys) : network;
+  const rule = networks[key];
+
+  if (!rule) {
+    throw new RangeError(
+      `unknown network "${network}" — expected one of: ${networkKeys.join(', ')}`
+    );
+  }
+
+  const length = options.length ?? choose(rule.lengths);
+  if (!rule.lengths.includes(length)) {
+    throw new RangeError(
+      `${rule.name} does not issue ${length}-digit numbers — accepted: ${rule.lengths.join(', ')}`
+    );
+  }
+
+  const prefix = choosePrefix(rule.prefixes);
+  const payload = prefix + randomDigits(length - prefix.length - 1);
+  const pan = payload + luhnCheckDigit(payload);
+
+  const now = new Date();
+  const yearsAhead = options.expiryYearsAhead ?? 5;
+
+  /** @type {TestCard} */
+  const card = {
+    network: key,
+    networkName: rule.name,
+    pan,
+    cvv: randomDigits(rule.cvvLength),
+    expiryMonth: String(randomInt(1, 12)).padStart(2, '0'),
+    expiryYear: String(now.getFullYear() + randomInt(1, yearsAhead)),
+  };
+
+  if (options.formatted) {
+    card.formatted = format(pan, rule.groups);
+  }
+
+  return card;
+}
+
+/**
+ * Generate `count` cards.
+ *
+ * Numbers are not deduplicated: collisions are astronomically unlikely at any
+ * realistic count, and silently discarding draws would bias the output.
+ *
+ * @param {number} count
+ * @param {string} [network]
+ * @param {GenerateOptions} [options]
+ * @returns {TestCard[]}
+ * @throws {RangeError} If `count` is not a positive integer.
+ */
+export function generateMany(count, network = 'random', options = {}) {
+  if (!Number.isInteger(count) || count < 1) {
+    throw new RangeError('count must be a positive integer');
+  }
+
+  return Array.from({ length: count }, () => generate(network, options));
+}

package/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * @ccgenerator/test-cards
+ *
+ * Synthetic, Luhn-valid payment card numbers for testing card input. No network
+ * calls, no dependencies, no real card data — see the README for what this is
+ * and is not for.
+ */
+
+export { generate, generateMany, format } from './generate.js';
+export { validate } from './validate.js';
+export { detectBrand } from './detect.js';
+export { luhnCheckDigit, isLuhnValid } from './luhn.js';
+export { networks, networkKeys } from './networks.js';

package/src/luhn.js

@@ -0,0 +1,74 @@
+/**
+ * The Luhn mod-10 checksum (ISO/IEC 7812-1, Annex B).
+ *
+ * Both functions walk the digits right to left, doubling every second one and
+ * subtracting 9 from any result above 9. They are kept as two functions rather
+ * than one because the check-digit case operates on a payload with the final
+ * position still empty, and folding that into the validator with a flag makes
+ * both harder to read than they need to be.
+ */
+
+const DIGITS = /^\d+$/;
+
+/**
+ * Sum a digit string under the Luhn weighting, doubling from the right.
+ *
+ * @param {string} digits
+ * @returns {number}
+ */
+function luhnSum(digits) {
+  let sum = 0;
+  let double = false;
+
+  for (let i = digits.length - 1; i >= 0; i -= 1) {
+    let value = digits.charCodeAt(i) - 48;
+    if (double) {
+      value *= 2;
+      if (value > 9) value -= 9;
+    }
+    sum += value;
+    double = !double;
+  }
+
+  return sum;
+}
+
+/**
+ * The digit that completes `payload` into a Luhn-valid number.
+ *
+ * `payload` is the number *without* its final check digit — for a 16-digit PAN
+ * that is 15 digits.
+ *
+ * @param {string} payload Digits only.
+ * @returns {string} A single digit, "0"–"9".
+ * @throws {TypeError} If `payload` is not a non-empty digit string.
+ */
+export function luhnCheckDigit(payload) {
+  if (typeof payload !== 'string' || !DIGITS.test(payload)) {
+    throw new TypeError('luhnCheckDigit expects a non-empty string of digits');
+  }
+
+  // Appending "0" puts the payload digits in the parity they will have once the
+  // real check digit occupies the last position.
+  return String((10 - (luhnSum(payload + '0') % 10)) % 10);
+}
+
+/**
+ * Whether a number satisfies the Luhn checksum.
+ *
+ * Separators are ignored, so "4111 1111 1111 1111" and "4111-1111-1111-1111"
+ * both work. A string containing anything other than digits, spaces and hyphens
+ * is rejected outright rather than silently stripped — a letter in a PAN is a
+ * data-entry bug worth surfacing, not whitespace worth forgiving.
+ *
+ * @param {string} pan
+ * @returns {boolean}
+ */
+export function isLuhnValid(pan) {
+  if (typeof pan !== 'string') return false;
+
+  const digits = pan.replace(/[ -]/g, '');
+  if (!DIGITS.test(digits)) return false;
+
+  return luhnSum(digits) % 10 === 0;
+}

package/src/networks.js

@@ -0,0 +1,138 @@
+/**
+ * Card network rules: the IIN ranges, accepted lengths, CVV length and display
+ * grouping for each network the package supports.
+ *
+ * This table is the same one the generators on ccgenerator.org run on
+ * (layouts/partials/card-generator.html). Ranges come from ISO/IEC 7812-1 and
+ * the networks' own published IIN allocations. Two of them are worth calling
+ * out because they are the most commonly wrong entries in other people's
+ * tables:
+ *
+ *   - Mastercard's 2-series (222100–272099) has been live since 2017. Code that
+ *     only checks 51–55 rejects a real, in-issue Mastercard.
+ *   - Maestro and UnionPay issue at 19 digits as well as 16. A form that hard
+ *     codes 16 truncates them.
+ *
+ * `prefixes` entries are either a literal digit string or a numeric range whose
+ * bounds have the same digit count.
+ */
+
+/**
+ * @typedef {{from: number, to: number}} PrefixRange
+ * @typedef {string | PrefixRange} Prefix
+ */
+
+export const networks = Object.freeze({
+  visa: {
+    name: 'Visa',
+    prefixes: ['4'],
+    lengths: [16],
+    cvvLength: 3,
+    groups: [4, 4, 4, 4],
+  },
+  mastercard: {
+    name: 'Mastercard',
+    prefixes: [{ from: 51, to: 55 }, { from: 2221, to: 2720 }],
+    lengths: [16],
+    cvvLength: 3,
+    groups: [4, 4, 4, 4],
+  },
+  amex: {
+    name: 'American Express',
+    prefixes: ['34', '37'],
+    lengths: [15],
+    cvvLength: 4,
+    groups: [4, 6, 5],
+  },
+  discover: {
+    name: 'Discover',
+    prefixes: ['6011', '65', { from: 644, to: 649 }],
+    lengths: [16],
+    cvvLength: 3,
+    groups: [4, 4, 4, 4],
+  },
+  jcb: {
+    name: 'JCB',
+    prefixes: [{ from: 3528, to: 3589 }],
+    lengths: [16],
+    cvvLength: 3,
+    groups: [4, 4, 4, 4],
+  },
+  diners: {
+    name: 'Diners Club',
+    prefixes: [{ from: 300, to: 305 }, '36', '38', '39'],
+    lengths: [14],
+    cvvLength: 3,
+    groups: [4, 6, 4],
+  },
+  maestro: {
+    name: 'Maestro',
+    // Not the "50, 56–69" approximation that circulates widely. That range
+    // swallows 6011 and 65 (Discover), 644–649 (Discover) and 62 (UnionPay), so
+    // a generator built on it emits numbers that are not Maestro at all. These
+    // are the allocations Maestro actually issues on.
+    prefixes: ['50', { from: 56, to: 58 }, '6304', '6759', { from: 6761, to: 6763 }],
+    lengths: [16, 19],
+    cvvLength: 3,
+    groups: [4, 4, 4, 4, 3],
+  },
+  unionpay: {
+    name: 'UnionPay',
+    prefixes: ['62', '81'],
+    lengths: [16, 19],
+    cvvLength: 3,
+    groups: [4, 4, 4, 4, 3],
+  },
+  troy: {
+    name: 'Troy',
+    prefixes: ['9792'],
+    lengths: [16],
+    cvvLength: 3,
+    groups: [4, 4, 4, 4],
+  },
+});
+
+/** Every supported network key. */
+export const networkKeys = Object.freeze(Object.keys(networks));
+
+/**
+ * Whether a digit string starts inside a prefix rule.
+ *
+ * Partial input matches: "42" is enough to identify Visa, and "2" is enough to
+ * keep Mastercard in play without committing to it, which is what a brand
+ * indicator in a card field needs while the user is still typing.
+ *
+ * @param {string} digits
+ * @param {Prefix} prefix
+ * @returns {boolean}
+ */
+export function matchesPrefix(digits, prefix) {
+  if (typeof prefix === 'string') {
+    const width = Math.min(digits.length, prefix.length);
+    return digits.slice(0, width) === prefix.slice(0, width);
+  }
+
+  const width = String(prefix.to).length;
+  const head = digits.slice(0, width);
+  if (head.length === 0) return false;
+
+  // Compare at the length actually available: a partial "22" against 2221–2720
+  // is checked as 22 against 22–27.
+  const scale = 10 ** (width - head.length);
+  const from = Math.floor(prefix.from / scale);
+  const to = Math.floor(prefix.to / scale);
+  const value = Number(head);
+
+  return value >= from && value <= to;
+}
+
+/**
+ * How many digits of a prefix rule are known — used to rank competing matches
+ * so the most specific network wins.
+ *
+ * @param {Prefix} prefix
+ * @returns {number}
+ */
+export function prefixWidth(prefix) {
+  return typeof prefix === 'string' ? prefix.length : String(prefix.to).length;
+}

package/src/random.js

@@ -0,0 +1,72 @@
+/**
+ * Uniform random integers, from Web Crypto where it exists.
+ *
+ * Rejection sampling rather than `% range`: taking a modulus of a 32-bit value
+ * biases the low end of the range whenever the range does not divide 2^32
+ * evenly. Values at or above the largest exact multiple of `range` are discarded
+ * and redrawn, which keeps every value equally likely.
+ *
+ * This is not a security requirement — nothing here protects anything, and the
+ * output is synthetic test data by definition. It is a correctness requirement:
+ * a biased generator produces test corpora that under-sample part of the range,
+ * which is exactly the kind of gap a test corpus exists to close.
+ */
+
+/* globals crypto */
+const source =
+  typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function'
+    ? crypto
+    : null;
+
+/**
+ * Uniform integer in [min, max], inclusive.
+ *
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+export function randomInt(min, max) {
+  const range = max - min + 1;
+
+  if (!source) {
+    // Only reached on runtimes with no Web Crypto at all. Node has had it
+    // globally since v19, and every browser this package targets has it.
+    return Math.floor(Math.random() * range) + min;
+  }
+
+  const limit = Math.floor(0x100000000 / range) * range;
+  const buffer = new Uint32Array(1);
+  let value;
+
+  do {
+    source.getRandomValues(buffer);
+    value = buffer[0];
+  } while (value >= limit);
+
+  return min + (value % range);
+}
+
+/**
+ * A string of `length` random digits.
+ *
+ * @param {number} length
+ * @returns {string}
+ */
+export function randomDigits(length) {
+  let digits = '';
+  for (let i = 0; i < length; i += 1) {
+    digits += String(randomInt(0, 9));
+  }
+  return digits;
+}
+
+/**
+ * A uniformly chosen element of `items`.
+ *
+ * @template T
+ * @param {readonly T[]} items
+ * @returns {T}
+ */
+export function choose(items) {
+  return items[randomInt(0, items.length - 1)];
+}

package/src/validate.js

@@ -0,0 +1,87 @@
+/**
+ * PAN validation: structure only.
+ *
+ * Nothing here says a card exists, has funds, or would authorise. A PAN can
+ * pass every check in this file and still be declined for a dozen reasons no
+ * client can see. Structural validation is exactly the job of the card field in
+ * a checkout form, and nothing more.
+ */
+
+import { networks } from './networks.js';
+import { isLuhnValid } from './luhn.js';
+import { detectBrand } from './detect.js';
+
+/**
+ * @typedef {object} ValidationResult
+ * @property {boolean} valid True only when every structural check passed.
+ * @property {string | null} network Detected network key, or null.
+ * @property {string} pan The PAN with separators removed.
+ * @property {number} length Digit count.
+ * @property {boolean} luhn Whether the Luhn checksum holds.
+ * @property {string[]} errors Machine-readable reasons, empty when valid.
+ */
+
+/**
+ * Validate the structure of a PAN.
+ *
+ * The `errors` array is deliberately made of stable string codes rather than
+ * sentences, so callers can map them to their own copy and their own
+ * translations:
+ *
+ *   not_a_string, empty, non_digit, unknown_network,
+ *   bad_length, luhn_failed
+ *
+ * ISO/IEC 7812-1 allows 12 to 19 digits, so a number that matches no known IIN
+ * range is reported as `unknown_network` rather than rejected outright — new
+ * ranges are allocated, and this table will be out of date before the standard
+ * is.
+ *
+ * @param {string} pan
+ * @returns {ValidationResult}
+ */
+export function validate(pan) {
+  /** @type {ValidationResult} */
+  const result = {
+    valid: false,
+    network: null,
+    pan: '',
+    length: 0,
+    luhn: false,
+    errors: [],
+  };
+
+  if (typeof pan !== 'string') {
+    result.errors.push('not_a_string');
+    return result;
+  }
+
+  const digits = pan.replace(/[ -]/g, '');
+  result.pan = digits;
+  result.length = digits.length;
+
+  if (digits.length === 0) {
+    result.errors.push('empty');
+    return result;
+  }
+
+  if (!/^\d+$/.test(digits)) {
+    result.errors.push('non_digit');
+    return result;
+  }
+
+  result.luhn = isLuhnValid(digits);
+  result.network = detectBrand(digits);
+
+  if (!result.network) {
+    result.errors.push('unknown_network');
+  } else if (!networks[result.network].lengths.includes(digits.length)) {
+    result.errors.push('bad_length');
+  }
+
+  if (!result.luhn) {
+    result.errors.push('luhn_failed');
+  }
+
+  result.valid = result.errors.length === 0;
+  return result;
+}