euredact 0.6.0 → 0.7.1

package/dist/esm/rules/validators.d.ts

@@ -65,7 +65,21 @@ export declare function validateSpanishDni(candidate: string): boolean;
 export declare function validateSpanishNie(candidate: string): boolean;
 export declare function validatePortugueseNif(candidate: string): boolean;
 export declare function validatePolishPesel(candidate: string): boolean;
+/** Polish domestic account number (NRB): the PL IBAN without its "PL", so the IBAN's mod-97 decides it (rules-engine#93). */
+export declare function validatePolishNrb(candidate: string): boolean;
 export declare function validatePolishNip(candidate: string): boolean;
+/**
+ * Polish identity card (dowód osobisty): 3 letters + 6 digits, the first digit
+ * a check digit. Letters A=10 … Z=35, weights 7,3,1,9,7,3,1,7,3: the weighted
+ * sum of all nine is 0 mod 10 exactly when the check digit is right (rules-engine#75).
+ */
+export declare function validatePolishIdCard(candidate: string): boolean;
+/**
+ * Polish REGON: 9 digits, or 14 for a local unit, each with a mod-11 check (a
+ * remainder of 10 counts as 0). A 14-digit REGON begins with its parent's valid
+ * 9-digit REGON (rules-engine#76).
+ */
+export declare function validatePolishRegon(candidate: string): boolean;
 export declare function validateCzechBirthNumber(candidate: string): boolean;
 export declare function validateRomanianCnp(candidate: string): boolean;
 export declare function validateHungarianTaj(candidate: string): boolean;

package/dist/esm/rules/validators.js

@@ -492,6 +492,13 @@ export function validatePolishPesel(candidate) {
         total += d[i] * weights[i];
     return d[10] === (10 - (total % 10)) % 10;
 }
