@crewhaus/tool-kyc 0.7.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.
- package/README.md +216 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +821 -0
- package/dist/lib/entity.d.ts +94 -0
- package/dist/lib/entity.js +230 -0
- package/dist/lib/names.d.ts +136 -0
- package/dist/lib/names.js +330 -0
- package/dist/lib/net.d.ts +151 -0
- package/dist/lib/net.js +399 -0
- package/dist/lib/screen.d.ts +186 -0
- package/dist/lib/screen.js +409 -0
- package/dist/lib/vat.d.ts +137 -0
- package/dist/lib/vat.js +388 -0
- package/dist/paths.d.ts +42 -0
- package/dist/paths.js +158 -0
- package/package.json +47 -0
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Company registers: GLEIF and SEC EDGAR, normalized per register and NEVER
|
|
3
|
+
* merged.
|
|
4
|
+
*
|
|
5
|
+
* The temptation is one confident record with one legal name and one status.
|
|
6
|
+
* Two registers describing the same company disagree about all of it — the
|
|
7
|
+
* legal name's suffix and accents, the registration number's format, and above
|
|
8
|
+
* all what "status" means. GLEIF publishes two of them that answer different
|
|
9
|
+
* questions:
|
|
10
|
+
*
|
|
11
|
+
* - `entity.status` — is the company itself still there (ACTIVE / INACTIVE)
|
|
12
|
+
* - `registration.status` — is its LEI paid up (ISSUED / LAPSED / RETIRED /
|
|
13
|
+
* ANNULLED / MERGED / DUPLICATE)
|
|
14
|
+
*
|
|
15
|
+
* A LAPSED registration is overwhelmingly an unpaid renewal fee on a trading
|
|
16
|
+
* company. Folding it into a `dissolved: true` would have a harness refuse to
|
|
17
|
+
* pay a live supplier over a €90 invoice the supplier forgot. So both travel,
|
|
18
|
+
* under their own names, with the register that said them.
|
|
19
|
+
*
|
|
20
|
+
* What this file does instead of merging is make the DIFFERENCES visible: one
|
|
21
|
+
* row per register, each with its own source URL and retrieval time, and a
|
|
22
|
+
* comparison the caller reads.
|
|
23
|
+
*/
|
|
24
|
+
/** The three outcomes, per register. */
|
|
25
|
+
export type RegistryOutcome = "found" | "notFound" | "unavailable";
|
|
26
|
+
export type RegistryRow = {
|
|
27
|
+
readonly registry: "gleif" | "sec-edgar";
|
|
28
|
+
readonly outcome: RegistryOutcome;
|
|
29
|
+
/** The exact document this row was read from. */
|
|
30
|
+
readonly sourceUrl: string;
|
|
31
|
+
readonly retrievedAt: string;
|
|
32
|
+
readonly record?: EntityRecord;
|
|
33
|
+
/** Present on `notFound` and `unavailable`: which, and why. */
|
|
34
|
+
readonly reason?: string;
|
|
35
|
+
readonly retryable?: boolean;
|
|
36
|
+
};
|
|
37
|
+
export type EntityRecord = {
|
|
38
|
+
readonly legalName: string;
|
|
39
|
+
/** Former names, trade names, transliterations — whatever the register carries. */
|
|
40
|
+
readonly otherNames: ReadonlyArray<string>;
|
|
41
|
+
readonly identifiers: Readonly<Record<string, string | ReadonlyArray<string>>>;
|
|
42
|
+
/**
|
|
43
|
+
* Status fields under the register's OWN names. There is no shared
|
|
44
|
+
* `active: boolean` here on purpose: see the header.
|
|
45
|
+
*/
|
|
46
|
+
readonly status: Readonly<Record<string, string>>;
|
|
47
|
+
readonly jurisdiction?: string;
|
|
48
|
+
readonly legalForm?: string;
|
|
49
|
+
readonly address?: string;
|
|
50
|
+
readonly dates: Readonly<Record<string, string>>;
|
|
51
|
+
};
|
|
52
|
+
/** 18 alphanumerics and 2 check digits (ISO 17442). */
|
|
53
|
+
export declare const LEI_PATTERN: RegExp;
|
|
54
|
+
/**
|
|
55
|
+
* ISO 7064 MOD 97-10, the same check IBANs use: letters become two-digit
|
|
56
|
+
* numbers and the whole string modulo 97 must be 1.
|
|
57
|
+
*
|
|
58
|
+
* Worth doing locally because it is exact. A typed LEI with two transposed
|
|
59
|
+
* characters fails here in microseconds instead of coming back from GLEIF as a
|
|
60
|
+
* 404 that reads like "this company has no LEI" — which is a different and
|
|
61
|
+
* much more interesting fact.
|
|
62
|
+
*/
|
|
63
|
+
export declare function leiChecksumValid(lei: string): boolean;
|
|
64
|
+
/**
|
|
65
|
+
* Read one GLEIF `lei-records` record.
|
|
66
|
+
*
|
|
67
|
+
* GLEIF speaks JSON:API, so the useful part is two levels down under
|
|
68
|
+
* `data.attributes`, and a search answers with an ARRAY at `data` while a
|
|
69
|
+
* direct read answers with an object. Both shapes come through here.
|
|
70
|
+
*/
|
|
71
|
+
export declare function normalizeGleif(attributes: unknown): EntityRecord | null;
|
|
72
|
+
/**
|
|
73
|
+
* EDGAR's CIK, zero-padded to ten digits.
|
|
74
|
+
*
|
|
75
|
+
* The submissions path is `CIK##########.json` with the padding and the ticker
|
|
76
|
+
* map publishes the number unpadded, so exactly one of the two has to be
|
|
77
|
+
* converted and it is always this one. `CIK320193.json` is a 404, which would
|
|
78
|
+
* otherwise read as "Apple does not file with the SEC".
|
|
79
|
+
*/
|
|
80
|
+
export declare function padCik(value: string | number): string | null;
|
|
81
|
+
/** Map tickers to padded CIKs from EDGAR's `company_tickers.json`. */
|
|
82
|
+
export declare function tickerIndex(document: unknown): Map<string, {
|
|
83
|
+
cik: string;
|
|
84
|
+
title: string;
|
|
85
|
+
}>;
|
|
86
|
+
/**
|
|
87
|
+
* Read an EDGAR submissions document.
|
|
88
|
+
*
|
|
89
|
+
* `formerNames` is kept rather than dropped: when EDGAR and GLEIF disagree
|
|
90
|
+
* about a company's name, a former name that matches the other register turns
|
|
91
|
+
* "these look like two companies" into "this one was renamed", and that is the
|
|
92
|
+
* difference between a payment held and a payment made.
|
|
93
|
+
*/
|
|
94
|
+
export declare function normalizeEdgar(document: unknown): EntityRecord | null;
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Company registers: GLEIF and SEC EDGAR, normalized per register and NEVER
|
|
3
|
+
* merged.
|
|
4
|
+
*
|
|
5
|
+
* The temptation is one confident record with one legal name and one status.
|
|
6
|
+
* Two registers describing the same company disagree about all of it — the
|
|
7
|
+
* legal name's suffix and accents, the registration number's format, and above
|
|
8
|
+
* all what "status" means. GLEIF publishes two of them that answer different
|
|
9
|
+
* questions:
|
|
10
|
+
*
|
|
11
|
+
* - `entity.status` — is the company itself still there (ACTIVE / INACTIVE)
|
|
12
|
+
* - `registration.status` — is its LEI paid up (ISSUED / LAPSED / RETIRED /
|
|
13
|
+
* ANNULLED / MERGED / DUPLICATE)
|
|
14
|
+
*
|
|
15
|
+
* A LAPSED registration is overwhelmingly an unpaid renewal fee on a trading
|
|
16
|
+
* company. Folding it into a `dissolved: true` would have a harness refuse to
|
|
17
|
+
* pay a live supplier over a €90 invoice the supplier forgot. So both travel,
|
|
18
|
+
* under their own names, with the register that said them.
|
|
19
|
+
*
|
|
20
|
+
* What this file does instead of merging is make the DIFFERENCES visible: one
|
|
21
|
+
* row per register, each with its own source URL and retrieval time, and a
|
|
22
|
+
* comparison the caller reads.
|
|
23
|
+
*/
|
|
24
|
+
// ---------------------------------------------------------------------------
|
|
25
|
+
// LEI
|
|
26
|
+
// ---------------------------------------------------------------------------
|
|
27
|
+
/** 18 alphanumerics and 2 check digits (ISO 17442). */
|
|
28
|
+
export const LEI_PATTERN = /^[A-Z0-9]{18}\d{2}$/;
|
|
29
|
+
/**
|
|
30
|
+
* ISO 7064 MOD 97-10, the same check IBANs use: letters become two-digit
|
|
31
|
+
* numbers and the whole string modulo 97 must be 1.
|
|
32
|
+
*
|
|
33
|
+
* Worth doing locally because it is exact. A typed LEI with two transposed
|
|
34
|
+
* characters fails here in microseconds instead of coming back from GLEIF as a
|
|
35
|
+
* 404 that reads like "this company has no LEI" — which is a different and
|
|
36
|
+
* much more interesting fact.
|
|
37
|
+
*/
|
|
38
|
+
export function leiChecksumValid(lei) {
|
|
39
|
+
const value = lei.toUpperCase();
|
|
40
|
+
if (!LEI_PATTERN.test(value))
|
|
41
|
+
return false;
|
|
42
|
+
let remainder = 0;
|
|
43
|
+
for (const ch of value) {
|
|
44
|
+
const code = ch.charCodeAt(0);
|
|
45
|
+
const piece = code >= 65 ? String(code - 55) : ch;
|
|
46
|
+
for (const digit of piece)
|
|
47
|
+
remainder = (remainder * 10 + Number(digit)) % 97;
|
|
48
|
+
}
|
|
49
|
+
return remainder === 1;
|
|
50
|
+
}
|
|
51
|
+
function str(value) {
|
|
52
|
+
return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
|
|
53
|
+
}
|
|
54
|
+
function joinAddress(node) {
|
|
55
|
+
const a = node;
|
|
56
|
+
if (a === undefined || a === null)
|
|
57
|
+
return undefined;
|
|
58
|
+
const lines = Array.isArray(a["addressLines"])
|
|
59
|
+
? a["addressLines"].map(str).filter((l) => l !== undefined)
|
|
60
|
+
: [str(a["street1"]), str(a["street2"])].filter((l) => l !== undefined);
|
|
61
|
+
const parts = [
|
|
62
|
+
...lines,
|
|
63
|
+
str(a["city"]),
|
|
64
|
+
str(a["region"]) ?? str(a["stateOrCountry"]),
|
|
65
|
+
str(a["postalCode"]) ?? str(a["zipCode"]),
|
|
66
|
+
str(a["country"]),
|
|
67
|
+
].filter((p) => p !== undefined);
|
|
68
|
+
return parts.length === 0 ? undefined : parts.join(", ");
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Read one GLEIF `lei-records` record.
|
|
72
|
+
*
|
|
73
|
+
* GLEIF speaks JSON:API, so the useful part is two levels down under
|
|
74
|
+
* `data.attributes`, and a search answers with an ARRAY at `data` while a
|
|
75
|
+
* direct read answers with an object. Both shapes come through here.
|
|
76
|
+
*/
|
|
77
|
+
export function normalizeGleif(attributes) {
|
|
78
|
+
const attrs = attributes;
|
|
79
|
+
if (attrs === undefined || attrs === null)
|
|
80
|
+
return null;
|
|
81
|
+
const entity = (attrs["entity"] ?? {});
|
|
82
|
+
const registration = (attrs["registration"] ?? {});
|
|
83
|
+
const legalName = str(entity["legalName"]?.["name"]);
|
|
84
|
+
const lei = str(attrs["lei"]);
|
|
85
|
+
if (legalName === undefined && lei === undefined)
|
|
86
|
+
return null;
|
|
87
|
+
const otherNames = [
|
|
88
|
+
...(Array.isArray(entity["otherNames"]) ? entity["otherNames"] : []),
|
|
89
|
+
...(Array.isArray(entity["transliteratedOtherNames"])
|
|
90
|
+
? entity["transliteratedOtherNames"]
|
|
91
|
+
: []),
|
|
92
|
+
]
|
|
93
|
+
.map((n) => str(n?.["name"]))
|
|
94
|
+
.filter((n) => n !== undefined);
|
|
95
|
+
const jurisdiction = str(entity["jurisdiction"]);
|
|
96
|
+
const legalForm = str(entity["legalForm"]?.["id"]);
|
|
97
|
+
const address = joinAddress(entity["legalAddress"]);
|
|
98
|
+
const registeredAs = str(entity["registeredAs"]);
|
|
99
|
+
return {
|
|
100
|
+
legalName: legalName ?? "",
|
|
101
|
+
otherNames,
|
|
102
|
+
identifiers: {
|
|
103
|
+
...(lei === undefined ? {} : { lei }),
|
|
104
|
+
// The company-register number in its OWN jurisdiction's format, which is
|
|
105
|
+
// the id a Companies House or a Handelsregister would be searched by.
|
|
106
|
+
// Formats differ per country; it is echoed, never reformatted.
|
|
107
|
+
...(registeredAs === undefined ? {} : { registeredAs }),
|
|
108
|
+
},
|
|
109
|
+
status: {
|
|
110
|
+
// Both, always. Collapsing these two is the mistake this package is
|
|
111
|
+
// built to avoid.
|
|
112
|
+
...(str(entity["status"]) === undefined ? {} : { entityStatus: String(entity["status"]) }),
|
|
113
|
+
...(str(registration["status"]) === undefined
|
|
114
|
+
? {}
|
|
115
|
+
: { registrationStatus: String(registration["status"]) }),
|
|
116
|
+
...(str(entity["subCategory"]) === undefined
|
|
117
|
+
? {}
|
|
118
|
+
: { subCategory: String(entity["subCategory"]) }),
|
|
119
|
+
},
|
|
120
|
+
...(jurisdiction === undefined ? {} : { jurisdiction }),
|
|
121
|
+
...(legalForm === undefined ? {} : { legalForm }),
|
|
122
|
+
...(address === undefined ? {} : { address }),
|
|
123
|
+
dates: {
|
|
124
|
+
...(str(registration["initialRegistrationDate"]) === undefined
|
|
125
|
+
? {}
|
|
126
|
+
: { leiFirstIssued: String(registration["initialRegistrationDate"]) }),
|
|
127
|
+
...(str(registration["lastUpdateDate"]) === undefined
|
|
128
|
+
? {}
|
|
129
|
+
: { leiLastUpdated: String(registration["lastUpdateDate"]) }),
|
|
130
|
+
...(str(registration["nextRenewalDate"]) === undefined
|
|
131
|
+
? {}
|
|
132
|
+
: { leiNextRenewal: String(registration["nextRenewalDate"]) }),
|
|
133
|
+
},
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
// ---------------------------------------------------------------------------
|
|
137
|
+
// EDGAR
|
|
138
|
+
// ---------------------------------------------------------------------------
|
|
139
|
+
/**
|
|
140
|
+
* EDGAR's CIK, zero-padded to ten digits.
|
|
141
|
+
*
|
|
142
|
+
* The submissions path is `CIK##########.json` with the padding and the ticker
|
|
143
|
+
* map publishes the number unpadded, so exactly one of the two has to be
|
|
144
|
+
* converted and it is always this one. `CIK320193.json` is a 404, which would
|
|
145
|
+
* otherwise read as "Apple does not file with the SEC".
|
|
146
|
+
*/
|
|
147
|
+
export function padCik(value) {
|
|
148
|
+
const digits = String(value).trim().replace(/^CIK/i, "").replace(/^0+/, "");
|
|
149
|
+
if (!/^\d{1,10}$/.test(digits))
|
|
150
|
+
return null;
|
|
151
|
+
return digits.padStart(10, "0");
|
|
152
|
+
}
|
|
153
|
+
/** Map tickers to padded CIKs from EDGAR's `company_tickers.json`. */
|
|
154
|
+
export function tickerIndex(document) {
|
|
155
|
+
const out = new Map();
|
|
156
|
+
const rows = (document ?? {});
|
|
157
|
+
for (const row of Object.values(rows)) {
|
|
158
|
+
const entry = row;
|
|
159
|
+
const ticker = str(entry?.["ticker"]);
|
|
160
|
+
const cik = entry?.["cik_str"];
|
|
161
|
+
if (ticker === undefined || cik === undefined)
|
|
162
|
+
continue;
|
|
163
|
+
const padded = padCik(cik);
|
|
164
|
+
if (padded === null)
|
|
165
|
+
continue;
|
|
166
|
+
// First spelling wins: the file lists one row per ticker per exchange, and
|
|
167
|
+
// a later duplicate is the same company on another venue.
|
|
168
|
+
if (!out.has(ticker.toUpperCase())) {
|
|
169
|
+
out.set(ticker.toUpperCase(), { cik: padded, title: str(entry?.["title"]) ?? "" });
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
return out;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Read an EDGAR submissions document.
|
|
176
|
+
*
|
|
177
|
+
* `formerNames` is kept rather than dropped: when EDGAR and GLEIF disagree
|
|
178
|
+
* about a company's name, a former name that matches the other register turns
|
|
179
|
+
* "these look like two companies" into "this one was renamed", and that is the
|
|
180
|
+
* difference between a payment held and a payment made.
|
|
181
|
+
*/
|
|
182
|
+
export function normalizeEdgar(document) {
|
|
183
|
+
const doc = (document ?? {});
|
|
184
|
+
const name = str(doc["name"]);
|
|
185
|
+
const cik = str(doc["cik"]);
|
|
186
|
+
if (name === undefined && cik === undefined)
|
|
187
|
+
return null;
|
|
188
|
+
const formerNames = (Array.isArray(doc["formerNames"]) ? doc["formerNames"] : [])
|
|
189
|
+
.map((n) => str(n?.["name"]))
|
|
190
|
+
.filter((n) => n !== undefined);
|
|
191
|
+
const tickers = (Array.isArray(doc["tickers"]) ? doc["tickers"] : [])
|
|
192
|
+
.map(str)
|
|
193
|
+
.filter((t) => t !== undefined);
|
|
194
|
+
const addresses = (doc["addresses"] ?? {});
|
|
195
|
+
const address = joinAddress(addresses["business"]) ?? joinAddress(addresses["mailing"]);
|
|
196
|
+
const filings = (doc["filings"] ?? {})["recent"];
|
|
197
|
+
const forms = Array.isArray(filings?.["form"]) ? filings?.["form"] : [];
|
|
198
|
+
const dates = Array.isArray(filings?.["filingDate"])
|
|
199
|
+
? filings?.["filingDate"]
|
|
200
|
+
: [];
|
|
201
|
+
const latestForm = str(forms[0]);
|
|
202
|
+
const latestDate = str(dates[0]);
|
|
203
|
+
const padded = cik === undefined ? null : padCik(cik);
|
|
204
|
+
const jurisdiction = str(doc["stateOfIncorporation"]);
|
|
205
|
+
const legalForm = str(doc["entityType"]);
|
|
206
|
+
return {
|
|
207
|
+
legalName: name ?? "",
|
|
208
|
+
otherNames: formerNames,
|
|
209
|
+
identifiers: {
|
|
210
|
+
...(padded === null ? {} : { cik: padded }),
|
|
211
|
+
...(str(doc["ein"]) === undefined ? {} : { ein: String(doc["ein"]) }),
|
|
212
|
+
...(tickers.length === 0 ? {} : { tickers }),
|
|
213
|
+
},
|
|
214
|
+
status: {
|
|
215
|
+
// EDGAR publishes no "active" flag at all. The nearest honest thing is
|
|
216
|
+
// the most recent filing, which is a SIGNAL about whether anybody is
|
|
217
|
+
// still filing — not a registration status, and labelled so.
|
|
218
|
+
...(latestForm === undefined || latestDate === undefined
|
|
219
|
+
? { filingActivity: "no filings in the document" }
|
|
220
|
+
: { latestFiling: `${latestForm} on ${latestDate}` }),
|
|
221
|
+
...(str(doc["sicDescription"]) === undefined
|
|
222
|
+
? {}
|
|
223
|
+
: { sic: `${str(doc["sic"]) ?? ""} ${String(doc["sicDescription"])}`.trim() }),
|
|
224
|
+
},
|
|
225
|
+
...(jurisdiction === undefined ? {} : { jurisdiction }),
|
|
226
|
+
...(legalForm === undefined ? {} : { legalForm }),
|
|
227
|
+
...(address === undefined ? {} : { address }),
|
|
228
|
+
dates: {},
|
|
229
|
+
};
|
|
230
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
export declare const MAX_HITS_PER_CALL = 100;
|
|
2
|
+
/**
|
|
3
|
+
* Legal forms, stripped from an ORGANISATION's name before comparison.
|
|
4
|
+
*
|
|
5
|
+
* "Acme Ltd" and "ACME LIMITED" are the same company, and a token-weighted
|
|
6
|
+
* score that counts "ltd" as a shared token inflates every comparison between
|
|
7
|
+
* two British companies. Dropped suffixes are recorded rather than discarded,
|
|
8
|
+
* because "which tokens did you actually compare" is half of a match basis.
|
|
9
|
+
*
|
|
10
|
+
* The list is deliberately short and covers the forms that are genuinely
|
|
11
|
+
* interchangeable with nothing. It is NOT applied to people: "Inc" is not a
|
|
12
|
+
* legal form in "Ali Inc." when the subject is a person, and more to the point
|
|
13
|
+
* a person's name can legitimately be any word at all.
|
|
14
|
+
*/
|
|
15
|
+
export declare const LEGAL_SUFFIXES: ReadonlySet<string>;
|
|
16
|
+
export type CanonicalName = {
|
|
17
|
+
/** Exactly what was passed in. */
|
|
18
|
+
readonly input: string;
|
|
19
|
+
/** Folded, punctuation-free, space-collapsed. The string that is compared. */
|
|
20
|
+
readonly canonical: string;
|
|
21
|
+
readonly tokens: ReadonlyArray<string>;
|
|
22
|
+
/** Legal forms removed, in the order they appeared. */
|
|
23
|
+
readonly droppedSuffixes: ReadonlyArray<string>;
|
|
24
|
+
/**
|
|
25
|
+
* True when the input carried zero-width or bidirectional control
|
|
26
|
+
* characters. Those survive copy-paste, break equality silently, and are an
|
|
27
|
+
* obvious way to make a name miss a list it should hit — so their removal is
|
|
28
|
+
* reported rather than done quietly.
|
|
29
|
+
*/
|
|
30
|
+
readonly hadInvisibleCharacters: boolean;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* Canonicalize one name for comparison.
|
|
34
|
+
*
|
|
35
|
+
* Step one is `tool-text`'s `NormalizeText` (NFKC, invisibles stripped,
|
|
36
|
+
* lowercased). Step two is the part it deliberately does not do: folding
|
|
37
|
+
* diacritics. That asymmetry is correct in both places — for a diff, "resume"
|
|
38
|
+
* and "résumé" are two different files and folding them would hide a real
|
|
39
|
+
* change; for a name they are one person, and the sanctions lists themselves
|
|
40
|
+
* publish both spellings.
|
|
41
|
+
*/
|
|
42
|
+
export declare function canonicalizeName(raw: string, options?: {
|
|
43
|
+
readonly dropLegalSuffixes?: boolean;
|
|
44
|
+
}): Promise<CanonicalName>;
|
|
45
|
+
export declare function hasInvisibleCharacters(text: string): boolean;
|
|
46
|
+
export type RankedName = {
|
|
47
|
+
readonly candidate: string;
|
|
48
|
+
readonly score: number;
|
|
49
|
+
readonly index: number;
|
|
50
|
+
};
|
|
51
|
+
export type RankedNames = {
|
|
52
|
+
readonly hits: ReadonlyArray<RankedName>;
|
|
53
|
+
/**
|
|
54
|
+
* True when a chunk came back holding exactly as many hits as `FuzzyMatch`
|
|
55
|
+
* is allowed to return, so there are probably names past the cut this call
|
|
56
|
+
* never saw.
|
|
57
|
+
*
|
|
58
|
+
* It is reported rather than inferred by the caller because the caller
|
|
59
|
+
* cannot infer it. Asking for `limit` hits and counting fewer than `limit`
|
|
60
|
+
* back looks like "nothing was dropped" and is wrong whenever `limit` is
|
|
61
|
+
* over `MAX_HITS_PER_CALL`: the per-call cap bites first, silently, and the
|
|
62
|
+
* caller's own comparison can never be true. A cap that only reports itself
|
|
63
|
+
* when it happens to be under another cap is not a report.
|
|
64
|
+
*/
|
|
65
|
+
readonly capped: boolean;
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* Rank `candidates` against `query` through `tool-text`'s `FuzzyMatch`.
|
|
69
|
+
*
|
|
70
|
+
* Candidates are chunked to the size that tool's own schema permits. The
|
|
71
|
+
* schema is not enforced by `execute`, so nothing would stop a 200 000-name
|
|
72
|
+
* list going through in one call — but a published limit that callers honour
|
|
73
|
+
* only when something checks is not a limit, and chunking costs one extra
|
|
74
|
+
* function call per ten thousand names.
|
|
75
|
+
*/
|
|
76
|
+
export declare function rankNamesCapped(query: string, candidates: ReadonlyArray<string>, minScore: number, limit: number, method?: "jaro" | "trigram" | "levenshtein" | "tokenJaccard"): Promise<RankedNames>;
|
|
77
|
+
/** `rankNamesCapped` for the callers that ask for one hit and cannot truncate. */
|
|
78
|
+
export declare function rankNames(query: string, candidates: ReadonlyArray<string>, minScore: number, limit: number, method?: "jaro" | "trigram" | "levenshtein" | "tokenJaccard"): Promise<RankedName[]>;
|
|
79
|
+
/**
|
|
80
|
+
* Every candidate's score against `query`, in the candidates' own order.
|
|
81
|
+
*
|
|
82
|
+
* Chunked at the HITS cap rather than the candidates cap, so every chunk can
|
|
83
|
+
* return all of itself; asking for more hits than a call may give back is how
|
|
84
|
+
* a "score them all" helper silently returns zeros for the tail.
|
|
85
|
+
*/
|
|
86
|
+
export declare function scoreEach(query: string, candidates: ReadonlyArray<string>, method?: "jaro" | "trigram" | "levenshtein" | "tokenJaccard"): Promise<number[]>;
|
|
87
|
+
/** One token of the subject's name, aligned against its best partner. */
|
|
88
|
+
export type TokenAlignment = {
|
|
89
|
+
readonly subjectToken: string;
|
|
90
|
+
/** The entry token it aligned with, or null when nothing scored high enough. */
|
|
91
|
+
readonly entryToken: string | null;
|
|
92
|
+
readonly score: number;
|
|
93
|
+
/** How much this token counts: rarer across the list means heavier. */
|
|
94
|
+
readonly weight: number;
|
|
95
|
+
};
|
|
96
|
+
/**
|
|
97
|
+
* Below this, two tokens are not the same word. 0.85 on Jaro-Winkler keeps
|
|
98
|
+
* mohamed/mohammed and abdulaziz/abdelaziz together while keeping hassan and
|
|
99
|
+
* hussein apart — which is the pair the naive threshold gets wrong in both
|
|
100
|
+
* directions.
|
|
101
|
+
*/
|
|
102
|
+
export declare const TOKEN_ALIGNMENT_FLOOR = 0.85;
|
|
103
|
+
/**
|
|
104
|
+
* Align each subject token to its best partner in the entry's tokens, and
|
|
105
|
+
* weight the result by how rare each token is across the list.
|
|
106
|
+
*
|
|
107
|
+
* This is the correction to a flat token-set ratio. On a list where half the
|
|
108
|
+
* entries contain "mohammed", matching that token is worth almost nothing and
|
|
109
|
+
* matching a rare surname is worth almost everything; scoring them equally is
|
|
110
|
+
* what floods an operator with false positives on common given names while
|
|
111
|
+
* still missing the transliteration pairs.
|
|
112
|
+
*/
|
|
113
|
+
export declare function alignTokens(subjectTokens: ReadonlyArray<string>, entryTokens: ReadonlyArray<string>, weightOf: (token: string) => number): Promise<{
|
|
114
|
+
alignments: TokenAlignment[];
|
|
115
|
+
score: number;
|
|
116
|
+
}>;
|
|
117
|
+
/** Six places is past any threshold anybody sets and keeps JSON stable. */
|
|
118
|
+
export declare function round6(value: number): number;
|
|
119
|
+
/**
|
|
120
|
+
* Inverse document frequency over the list's own names.
|
|
121
|
+
*
|
|
122
|
+
* Computed from the lists being screened against, never from a fixed table:
|
|
123
|
+
* "bank" is a common token on a Russian-sector list and a rare one on a
|
|
124
|
+
* vessel list, and a weight that does not come from the corpus in front of it
|
|
125
|
+
* is a guess.
|
|
126
|
+
*/
|
|
127
|
+
export declare function buildTokenWeights(documents: ReadonlyArray<ReadonlyArray<string>>): Map<string, number>;
|
|
128
|
+
/**
|
|
129
|
+
* The weight for a token the list has never seen.
|
|
130
|
+
*
|
|
131
|
+
* `log(1 + N/1)` — the weight of a token that appears exactly once — because
|
|
132
|
+
* a subject token absent from the whole list is at least as distinctive as the
|
|
133
|
+
* rarest token in it. Treating it as weightless would let an unmatched rare
|
|
134
|
+
* surname cost nothing.
|
|
135
|
+
*/
|
|
136
|
+
export declare function unseenTokenWeight(documentCount: number): number;
|