korean-bank-detect 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { type Registry, type AccountInstitutionMatchResult, type InstitutionCategory } from './match.js';
+/** The bundled 금결원 CMS registry (26.06.01). */
+export declare const registry: Registry;
+export interface DetectOptions {
+    /**
+     * Max candidates to display (default 3 — the density real apps like Toss
+     * use). Grade-ordered: matched → unknown → contradicted, each rank-ordered.
+     * Raise it (or use Infinity for the full picker list) to see more.
+     */
+    limit?: number;
+    /**
+     * Restrict candidates to these categories — e.g. ['bank'] 은행만,
+     * ['securities'] 증권사만, ['bank', 'non-bank'] 은행+비은행.
+     * Omit (or empty) for 전체. Applied BEFORE shortlisting, so the structural
+     * guarantee and padding operate within the filtered set.
+     */
+    categories?: InstitutionCategory[];
+    /**
+     * HARD filter: only these 대표코드 institutions are eligible (e.g. the banks
+     * your service actually supports for transfers). This is the first, strongest
+     * narrowing lever — recommended over relying on the heuristic priority.
+     */
+    allowedCodes?: string[];
+    /**
+     * HARD filter, inverse: drop these 대표코드 institutions. Useful for syncing
+     * with an existing app's bank list by subtraction (e.g. categories:['bank']
+     * plus a few exclusions) instead of maintaining a full whitelist.
+     * Applied after allowedCodes/categories.
+     */
+    excludeCodes?: string[];
+    /**
+     * Minimum digits before suggestions appear (default 7 — the shortest
+     * documented Korean account length; below it no account can even be complete,
+     * so suggestions would be pure speculation. Real apps like Toss behave the
+     * same). Below the threshold `candidates` is empty. Set 0 to disable.
+     */
+    minDigits?: number;
+    /**
+     * Use a different registry than the bundled one — load the SAME JSON shape
+     * from your DB / remote storage / config service and pass it here. This
+     * decouples DATA updates (금결원 PDF 개정, prefix 추가, 오류 수정) from library
+     * releases: replace the stored JSON, no npm update or redeploy needed.
+     * The bundled registry remains the fallback.
+     */
+    registry?: Registry;
+}
+export declare function detect(account: unknown, options?: DetectOptions): AccountInstitutionMatchResult;
+export type { BranchRule, RegistryInstitution, Registry, CandidateMatch, AccountInstitutionMatchResult, InstitutionCategory, } from './match.js';
+export { matchAccount } from './match.js';

package/dist/index.js