+/** Polish domestic account number (NRB): the PL IBAN without its "PL", so the IBAN's mod-97 decides it (rules-engine#93). */
+export function validatePolishNrb(candidate) {
+    const c = candidate.replace(/[\s\-]/g, "");
+    if (!/^\d{26}$/.test(c))
+        return false;
+    return validateIban("PL" + c);
+}
 export function validatePolishNip(candidate) {
     const c = candidate.replace(/[\s\-]/g, "");
     if (c.length !== 10 || !/^\d{10}$/.test(c))
@@ -503,6 +510,43 @@ export function validatePolishNip(candidate) {
         total += d[i] * weights[i];
     return total % 11 === d[9];
 }
+/**
+ * Polish identity card (dowód osobisty): 3 letters + 6 digits, the first digit
+ * a check digit. Letters A=10 … Z=35, weights 7,3,1,9,7,3,1,7,3: the weighted
+ * sum of all nine is 0 mod 10 exactly when the check digit is right (rules-engine#75).
+ */
+export function validatePolishIdCard(candidate) {
+    const c = candidate.replace(/\s/g, "").toUpperCase();
+    if (!/^[A-Z]{3}\d{6}$/.test(c))
+        return false;
+    const weights = [7, 3, 1, 9, 7, 3, 1, 7, 3];
+    let total = 0;
+    for (let i = 0; i < 9; i++) {
+        const ch = c[i];
+        total += (/[A-Z]/.test(ch) ? ch.charCodeAt(0) - 55 : Number(ch)) * weights[i];
+    }
+    return total % 10 === 0;
+}
+/**
+ * Polish REGON: 9 digits, or 14 for a local unit, each with a mod-11 check (a
+ * remainder of 10 counts as 0). A 14-digit REGON begins with its parent's valid
+ * 9-digit REGON (rules-engine#76).
+ */
+export function validatePolishRegon(candidate) {
+    const c = candidate.replace(/[\s\-]/g, "");
+    if (!/^\d+$/.test(c) || (c.length !== 9 && c.length !== 14))
+        return false;
+    const check = (digits, weights) => {
+        let total = 0;
+        for (let i = 0; i < weights.length; i++)
+            total += Number(digits[i]) * weights[i];
+        const rest = total % 11;
+        return (rest === 10 ? 0 : rest) === Number(digits[weights.length]);
+    };
+    if (!check(c.slice(0, 9), [8, 9, 2, 3, 4, 5, 6, 7]))
+        return false;
+    return c.length === 9 || check(c, [2, 4, 8, 5, 0, 9, 7, 3, 6, 1, 2, 4, 8]);
+}
 // Days per month for the rodné číslo date check. February is 29 because the
 // century is not recoverable from a two-digit year, so a leap year cannot be
 // ruled out -- being permissive by one day is the right direction here.
@@ -753,6 +797,9 @@ export const VALIDATORS = {
     portuguese_nif: validatePortugueseNif,
     polish_pesel: validatePolishPesel,
     polish_nip: validatePolishNip,
+    polish_nrb: validatePolishNrb,
+    polish_id_card: validatePolishIdCard,
+    polish_regon: validatePolishRegon,
     czech_birth_number: validateCzechBirthNumber,
     romanian_cnp: validateRomanianCnp,
     hungarian_taj: validateHungarianTaj,

package/dist/esm/sdk.d.ts

@@ -22,11 +22,51 @@ type LabelFor = (det: Detection, slice: string) => string;
  */
 export declare function applyReplacements(text: string, detections: Detection[], labelFor: LabelFor): string;
 /**
- * Characters a token suffix is drawn from. No vowels, so a suffix never spells
- * a word; no 0/1/I/O, so it survives being read back by a person; no
- * underscore, so the type prefix stays unambiguous.
+ * One label in the text sent to the cloud tier: where it sits in the masked
+ * text, and the extent of the original it replaced —
+ * `[maskedStart, maskedEnd, start, end]`.
  */
-export declare const TOKEN_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export type WireLabel = [number, number, number, number];
+/**
+ * Bracket-mask `text` and record where each label landed.
+ *
+ * Returns what is sent to the cloud tier, plus one `WireLabel` per label.
+ * Everything between labels is copied unchanged, so the labels are all it
+ * takes to carry an offset from the masked text back to the original.
+ *
+ * Always `[TYPE]`, whatever label scheme the caller asked for. That is the
+ * syntax the model was trained on, where a placeholder means "already handled,
+ * do not list it". A token or a numbered label would be read as ordinary text,
+ * so the format on the wire is a model contract and not an output option.
+ */
+/** @internal Shared with cloud/batches.ts. */
+export declare function maskForCloud(text: string, detections: Detection[]): [string, WireLabel[]];
+/**
+ * Carry the service's spans from the masked text onto the original.
+ *
+ * The service only ever saw `masked`, so its offsets index that. An offset in
+ * copied text shifts by whatever the labels before it added or removed. An
+ * offset inside a label has no counterpart in the original, so it snaps
+ * outward to the edge of the value the label replaced: an address the model
+ * reports around `[POSTAL_CODE]` covers the postal code, never half of it.
+ * Over-masking is the safe direction.
+ *
+ * A span lying wholly inside one label describes the label, not the document.
+ * It is dropped; the local detection behind the label stands.
+ *
+ * Throws `Unplaceable` when a span does not match the text that was sent. Such
+ * a span cannot be placed, and masking where it points would cover the wrong
+ * characters and leave the right ones in the clear.
+ */
+/** @internal Shared with cloud/batches.ts. */
+export declare function ontoOriginal(spans: Detection[], masked: string, text: string, labels: WireLabel[], Unplaceable: new (message: string) => Error): Detection[];
+/**
+ * Characters a token suffix is drawn from. No vowels (and no Y), so a suffix
+ * never spells a word; no 0/1/I/O, so it survives being read back by a person;
+ * no underscore, so the type prefix stays unambiguous. A, E, U and Y were in it
+ * until rules-engine#55, against this comment.
+ */
+export declare const TOKEN_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ23456789";
 export declare const TOKEN_SUFFIX_LENGTH = 4;
 /**
  * Maps each distinct PII value in one call to a reversible token.
@@ -64,6 +104,15 @@ export declare class TokenMapper {
  * restored, since leaving a token behind is the worse failure.
  */
 export declare function restore(text: string, tokens: Record<string, string>): string;
+/**
+ * The entity types a caller asked to leave in the text, by canonical name.
+ *
+ * Names are matched case-insensitively and legacy names resolve (`IBAN` is
+ * `BANK_ACCOUNT`, `CREDENTIAL` is `SECRET`). A custom pattern's name counts
+ * once it is registered. Anything else throws: a typo in a type meant to be
+ * switched off would otherwise switch nothing off (rules-engine#125).
+ */
+export declare function normalizeExcludeTypes(values: unknown, customNames?: ReadonlySet<string>, param?: string): Set<string>;
 export interface RedactOptions {
     /**
      * Scope. Detections attributed elsewhere are flagged `outOfScope`, never
@@ -104,8 +153,24 @@ export interface RedactOptions {
      * EMAIL and URL only, and covers subdomains. Merged with the instance list.
      */
     allowlistDomains?: string[] | null;
+    /**
+     * Entity types to leave in the text: neither in `detections` nor masked, and
+     * each such detection reported in `RedactResult.exempted` (`ruleKind:
+     * "type"`). Names are case-insensitive and legacy names resolve; unknown
+     * names throw. Merged with the instance's list. Default: nothing excluded.
+     * In `mode: "cloud"` an excluded rules type is still masked in the text sent
+     * to the service — this decides what comes back, not what may leave.
+     */
+    excludeTypes?: string[] | null;
     detectDates?: boolean;
     cache?: boolean;
+    /**
+     * `mode: "cloud"` only. Sent as the request's `Idempotency-Key`: the same key
+     * returns the same job instead of running (and billing) the document again,
+     * which is what a caller retrying after its own timeout needs. One is
+     * generated per call when omitted.
+     */
+    idempotencyKey?: string;
 }
 export declare class EuRedact {
     private engine;
@@ -114,16 +179,22 @@ export declare class EuRedact {
     private maxInputLength;
     private allowlist;
     private allowlistDomains;
+    private customNames;
+    private excludeTypes;
     /**
      * @param options.maxInputLength Longest document `redact` accepts, in characters.
      * @param options.allowlist Values never to redact, for every call on this
      *   instance — an organisation's own name, its own addresses. Merged with
      *   the per-call `allowlist`. Matched whole, case-insensitively.
+     * @param options.excludeTypes Entity types never reported or masked, for
+     *   every call on this instance, e.g. `["JOB_TITLE", "FINANCIAL_AMOUNT"]`.
+     *   Merged with the per-call value. Unknown names throw.
      */
     constructor(options?: {
         maxInputLength?: number;
         allowlist?: string[] | null;
         allowlistDomains?: string[] | null;
+        excludeTypes?: string[] | null;
     });
     addCustomPattern(name: string, pattern: string): void;
     /** Clear the result cache and referential integrity mappings.
@@ -131,6 +202,8 @@ export declare class EuRedact {
     clear(): void;
     /** The instance allowlist merged with a call's, in comparison form. */
     private allowedFor;
+    /** The instance's excluded types merged with a call's. */
+    private excludedFor;
     /** The instance domain list merged with a call's. */
     private domainsFor;
     /** The label function for one call, given its output options. */

package/dist/esm/sdk.js

@@ -1,9 +1,9 @@
-import { randomInt } from "node:crypto";
+import { randomIndex } from "./platform.js";
 import { ResultCache } from "./cache.js";
 import { normalize, mapOffsetToOriginal } from "./normalizer.js";
 import { RuleEngine } from "./rules/engine.js";
 import { weightsToRanking } from "./rules/evidence.js";
-import { EntityType } from "./types.js";
+import { EntityType, canonicalType } from "./types.js";
 const DATE_TYPES = new Set([EntityType.DOB, EntityType.DATE_OF_DEATH]);
 /**
  * Splice a label over every detection and return the masked text.
@@ -60,7 +60,8 @@ export function applyReplacements(text, detections, labelFor) {
  * do not list it". A token or a numbered label would be read as ordinary text,
  * so the format on the wire is a model contract and not an output option.
  */
-function maskForCloud(text, detections) {
+/** @internal Shared with cloud/batches.ts. */
+export function maskForCloud(text, detections) {
     const parts = [];
     const labels = [];
     let pos = 0;
@@ -110,7 +111,8 @@ function labelBefore(labels, offset, strict) {
  * a span cannot be placed, and masking where it points would cover the wrong
  * characters and leave the right ones in the clear.
  */
-function ontoOriginal(spans, masked, text, labels, Unplaceable) {
+/** @internal Shared with cloud/batches.ts. */
+export function ontoOriginal(spans, masked, text, labels, Unplaceable) {
     const placed = [];
     for (const span of spans) {
         if (!(0 <= span.start && span.start <= span.end && span.end <= masked.length) ||
@@ -139,11 +141,12 @@ function ontoOriginal(spans, masked, text, labels, Unplaceable) {
     return placed;
 }
 /**
- * Characters a token suffix is drawn from. No vowels, so a suffix never spells
- * a word; no 0/1/I/O, so it survives being read back by a person; no
- * underscore, so the type prefix stays unambiguous.
+ * Characters a token suffix is drawn from. No vowels (and no Y), so a suffix
+ * never spells a word; no 0/1/I/O, so it survives being read back by a person;
+ * no underscore, so the type prefix stays unambiguous. A, E, U and Y were in it
+ * until rules-engine#55, against this comment.
  */
-export const TOKEN_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export const TOKEN_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ23456789";
 export const TOKEN_SUFFIX_LENGTH = 4;
 const TOKEN_MAX_DRAWS = 100;
 function escapeRegExp(s) {
@@ -191,7 +194,7 @@ export class TokenMapper {
                 }
                 let suffix = "";
                 for (let i = 0; i < TOKEN_SUFFIX_LENGTH; i++) {
-                    suffix += TOKEN_ALPHABET[randomInt(TOKEN_ALPHABET.length)];
+                    suffix += TOKEN_ALPHABET[randomIndex(TOKEN_ALPHABET.length)];
                 }
                 token = prefix + suffix;
             } while (this.taken.has(token));
@@ -350,6 +353,70 @@ function applyAllowlist(text, detections, allowed, domains) {
     }
     return [kept, exempted];
 }
+const KNOWN_TYPES = new Set(Object.values(EntityType));
+/**
+ * The entity types a caller asked to leave in the text, by canonical name.
+ *
+ * Names are matched case-insensitively and legacy names resolve (`IBAN` is
+ * `BANK_ACCOUNT`, `CREDENTIAL` is `SECRET`). A custom pattern's name counts
+ * once it is registered. Anything else throws: a typo in a type meant to be
+ * switched off would otherwise switch nothing off (rules-engine#125).
+ */
+export function normalizeExcludeTypes(values, customNames = new Set(), param = "excludeTypes") {
+    const out = new Set();
+    if (values === null || values === undefined)
+        return out;
+    checkAllowlistArg(values, param);
+    for (const v of values) {
+        if (typeof v !== "string") {
+            throw new TypeError(`${param} entries must be type names, not ${typeof v}`);
+        }
+        if (customNames.has(v)) {
+            out.add(v);
+            continue;
+        }
+        const name = canonicalType(v);
+        if (!KNOWN_TYPES.has(name)) {
+            throw new Error(`unknown entity type ${JSON.stringify(v)} in ${param}. Known types: ` +
+                [...KNOWN_TYPES].sort().join(", ") +
+                (customNames.size ? `; custom patterns: ${[...customNames].sort().join(", ")}` : ""));
+        }
+        out.add(name);
+    }
+    return out;
+}
+/**
+ * Split off the detections of the types the caller excluded. Applied to each
+ * span's final type, after ranking: dropping an excluded type's candidates
+ * earlier would let the next-best type claim the same span.
+ */
+function applyTypeExclusion(text, detections, excluded) {
+    if (excluded.size === 0)
+        return [detections, []];
+    const kept = [];
+    const exempted = [];
+    for (const d of detections) {
+        const name = String(d.entityType);
+        if (excluded.has(name)) {
+            exempted.push({
+                entityType: d.entityType, start: d.start, end: d.end,
+                text: text.slice(d.start, d.end), rule: name, ruleKind: "type",
+            });
+        }
+        else
+            kept.push(d);
+    }
+    return [kept, exempted];
+}
+/** Allowlist first, then excluded types; every exemption in text order. */
+function exempt(text, detections, allowed, domains, excluded) {
+    const [afterValues, byValue] = applyAllowlist(text, detections, allowed, domains);
+    const [kept, byType] = applyTypeExclusion(text, afterValues, excluded);
+    const exempted = [...byValue, ...byType];
+    if (byValue.length && byType.length)
+        exempted.sort((a, b) => a.start - b.start || b.end - a.end);
+    return [kept, exempted];
+}
 /** Two label schemes for the same spans cannot both apply. */
 function checkLabelOptions(options) {
     if (options.tokenize && options.referentialIntegrity) {
@@ -430,19 +497,26 @@ export class EuRedact {
     maxInputLength;
     allowlist;
     allowlistDomains;
+    customNames = new Set();
+    excludeTypes;
     /**
      * @param options.maxInputLength Longest document `redact` accepts, in characters.
      * @param options.allowlist Values never to redact, for every call on this
      *   instance — an organisation's own name, its own addresses. Merged with
      *   the per-call `allowlist`. Matched whole, case-insensitively.
+     * @param options.excludeTypes Entity types never reported or masked, for
+     *   every call on this instance, e.g. `["JOB_TITLE", "FINANCIAL_AMOUNT"]`.
+     *   Merged with the per-call value. Unknown names throw.
      */
     constructor(options) {
         this.maxInputLength = options?.maxInputLength ?? DEFAULT_MAX_INPUT_LENGTH;
         this.allowlist = normalizeAllowlist(options?.allowlist);
         this.allowlistDomains = normalizeDomains(options?.allowlistDomains);
+        this.excludeTypes = normalizeExcludeTypes(options?.excludeTypes);
     }
     addCustomPattern(name, pattern) {
         this.engine.addCustomPattern(name, pattern);
+        this.customNames.add(name);
         this.cache.clear();
     }
     /** Clear the result cache and referential integrity mappings.
@@ -458,6 +532,13 @@ export class EuRedact {
             allowed.set(k, v);
         return allowed;
     }
+    /** The instance's excluded types merged with a call's. */
+    excludedFor(options) {
+        const excluded = new Set(this.excludeTypes);
+        for (const t of normalizeExcludeTypes(options.excludeTypes, this.customNames))
+            excluded.add(t);
+        return excluded;
+    }
     /** The instance domain list merged with a call's. */
     domainsFor(options) {
         const domains = new Map(this.allowlistDomains);
@@ -514,22 +595,26 @@ export class EuRedact {
         }
         const allowed = this.allowedFor(options);
         const domains = this.domainsFor(options);
+        const excluded = this.excludedFor(options);
         const client = new CloudClient();
         // Dates are always on, whatever detectDates says: that is the rules output
         // the model was trained against, and a date of birth the rules can place
         // has no reason to travel. It is the one ignored option that is safe to
         // ignore — it can only cause MORE to be detected, never less.
         //
-        // No allowlist and no tokens on this pass. An exemption says what the
-        // caller wants back, not what may leave; both are applied below, after the
+        // No allowlist, no excluded types and no tokens on this pass. An exemption
+        // says what the caller wants back, not what may leave: an excluded EMAIL is
+        // still masked in the request. All three are applied below, after the
         // response, to the merged spans.
         const local = this.redactRules(text, { countries, detectDates: true, cache: options.cache }, new Map(), new Map());
         const [masked, labels] = maskForCloud(text, local.detections);
         // The client converts the service's code-point offsets to UTF-16 units of
         // the text it sent, so everything from here on is in one unit.
-        const remote = await client.redact(masked, { country: countries[0] });
+        const remote = await client.redact(masked, {
+            country: countries[0], idempotencyKey: options.idempotencyKey,
+        });
         // A new array throughout: `local` may be the cached rules result.
-        const [detections, exempted] = applyAllowlist(text, [...local.detections, ...ontoOriginal(remote.detections, masked, text, labels, CloudError)], allowed, domains);
+        const [detections, exempted] = exempt(text, [...local.detections, ...ontoOriginal(remote.detections, masked, text, labels, CloudError)], allowed, domains, excluded);
         detections.sort((a, b) => a.start - b.start || b.end - a.end);
         const tokenMapper = options.tokenize ? new TokenMapper(text, detections) : null;
         return {
@@ -539,6 +624,7 @@ export class EuRedact {
             source: "cloud",
             tokens: tokenMapper ? tokenMapper.tokens : {},
             exempted,
+            ...(remote.cloud ? { cloud: remote.cloud } : {}),
         };
     }
     redact(text, options = {}) {
@@ -547,6 +633,7 @@ export class EuRedact {
         checkLabelOptions(options);
         const allowed = this.allowedFor(options);
         const domains = this.domainsFor(options);
+        const excluded = this.excludedFor(options);
         const requestedMode = options.mode ?? "rules";
         if (requestedMode === "cloud") {
             // Cannot be served synchronously: the cloud tier is a network call, and
@@ -560,10 +647,13 @@ export class EuRedact {
         if (requestedMode !== "rules") {
             throw new Error(`unknown mode ${JSON.stringify(requestedMode)}: expected "rules" or "cloud"`);
         }
-        return this.redactRules(text, options, allowed, domains);
+        if (options.idempotencyKey !== undefined) {
+            throw new Error('idempotencyKey applies to mode: "cloud" only: a rules-only redaction makes no request to deduplicate');
+        }
+        return this.redactRules(text, options, allowed, domains, excluded);
     }
     /** The local pipeline: normalise, detect, exempt, mask. */
-    redactRules(text, options, allowed, domains) {
+    redactRules(text, options, allowed, domains, excluded = new Set()) {
         if (text.length > this.maxInputLength) {
             throw new Error(`Input text length (${text.length.toLocaleString()} chars) exceeds the maximum ` +
                 `(${this.maxInputLength.toLocaleString()} chars). Split the input or ` +
@@ -586,7 +676,8 @@ export class EuRedact {
         // JSON rather than a joined string: an entry may itself contain the
         // separator, and two different lists must never share a key.
         const allowKey = (allowed.size ? JSON.stringify([...allowed.keys()].sort()) : "")
-            + (domains.size ? "|dom=" + JSON.stringify([...domains.keys()].sort()) : "");
+            + (domains.size ? "|dom=" + JSON.stringify([...domains.keys()].sort()) : "")
+            + (excluded.size ? "|excl=" + JSON.stringify([...excluded].sort()) : "");
         const cacheMode = `rules|dates=${detectDates}|hint=${hintKey}|ri=${referentialIntegrity}|tok=${tokenize}|allow=${allowKey}`;
         let cacheKey;
         if (cache) {
@@ -610,7 +701,7 @@ export class EuRedact {
             detections = detections.filter(d => !DATE_TYPES.has(d.entityType));
         }
         let exempted;
-        [detections, exempted] = applyAllowlist(text, detections, allowed, domains);
+        [detections, exempted] = exempt(text, detections, allowed, domains, excluded);
         detections.sort((a, b) => a.start - b.start || b.end - a.end);
         const tokenMapper = tokenize ? new TokenMapper(text, detections) : null;
         const redacted = applyReplacements(text, detections, this.labelFor(referentialIntegrity, tokenMapper));

package/dist/esm/types.d.ts

@@ -69,7 +69,8 @@ export declare enum EntityType {
     BIOMETRIC_REF = "BIOMETRIC_REF",
     FINANCIAL_AMOUNT = "FINANCIAL_AMOUNT",
     QUASI_IDENTIFIER = "QUASI_IDENTIFIER",
-    CREDENTIAL = "CREDENTIAL",
+    /** Legacy alias of SECRET: every credential, the model's included, is SECRET (rules-engine#111). */
+    CREDENTIAL = "SECRET",
     URL = "URL",
     OTHER = "OTHER"
 }
@@ -116,7 +117,13 @@ export interface Detection {
     text: string;
     source: DetectionSource;
     country: string | null;
-    confidence: string;
+    /**
+     * How the type was arrived at: "high", "medium" or "low" for a rules
+     * detection. `null` for a span the cloud model found and reported no
+     * confidence for: the model emits none today, and "high" would claim the
+     * checksum-backed evidence a rules detection has (rules-engine#108).
+     */
+    confidence: string | null;
     /**
      * How strongly the document supports {@link Detection.country}, in [0, 1].
      *
@@ -134,7 +141,7 @@ export interface Detection {
     outOfScope?: boolean;
 }
 /**
- * A detection the allowlist kept out of the redacted output.
+ * A detection the allowlist or `excludeTypes` kept out of the redacted output.
  *
  * An exemption is a deliberate decision to leave a direct identifier in a
  * document that otherwise claims to be redacted, so it is reported rather than
@@ -146,10 +153,58 @@ export interface Exemption {
     start: number;
     end: number;
     text: string;
-    /** The allowlist entry that matched, as the caller wrote it. */
+    /** The allowlist entry that matched, as the caller wrote it; for an
+     *  excluded type, the type's canonical name. */
     rule: string;
-    /** `"value"` for the literal allowlist, `"domain"` for allowlistDomains. */
-    ruleKind: "value" | "domain";
+    /** `"value"` for the literal allowlist, `"domain"` for allowlistDomains,
+     *  `"type"` for excludeTypes (rules-engine#125). */
+    ruleKind: "value" | "domain" | "type";
+}
+/**
+ * One reason a cloud request cost what it did. `code` is one of the service's
+ * factor codes (`rules_only`, `document_length`, `instructions`,
+ * `dense_document`, `special_category_check`, `long_document`, `batch_rate`),
+ * kept as a string so a code added later on the service still arrives.
+ */
+export interface UsageFactor {
+    code: string;
+    /** One sentence explaining the factor, written by the service. */
+    detail: string;
+    /** `special_category_check` only: the kinds of data that triggered it. */
+    types?: string[];
+}
+/**
+ * What a cloud request cost, and why (rules-engine#89). A total and its
+ * reasons, never a cost per step; `credits` is `round(tokens * billingRate)`,
+ * the formula the service debits by.
+ */
+export interface Usage {
+    tokens: number;
+    billingRate: number;
+    credits: number;
+    factors: UsageFactor[];
+}
+/**
+ * Something the model found that could not be placed in the document: the
+ * service could not match it to a position in what it was sent, so nothing was
+ * masked for it. Reported so a caller can decide, rather than never being told.
+ */
+export interface Unlocated {
+    text: string;
+    entityType: EntityType | string;
+}
+/** What the cloud service said about a request, beside its spans (rules-engine#89). */
+export interface CloudInfo {
+    /** The service's job id: for support, for `Jobs.retrieve`, and to recognise an
+     *  idempotent replay. `null` for a batch document. */
+    jobId: string | null;
+    /** The public name of the model that answered, `null` when only rules ran. */
+    modelVersion: string | null;
+    /** What the request cost and why. Absent when the service does not report it
+     *  (older versions, batch documents) or reported it malformed. */
+    usage?: Usage;
+    /** What the model found but could not place in the text it was sent. */
+    unlocated: Unlocated[];
 }
 export interface RedactResult {
     redactedText: string;
@@ -188,6 +243,9 @@ export interface RedactResult {
     /** Detections the allowlist kept out of the output, with the rule that
      *  matched. Empty unless an allowlist was in force. */
     exempted: Exemption[];
+    /** What the cloud service reported beside the spans: job id, model, cost and
+     *  anything it could not place. Absent on a rules-only result. */
+    cloud?: CloudInfo;
 }
 export interface PatternDef {
     entityType: EntityType | string;

package/dist/esm/types.js

@@ -75,7 +75,8 @@ export var EntityType;
     EntityType["BIOMETRIC_REF"] = "BIOMETRIC_REF";
     EntityType["FINANCIAL_AMOUNT"] = "FINANCIAL_AMOUNT";
     EntityType["QUASI_IDENTIFIER"] = "QUASI_IDENTIFIER";
-    EntityType["CREDENTIAL"] = "CREDENTIAL";
+    /** Legacy alias of SECRET: every credential, the model's included, is SECRET (rules-engine#111). */
+    EntityType["CREDENTIAL"] = "SECRET";
     EntityType["URL"] = "URL";
     EntityType["OTHER"] = "OTHER";
 })(EntityType || (EntityType = {}));
@@ -89,6 +90,8 @@ export const LEGACY_TYPE_ALIASES = {
     NAME: "PERSON_NAME",
     STREET_ADDRESS: "ADDRESS",
     NATIONALITY_ETHNICITY: "SENSITIVE_ATTRIBUTE",
+    // The model labels prose credentials CREDENTIAL; the SDK reports every credential as SECRET (rules-engine#111).
+    CREDENTIAL: "SECRET",
 };
 /**
  * Resolve a possibly-legacy type name to its canonical form.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euredact",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "European PII redaction SDK -- fast, zero-dependency, rule-based detection and redaction of personal data across 31 European countries",
   "homepage": "https://euredact.dev",
   "license": "Apache-2.0",
@@ -20,10 +20,15 @@
       }
     }
   },
+  "browser": {
+    "./dist/esm/platform.js": "./dist/esm/platform.browser.js",
+    "./dist/cjs/platform.js": "./dist/cjs/platform.browser.js"
+  },
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "engines": {
     "node": ">=16.0.0"
@@ -54,7 +59,7 @@
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "postbuild:cjs": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
     "build": "rm -rf dist && npm run build:esm && npm run build:cjs",
-    "test": "npm run test:spec && npm run test:inference && npm run test:cloud && npm run test:tokenize && npm run test:allowlist && npm run test:eval-scoring && npm run test:conformance",
+    "test": "npm run test:spec && npm run test:inference && npm run test:cloud && npm run test:cloud-api && npm run test:tokenize && npm run test:allowlist && npm run test:exclude-types && npm run test:eval-scoring && npm run test:platform && npm run test:batches && npm run test:conformance",
     "benchmark": "node --import tsx src/__tests__/benchmark.ts",
     "prepublishOnly": "npm run build",
     "test:spec": "node --import tsx src/__tests__/spec.ts",
@@ -64,9 +69,13 @@
     "test:inference": "node --import tsx src/__tests__/inference.ts",
     "dump": "node --import tsx src/__tests__/dump.ts",
     "test:cloud": "node --import tsx src/__tests__/cloud.ts",
+    "test:cloud-api": "node --import tsx src/__tests__/cloudApi.ts",
     "test:tokenize": "node --import tsx src/__tests__/tokenize.ts",
     "test:allowlist": "node --import tsx src/__tests__/allowlist.ts",
-    "test:eval-scoring": "node --import tsx src/__tests__/evalScoring.ts"
+    "test:exclude-types": "node --import tsx src/__tests__/excludeTypes.ts",
+    "test:eval-scoring": "node --import tsx src/__tests__/evalScoring.ts",
+    "test:platform": "node --import tsx src/__tests__/platform.ts",
+    "test:batches": "node --import tsx src/__tests__/batches.ts"
   },
   "devDependencies": {
     "@types/node": "22.10.2",