@sampuli/data 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +106 -28
  2. package/dist/cli.js +13148 -0
  3. package/dist/index.cjs +3219 -84
  4. package/dist/index.js +3219 -84
  5. package/package.json +13 -7
package/README.md CHANGED
@@ -1,43 +1,98 @@
1
1
  # @sampuli/data
2
2
 
3
- **Format-true synthetic test data — 27 countries, Kenya first.** Valid KRA
4
- PINs and M-Pesa numbers, Nigerian BVNs, South African IDs, real bank SWIFT/BIC
5
- codes, and ready-made KYC / transfer / payment / merchant scenarios per
6
- country — generated on the spot, never real people.
3
+ [![npm version](https://img.shields.io/npm/v/@sampuli/data.svg)](https://www.npmjs.com/package/@sampuli/data)
4
+ [![downloads](https://img.shields.io/npm/dm/@sampuli/data.svg)](https://www.npmjs.com/package/@sampuli/data)
5
+ [![CI](https://github.com/kevinbett/sampuli/actions/workflows/ci.yml/badge.svg)](https://github.com/kevinbett/sampuli/actions/workflows/ci.yml)
6
+ [![license](https://img.shields.io/npm/l/@sampuli/data.svg)](./README.md)
7
+ [![zero deps](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#)
7
8
 
8
- Built for QA and dev teams at African banks and fintechs (and beyond) who need
9
- test data that *passes their own format validation*. Free, no volume caps.
10
- The engine behind [Sampuli](https://sampuli.site).
9
+ > **Synthetic test data that passes your own validators — 90 countries.**
10
+
11
+ Most fake-data tools give you `John Doe` and a random 16-digit number. `@sampuli/data`
12
+ gives you a **KRA PIN that passes a KRA validator**, a **real bank's SWIFT/BIC**, a
13
+ **valid IBAN** (mod-97), an **ICAO-9303 passport MRZ**, a **Luhn-valid card** — each
14
+ one shaped to its country's actual rules (checksums, prefixes, bank codes). Entirely
15
+ synthetic; corresponds to no real person or account.
11
16
 
12
17
  ```bash
13
18
  npm install @sampuli/data
14
19
  ```
15
20
 
21
+ **▶ Try it in your browser, no install:** [sampuli.site](https://sampuli.site) · or in your terminal: `npx @sampuli/data ke.person`
22
+
23
+ ## Why not faker / Mockaroo?
24
+
25
+ | | faker.js | Mockaroo | **@sampuli/data** |
26
+ |---|:---:|:---:|:---:|
27
+ | Country-specific ID / tax formats | ✗ | partial | **✓ 90 countries** |
28
+ | Checksum-valid (Luhn, mod-97, mod-11…) | ✗ | ✗ | **✓** |
29
+ | Real bank names + SWIFT/BIC | ✗ | ✗ | **✓** |
30
+ | Valid IBANs, CLABE, NUBAN… | ✗ | ✗ | **✓** |
31
+ | Passport MRZ (ICAO-9303) | ✗ | ✗ | **✓** |
32
+ | Coherent records (bank↔SWIFT, gender↔name) | partial | ✗ | **✓** |
33
+ | Reproducible seeds · zero deps · free | ✓ | – | **✓** |
34
+
35
+ Built for **QA and CI at banks and fintechs** — test data that *passes your own
36
+ format validation*, so you can exercise KYC, onboarding and payment flows without
37
+ touching real PII.
38
+
39
+ <details><summary>Older intro / disclaimer</summary>
40
+
41
+ One API, dozens of countries: Kenyan KRA PINs & M-Pesa numbers, Nigerian BVNs,
42
+ German & Gulf IBANs, Italian Codice Fiscale, Brazilian CPF/CNPJ, Mexican CLABE,
43
+ Turkish TCKN, Singapore NRIC — and many more.
44
+
45
+ > **Every value is entirely synthetic.** It matches the real *format* only and
46
+ > corresponds to no real person, account, or registered number. Never present
47
+ > any output as a genuine ID, tax number, IBAN, or bank account.
48
+
49
+ </details>
50
+
51
+ ## From the terminal (CLI)
52
+
53
+ No code needed — try it with `npx`:
54
+
55
+ ```bash
56
+ npx @sampuli/data ke.person # one Kenyan record (JSON)
57
+ npx @sampuli/data ke.kra_pin # a single value
58
+ npx @sampuli/data ng.person -n 100 # 100 records
59
+ npx @sampuli/data de.person -f name,account,card,passport_mrz
60
+ npx @sampuli/data ke.person -n 500 --csv # CSV to stdout
61
+ npx @sampuli/data ke.preset:kyc # a KYC scenario
62
+ npx @sampuli/data --list # list all 90 country codes
63
+ npx @sampuli/data --list ke # a country's fields & presets
64
+ ```
65
+
16
66
  ## Quick start
17
67
 
18
68
  ```js
19
69
  import { generate, generateMany, listPacks } from '@sampuli/data'
20
70
 
21
- listPacks() // ['KE','DZ','AO', … 'FR','NL','BR', …] — every Sampuli country
71
+ listPacks() // every installed country, e.g.
72
+ // ['KE','NG','ZA','EG','DE','FR','IT','TR','SA','BR','MX','SG', …]
22
73
 
23
- generate('ke.phone') // → '0712345678' (a real Safaricom/Airtel/Telkom prefix)
24
- generate('ke.kra_pin') // → 'A123456789Z' (valid KRA PIN format)
25
- generate('ng.person') // → a coherent Nigerian record
26
- generate('za.person') // → a coherent South African record
74
+ // One value — the spec is `country.field`:
75
+ generate('ke.phone') // Kenya → '0712345678'
76
+ generate('ng.bvn') // Nigeria → '22803022407'
77
+ generate('de.account') // Germany → 'DE19100900004650895069' (IBAN)
78
+ generate('it.id') // Italy → 'LNEFRC90M22F205G' (Codice Fiscale)
79
+ generate('sg.id') // Singapore → 'S6763250H' (NRIC)
27
80
 
28
- generate('ke.person')
81
+ // A whole coherent record — any country:
82
+ generate('de.person')
29
83
  // → {
30
- // name: 'Mercy Achieng', phone: '0748163920', id: '27380011',
31
- // kra: 'A661044820Q', bank: 'Equity Bank', swift: 'EQBLKENA',
32
- // account: '830155120774', amount: 'KES 12,400.00'
84
+ // name: 'Mia Zimmermann', phone: '0179 1480356', id: 'L0PYL465F',
85
+ // tax: '74259823954', bank: 'HypoVereinsbank', swift: 'HYVEDEMMXXX',
86
+ // account: 'DE68700202706388873556', amount: '€16.680,00'
33
87
  // }
34
88
 
35
- generateMany('ke.person', 200) // → 200 coherent records
89
+ generateMany('br.person', 500) // → 500 coherent Brazilian records
36
90
  ```
37
91
 
38
92
  Every pack uses the same spec shape — swap the country code. A pack's fields
39
93
  and presets vary by country; discover them with `listFields(code)` /
40
- `listPresets(code)`. (Kenya's tax id field is `kra`; most other packs use `tax`.)
94
+ `listPresets(code)`. Records stay internally coherent (bank ↔ SWIFT, gender ↔
95
+ name, town ↔ region, email ↔ name).
41
96
 
42
97
  CommonJS works too:
43
98
 
@@ -72,6 +127,28 @@ Kenya's field keys, for example: `name`, `phone`, `id`, `kra`, `bank`,
72
127
  swift/account/amount) with locale-specific extras and presets — always check
73
128
  `listFields(code)`.
74
129
 
130
+ **Every country also has payment-card and passport fields** (off by default):
131
+ `card` (Luhn-valid PAN, scheme-correct BIN), `card_scheme` (Visa / Mastercard /
132
+ American Express), `card_expiry` (MM/YY), `card_cvv`, `passport` (number),
133
+ `passport_expiry`, and `passport_mrz` — a full ICAO-9303 TD3 machine-readable
134
+ zone with correct check digits, coherent with the record's name and gender.
135
+
136
+ ```js
137
+ generate('dk.card') // → '4536 3094 5269 0134' (Visa, Luhn-valid)
138
+ generate('gb.person', { fields: ['name', 'card', 'card_scheme', 'card_cvv', 'passport'] })
139
+ generate('za.passport_mrz') // → two 44-char MRZ lines with valid ICAO check digits
140
+ ```
141
+
142
+ **And a set of cross-country extras** (also off by default): a transaction
143
+ (`txn_datetime`, `txn_type`, `txn_status`, `txn_channel`, `txn_mcc` with real
144
+ ISO-18245 codes), `ip` / `ipv6`, `licence` (driver's licence), `income`
145
+ (currency-magnitude-aware for the pack's currency), `employer`, and `country`.
146
+
147
+ ```js
148
+ generate('jp.income') // → '9,970,000 JPY' (scaled to the local currency)
149
+ generate('ke.person', { fields: ['name', 'txn_datetime', 'txn_type', 'txn_mcc', 'ip', 'income'] })
150
+ ```
151
+
75
152
  ## Choosing which fields a record has
76
153
 
77
154
  `generate('ke.person')` returns the on-by-default columns. To include the
@@ -116,18 +193,19 @@ generateMany('ke.person', 100, { seed: 'batch' }) // identical batch every run
116
193
 
117
194
  ## Scope
118
195
 
119
- Ships **all 27 Sampuli country packs**, free, with no volume caps — Africa
120
- (Kenya, Nigeria, South Africa, Egypt, Ghana, Tanzania, Uganda, Rwanda,
121
- Algeria, Angola, Morocco, Ethiopia, Côte d'Ivoire, DR Congo, Tunisia,
122
- Cameroon, Mauritius), plus Germany, Switzerland, UK, Canada, US, UAE,
123
- Australia, China, India, Japan. Try them at [sampuli.site](https://sampuli.site).
124
- Additional packs can be plugged in at runtime via `registerPack(pack)`.
196
+ Ships every Sampuli country pack, free, with no volume caps — countries across
197
+ Africa, Europe, the Middle East, Asia-Pacific and the Americas, and growing.
198
+ Call `listPacks()` for the full set installed, or browse them at
199
+ [sampuli.site](https://sampuli.site). Additional packs can be plugged in at
200
+ runtime via `registerPack(pack)`.
125
201
 
126
- ## Accuracy
202
+ ## Accuracy & synthetic data
127
203
 
128
- Every value is *format-valid*: it matches the real shape and passes standard
129
- format checks. It is entirely synthetic — invented at call time, corresponding
130
- to no real person, account, or business.
204
+ Every value is *format-correct*: it matches the real shape and passes standard
205
+ format checks. It is **entirely synthetic** — invented at call time and
206
+ corresponding to no real person, account, business, or registered number. It is
207
+ for testing only; do not present any output as a genuine KRA PIN, national ID,
208
+ tax number, IBAN, or bank account.
131
209
 
132
210
  ## License
133
211