@mboka-dev/core 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @mboka-dev/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local data and helpers for Congo-Brazzaville: +242 phone numbers, administrative divisions, FCFA amounts. Zero runtime dependencies.
+
+```bash
+npm install @mboka-dev/core
+```
+
+```ts
+import { phone, money, geo, text } from '@mboka-dev/core';
+
+phone.parse('06 123 45 67').e164;   // '+242061234567'
+money.format(125000);               // '125 000 FCFA'
+```
+
+Documentation (in French): https://github.com/mboka-dev/core

package/dist/cjs/generated/data.d.ts

@@ -0,0 +1,5 @@
+import type { DepartementsFile, CommunesFile, ArrondissementsFile, NumerotationFile } from '../types.js';
+export declare const arrondissements: ArrondissementsFile;
+export declare const communes: CommunesFile;
+export declare const departements: DepartementsFile;
+export declare const numerotation: NumerotationFile;

package/dist/cjs/generated/data.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.numerotation = exports.departements = exports.communes = exports.arrondissements = void 0;
+exports.arrondissements = {
+    "items": []
+};
+exports.communes = {
+    "items": []
+};
+exports.departements = {
+    "items": []
+};
+exports.numerotation = {
+    "countryCode": "242",
+    "nationalNumberLength": 9,
+    "nationalGrouping": [
+        2,
+        3,
+        2,
+        2
+    ],
+    "verification": {
+        "status": "a_verifier",
+        "note": "Bootstrap value. To be confirmed against the national numbering plan published by the regulator (issue #2)."
+    },
+    "prefixes": [
+        {
+            "prefix": "06",
+            "type": "mobile",
+            "operator": "MTN",
+            "verification": {
+                "status": "a_verifier",
+                "note": "Bootstrap value, see issue #2."
+            }
+        },
+        {
+            "prefix": "05",
+            "type": "mobile",
+            "operator": "Airtel",
+            "verification": {
+                "status": "a_verifier",
+                "note": "Bootstrap value, see issue #2."
+            }
+        }
+    ]
+};

package/dist/cjs/geo.d.ts

@@ -0,0 +1,22 @@
+import type { Arrondissement, Commune, Departement } from './types.js';
+export type Level = 'departement' | 'commune' | 'arrondissement';
+export type GeoMatch = ({
+    level: 'departement';
+} & Departement) | ({
+    level: 'commune';
+} & Commune) | ({
+    level: 'arrondissement';
+} & Arrondissement);
+export declare function departements(): Departement[];
+export declare function communes(departementId?: string): Commune[];
+export declare function arrondissements(communeId?: string): Arrondissement[];
+/** All entries whose official name or alias matches, in order: départements, communes, arrondissements. */
+export declare function findAll(name: string, options?: {
+    level?: Level;
+}): GeoMatch[];
+/** First match (exact, after normalization), or null. Fuzzy matching is planned for v0.3. */
+export declare function find(name: string, options?: {
+    level?: Level;
+}): GeoMatch | null;
+/** Official name for a free-text input, or null if unknown. Handy to clean a data column. */
+export declare function normalizeName(name: string): string | null;

