euredact 0.3.9 → 0.4.0

package/dist/esm/index.d.ts

@@ -1,13 +1,21 @@
-export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES } from "./types.js";
+export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES, canonicalType } from "./types.js";
 export type { Detection, RedactResult, PatternDef, CountryConfig, CountryEvidence } from "./types.js";
 export { DocumentContext } from "./rules/context.js";
 export { EuRedact, type RedactOptions } from "./sdk.js";
 export { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 export { setBicRegistry, getBicRegistry, SEED_BIC6_PREFIXES, type BicRegistryProvider } from "./rules/bicRegistry.js";
+export { configure, getConfig, CloudClient, CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, type CloudConfig, type ConfigureOptions, type CloudRedactOptions, } from "./cloud/index.js";
 import { type RedactOptions } from "./sdk.js";
 import type { RedactResult } from "./types.js";
 export declare function availableCountries(): string[];
 export declare function redact(text: string, options?: RedactOptions): RedactResult;
+/**
+ * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
+ *
+ * `mode: "rules"` resolves immediately with exactly what `redact()` returns,
+ * so a caller that may or may not use the cloud tier can hold one code path.
+ */
+export declare function redactAsync(text: string, options?: RedactOptions): Promise<RedactResult>;
 export declare function addCustomPattern(name: string, pattern: string): void;
 export declare function clear(): void;
 export declare function redactBatch(texts: string[], options?: RedactOptions): RedactResult[];

package/dist/esm/index.js

@@ -1,8 +1,9 @@
-export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES } from "./types.js";
+export { EntityType, DetectionSource, LEGACY_TYPE_ALIASES, canonicalType } from "./types.js";
 export { DocumentContext } from "./rules/context.js";
 export { EuRedact } from "./sdk.js";
 export { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 export { setBicRegistry, getBicRegistry, SEED_BIC6_PREFIXES } from "./rules/bicRegistry.js";
+export { configure, getConfig, CloudClient, CloudError, NotConfiguredError, QuotaExceededError, TooLargeError, } from "./cloud/index.js";
 import { EuRedact } from "./sdk.js";
 import { COUNTRY_CONFIGS } from "./rules/countries/index.js";
 let _instance = null;
@@ -17,6 +18,15 @@ export function availableCountries() {
 export function redact(text, options) {
     return getInstance().redact(text, options);
 }
+/**
+ * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
+ *
+ * `mode: "rules"` resolves immediately with exactly what `redact()` returns,
+ * so a caller that may or may not use the cloud tier can hold one code path.
+ */
+export function redactAsync(text, options) {
+    return getInstance().redactAsync(text, options);
+}
 export function addCustomPattern(name, pattern) {
     getInstance().addCustomPattern(name, pattern);
 }

package/dist/esm/sdk.d.ts

@@ -40,5 +40,12 @@ export declare class EuRedact {
      *  Call this in long-running processes to free PII from memory. */
     clear(): void;
     redact(text: string, options?: RedactOptions): RedactResult;
+    /**
+     * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
+     *
+     * `mode: "rules"` resolves immediately with exactly what `redact()` returns,
+     * so callers that may or may not use the cloud tier can hold one code path.
+     */
+    redactAsync(text: string, options?: RedactOptions): Promise<RedactResult>;
     redactBatch(texts: string[], options?: RedactOptions): RedactResult[];
 }

package/dist/esm/sdk.js

@@ -45,6 +45,40 @@ class ReferentialMapper {
     }
 }
 const DEFAULT_MAX_INPUT_LENGTH = 10_485_760; // ~10 MB of text
+/**
+ * Send a document to the cloud tier.
+ *
+ * Options the service cannot honour throw rather than being ignored. Silently
+ * dropping one would mean returning a result that does not match what was
+ * asked for — which, for anything that changes which spans come back, is
+ * under-redaction wearing a plausible face.
+ */
+async function redactViaCloud(text, options) {
+    const { CloudClient } = await import("./cloud/client.js");
+    const countries = options.countries ?? null;
+    if (!countries || countries.length !== 1) {
+        throw new Error('cloud mode needs exactly one country, e.g. { countries: ["BE"] }. The ' +
+            "model is trained and evaluated per country, so a multi-country request " +
+            "has no defined behaviour.");
+    }
+    if (options.countryHint) {
+        throw new Error("countryHint is not supported in cloud mode");
+    }
+    if (options.context || options.chunkOffset) {
+        throw new Error("context/chunkOffset are not supported in cloud mode: the model has never " +
+            "seen a chunk boundary, so the service rejects oversized input rather " +
+            "than splitting it");
+    }
+    if (options.referentialIntegrity) {
+        throw new Error("referentialIntegrity is not supported in cloud mode");
+    }
+    // detectDates is deliberately NOT forwarded. The service always runs its
+    // rules engine with dates on, because that is what the model was trained
+    // against; the caller's value cannot change that. It is the one ignored
+    // option that is safe to ignore — it can only cause MORE to be detected,
+    // never less, so it cannot produce under-redaction.
+    return new CloudClient().redact(text, { country: countries[0] });
+}
 /**
  * Reject a bare string where a list of country codes is expected.
  *
@@ -92,6 +126,19 @@ export class EuRedact {
     redact(text, options = {}) {
         checkCountryArg(options.countries, "countries");
         checkCountryArg(options.countryHint, "countryHint");
+        const requestedMode = options.mode ?? "rules";
+        if (requestedMode === "cloud") {
+            // Cannot be served synchronously: the cloud tier is a network call, and
+            // returning rules-only output instead would be the silent under-redaction
+            // this guard exists to prevent. Point at the async entry point rather
+            // than inventing a Promise-or-value union return type.
+            throw new Error('mode: "cloud" is asynchronous — use redactAsync(text, { mode: "cloud" }) ' +
+                "(or EuRedact#redactAsync). redact() is synchronous and can only serve " +
+                'mode: "rules".');
+        }
+        if (requestedMode !== "rules") {
+            throw new Error(`unknown mode ${JSON.stringify(requestedMode)}: expected "rules" or "cloud"`);
+        }
         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 ` +
@@ -175,6 +222,18 @@ export class EuRedact {
         }
         return result;
     }
+    /**
+     * Redact, awaiting the cloud tier when `mode: "cloud"` is asked for.
+     *
+     * `mode: "rules"` resolves immediately with exactly what `redact()` returns,
+     * so callers that may or may not use the cloud tier can hold one code path.
+     */
+    async redactAsync(text, options = {}) {
+        const mode = options.mode ?? "rules";
+        if (mode !== "cloud")
+            return this.redact(text, options);
+        return redactViaCloud(text, options);
+    }
     redactBatch(texts, options = {}) {
         // Generation is country-blind, so every country's patterns are loaded
         // regardless of what the caller declared.

package/dist/esm/types.d.ts

@@ -1,5 +1,20 @@
 export declare enum EntityType {
-    NAME = "NAME",
+    /**
+     * Canonical name for a person's name. `NAME` is kept below as a legacy alias
+     * with the same value, exactly as `IBAN` aliases `BANK_ACCOUNT`, so
+     * `EntityType.NAME === EntityType.PERSON_NAME` and existing code keeps
+     * working — but the emitted value, and therefore the `[PERSON_NAME]`
+     * placeholder written into redacted text, is canonical.
+     *
+     * Renamed rather than translated at the cloud boundary: two names for one
+     * type is how a whole category goes missing when someone filters on the
+     * spelling they happened to know. Nothing could have depended on the old
+     * value — the type is cloud-only and the cloud tier was stubbed, so it was
+     * never emitted.
+     */
+    PERSON_NAME = "PERSON_NAME",
+    /** @deprecated legacy alias of {@link EntityType.PERSON_NAME} */
+    NAME = "PERSON_NAME",
     ADDRESS = "ADDRESS",
     /**
      * Canonical name for a bank account identifier. `IBAN` is kept below as a
@@ -47,6 +62,15 @@ export declare enum EntityType {
     UUID = "UUID",
     SOCIAL_HANDLE = "SOCIAL_HANDLE",
     SECRET = "SECRET",
+    ORGANISATION_NAME = "ORGANISATION_NAME",
+    JOB_TITLE = "JOB_TITLE",
+    MEDICAL_CONDITION = "MEDICAL_CONDITION",
+    SENSITIVE_ATTRIBUTE = "SENSITIVE_ATTRIBUTE",
+    BIOMETRIC_REF = "BIOMETRIC_REF",
+    FINANCIAL_AMOUNT = "FINANCIAL_AMOUNT",
+    QUASI_IDENTIFIER = "QUASI_IDENTIFIER",
+    CREDENTIAL = "CREDENTIAL",
+    URL = "URL",
     OTHER = "OTHER"
 }
 /**
@@ -55,6 +79,14 @@ export declare enum EntityType {
  * legacy_aliases). The engine never *emits* these names.
  */
 export declare const LEGACY_TYPE_ALIASES: Record<string, string>;
+/**
+ * Resolve a possibly-legacy type name to its canonical form.
+ *
+ * Mirrors `EntityType._missing_` in the Python SDK. An unrecognised name is
+ * returned unchanged rather than dropped: a client one release behind the
+ * service must not silently lose a whole category of PII.
+ */
+export declare function canonicalType(name: string): string;
 export declare enum DetectionSource {
     RULES = "rules",
     CLOUD = "cloud"

package/dist/esm/types.js

@@ -1,6 +1,21 @@
 export var EntityType;
 (function (EntityType) {
-    EntityType["NAME"] = "NAME";
+    /**
+     * Canonical name for a person's name. `NAME` is kept below as a legacy alias
+     * with the same value, exactly as `IBAN` aliases `BANK_ACCOUNT`, so
+     * `EntityType.NAME === EntityType.PERSON_NAME` and existing code keeps
+     * working — but the emitted value, and therefore the `[PERSON_NAME]`
+     * placeholder written into redacted text, is canonical.
+     *
+     * Renamed rather than translated at the cloud boundary: two names for one
+     * type is how a whole category goes missing when someone filters on the
+     * spelling they happened to know. Nothing could have depended on the old
+     * value — the type is cloud-only and the cloud tier was stubbed, so it was
+     * never emitted.
+     */
+    EntityType["PERSON_NAME"] = "PERSON_NAME";
+    /** @deprecated legacy alias of {@link EntityType.PERSON_NAME} */
+    EntityType["NAME"] = "PERSON_NAME";
     EntityType["ADDRESS"] = "ADDRESS";
     /**
      * Canonical name for a bank account identifier. `IBAN` is kept below as a
@@ -48,6 +63,20 @@ export var EntityType;
     EntityType["UUID"] = "UUID";
     EntityType["SOCIAL_HANDLE"] = "SOCIAL_HANDLE";
     EntityType["SECRET"] = "SECRET";
+    // ── [CLOUD EXTENSION] ────────────────────────────────────────────────────
+    // Types only the cloud tier can detect. The rule engine never emits these —
+    // there is no shape to match on — which is exactly why they exist: the
+    // model's job is what the rules cannot catch. Named to match the detection
+    // canon the service is trained and evaluated against.
+    EntityType["ORGANISATION_NAME"] = "ORGANISATION_NAME";
+    EntityType["JOB_TITLE"] = "JOB_TITLE";
+    EntityType["MEDICAL_CONDITION"] = "MEDICAL_CONDITION";
+    EntityType["SENSITIVE_ATTRIBUTE"] = "SENSITIVE_ATTRIBUTE";
+    EntityType["BIOMETRIC_REF"] = "BIOMETRIC_REF";
+    EntityType["FINANCIAL_AMOUNT"] = "FINANCIAL_AMOUNT";
+    EntityType["QUASI_IDENTIFIER"] = "QUASI_IDENTIFIER";
+    EntityType["CREDENTIAL"] = "CREDENTIAL";
+    EntityType["URL"] = "URL";
     EntityType["OTHER"] = "OTHER";
 })(EntityType || (EntityType = {}));
 /**
@@ -57,7 +86,21 @@ export var EntityType;
  */
 export const LEGACY_TYPE_ALIASES = {
     IBAN: "BANK_ACCOUNT",
+    NAME: "PERSON_NAME",
+    STREET_ADDRESS: "ADDRESS",
+    NATIONALITY_ETHNICITY: "SENSITIVE_ATTRIBUTE",
 };
+/**
+ * Resolve a possibly-legacy type name to its canonical form.
+ *
+ * Mirrors `EntityType._missing_` in the Python SDK. An unrecognised name is
+ * returned unchanged rather than dropped: a client one release behind the
+ * service must not silently lose a whole category of PII.
+ */
+export function canonicalType(name) {
+    const upper = String(name ?? "").trim().toUpperCase();
+    return LEGACY_TYPE_ALIASES[upper] ?? upper;
+}
 export var DetectionSource;
 (function (DetectionSource) {
     DetectionSource["RULES"] = "rules";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euredact",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "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",
@@ -54,7 +54,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:conformance",
+    "test": "npm run test:spec && npm run test:inference && npm run test:cloud && 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",
@@ -62,7 +62,8 @@
     "test:eval:full": "node --max-old-space-size=8192 --import tsx src/__tests__/evalFull.ts",
     "test:conformance": "node --import tsx src/__tests__/conformance.ts",
     "test:inference": "node --import tsx src/__tests__/inference.ts",
-    "dump": "node --import tsx src/__tests__/dump.ts"
+    "dump": "node --import tsx src/__tests__/dump.ts",
+    "test:cloud": "node --import tsx src/__tests__/cloud.ts"
   },
   "devDependencies": {
     "@types/node": "22.10.2",