@@ -0,0 +1,92 @@
+/**
+ * korean-bank-detect
+ *
+ * Zero-dependency TypeScript library that identifies the Korean deposit
+ * institution(s) a CMS account number belongs to, using the 금융결제원 CMS
+ * 계좌번호체계 PDF (26.06.01) as the single source of truth.
+ *
+ * Pure data in, pure JSON out. No UI, no score/confidence, no check-digit
+ * computation. Matching is by documented account length plus machine-executable
+ * branch rules (수협 007 ⇄ 030). Partial input is supported (progressive
+ * narrowing); the true institution is never dropped from the candidate set.
+ *
+ * @example
+ * import { detect } from 'korean-bank-detect';
+ * const { candidates } = detect('212123456789');
+ * candidates[0].institutionName; // '수협중앙회'  (routed by branch rule)
+ *
+ * @example  // pass your own registry (e.g. a pinned/older revision)
+ * import { matchAccount } from 'korean-bank-detect';
+ * import registry from 'korean-bank-detect/registry' with { type: 'json' };
+ * matchAccount('110-436-387740', registry);
+ */
+import registryJson from '../data/registry.json' with { type: 'json' };
+import { matchAccount, } from './match.js';
+/** The bundled 금결원 CMS registry (26.06.01). */
+export const registry = registryJson;
+/**
+ * Match against the bundled registry and return a SHORT, pickable candidate list
+ * — the point is "show a few options to pick", not 30.
+ *
+ * Narrowing — evidence-based:
+ *   1. hard filters first: `allowedCodes` (your service's supported banks),
+ *      `categories`, and documented-length compatibility (membership itself).
+ *   2. DETERMINED input — an exact-length strong signal exists (exactStrength
+ *      ≥ 3: 실무 프리픽스 / front 과목코드 / 분기규칙 at exactly this length, which
+ *      also implies the input is a complete documented length) → return the
+ *      'matched' candidates ONLY. A fully-typed 카카오 account is [카카오뱅크],
+ *      not 8 rows. Unknown/contradicted stay reachable via `limit: Infinity`,
+ *      the `grade` field on `matchAccount`, or your own full bank picker.
+ *   3. NOT determined (typing in progress, or only weak shared codes) → the
+ *      matched candidates plus a display budget (`limit` − matched) filled by
+ *      rank with 'unknown' first (no signal capability — no information),
+ *      then 'contradicted' (codes at this length, none matched — demoted last,
+ *      never silently unreachable).
+ *
+ * Ranking within the list is matchAccount's: strength (incl. progressive
+ * prefix boosts) → evidence count → priority → 가나다. Note `priority` is a
+ * HEURISTIC display order (no official popularity source exists) — for real
+ * products, re-rank ties with your own verification stats and confirm via a
+ * 예금주조회 API before money moves. Never auto-trust candidates[0]; treat
+ * `exactStrength >= 3` as the minimum bar for even suggesting auto-selection.
+ *
+ * `limit: Infinity` → the full ranked pool (picker UX; 전체/탭 화면용).
+ * For the raw unfiltered list use `matchAccount(account, registry)`.
+ */
+const STRONG = 3;
+export function detect(account, options = {}) {
+    const limit = options.limit ?? 3;
+    const minDigits = options.minDigits ?? 7;
+    const full = matchAccount(account, options.registry ?? registry);
+    const digitCount = typeof account === 'string' ? account.replace(/[-\s]/g, '').length : 0;
+    if (digitCount < minDigits)
+        return { ...full, candidates: [] };
+    let pool = full.candidates;
+    if (options.allowedCodes && options.allowedCodes.length > 0) {
+        const allowed = new Set(options.allowedCodes);
+        pool = pool.filter((c) => allowed.has(c.institutionCode));
+    }
+    if (options.categories && options.categories.length > 0) {
+        pool = pool.filter((c) => options.categories.includes(c.category));
+    }
+    if (options.excludeCodes && options.excludeCodes.length > 0) {
+        const excluded = new Set(options.excludeCodes);
+        pool = pool.filter((c) => !excluded.has(c.institutionCode));
+    }
+    if (limit === Infinity)
+        return { ...full, candidates: pool };
+    const determined = pool.some((c) => c.exactStrength >= STRONG);
+    if (determined) {
+        // complete input with an exact strong signal → matched only (top `limit`)
+        return { ...full, candidates: pool.filter((c) => c.grade === 'matched').slice(0, limit) };
+    }
+    // grade-ordered display: matched → unknown → contradicted (rank order within
+    // each grade), capped at `limit` — the Toss-style top-N suggestion density
+    const ordered = [
+        ...pool.filter((c) => c.grade === 'matched'),
+        ...pool.filter((c) => c.grade === 'unknown'),
+        ...pool.filter((c) => c.grade === 'contradicted'),
+    ];
+    return { ...full, candidates: ordered.slice(0, limit) };
+}
+export { matchAccount } from './match.js';

