swedish-pii 1.2.0

package/dist/index.d.cts

@@ -0,0 +1,163 @@
+/** All PII labels this library can detect. */
+type PiiLabel = "PER_FIRST" | "PER_LAST" | "AMEX_CREDIT_CARD" | "MASTERCARD_CREDIT_CARD" | "VISA_CREDIT_CARD" | "IBAN_CODE" | "BIC_CODE" | "SE_BANK_NUMBER" | "SE_BANKGIRO" | "SE_PLUSGIRO" | "SE_VAT_NUMBER" | "CRYPTO_WALLET" | "SE_PERSONAL_IDENTITY_NUMBER_MALE" | "SE_PERSONAL_IDENTITY_NUMBER_FEMALE" | "SE_COORDINATION_NUMBER_MALE" | "SE_COORDINATION_NUMBER_FEMALE" | "SE_PASSPORT_NUMBER" | "EMAIL_ADDRESS" | "PHONE_NUMBER" | "SOCIAL_MEDIA" | "SE_STREET_ADDRESS" | "SE_POSTAL_CODE" | "SE_MUNICIPALITY" | "SE_COUNTY" | "SE_CITY" | "SE_PROPERTY_DESIGNATION" | "COORDINATE" | "SE_WORK_ORGANIZATION" | "SE_EDUCATION_ORGANIZATION" | "SE_EDUCATION_PROGRAM" | "SE_WORK_PROFESSION" | "SE_ORGANIZATION_NUMBER" | "MARITAL_STATUS" | "GENETIC_SEX" | "DISABILITY" | "RELIGION" | "SEXUAL_ORIENTATION" | "DEMOGRAPHIC" | "POLITICAL_IDEOLOGIES" | "SE_LABOR_UNION" | "SE_LICENSE_PLATE" | "IP_ADDRESS" | "MAC_ADDRESS" | "DATE" | "TIME" | "SE_CASE_NUMBER" | "AGE";
+/** A single detected PII entity, anchored to the original text. */
+interface PiiEntity {
+    /** Unique id within one detection run, e.g. `PHONE_NUMBER_1`. */
+    id: string;
+    label: PiiLabel;
+    /** The matched text exactly as it appears in the input. */
+    value: string;
+    /** Start offset (inclusive) in the original text. */
+    start: number;
+    /** End offset (exclusive) in the original text. */
+    end: number;
+    /**
+     * Confidence in (0, 1]. Checksum-validated matches score ~0.95,
+     * exact gazetteer hits ~0.85–0.9, plain pattern shapes ~0.6, matches
+     * that failed a checksum ~0.45, and context-starved shapes ~0.25
+     * (below the default threshold).
+     */
+    score: number;
+}
+/** An entity candidate produced by a detector, before ids are assigned. */
+type EntitySpan = Omit<PiiEntity, "id">;
+interface DetectOptions {
+    /**
+     * When true, matches that carry a checksum (credit cards, personal
+     * identity numbers, organization numbers, IBANs) must pass validation,
+     * and date-based numbers must encode a real calendar date.
+     * Defaults to false so that synthetic/example data is still masked.
+     */
+    strict?: boolean;
+    /**
+     * Entities scoring below this are dropped. Defaults to
+     * DEFAULT_SCORE_THRESHOLD (0.4): checksum failures (0.45) survive,
+     * context-starved shapes (0.25) do not. Lower it to catch e.g. bank
+     * account numbers in bare CSV columns with no surrounding words;
+     * raise it to keep only high-confidence entities.
+     * Must be a finite number from 0 through 1; other values throw a
+     * RangeError.
+     */
+    scoreThreshold?: number;
+}
+/** A detector produces entity spans for one or more labels. */
+interface Detector {
+    /** The label(s) this detector can emit — used for documentation/tooling. */
+    labels: readonly PiiLabel[];
+    detect(text: string, options: Required<DetectOptions>): EntitySpan[];
+}
+interface MaskedValue {
+    id: string;
+    value: string;
+}
+/** Detected values grouped per label, in order of appearance. */
+type MaskedData = Partial<Record<PiiLabel, MaskedValue[]>>;
+interface MaskResult {
+    /** Input text with every detected entity replaced by `<LABEL_n>`. */
+    maskedText: string;
+    /** Detected values grouped per label. */
+    maskedData: MaskedData;
+    /** Flat list of detected entities with offsets into the original text. */
+    entities: PiiEntity[];
+}
+
+/**
+ * Detectors in priority order: when two detectors match overlapping
+ * text, the one listed first wins. Names run first, then patterns from
+ * most to least specific — in particular, the generic Swedish bank
+ * account number (10–11 digits) runs after personnummer, organization
+ * numbers, cards and phone numbers, all of which it would otherwise
+ * shadow.
+ */
+declare const detectors: Detector[];
+/**
+ * Run all detectors in priority order. Each detector sees the input
+ * with higher-priority matches blanked out (never with placeholder text,
+ * so placeholders can't be re-matched or corrupted). Blanking — rather
+ * than dropping overlapping candidates outright — lets a lower-priority
+ * detector still match the uncovered remainder: in "Lilla Vägen 7",
+ * where "Lilla" is a registered first name, the street detector can
+ * still mask "Vägen 7".
+ *
+ * Every candidate carries a confidence score; candidates below
+ * `scoreThreshold` are discarded before overlap resolution.
+ */
+declare function detectPII(text: string, options?: DetectOptions): PiiEntity[];
+/**
+ * Mask every detected entity in `text`, replacing it with `<LABEL_n>`.
+ * The returned `maskedData` maps each label to its values in order of
+ * appearance, and `entities` carries exact offsets into the input.
+ */
+declare function maskPII(text: string, options?: DetectOptions): MaskResult;
+
+/**
+ * Match a "First Last" string against the name lists. Returns the
+ * canonical matched names, or null when either part misses.
+ */
+declare function matchFullName(fullName: string): {
+    first: string;
+    last: string;
+} | null;
+
+/**
+ * Luhn (mod 10) checksum, used by payment card numbers, Swedish personal
+ * identity numbers (personnummer), coordination numbers and organization
+ * numbers.
+ */
+declare function luhnCheck(digits: string): boolean;
+/**
+ * Validate the checksum of a Swedish personnummer / samordningsnummer /
+ * organisationsnummer. The Luhn sum is always computed over the final
+ * 10 digits (century digits are excluded).
+ */
+declare function swedishIdChecksum(value: string): boolean;
+
+/**
+ * IBAN mod-97 checksum (ISO 13616): move the first four characters to
+ * the end, convert letters to numbers (A=10 … Z=35), and the whole
+ * number must be ≡ 1 (mod 97). Computed digit-by-digit to stay within
+ * safe integer range regardless of IBAN length.
+ */
+declare function ibanChecksum(iban: string): boolean;
+
+/**
+ * True when year/month/day form a real calendar date (leap years included).
+ * Month and day are 1-based.
+ */
+declare function isRealDate(year: number, month: number, day: number): boolean;
+/**
+ * Validate the date part of a Swedish identity number.
+ *
+ * @param digits - The identity number's digits (10 or 12, separators removed).
+ * @param dayOffset - 60 for samordningsnummer (day is stored as day + 60).
+ */
+declare function isValidIdentityDate(digits: string, dayOffset?: number): boolean;
+
+declare function jaroWinkler(s1: string, s2: string): number;
+
+/**
+ * Confidence levels, Presidio-style: recognizers report how sure they
+ * are, callers filter with `scoreThreshold`.
+ */
+declare const SCORE: {
+    /** Checksum (Luhn / mod-97) or calendar validation passed. */
+    readonly VALIDATED: 0.95;
+    /** Exact hit in a curated gazetteer (streets, municipalities). */
+    readonly EXACT_MATCH: 0.9;
+    /** Fuzzy full-name match or context-corroborated shape. */
+    readonly CONTEXT: 0.85;
+    /** Exact single-word lookup in a large list (names). */
+    readonly LOOKUP: 0.55;
+    /** A plain pattern/term match with no further evidence. */
+    readonly PATTERN: 0.6;
+    /** Heuristic shape (capitalized words + street suffix). */
+    readonly HEURISTIC: 0.5;
+    /** Shape matched but its checksum failed. */
+    readonly FAILED_VALIDATION: 0.45;
+    /** Shape matched but the expected nearby context is missing. */
+    readonly NO_CONTEXT: 0.25;
+};
+/** Entities scoring below this are dropped unless the caller opts in. */
+declare const DEFAULT_SCORE_THRESHOLD = 0.4;
+
+export { DEFAULT_SCORE_THRESHOLD, type DetectOptions, type Detector, type EntitySpan, type MaskResult, type MaskedData, type MaskedValue, type PiiEntity, type PiiLabel, SCORE, detectPII, detectors, ibanChecksum, isRealDate, isValidIdentityDate, jaroWinkler, luhnCheck, maskPII, matchFullName, swedishIdChecksum };

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+/** All PII labels this library can detect. */
+type PiiLabel = "PER_FIRST" | "PER_LAST" | "AMEX_CREDIT_CARD" | "MASTERCARD_CREDIT_CARD" | "VISA_CREDIT_CARD" | "IBAN_CODE" | "BIC_CODE" | "SE_BANK_NUMBER" | "SE_BANKGIRO" | "SE_PLUSGIRO" | "SE_VAT_NUMBER" | "CRYPTO_WALLET" | "SE_PERSONAL_IDENTITY_NUMBER_MALE" | "SE_PERSONAL_IDENTITY_NUMBER_FEMALE" | "SE_COORDINATION_NUMBER_MALE" | "SE_COORDINATION_NUMBER_FEMALE" | "SE_PASSPORT_NUMBER" | "EMAIL_ADDRESS" | "PHONE_NUMBER" | "SOCIAL_MEDIA" | "SE_STREET_ADDRESS" | "SE_POSTAL_CODE" | "SE_MUNICIPALITY" | "SE_COUNTY" | "SE_CITY" | "SE_PROPERTY_DESIGNATION" | "COORDINATE" | "SE_WORK_ORGANIZATION" | "SE_EDUCATION_ORGANIZATION" | "SE_EDUCATION_PROGRAM" | "SE_WORK_PROFESSION" | "SE_ORGANIZATION_NUMBER" | "MARITAL_STATUS" | "GENETIC_SEX" | "DISABILITY" | "RELIGION" | "SEXUAL_ORIENTATION" | "DEMOGRAPHIC" | "POLITICAL_IDEOLOGIES" | "SE_LABOR_UNION" | "SE_LICENSE_PLATE" | "IP_ADDRESS" | "MAC_ADDRESS" | "DATE" | "TIME" | "SE_CASE_NUMBER" | "AGE";
+/** A single detected PII entity, anchored to the original text. */
+interface PiiEntity {
+    /** Unique id within one detection run, e.g. `PHONE_NUMBER_1`. */
+    id: string;
+    label: PiiLabel;
+    /** The matched text exactly as it appears in the input. */
+    value: string;
+    /** Start offset (inclusive) in the original text. */
+    start: number;
+    /** End offset (exclusive) in the original text. */
+    end: number;
+    /**
+     * Confidence in (0, 1]. Checksum-validated matches score ~0.95,
+     * exact gazetteer hits ~0.85–0.9, plain pattern shapes ~0.6, matches
+     * that failed a checksum ~0.45, and context-starved shapes ~0.25
+     * (below the default threshold).
+     */
+    score: number;
+}
+/** An entity candidate produced by a detector, before ids are assigned. */
+type EntitySpan = Omit<PiiEntity, "id">;
+interface DetectOptions {
+    /**
+     * When true, matches that carry a checksum (credit cards, personal
+     * identity numbers, organization numbers, IBANs) must pass validation,
+     * and date-based numbers must encode a real calendar date.
+     * Defaults to false so that synthetic/example data is still masked.
+     */
+    strict?: boolean;
+    /**
+     * Entities scoring below this are dropped. Defaults to
+     * DEFAULT_SCORE_THRESHOLD (0.4): checksum failures (0.45) survive,
+     * context-starved shapes (0.25) do not. Lower it to catch e.g. bank
+     * account numbers in bare CSV columns with no surrounding words;
+     * raise it to keep only high-confidence entities.
+     * Must be a finite number from 0 through 1; other values throw a
+     * RangeError.
+     */
+    scoreThreshold?: number;
+}
+/** A detector produces entity spans for one or more labels. */
+interface Detector {
+    /** The label(s) this detector can emit — used for documentation/tooling. */
+    labels: readonly PiiLabel[];
+    detect(text: string, options: Required<DetectOptions>): EntitySpan[];
+}
+interface MaskedValue {
+    id: string;
+    value: string;
+}
+/** Detected values grouped per label, in order of appearance. */
+type MaskedData = Partial<Record<PiiLabel, MaskedValue[]>>;
+interface MaskResult {
+    /** Input text with every detected entity replaced by `<LABEL_n>`. */
+    maskedText: string;
+    /** Detected values grouped per label. */
+    maskedData: MaskedData;
+    /** Flat list of detected entities with offsets into the original text. */
+    entities: PiiEntity[];
+}
+
+/**
+ * Detectors in priority order: when two detectors match overlapping
+ * text, the one listed first wins. Names run first, then patterns from
+ * most to least specific — in particular, the generic Swedish bank
+ * account number (10–11 digits) runs after personnummer, organization
+ * numbers, cards and phone numbers, all of which it would otherwise
+ * shadow.
+ */
+declare const detectors: Detector[];
+/**
+ * Run all detectors in priority order. Each detector sees the input
+ * with higher-priority matches blanked out (never with placeholder text,
+ * so placeholders can't be re-matched or corrupted). Blanking — rather
+ * than dropping overlapping candidates outright — lets a lower-priority
+ * detector still match the uncovered remainder: in "Lilla Vägen 7",
+ * where "Lilla" is a registered first name, the street detector can
+ * still mask "Vägen 7".
+ *
+ * Every candidate carries a confidence score; candidates below
+ * `scoreThreshold` are discarded before overlap resolution.
+ */
+declare function detectPII(text: string, options?: DetectOptions): PiiEntity[];
+/**
+ * Mask every detected entity in `text`, replacing it with `<LABEL_n>`.
+ * The returned `maskedData` maps each label to its values in order of
+ * appearance, and `entities` carries exact offsets into the input.
+ */
+declare function maskPII(text: string, options?: DetectOptions): MaskResult;
+
+/**
+ * Match a "First Last" string against the name lists. Returns the
+ * canonical matched names, or null when either part misses.
+ */
+declare function matchFullName(fullName: string): {
+    first: string;
+    last: string;
+} | null;
+
+/**
+ * Luhn (mod 10) checksum, used by payment card numbers, Swedish personal
+ * identity numbers (personnummer), coordination numbers and organization
+ * numbers.
+ */
+declare function luhnCheck(digits: string): boolean;
+/**
+ * Validate the checksum of a Swedish personnummer / samordningsnummer /
+ * organisationsnummer. The Luhn sum is always computed over the final
+ * 10 digits (century digits are excluded).
+ */
+declare function swedishIdChecksum(value: string): boolean;
+
+/**
+ * IBAN mod-97 checksum (ISO 13616): move the first four characters to
+ * the end, convert letters to numbers (A=10 … Z=35), and the whole
+ * number must be ≡ 1 (mod 97). Computed digit-by-digit to stay within
+ * safe integer range regardless of IBAN length.
+ */
+declare function ibanChecksum(iban: string): boolean;
+
+/**
+ * True when year/month/day form a real calendar date (leap years included).
+ * Month and day are 1-based.
+ */
+declare function isRealDate(year: number, month: number, day: number): boolean;
+/**
+ * Validate the date part of a Swedish identity number.
+ *
+ * @param digits - The identity number's digits (10 or 12, separators removed).
+ * @param dayOffset - 60 for samordningsnummer (day is stored as day + 60).
+ */
+declare function isValidIdentityDate(digits: string, dayOffset?: number): boolean;
+
+declare function jaroWinkler(s1: string, s2: string): number;
+
+/**
+ * Confidence levels, Presidio-style: recognizers report how sure they
+ * are, callers filter with `scoreThreshold`.
+ */
+declare const SCORE: {
+    /** Checksum (Luhn / mod-97) or calendar validation passed. */
+    readonly VALIDATED: 0.95;
+    /** Exact hit in a curated gazetteer (streets, municipalities). */
+    readonly EXACT_MATCH: 0.9;
+    /** Fuzzy full-name match or context-corroborated shape. */
+    readonly CONTEXT: 0.85;
+    /** Exact single-word lookup in a large list (names). */
+    readonly LOOKUP: 0.55;
+    /** A plain pattern/term match with no further evidence. */
+    readonly PATTERN: 0.6;
+    /** Heuristic shape (capitalized words + street suffix). */
+    readonly HEURISTIC: 0.5;
+    /** Shape matched but its checksum failed. */
+    readonly FAILED_VALIDATION: 0.45;
+    /** Shape matched but the expected nearby context is missing. */
+    readonly NO_CONTEXT: 0.25;
+};
+/** Entities scoring below this are dropped unless the caller opts in. */
+declare const DEFAULT_SCORE_THRESHOLD = 0.4;
+
+export { DEFAULT_SCORE_THRESHOLD, type DetectOptions, type Detector, type EntitySpan, type MaskResult, type MaskedData, type MaskedValue, type PiiEntity, type PiiLabel, SCORE, detectPII, detectors, ibanChecksum, isRealDate, isValidIdentityDate, jaroWinkler, luhnCheck, maskPII, matchFullName, swedishIdChecksum };