package/dist/cjs/geo.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.departements = departements;
+exports.communes = communes;
+exports.arrondissements = arrondissements;
+exports.findAll = findAll;
+exports.find = find;
+exports.normalizeName = normalizeName;
+const data_js_1 = require("./generated/data.js");
+const text_js_1 = require("./text.js");
+// Data is plain JSON, so a JSON round-trip is a safe deep copy in every runtime.
+const clone = (value) => JSON.parse(JSON.stringify(value));
+function departements() {
+    return clone(data_js_1.departements.items);
+}
+function communes(departementId) {
+    const items = departementId ? data_js_1.communes.items.filter((c) => c.departement === departementId) : data_js_1.communes.items;
+    return clone(items);
+}
+function arrondissements(communeId) {
+    const items = communeId ? data_js_1.arrondissements.items.filter((a) => a.commune === communeId) : data_js_1.arrondissements.items;
+    return clone(items);
+}
+function matches(entry, needle) {
+    return [entry.nom, ...entry.aliases].some((n) => (0, text_js_1.normalize)(n) === needle);
+}
+/** All entries whose official name or alias matches, in order: départements, communes, arrondissements. */
+function findAll(name, options = {}) {
+    const needle = (0, text_js_1.normalize)(name);
+    if (!needle)
+        return [];
+    const results = [];
+    const want = (level) => !options.level || options.level === level;
+    if (want('departement'))
+        for (const d of data_js_1.departements.items)
+            if (matches(d, needle))
+                results.push({ level: 'departement', ...clone(d) });
+    if (want('commune'))
+        for (const c of data_js_1.communes.items)
+            if (matches(c, needle))
+                results.push({ level: 'commune', ...clone(c) });
+    if (want('arrondissement'))
+        for (const a of data_js_1.arrondissements.items)
+            if (matches(a, needle))
+                results.push({ level: 'arrondissement', ...clone(a) });
+    return results;
+}
+/** First match (exact, after normalization), or null. Fuzzy matching is planned for v0.3. */
+function find(name, options = {}) {
+    return findAll(name, options)[0] ?? null;
+}
+/** Official name for a free-text input, or null if unknown. Handy to clean a data column. */
+function normalizeName(name) {
+    return find(name)?.nom ?? null;
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,5 @@
+export * as phone from './phone.js';
+export * as money from './money.js';
+export * as geo from './geo.js';
+export * as text from './text.js';
+export type * from './types.js';

package/dist/cjs/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.text = exports.geo = exports.money = exports.phone = void 0;
+exports.phone = require("./phone.js");
+exports.money = require("./money.js");
+exports.geo = require("./geo.js");
+exports.text = require("./text.js");

package/dist/cjs/money.d.ts

@@ -0,0 +1,19 @@
+export interface FormatOptions {
+    /** Text after the amount. Default 'FCFA'. Use 'XAF' for the ISO code, '' for none. */
+    label?: string;
+    /** Thousands separator. Default U+202F (narrow no-break space). */
+    separator?: string;
+}
+export interface ToWordsOptions {
+    /** Append "franc(s) CFA". Default true. */
+    currency?: boolean;
+    /** 'traditionnelle' (default) or '1990' (hyphens between all numerals). */
+    orthographe?: 'traditionnelle' | '1990';
+}
+/** money.format(125000) === '125 000 FCFA' (with non-breaking spaces) */
+export declare function format(amount: number, options?: FormatOptions): string;
+/**
+ * Amount in words: toWords(125000) === 'cent vingt-cinq mille francs CFA'.
+ * Specified by fixtures/money/to-words.json. Not implemented yet: see the open issue.
+ */
+export declare function toWords(amount: number, _options?: ToWordsOptions): string;

package/dist/cjs/money.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.format = format;
+exports.toWords = toWords;
+function assertAmount(amount, fn) {
+    if (typeof amount !== 'number' || !Number.isFinite(amount)) {
+        throw new TypeError(`money.${fn} expects a finite number`);
+    }
+    if (!Number.isSafeInteger(amount)) {
+        throw new RangeError(`money.${fn} expects an integer amount: the CFA franc has no subunit`);
+    }
+}
+/** money.format(125000) === '125 000 FCFA' (with non-breaking spaces) */
+function format(amount, options = {}) {
+    assertAmount(amount, 'format');
+    const { label = 'FCFA', separator = ' ' } = options;
+    const sign = amount < 0 ? '-' : '';
+    const grouped = Math.abs(amount).toString().replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+    return label ? `${sign}${grouped} ${label}` : `${sign}${grouped}`;
+}
+/**
+ * Amount in words: toWords(125000) === 'cent vingt-cinq mille francs CFA'.
+ * Specified by fixtures/money/to-words.json. Not implemented yet: see the open issue.
+ */
+function toWords(amount, _options = {}) {
+    assertAmount(amount, 'toWords');
+    throw new Error('money.toWords is not implemented yet. Contributions welcome: see fixtures/money/to-words.json');
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/phone.d.ts

@@ -0,0 +1,21 @@
+import type { PhonePrefix } from './types.js';
+export type InvalidReason = 'empty' | 'invalid_characters' | 'foreign_number' | 'length' | 'unknown_prefix';
+export type FormatStyle = 'national' | 'international' | 'e164';
+export interface ParsedPhone {
+    input: string;
+    valid: boolean;
+    /** +242061234567 */
+    e164: string | null;
+    /** 06 123 45 67 */
+    national: string | null;
+    /** +242 06 123 45 67 */
+    international: string | null;
+    operator: string | null;
+    type: PhonePrefix['type'] | null;
+    reason: InvalidReason | null;
+}
+/** Parses any common way of writing a Congo-Brazzaville number. Never throws on bad numbers, only on non-strings. */
+export declare function parse(input: string): ParsedPhone;
+export declare function isValid(input: string): boolean;
+/** Formats a number in the requested style. Throws if the number is invalid. */
+export declare function format(input: string, style?: FormatStyle): string;

package/dist/cjs/phone.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = parse;
+exports.isValid = isValid;
+exports.format = format;
+const data_js_1 = require("./generated/data.js");
+const SEPARATORS = /[\s().\-/]/g;
+function group(digits) {
+    const sizes = data_js_1.numerotation.nationalGrouping ?? [digits.length];
+    const parts = [];
+    let i = 0;
+    for (const size of sizes) {
+        if (i >= digits.length)
+            break;
+        parts.push(digits.slice(i, i + size));
+        i += size;
+    }
+    if (i < digits.length)
+        parts.push(digits.slice(i));
+    return parts.join(' ');
+}
+function invalid(input, reason) {
+    return { input, valid: false, e164: null, national: null, international: null, operator: null, type: null, reason };
+}
+/** Parses any common way of writing a Congo-Brazzaville number. Never throws on bad numbers, only on non-strings. */
+function parse(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('phone.parse expects a string');
+    const compact = input.replace(SEPARATORS, '');
+    if (compact === '')
+        return invalid(input, 'empty');
+    if (!/^\+?[0-9]+$/.test(compact))
+        return invalid(input, 'invalid_characters');
+    const cc = data_js_1.numerotation.countryCode;
+    const length = data_js_1.numerotation.nationalNumberLength;
+    let national;
+    if (compact.startsWith('+') || compact.startsWith('00')) {
+        const rest = compact.startsWith('+') ? compact.slice(1) : compact.slice(2);
+        if (!rest.startsWith(cc))
+            return invalid(input, 'foreign_number');
+        national = rest.slice(cc.length);
+    }
+    else if (compact.startsWith(cc) && compact.length === cc.length + length) {
+        national = compact.slice(cc.length);
+    }
+    else {
+        national = compact;
+    }
+    if (national.length !== length)
+        return invalid(input, 'length');
+    const prefix = data_js_1.numerotation.prefixes.find((p) => national.startsWith(p.prefix));
+    if (!prefix)
+        return invalid(input, 'unknown_prefix');
+    const grouped = group(national);
+    return {
+        input,
+        valid: true,
+        e164: `+${cc}${national}`,
+        national: grouped,
+        international: `+${cc} ${grouped}`,
+        operator: prefix.operator ?? null,
+        type: prefix.type,
+        reason: null,
+    };
+}
+function isValid(input) {
+    return typeof input === 'string' && parse(input).valid;
+}
+/** Formats a number in the requested style. Throws if the number is invalid. */
+function format(input, style = 'national') {
+    const parsed = parse(input);
+    if (!parsed.valid)
+        throw new Error(`Invalid +242 number (${parsed.reason}): "${input}"`);
+    switch (style) {
+        case 'national':
+            return parsed.national;
+        case 'international':
+            return parsed.international;
+        case 'e164':
+            return parsed.e164;
+        default:
+            throw new Error(`Unknown format style "${String(style)}". Use national, international or e164.`);
+    }
+}

package/dist/cjs/text.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Normalizes free text for comparison: lowercase, no accents,
+ * any run of non-alphanumeric characters becomes a single space.
+ *
+ * normalize('Pointe-Noire') === 'pointe noire'
+ */
+export declare function normalize(input: string): string;

package/dist/cjs/text.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalize = normalize;
+const LIGATURES = { œ: 'oe', Œ: 'OE', æ: 'ae', Æ: 'AE' };
+/**
+ * Normalizes free text for comparison: lowercase, no accents,
+ * any run of non-alphanumeric characters becomes a single space.
+ *
+ * normalize('Pointe-Noire') === 'pointe noire'
+ */
+function normalize(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('text.normalize expects a string');
+    return input
+        .replace(/[œŒæÆ]/g, (c) => LIGATURES[c] ?? c)
+        .normalize('NFD')
+        .replace(/\p{M}/gu, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+}

package/dist/cjs/types.d.ts

@@ -0,0 +1,61 @@
+export interface Verification {
+    status: 'verifie' | 'a_verifier';
+    source?: string;
+    sourceUrl?: string;
+    verifiedAt?: string;
+    verifiedBy?: string;
+    note?: string;
+}
+interface Validity {
+    validFrom?: string;
+    validUntil?: string;
+    replacedBy?: string[];
+}
+export interface Departement extends Validity {
+    id: string;
+    nom: string;
+    iso3166_2?: string;
+    chefLieu?: string;
+    aliases: string[];
+    verification: Verification;
+}
+export interface Commune extends Validity {
+    id: string;
+    nom: string;
+    departement: string;
+    aliases: string[];
+    verification: Verification;
+}
+export interface Arrondissement extends Validity {
+    id: string;
+    nom: string;
+    numero?: number;
+    commune: string;
+    aliases: string[];
+    verification: Verification;
+}
+export interface PhonePrefix {
+    prefix: string;
+    type: 'mobile' | 'fixe' | 'special';
+    operator?: string;
+    mobileMoney?: string;
+    note?: string;
+    verification: Verification;
+}
+export interface DepartementsFile {
+    items: Departement[];
+}
+export interface CommunesFile {
+    items: Commune[];
+}
+export interface ArrondissementsFile {
+    items: Arrondissement[];
+}
+export interface NumerotationFile {
+    countryCode: '242';
+    nationalNumberLength: number;
+    nationalGrouping?: number[];
+    verification: Verification;
+    prefixes: PhonePrefix[];
+}
+export {};

package/dist/cjs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// Shapes of the files in /data. Keep in sync with /data/schema/*.schema.json.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/generated/data.d.ts

@@ -0,0 +1,5 @@
+import type { DepartementsFile, CommunesFile, ArrondissementsFile, NumerotationFile } from '../types.js';
+export declare const arrondissements: ArrondissementsFile;
+export declare const communes: CommunesFile;
+export declare const departements: DepartementsFile;
+export declare const numerotation: NumerotationFile;

package/dist/esm/generated/data.js

@@ -0,0 +1,43 @@
+export const arrondissements = {
+    "items": []
+};
+export const communes = {
+    "items": []
+};
+export const departements = {
+    "items": []
+};
+export const numerotation = {
+    "countryCode": "242",
+    "nationalNumberLength": 9,
+    "nationalGrouping": [
+        2,
+        3,
+        2,
+        2
+    ],
+    "verification": {
+        "status": "a_verifier",
+        "note": "Bootstrap value. To be confirmed against the national numbering plan published by the regulator (issue #2)."
+    },
+    "prefixes": [
+        {
+            "prefix": "06",
+            "type": "mobile",
+            "operator": "MTN",
+            "verification": {
+                "status": "a_verifier",
+                "note": "Bootstrap value, see issue #2."
+            }
+        },
+        {
+            "prefix": "05",
+            "type": "mobile",
+            "operator": "Airtel",
+            "verification": {
+                "status": "a_verifier",
+                "note": "Bootstrap value, see issue #2."
+            }
+        }
+    ]
+};

package/dist/esm/geo.d.ts

@@ -0,0 +1,22 @@
+import type { Arrondissement, Commune, Departement } from './types.js';
+export type Level = 'departement' | 'commune' | 'arrondissement';
+export type GeoMatch = ({
+    level: 'departement';
+} & Departement) | ({
+    level: 'commune';
+} & Commune) | ({
+    level: 'arrondissement';
+} & Arrondissement);
+export declare function departements(): Departement[];
+export declare function communes(departementId?: string): Commune[];
+export declare function arrondissements(communeId?: string): Arrondissement[];
+/** All entries whose official name or alias matches, in order: départements, communes, arrondissements. */
+export declare function findAll(name: string, options?: {
+    level?: Level;
+}): GeoMatch[];
+/** First match (exact, after normalization), or null. Fuzzy matching is planned for v0.3. */
+export declare function find(name: string, options?: {
+    level?: Level;
+}): GeoMatch | null;
+/** Official name for a free-text input, or null if unknown. Handy to clean a data column. */
+export declare function normalizeName(name: string): string | null;

package/dist/esm/geo.js

@@ -0,0 +1,47 @@
+import { departements as depFile, communes as comFile, arrondissements as arrFile } from './generated/data.js';
+import { normalize } from './text.js';
+// Data is plain JSON, so a JSON round-trip is a safe deep copy in every runtime.
+const clone = (value) => JSON.parse(JSON.stringify(value));
+export function departements() {
+    return clone(depFile.items);
+}
+export function communes(departementId) {
+    const items = departementId ? comFile.items.filter((c) => c.departement === departementId) : comFile.items;
+    return clone(items);
+}
+export function arrondissements(communeId) {
+    const items = communeId ? arrFile.items.filter((a) => a.commune === communeId) : arrFile.items;
+    return clone(items);
+}
+function matches(entry, needle) {
+    return [entry.nom, ...entry.aliases].some((n) => normalize(n) === needle);
+}
+/** All entries whose official name or alias matches, in order: départements, communes, arrondissements. */
+export function findAll(name, options = {}) {
+    const needle = normalize(name);
+    if (!needle)
+        return [];
+    const results = [];
+    const want = (level) => !options.level || options.level === level;
+    if (want('departement'))
+        for (const d of depFile.items)
+            if (matches(d, needle))
+                results.push({ level: 'departement', ...clone(d) });
+    if (want('commune'))
+        for (const c of comFile.items)
+            if (matches(c, needle))
+                results.push({ level: 'commune', ...clone(c) });
+    if (want('arrondissement'))
+        for (const a of arrFile.items)
+            if (matches(a, needle))
+                results.push({ level: 'arrondissement', ...clone(a) });
+    return results;
+}
+/** First match (exact, after normalization), or null. Fuzzy matching is planned for v0.3. */
+export function find(name, options = {}) {
+    return findAll(name, options)[0] ?? null;
+}
+/** Official name for a free-text input, or null if unknown. Handy to clean a data column. */
+export function normalizeName(name) {
+    return find(name)?.nom ?? null;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+export * as phone from './phone.js';
+export * as money from './money.js';
+export * as geo from './geo.js';
+export * as text from './text.js';
+export type * from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export * as phone from './phone.js';
+export * as money from './money.js';
+export * as geo from './geo.js';
+export * as text from './text.js';

package/dist/esm/money.d.ts

@@ -0,0 +1,19 @@
+export interface FormatOptions {
+    /** Text after the amount. Default 'FCFA'. Use 'XAF' for the ISO code, '' for none. */
+    label?: string;
+    /** Thousands separator. Default U+202F (narrow no-break space). */
+    separator?: string;
+}
+export interface ToWordsOptions {
+    /** Append "franc(s) CFA". Default true. */
+    currency?: boolean;
+    /** 'traditionnelle' (default) or '1990' (hyphens between all numerals). */
+    orthographe?: 'traditionnelle' | '1990';
+}
+/** money.format(125000) === '125 000 FCFA' (with non-breaking spaces) */
+export declare function format(amount: number, options?: FormatOptions): string;
+/**
+ * Amount in words: toWords(125000) === 'cent vingt-cinq mille francs CFA'.
+ * Specified by fixtures/money/to-words.json. Not implemented yet: see the open issue.
+ */
+export declare function toWords(amount: number, _options?: ToWordsOptions): string;

package/dist/esm/money.js

@@ -0,0 +1,24 @@
+function assertAmount(amount, fn) {
+    if (typeof amount !== 'number' || !Number.isFinite(amount)) {
+        throw new TypeError(`money.${fn} expects a finite number`);
+    }
+    if (!Number.isSafeInteger(amount)) {
+        throw new RangeError(`money.${fn} expects an integer amount: the CFA franc has no subunit`);
+    }
+}
+/** money.format(125000) === '125 000 FCFA' (with non-breaking spaces) */
+export function format(amount, options = {}) {
+    assertAmount(amount, 'format');
+    const { label = 'FCFA', separator = ' ' } = options;
+    const sign = amount < 0 ? '-' : '';
+    const grouped = Math.abs(amount).toString().replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+    return label ? `${sign}${grouped} ${label}` : `${sign}${grouped}`;
+}
+/**
+ * Amount in words: toWords(125000) === 'cent vingt-cinq mille francs CFA'.
+ * Specified by fixtures/money/to-words.json. Not implemented yet: see the open issue.
+ */
+export function toWords(amount, _options = {}) {
+    assertAmount(amount, 'toWords');
+    throw new Error('money.toWords is not implemented yet. Contributions welcome: see fixtures/money/to-words.json');
+}

package/dist/esm/phone.d.ts

@@ -0,0 +1,21 @@
+import type { PhonePrefix } from './types.js';
+export type InvalidReason = 'empty' | 'invalid_characters' | 'foreign_number' | 'length' | 'unknown_prefix';
+export type FormatStyle = 'national' | 'international' | 'e164';
+export interface ParsedPhone {
+    input: string;
+    valid: boolean;
+    /** +242061234567 */
+    e164: string | null;
+    /** 06 123 45 67 */
+    national: string | null;
+    /** +242 06 123 45 67 */
+    international: string | null;
+    operator: string | null;
+    type: PhonePrefix['type'] | null;
+    reason: InvalidReason | null;
+}
+/** Parses any common way of writing a Congo-Brazzaville number. Never throws on bad numbers, only on non-strings. */
+export declare function parse(input: string): ParsedPhone;
+export declare function isValid(input: string): boolean;
+/** Formats a number in the requested style. Throws if the number is invalid. */
+export declare function format(input: string, style?: FormatStyle): string;

package/dist/esm/phone.js

@@ -0,0 +1,79 @@
+import { numerotation as plan } from './generated/data.js';
+const SEPARATORS = /[\s().\-/]/g;
+function group(digits) {
+    const sizes = plan.nationalGrouping ?? [digits.length];
+    const parts = [];
+    let i = 0;
+    for (const size of sizes) {
+        if (i >= digits.length)
+            break;
+        parts.push(digits.slice(i, i + size));
+        i += size;
+    }
+    if (i < digits.length)
+        parts.push(digits.slice(i));
+    return parts.join(' ');
+}
+function invalid(input, reason) {
+    return { input, valid: false, e164: null, national: null, international: null, operator: null, type: null, reason };
+}
+/** Parses any common way of writing a Congo-Brazzaville number. Never throws on bad numbers, only on non-strings. */
+export function parse(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('phone.parse expects a string');
+    const compact = input.replace(SEPARATORS, '');
+    if (compact === '')
+        return invalid(input, 'empty');
+    if (!/^\+?[0-9]+$/.test(compact))
+        return invalid(input, 'invalid_characters');
+    const cc = plan.countryCode;
+    const length = plan.nationalNumberLength;
+    let national;
+    if (compact.startsWith('+') || compact.startsWith('00')) {
+        const rest = compact.startsWith('+') ? compact.slice(1) : compact.slice(2);
+        if (!rest.startsWith(cc))
+            return invalid(input, 'foreign_number');
+        national = rest.slice(cc.length);
+    }
+    else if (compact.startsWith(cc) && compact.length === cc.length + length) {
+        national = compact.slice(cc.length);
+    }
+    else {
+        national = compact;
+    }
+    if (national.length !== length)
+        return invalid(input, 'length');
+    const prefix = plan.prefixes.find((p) => national.startsWith(p.prefix));
+    if (!prefix)
+        return invalid(input, 'unknown_prefix');
+    const grouped = group(national);
+    return {
+        input,
+        valid: true,
+        e164: `+${cc}${national}`,
+        national: grouped,
+        international: `+${cc} ${grouped}`,
+        operator: prefix.operator ?? null,
+        type: prefix.type,
+        reason: null,
+    };
+}
+export function isValid(input) {
+    return typeof input === 'string' && parse(input).valid;
+}
+/** Formats a number in the requested style. Throws if the number is invalid. */
+export function format(input, style = 'national') {
+    const parsed = parse(input);
+    if (!parsed.valid)
+        throw new Error(`Invalid +242 number (${parsed.reason}): "${input}"`);
+    switch (style) {
+        case 'national':
+            return parsed.national;
+        case 'international':
+            return parsed.international;
+        case 'e164':
+            return parsed.e164;
+        default:
+            throw new Error(`Unknown format style "${String(style)}". Use national, international or e164.`);
+    }
+}

package/dist/esm/text.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Normalizes free text for comparison: lowercase, no accents,
+ * any run of non-alphanumeric characters becomes a single space.
+ *
+ * normalize('Pointe-Noire') === 'pointe noire'
+ */
+export declare function normalize(input: string): string;

package/dist/esm/text.js

@@ -0,0 +1,18 @@
+const LIGATURES = { œ: 'oe', Œ: 'OE', æ: 'ae', Æ: 'AE' };
+/**
+ * Normalizes free text for comparison: lowercase, no accents,
+ * any run of non-alphanumeric characters becomes a single space.
+ *
+ * normalize('Pointe-Noire') === 'pointe noire'
+ */
+export function normalize(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('text.normalize expects a string');
+    return input
+        .replace(/[œŒæÆ]/g, (c) => LIGATURES[c] ?? c)
+        .normalize('NFD')
+        .replace(/\p{M}/gu, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,61 @@
+export interface Verification {
+    status: 'verifie' | 'a_verifier';
+    source?: string;
+    sourceUrl?: string;
+    verifiedAt?: string;
+    verifiedBy?: string;
+    note?: string;
+}
+interface Validity {
+    validFrom?: string;
+    validUntil?: string;
+    replacedBy?: string[];
+}
+export interface Departement extends Validity {
+    id: string;
+    nom: string;
+    iso3166_2?: string;
+    chefLieu?: string;
+    aliases: string[];
+    verification: Verification;
+}
+export interface Commune extends Validity {
+    id: string;
+    nom: string;
+    departement: string;
+    aliases: string[];
+    verification: Verification;
+}
+export interface Arrondissement extends Validity {
+    id: string;
+    nom: string;
+    numero?: number;
+    commune: string;
+    aliases: string[];
+    verification: Verification;
+}
+export interface PhonePrefix {
+    prefix: string;
+    type: 'mobile' | 'fixe' | 'special';
+    operator?: string;
+    mobileMoney?: string;
+    note?: string;
+    verification: Verification;
+}
+export interface DepartementsFile {
+    items: Departement[];
+}
+export interface CommunesFile {
+    items: Commune[];
+}
+export interface ArrondissementsFile {
+    items: Arrondissement[];
+}
+export interface NumerotationFile {
+    countryCode: '242';
+    nationalNumberLength: number;
+    nationalGrouping?: number[];
+    verification: Verification;
+    prefixes: PhonePrefix[];
+}
+export {};

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+// Shapes of the files in /data. Keep in sync with /data/schema/*.schema.json.
+export {};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@mboka-dev/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Local data and helpers for Congo-Brazzaville: +242 phone numbers, administrative divisions, FCFA amounts.",
+  "keywords": [
+    "congo",
+    "brazzaville",
+    "cg",
+    "phone",
+    "fcfa",
+    "xaf",
+    "geo",
+    "africa"
+  ],
+  "license": "MIT",
+  "author": "Euloge and contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mboka-dev/core.git",
+    "directory": "packages/js"
+  },
+  "homepage": "https://github.com/mboka-dev/core#readme",
+  "bugs": "https://github.com/mboka-dev/core/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json',JSON.stringify({type:'commonjs'}))\"",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "typescript": "^5.9.3"
+  }
+}