package/dist/match.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Matching engine for Korean CMS account numbers.
+ *
+ * Accepts a raw account-number string (may be partial, hyphenated, or malformed)
+ * and the institution registry, and returns candidate deposit institutions each
+ * with a document-sourced matching-evidence array.
+ *
+ * Guarantees (per seed contract):
+ * - Never throws on any input value.
+ * - Empty candidates + isComplete=false for malformed/empty/non-digit/oversized
+ *   strings and non-string values.
+ * - Document-based recall: an institution stays a candidate at every prefix until
+ *   its documented lengths become unreachable (candidate set only shrinks).
+ * - Machine-executable definitive routing for document-declared branch rules
+ *   (수협 007 ⇄ 030): once the deciding digits are present, the candidate is
+ *   routed to the target institution.
+ * - No score/confidence fields. Deterministic sort: matched-count desc → name 가나다순.
+ * - Only internal normalization: strip hyphens/whitespace before matching.
+ */
+/** A digit-value branch rule: routes one 대표코드 to another by examined digits. */
+export interface BranchRule {
+    /** the length-pattern this rule applies to */
+    length: number;
+    /** 0-indexed start of the examined digit window */
+    position: number;
+    /** number of digits examined */
+    matchLength: number;
+    /** exact values and/or inclusive {from,to} ranges that trigger routing */
+    match: Array<number | {
+        from: number;
+        to: number;
+    }>;
+    /** institution code routed TO when the digits match */
+    targetCode: string;
+    /** institution name routed TO when the digits match */
+    targetName: string;
+    /** verbatim PDF sentence declaring the rule */
+    sourceQuote: string;
+}
+/** 계정과목코드 spec: subject code sits at [position, position+codeLength) for this length. */
+export interface SubjectCodeSpec {
+    length: number;
+    position: number;
+    codeLength: number;
+    codes: string[];
+    /**
+     * true for PRACTICAL prefixes (실무 관측 데이터, e.g. 카카오 3333) — sourced
+     * outside the PDF and reported with a '프리픽스' evidence token instead of '과목코드'.
+     */
+    practical?: boolean;
+    /**
+     * true when the PDF marks this pattern as a 가상계좌 (virtual/deposit-shell
+     * account, e.g. 아이엠 14d 937/938/999 모임통장용). A virtual-code match is a
+     * weaker prior for user-typed transfer targets, so its ranking strength is
+     * HALVED — the candidate stays matched and listed, just below real-account
+     * matches (국민 938... 실계좌 vs 아이엠 938 가상계좌 충돌의 원칙적 해소).
+     */
+    virtual?: boolean;
+}
+/**
+ * Institution category:
+ * 'bank' 은행 · 'non-bank' 비은행(중앙회·금고·우체국·저축은행) ·
+ * 'securities' 증권사 · 'clearing' 결제기관(금융결제원) ·
+ * 'foreign-branch' 외은지점(HSBC·도이치·JP모간·BOA·BNP — 개인 리테일 없음)
+ */
+export type InstitutionCategory = 'bank' | 'non-bank' | 'securities' | 'clearing' | 'foreign-branch';
+export interface RegistryInstitution {
+    representativeCode: string;
+    name: string;
+    category: InstitutionCategory;
+    allCodes: string[];
+    accountLengths: number[];
+    /** static PDF-transcribed flag; NEVER computed from an account number */
+    checkDigitDeclared: boolean | null;
+    branchRules: BranchRule[];
+    /** subject-code specs for evidence-based narrowing (may be absent for some institutions) */
+    subjectCodes?: SubjectCodeSpec[];
+    /** tie-break only: major banks outrank minor ones at equal match strength */
+    priority?: number;
+    logo: string;
+}
+export interface Registry {
+    generatedFrom: string;
+    sourceSha256: string | null;
+    institutions: RegistryInstitution[];
+}
+export interface CandidateMatch {
+    /** 3-digit 대표코드 (the target code when routed by a branch rule) */
+    institutionCode: string;
+    /** official 기관명 (the target name when routed by a branch rule) */
+    institutionName: string;
+    /** institution category: bank · non-bank · securities · clearing */
+    category: InstitutionCategory;
+    /** documented full account lengths for the institution */
+    accountLengths: number[];
+    /** evidence tokens satisfied for this input, e.g. '자릿수', '과목코드', '분기규칙' */
+    matched: string[];
+    /**
+     * Structural match strength: digits of subject-code evidence that matched
+     * (3 = near-unique front code, 2/1 = shared, 0 = length only). Higher ranks
+     * first. Branch-routed candidates get a high strength so they lead.
+     * Includes PROSPECTIVE front matches (a longer pattern's prefix fired while
+     * typing) — use for ranking only.
+     */
+    strength: number;
+    /**
+     * Strength from EXACT-length signals only (spec.length === input length, or a
+     * fired branch rule). A 14-digit prefix firing on a 13-digit input contributes
+     * to `strength` (ranking) but NOT here — so a possibly-complete shorter input
+     * is never treated as "determined" by a longer pattern's signal.
+     */
+    exactStrength: number;
+    /**
+     * Whether this institution COULD have signaled at this exact length (has a
+     * subject-code/prefix spec of this length, or a branch rule). If true and it
+     * didn't match, that is evidence AGAINST it; if false, absence of a match is
+     * no information — such institutions must not be evicted by others' matches.
+     */
+    signalCapableAtLength: boolean;
+    /**
+     * Evidence grade — the narrowing policy in one word:
+     *   'matched'      its signal fits these digits (kept, ranked first)
+     *   'unknown'      no signal capability at this length (no information)
+     *   'contradicted' had codes at this length, none matched (demoted LAST, not
+     *                  dropped — code sets can't be proven exhaustive, 입금전용/신탁
+     *                  codes sprawl into the PDF's 비고 column)
+     */
+    grade: 'matched' | 'unknown' | 'contradicted';
+    /** static PDF-transcribed flag; false where the PDF declares no check-digit verify */
+    checkDigitDeclared: boolean | null;
+    /** true when a document-declared branch rule definitively selected this institution */
+    routedByBranchRule: boolean;
+    /**
+     * true when the institution declares a branch rule for exactly this input
+     * length (수협 11/12/14d). Even when the deciding digits didn't fire the rule,
+     * the PDF's "이외의 경우 007 SET" else-branch means this institution remains a
+     * documented possibility for this length — shortlists must not drop it.
+     */
+    branchRuleAtLength: boolean;
+    /** institution priority (tie-break signal; higher = more common) */
+    priority: number;
+    /** institution logo/icon URL, empty string for now */
+    logo: string;
+}
+export interface AccountInstitutionMatchResult {
+    /** raw account number as provided */
+    input: string;
+    /** true when the normalized input length is a documented full length of some candidate */
+    isComplete: boolean;
+    /**
+     * Deterministically ordered candidate institutions.
+     * Sort: matched.length desc, then institutionName 가나다순.
+     * Empty for malformed / non-string / oversized input.
+     */
+    candidates: CandidateMatch[];
+}
+/**
+ * Match a raw account-number string against the institution registry.
+ * @returns AccountInstitutionMatchResult — never throws.
+ */
+export declare function matchAccount(raw: unknown, registry: Registry): AccountInstitutionMatchResult;

