@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.
@@ -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;