@sampuli/data 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,21 @@
 # @sampuli/data
 
-**Format-true synthetic test data — 27 countries, Kenya first.** Valid KRA
-PINs and M-Pesa numbers, Nigerian BVNs, South African IDs, real bank SWIFT/BIC
-codes, and ready-made KYC / transfer / payment / merchant scenarios per
-country — generated on the spot, never real people.
-
-Built for QA and dev teams at African banks and fintechs (and beyond) who need
-test data that *passes their own format validation*. Free, no volume caps.
+**Format-true synthetic test data for countries worldwide.** National IDs, tax
+numbers, IBANs & SWIFT/BIC, bank accounts, phone numbers and ready-made KYC /
+transfer / payment scenarios — each in the correct format for its own country,
+generated on the spot.
+
+One API, dozens of countries: Kenyan KRA PINs & M-Pesa numbers, Nigerian BVNs,
+German & Gulf IBANs, Italian Codice Fiscale, Brazilian CPF/CNPJ, Mexican CLABE,
+Turkish TCKN, Singapore NRIC — and many more, each shaped to its national rules
+(checksums, prefixes, bank codes).
+
+> **Every value is entirely synthetic.** It matches the real *format* only and
+> corresponds to no real person, account, or registered number. Never present
+> any output as a genuine ID, tax number, IBAN, or bank account.
+
+Built for QA and CI at banks and fintechs anywhere — test data that *passes
+your own format validation*. Free, no volume caps.
 The engine behind [Sampuli](https://sampuli.site).
 
 ```bash
@@ -18,26 +27,31 @@ npm install @sampuli/data
 ```js
 import { generate, generateMany, listPacks } from '@sampuli/data'
 
-listPacks()                     // ['KE','DZ','AO', … 'FR','NL','BR', …] — every Sampuli country
+listPacks()             // every installed country, e.g.
+                        // ['KE','NG','ZA','EG','DE','FR','IT','TR','SA','BR','MX','SG', …]
 
-generate('ke.phone')            // → '0712345678'   (a real Safaricom/Airtel/Telkom prefix)
-generate('ke.kra_pin')          // → 'A123456789Z'  (valid KRA PIN format)
-generate('ng.person')           // → a coherent Nigerian record
-generate('za.person')           // → a coherent South African record
+// One value — the spec is `country.field`:
+generate('ke.phone')    // Kenya     → '0712345678'
+generate('ng.bvn')      // Nigeria   → '22803022407'
+generate('de.account')  // Germany   → 'DE19100900004650895069'   (IBAN)
+generate('it.id')       // Italy     → 'LNEFRC90M22F205G'         (Codice Fiscale)
+generate('sg.id')       // Singapore → 'S6763250H'                (NRIC)
 
-generate('ke.person')
+// A whole coherent record — any country:
+generate('de.person')
 // → {
-//     name: 'Mercy Achieng', phone: '0748163920', id: '27380011',
-//     kra: 'A661044820Q', bank: 'Equity Bank', swift: 'EQBLKENA',
-//     account: '830155120774', amount: 'KES 12,400.00'
+//     name: 'Mia Zimmermann', phone: '0179 1480356', id: 'L0PYL465F',
+//     tax: '74259823954', bank: 'HypoVereinsbank', swift: 'HYVEDEMMXXX',
+//     account: 'DE68700202706388873556', amount: '€16.680,00'
 //   }
 
-generateMany('ke.person', 200)  // → 200 coherent records
+generateMany('br.person', 500)   // → 500 coherent Brazilian records
 ```
 
 Every pack uses the same spec shape — swap the country code. A pack's fields
 and presets vary by country; discover them with `listFields(code)` /
-`listPresets(code)`. (Kenya's tax id field is `kra`; most other packs use `tax`.)
+`listPresets(code)`. Records stay internally coherent (bank ↔ SWIFT, gender ↔
+name, town ↔ region, email ↔ name).
 
 CommonJS works too:
 
@@ -72,6 +86,28 @@ Kenya's field keys, for example: `name`, `phone`, `id`, `kra`, `bank`,
 swift/account/amount) with locale-specific extras and presets — always check
 `listFields(code)`.
 
+**Every country also has payment-card and passport fields** (off by default):
+`card` (Luhn-valid PAN, scheme-correct BIN), `card_scheme` (Visa / Mastercard /
+American Express), `card_expiry` (MM/YY), `card_cvv`, `passport` (number),
+`passport_expiry`, and `passport_mrz` — a full ICAO-9303 TD3 machine-readable
+zone with correct check digits, coherent with the record's name and gender.
+
+```js
+generate('dk.card')          // → '4536 3094 5269 0134'  (Visa, Luhn-valid)
+generate('gb.person', { fields: ['name', 'card', 'card_scheme', 'card_cvv', 'passport'] })
+generate('za.passport_mrz')  // → two 44-char MRZ lines with valid ICAO check digits
+```
+
+**And a set of cross-country extras** (also off by default): a transaction
+(`txn_datetime`, `txn_type`, `txn_status`, `txn_channel`, `txn_mcc` with real
+ISO-18245 codes), `ip` / `ipv6`, `licence` (driver's licence), `income`
+(currency-magnitude-aware for the pack's currency), `employer`, and `country`.
+
+```js
+generate('jp.income')   // → '9,970,000 JPY'   (scaled to the local currency)
+generate('ke.person', { fields: ['name', 'txn_datetime', 'txn_type', 'txn_mcc', 'ip', 'income'] })
+```
+
 ## Choosing which fields a record has
 
 `generate('ke.person')` returns the on-by-default columns. To include the
@@ -116,18 +152,19 @@ generateMany('ke.person', 100, { seed: 'batch' }) // identical batch every run
 
 ## Scope
 
-Ships **all 27 Sampuli country packs**, free, with no volume caps — Africa
-(Kenya, Nigeria, South Africa, Egypt, Ghana, Tanzania, Uganda, Rwanda,
-Algeria, Angola, Morocco, Ethiopia, Côte d'Ivoire, DR Congo, Tunisia,
-Cameroon, Mauritius), plus Germany, Switzerland, UK, Canada, US, UAE,
-Australia, China, India, Japan. Try them at [sampuli.site](https://sampuli.site).
-Additional packs can be plugged in at runtime via `registerPack(pack)`.
+Ships every Sampuli country pack, free, with no volume caps — countries across
+Africa, Europe, the Middle East, Asia-Pacific and the Americas, and growing.
+Call `listPacks()` for the full set installed, or browse them at
+[sampuli.site](https://sampuli.site). Additional packs can be plugged in at
+runtime via `registerPack(pack)`.
 
-## Accuracy
+## Accuracy & synthetic data
 
-Every value is *format-valid*: it matches the real shape and passes standard
-format checks. It is entirely synthetic — invented at call time, corresponding
-to no real person, account, or business.
+Every value is *format-correct*: it matches the real shape and passes standard
+format checks. It is **entirely synthetic** — invented at call time and
+corresponding to no real person, account, business, or registered number. It is
+for testing only; do not present any output as a genuine KRA PIN, national ID,
+tax number, IBAN, or bank account.
 
 ## License