package/dist/match.js

@@ -0,0 +1,172 @@
+/**
+ * Matching engine for Korean CMS account numbers.
+ *
+ * Accepts a raw account-number string (may be partial, hyphenated, or malformed)
+ * and the institution registry, and returns candidate deposit institutions each
+ * with a document-sourced matching-evidence array.
+ *
+ * Guarantees (per seed contract):
+ * - Never throws on any input value.
+ * - Empty candidates + isComplete=false for malformed/empty/non-digit/oversized
+ *   strings and non-string values.
+ * - Document-based recall: an institution stays a candidate at every prefix until
+ *   its documented lengths become unreachable (candidate set only shrinks).
+ * - Machine-executable definitive routing for document-declared branch rules
+ *   (수협 007 ⇄ 030): once the deciding digits are present, the candidate is
+ *   routed to the target institution.
+ * - No score/confidence fields. Deterministic sort: matched-count desc → name 가나다순.
+ * - Only internal normalization: strip hyphens/whitespace before matching.
+ */
+/** Strip hyphens/whitespace; null if empty or non-digit. */
+function normalizeDigits(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const s = raw.replace(/[-\s]/g, '');
+    if (s.length === 0 || !/^\d+$/.test(s))
+        return null;
+    return s;
+}
+/** Does the examined digit window satisfy any of the rule's values/ranges? */
+function branchMatches(digits, rule) {
+    const window = digits.slice(rule.position, rule.position + rule.matchLength);
+    if (window.length < rule.matchLength)
+        return false; // deciding digits not present yet
+    const v = Number(window);
+    if (Number.isNaN(v))
+        return false;
+    for (const m of rule.match) {
+        if (typeof m === 'number') {
+            if (v === m)
+                return true;
+        }
+        else if (v >= m.from && v <= m.to) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Match a raw account-number string against the institution registry.
+ * @returns AccountInstitutionMatchResult — never throws.
+ */
+export function matchAccount(raw, registry) {
+    const inputStr = typeof raw === 'string' ? raw : '';
+    const normalized = normalizeDigits(raw);
+    if (normalized === null)
+        return { input: inputStr, isComplete: false, candidates: [] };
+    const len = normalized.length;
+    const candidates = [];
+    for (const inst of registry.institutions) {
+        // candidate if some documented length is still reachable from the current input
+        if (!inst.accountLengths.some((l) => l >= len))
+            continue;
+        // '기관코드' = identity evidence; '자릿수' = a documented length is still reachable
+        const matched = ['기관코드', '자릿수'];
+        // Subject-code / prefix evidence. Two firing modes:
+        //   • front specs (position 0): PROGRESSIVE — fire as soon as the prefix
+        //     digits are typed, while the pattern length is still reachable
+        //     (spec.length >= len). This is how real apps surface 카카오 at "3333…".
+        //   • middle/end specs: fire only at the exact full pattern length (their
+        //     position is meaningless until the number is complete).
+        // strength = codeLength (+0.5 front bonus) — a 3/4-digit front code is
+        // near-unique to one institution; shared 2/1-digit codes are weaker.
+        // Evidence only — never drops a candidate (recall stays intact).
+        let strength = 0;
+        let exactStrength = 0;
+        let signalCapableAtLength = false;
+        let evidenceToken = null;
+        for (const spec of inst.subjectCodes ?? []) {
+            if (spec.length === len)
+                signalCapableAtLength = true;
+            const end = spec.position + spec.codeLength;
+            if (spec.position === 0) {
+                if (spec.length < len || normalized.length < end)
+                    continue; // unreachable or digits missing
+            }
+            else {
+                if (spec.length !== len || normalized.length < end)
+                    continue;
+            }
+            const code = normalized.slice(spec.position, end);
+            if (spec.codes.includes(code)) {
+                let s = spec.codeLength + (spec.position === 0 ? 0.5 : 0);
+                // 가상계좌 코드는 순위 강도 절반 — 실계좌 매칭(국민 02 등)보다 아래로,
+                // 단 matched 등급과 리스트 잔류는 유지 (가상계좌도 유효한 이체 대상)
+                if (spec.virtual)
+                    s *= 0.5;
+                if (s > strength) {
+                    strength = s;
+                    evidenceToken = spec.practical ? '프리픽스' : spec.virtual ? '가상계좌코드' : '과목코드';
+                }
+                // exact-length signals only — a longer pattern's prefix firing on a
+                // shorter (possibly complete) input must not count as determination
+                if (spec.length === len && s > exactStrength)
+                    exactStrength = s;
+            }
+        }
+        if (evidenceToken)
+            matched.push(evidenceToken);
+        // Branch routing: if a rule applies to the current length and its deciding
+        // digits are present and match, route the candidate to the target institution.
+        let institutionCode = inst.representativeCode;
+        let institutionName = inst.name;
+        let category = inst.category ?? 'bank';
+        let routedByBranchRule = false;
+        let branchRuleAtLength = false;
+        for (const rule of inst.branchRules) {
+            if (rule.length !== len)
+                continue;
+            branchRuleAtLength = true;
+            if (branchMatches(normalized, rule)) {
+                institutionCode = rule.targetCode;
+                institutionName = rule.targetName;
+                // the candidate now IS the target institution — carry its category
+                // (수협중앙회 is non-bank while 수협은행 is bank)
+                category =
+                    registry.institutions.find((t) => t.representativeCode === rule.targetCode)
+                        ?.category ?? category;
+                routedByBranchRule = true;
+                matched.push('분기규칙');
+                // a definitive document rule is the strongest possible structural signal
+                // (branch rules only fire at their exact length, so exactStrength too)
+                strength = Math.max(strength, 4);
+                exactStrength = Math.max(exactStrength, 4);
+            }
+            // rule exists for this length but digits don't match → stays source institution
+        }
+        candidates.push({
+            institutionCode,
+            institutionName,
+            category,
+            accountLengths: inst.accountLengths,
+            matched,
+            strength,
+            exactStrength,
+            signalCapableAtLength: signalCapableAtLength || branchRuleAtLength,
+            grade: strength > 0 || branchRuleAtLength
+                ? 'matched'
+                : signalCapableAtLength
+                    ? 'contradicted'
+                    : 'unknown',
+            checkDigitDeclared: inst.checkDigitDeclared,
+            routedByBranchRule,
+            branchRuleAtLength,
+            priority: typeof inst.priority === 'number' ? inst.priority : 0,
+            logo: typeof inst.logo === 'string' ? inst.logo : '',
+        });
+    }
+    // Sort: match strength desc (branch rule > front 3-digit code > 2/1-digit code
+    // > length only) → matched-count desc → priority desc (major banks first at a
+    // tie) → institutionName 가나다순.
+    candidates.sort((a, b) => {
+        if (b.strength !== a.strength)
+            return b.strength - a.strength;
+        if (b.matched.length !== a.matched.length)
+            return b.matched.length - a.matched.length;
+        if (b.priority !== a.priority)
+            return b.priority - a.priority;
+        return a.institutionName.localeCompare(b.institutionName, 'ko');
+    });
+    const isComplete = candidates.some((c) => c.accountLengths.includes(len));
+    return { input: inputStr, isComplete, candidates };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "korean-bank-detect",
+  "version": "0.1.0",
+  "description": "Korean bank account number detection via 금결원 CMS 계좌번호체계",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./registry": "./data/registry.json"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "node scripts/build-registry.mjs && tsc",
+    "generate": "node scripts/build-registry.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "korean-account": "^0.1.2",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "allowScripts": {
+    "esbuild@0.21.5": true,
+    "fsevents@2.3.3": true
+  },
+  "files": [
+    "dist",
+    "data/registry.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "korean",
+    "bank",
+    "account",
+    "계좌번호",
+    "은행",
+    "금융결제원",
+    "cms",
+    "fintech"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LESANF/korean-bank-detect.git"
+  },
+  "homepage": "https://github.com/LESANF/korean-bank-detect#readme",
+  "bugs": {
+    "url": "https://github.com/LESANF/korean-bank-detect/issues"
+  },
+  "author": "LESANF",
+  "sideEffects": false
+}