euredact 0.3.8 → 0.4.0

package/README.md

@@ -34,7 +34,8 @@ console.log(result.detections);
 ## Features
 
 - **31 European countries** with country-specific patterns
-- **25+ PII entity types:** national IDs, IBANs, phone numbers, email, VAT
+- **41 PII entity types** (30 from the rules engine, 11 from the
+  [cloud tier](#cloud-tier)): national IDs, IBANs, phone numbers, email, VAT
   numbers, license plates, credit cards, BIC/SWIFT, VIN, IMEI, GPS coordinates,
   UUIDs, social handles, IP/IPv6, MAC addresses, secrets/API keys, and more
 - **Secret/API key detection:** known-prefix patterns for AWS, GitHub, Stripe,
@@ -218,7 +219,7 @@ interface RedactResult {
 String enum with all supported PII categories:
 
 ```
-NAME              ADDRESS           BANK_ACCOUNT      BIC
+PERSON_NAME       ADDRESS           BANK_ACCOUNT      BIC
 CREDIT_CARD       PHONE             EMAIL             DOB
 DATE_OF_DEATH     NATIONAL_ID       SSN               TAX_ID
 PASSPORT          DRIVERS_LICENSE   RESIDENCE_PERMIT  LICENSE_PLATE
@@ -226,17 +227,110 @@ VIN               VAT               POSTAL_CODE       IP_ADDRESS
 IPV6_ADDRESS      MAC_ADDRESS       HEALTH_INSURANCE  HEALTHCARE_PROVIDER
 CHAMBER_OF_COMMERCE  IMEI          GPS_COORDINATES   UUID
 SOCIAL_HANDLE     SECRET            INTERNAL_ID       OTHER
+
+Cloud tier only — the rule engine never emits these, because there is no shape
+to match on. That is precisely why the model exists:
+
+ORGANISATION_NAME JOB_TITLE         MEDICAL_CONDITION SENSITIVE_ATTRIBUTE
+BIOMETRIC_REF     FINANCIAL_AMOUNT  QUASI_IDENTIFIER  CREDENTIAL
+URL
 ```
 
 `INTERNAL_ID` — an employee, badge or customer number tied to a person — is
 emitted **only** when an explicit label names it (`medarbejdernummer:`,
-`Personalnummer:`, `Employee No:`). There is no pattern for one, because there
-is no shape for one: without the label, a digit run is not distinguishable from
-any other. The type exists so that a labelled employee number is filed
-correctly instead of being claimed by the phone pattern.
+`Personalnummer:`, `Employee No:`, `Betriebsstättennr.`, `Badge`). There is no
+pattern for one, because there is no shape for one: without the label, a digit
+run is not distinguishable from any other. The type exists so that a labelled
+employee number is filed correctly instead of being claimed by the phone
+pattern.
+
+### What a label in front of a value decides
+
+A label touching the left edge of a value decides what that value is called.
+The label may be the abbreviation or the word it abbreviates — `BSN:` and
+`Burgerservicenummer:` both reach `NATIONAL_ID` — and it may be the official
+name in the document's own language:
+
+| label | type |
+|---|---|
+| `Companies House Registration:`, `Company Registration Number:` | `CHAMBER_OF_COMMERCE` |
+| `Sozialversicherungsnummer:` | `SSN` |
+| `Passport No.:`, `Paspoortnummer:` | `PASSPORT` |
+| `AGB-code:`, `LANR`, `GMC Number:` | `HEALTHCARE_PROVIDER` |
+| `Medical Card No.:` | `HEALTH_INSURANCE` |
+| `sort code`, `account number` | `BANK_ACCOUNT` |
+| `TAN-activatiecode`, `activation code` | `SECRET` |
+
+A label can also *rule a type out*. A four-digit run is not a postal code when
+a founding or payment participle introduces it (`Opgericht in 2016`,
+`Fondée en 2017`) or when it sits in a telephone parenthetical (`(toest. 3841)`,
+`(ext. 2219)`). Postal codes that merely look like years are unaffected —
+Antwerp's `2018` in `rustige ligging in 2018` is still a `POSTAL_CODE`.
+
+A label never moves a span; it only decides the label. Which characters are
+masked is unchanged either way.
 
 For custom patterns, `entityType` is a plain string (e.g. `"EMPLOYEE_ID"`).
 
+## Cloud tier
+
+> **Status: private alpha.** The cloud tier is in closed testing — it is **not**
+> in public beta and is not generally available. Keys are issued to alpha
+> participants only, and the request/response surface may still change between
+> releases. The rules engine below is unaffected and is the supported path:
+> `mode="rules"` is the default and carries no alpha caveat.
+
+The rule engine catches what has a shape: IBANs, national IDs, phone numbers,
+anything with a checksum. It cannot catch what does not — a person's name, an
+employer, a diagnosis, a job title. The cloud tier adds a fine-tuned model
+asked only *what did the rules miss?*
+
+```ts
+import { configure, redactAsync } from "euredact";
+
+configure({ apiKey: "erk_..." });               // or set EUREDACT_API_KEY
+const result = await redactAsync(text, { countries: ["BE"], mode: "cloud" });
+
+result.source;                                   // "cloud"
+result.detections.map(d => [d.entityType, d.text]);
+// [["PERSON_NAME", "Bas Verhoeven"], ["PHONE", "+32 ..."]]
+```
+
+**`redact()` is synchronous and cannot serve the cloud tier**, so
+`redact(text, { mode: "cloud" })` throws and names `redactAsync`. It never
+falls back to rules-only output: a caller who believes names and diagnoses were
+checked, and ships a document that only had its phone numbers masked, is the
+one failure this library must not have.
+
+`redactAsync` with `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.
+
+Retries carry an `Idempotency-Key`, so a retry after a timeout cannot bill
+twice. `Retry-After` is obeyed. A document that outlives the service's sync
+window is polled transparently. Oversized input rejects with `TooLargeError`
+(413): the service refuses it rather than chunking, because the model has never
+seen a chunk boundary.
+
+Options the service cannot honour reject rather than being ignored: multiple
+`countries`, `countryHint`, `context`/`chunkOffset` and `referentialIntegrity`.
+
+The package stays **zero-dependency** — the client uses the platform's own
+`fetch`. Node 18+ provides one; on Node 16 the rules engine is unaffected and a
+`fetchImpl` can be supplied.
+
+## `NAME` is now `PERSON_NAME`
+
+The canonical type name is `PERSON_NAME`; `NAME` is a legacy alias, exactly as
+`IBAN` aliases `BANK_ACCOUNT`. The placeholder written into redacted text is
+`[PERSON_NAME]`.
+
+Nothing could have depended on the old value: the type is cloud-only and the
+cloud tier was stubbed until this release, so it was never emitted. Code
+matching the *string* `"NAME"` should be updated; `LEGACY_TYPE_ALIASES`
+publishes the mapping, and `STREET_ADDRESS` → `ADDRESS` and
+`NATIONALITY_ETHNICITY` → `SENSITIVE_ATTRIBUTE` are recognised the same way.
+
 ## Country codes
 
 `countries` accepts **ISO 3166-1 alpha-2** codes. The two EU/VAT spellings are
@@ -287,8 +381,9 @@ redact("Rekening: BE68 5390 0754 7034", { countries: ["AT"] });
 ### Which country a value belongs to
 
 Because every pattern runs, the same digits often match several countries'
-schemes. 36.6% of national-ID values in our corpus validate under more than one
-country's checksum, so the digits alone cannot decide it — the *document* does.
+schemes. Of the national-ID values in our corpus that pass any country's checksum,
+34.7% pass more than one country's (32,827 of 94,528), so the digits alone
+cannot decide it — the *document* does.
 
 The engine infers the document's countries from entities that carry their
 country in the string, then uses that to resolve the ambiguity:
@@ -596,18 +691,24 @@ Two tiers are less obvious than they look:
 
 ## Performance
 
-Measured on one core, all 31 countries loaded, `detectDates: true`. Cost scales
-with document length, so the input size is stated rather than averaged away.
+Measured on one core (Apple Silicon M3 Pro, Node 22.12), all 31 countries
+loaded, `detectDates: true`, cache off, over two cohorts sampled evenly from the
+corpus: 3,000 distinct short records and 611 distinct real documents. Median per
+document, 10th–90th percentile in brackets:
 
 | Input | Latency | Throughput |
 |---|---:|---:|
-| Short record (186 chars) | 155 µs | 6,462 docs/s |
-| Real document (3,424 chars) | 1.56 ms | 643 docs/s |
+| Short record (~190 chars) | 154 µs <br><sub>89 – 237</sub> | 6,494 docs/s |
+| Real document (~3,450 chars) | 1.43 ms <br><sub>1.04 – 1.96</sub> | 699 docs/s |
+
+Cost tracks identifier density rather than length: the per-candidate cue and
+suppressor checks dominate, so a form-like document dense in national IDs costs
+several times an ordinary chat log of the same size.
 
 No optional accelerator is needed or offered. The Python SDK ships an
 `[fast]` extra (RE2 / Aho-Corasick) because CPython's regex engine is the
 bottleneck there; V8's has literal prefilters that make it unnecessary here.
-Measured on the same 611 documents, this SDK runs about 3× faster than the
+Measured on the same 611 documents, this SDK runs about 6–7× faster than the
 accelerated Python path, so adding a native addon — and with it the loss of
 bundler, edge-runtime and Deno compatibility — would buy nothing.
 

package/dist/cjs/cloud/client.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * [CLOUD EXTENSION] The cloud client.
+ *
+ * Speaks to the euRedact inference service: a deterministic rules engine
+ * followed by a fine-tuned model asked only *what did the rules miss?* The
+ * service returns both the redacted document and located spans, so this
+ * module's job is transport and translation, not detection.
+ *
+ * Three things it hides from the caller:
+ *
+ * - **Whether the document finished inside the service's sync window.** A short
+ *   document comes back on the original request; a long one, or one arriving
+ *   while a GPU node is cold, returns a job handle and is polled. Callers
+ *   should never write that branch, so `redact()` resolves either way.
+ * - **Retries.** Every request carries an `Idempotency-Key`, so a retry after a
+ *   timeout cannot produce a second job or a second usage row.
+ * - **`Retry-After`.** When the service says how long to wait, that is obeyed
+ *   rather than second-guessed with a backoff curve.
+ *
+ * Zero dependencies, like the rest of the package: this uses the platform's
+ * own `fetch`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudClient = void 0;
+const config_js_1 = require("./config.js");
+const errors_js_1 = require("./errors.js");
+const types_js_1 = require("../types.js");
+const RETRY_STATUS = new Set([429, 500, 502, 503, 504]);
+const MAX_BACKOFF_MS = 30_000;
+function requireFetch(supplied) {
+    const impl = supplied ?? globalThis.fetch;
+    if (typeof impl !== "function") {
+        throw new errors_js_1.NotConfiguredError("the cloud tier needs a global fetch. Node 18+ provides one; on Node 16 " +
+            "supply one via the fetchImpl option or install a polyfill.");
+    }
+    return impl;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function retryAfterMs(headers) {
+    const raw = headers?.get("Retry-After");
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    // The HTTP-date form is legal too; fall back to backoff rather than parse it.
+    return Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : null;
+}
+/**
+ * Full jitter. A synchronised retry storm from many clients is how a
+ * recovering service is knocked back over.
+ */
+function backoffMs(attempt, retryAfter) {
+    if (retryAfter !== null)
+        return Math.min(retryAfter, MAX_BACKOFF_MS);
+    return Math.min(MAX_BACKOFF_MS, Math.random() * 2 ** attempt * 1000);
+}
+function uuid() {
+    const c = globalThis.crypto;
+    if (c && typeof c.randomUUID === "function")
+        return c.randomUUID();
+    return `idem-${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+}
+/**
+ * Canon name -> EntityType, tolerating one this build has not heard of.
+ *
+ * An unknown type is passed through as a plain string rather than dropped:
+ * `Detection.entityType` is `EntityType | string` precisely so a client one
+ * release behind the service does not silently lose a whole category of PII.
+ */
+function toEntityType(raw) {
+    const canonical = (0, types_js_1.canonicalType)(raw);
+    const known = Object.values(types_js_1.EntityType).includes(canonical);
+    return known ? canonical : canonical;
+}
+function toResult(payload, text) {
+    const detections = (payload.entities ?? []).map(span => ({
+        entityType: toEntityType(span.type),
+        start: span.start,
+        end: span.end,
+        text: span.text,
+        source: span.source === "model" ? types_js_1.DetectionSource.CLOUD : types_js_1.DetectionSource.RULES,
+        country: null,
+        confidence: span.confidence ?? "high",
+    }));
+    detections.sort((a, b) => a.start - b.start || b.end - a.end);
+    return {
+        redactedText: payload.redacted_text ?? text,
+        detections,
+        source: "cloud",
+        degraded: false,
+        inferredCountries: [],
+        evidence: [],
+        detectionMode: "declared",
+    };
+}
+class CloudClient {
+    config;
+    constructor(config) {
+        const resolved = config ?? (0, config_js_1.getConfig)();
+        if (resolved === null)
+            throw new errors_js_1.NotConfiguredError();
+        this.config = resolved;
+    }
+    headers(idempotencyKey) {
+        return {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "Content-Type": "application/json",
+            // A retry after a timeout must not create a second job or a second usage
+            // row. The key is per logical document, not per attempt.
+            "Idempotency-Key": idempotencyKey,
+            ...this.config.headers,
+        };
+    }
+    raiseFor(status, payload) {
+        const message = payload.error ?? `HTTP ${status}`;
+        const detail = payload.detail ?? {};
+        if (status === 401)
+            throw new errors_js_1.CloudError(`authentication failed: ${message}`, status);
+        if (status === 413)
+            throw new errors_js_1.TooLargeError(message, status, detail);
+        if (status === 429)
+            throw new errors_js_1.QuotaExceededError(message, status, detail);
+        throw new errors_js_1.CloudError(message, status, detail);
+    }
+    async redact(text, options) {
+        const doFetch = requireFetch(options.fetchImpl);
+        const key = options.idempotencyKey ?? uuid();
+        const body = JSON.stringify({
+            text,
+            country: options.country.toUpperCase(),
+            language: options.language ?? "",
+            priority: options.priority ?? "interactive",
+            rules_only: options.rulesOnly ?? false,
+        });
+        let attempt = 0;
+        for (;;) {
+            let response;
+            let payload = {};
+            try {
+                response = await this.withTimeout(doFetch, `${this.config.baseUrl}/v1/redact`, {
+                    method: "POST",
+                    headers: this.headers(key),
+                    body,
+                });
+                payload = await readJson(response);
+            }
+            catch (e) {
+                if (attempt >= this.config.maxRetries) {
+                    throw new errors_js_1.CloudError(`cloud request failed: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            if (response) {
+                if (response.status === 202) {
+                    // Outlived the sync window. Location is where the answer will appear;
+                    // polling it is this client's job, not the caller's.
+                    const location = response.headers.get("Location") ??
+                        payload.location ??
+                        `/v1/jobs/${payload.job_id ?? ""}`;
+                    return toResult(await this.poll(doFetch, location, key), text);
+                }
+                if (response.status === 200)
+                    return toResult(payload, text);
+                if (!RETRY_STATUS.has(response.status) || attempt >= this.config.maxRetries) {
+                    this.raiseFor(response.status, payload);
+                }
+            }
+            await sleep(backoffMs(attempt, retryAfterMs(response?.headers)));
+            attempt++;
+        }
+    }
+    async poll(doFetch, location, key) {
+        const url = location.startsWith("http")
+            ? location
+            : `${this.config.baseUrl}${location}`;
+        const deadline = Date.now() + this.config.pollTimeoutMs;
+        let delay = 500;
+        for (;;) {
+            const response = await this.withTimeout(doFetch, url, {
+                method: "GET",
+                headers: this.headers(key),
+            });
+            const payload = await readJson(response);
+            if (response.status === 200 && payload.redacted_text !== undefined) {
+                return payload;
+            }
+            if (response.status !== 200 && !RETRY_STATUS.has(response.status)) {
+                this.raiseFor(response.status, payload);
+            }
+            if (Date.now() >= deadline) {
+                throw new errors_js_1.CloudError(`document did not complete within ${Math.round(this.config.pollTimeoutMs / 1000)}s (${url})`);
+            }
+            const after = retryAfterMs(response.headers);
+            await sleep(after ?? delay);
+            delay = Math.min(delay * 1.5, 5000);
+        }
+    }
+    async withTimeout(doFetch, url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            return await doFetch(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.CloudClient = CloudClient;
+async function readJson(response) {
+    try {
+        const data = await response.json();
+        return data && typeof data === "object" ? data : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/cjs/cloud/config.js

@@ -0,0 +1,57 @@
+"use strict";
+/** [CLOUD EXTENSION] Cloud tier configuration. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_RETRIES = exports.DEFAULT_POLL_TIMEOUT_MS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_BASE_URL = void 0;
+exports.configure = configure;
+exports.getConfig = getConfig;
+exports.reset = reset;
+exports.DEFAULT_BASE_URL = "https://api.euredact.dev";
+/**
+ * How long to wait for a single document. The service holds a connection open
+ * for its sync window and then hands back a job handle, so this has to exceed
+ * that window or the client abandons requests the service is about to answer.
+ */
+exports.DEFAULT_TIMEOUT_MS = 90_000;
+/**
+ * Total wall-clock budget for a document that outlives the sync window and has
+ * to be polled. Cold-starting a GPU node and loading an ~18 GB checkpoint takes
+ * minutes, and an async job absorbs that invisibly — but not forever.
+ */
+exports.DEFAULT_POLL_TIMEOUT_MS = 900_000;
+exports.DEFAULT_MAX_RETRIES = 3;
+let config = null;
+/** Read an env var where there is an environment to read. Browsers have none. */
+function env(name) {
+    const proc = globalThis.process;
+    return proc?.env?.[name];
+}
+/**
+ * Configure the cloud tier.
+ *
+ * Falls back to `EUREDACT_API_KEY` and `EUREDACT_BASE_URL` so a key never has
+ * to be written into source to get started.
+ */
+function configure(options = {}) {
+    const apiKey = options.apiKey ?? env("EUREDACT_API_KEY") ?? "";
+    if (!apiKey) {
+        throw new Error("no API key: pass configure({ apiKey }) or set EUREDACT_API_KEY");
+    }
+    config = {
+        apiKey,
+        baseUrl: (options.baseUrl ?? env("EUREDACT_BASE_URL") ?? exports.DEFAULT_BASE_URL)
+            .replace(/\/+$/, ""),
+        timeoutMs: options.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS,
+        pollTimeoutMs: options.pollTimeoutMs ?? exports.DEFAULT_POLL_TIMEOUT_MS,
+        maxRetries: options.maxRetries ?? exports.DEFAULT_MAX_RETRIES,
+        headers: { ...(options.headers ?? {}) },
+    };
+    return config;
+}
+/** The active configuration, or null. Never throws. */
+function getConfig() {
+    return config;
+}
+/** Forget the configuration. Mainly for tests. */
+function reset() {
+    config = null;
+}

package/dist/cjs/cloud/errors.js

@@ -0,0 +1,55 @@
+"use strict";
+/** [CLOUD EXTENSION] Errors the cloud tier can raise. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TooLargeError = exports.QuotaExceededError = exports.NotConfiguredError = exports.CloudError = void 0;
+class CloudError extends Error {
+    status;
+    detail;
+    constructor(message, status, detail) {
+        super(message);
+        this.name = "CloudError";
+        this.status = status;
+        this.detail = detail ?? {};
+    }
+}
+exports.CloudError = CloudError;
+/**
+ * Raised when the cloud tier is used without configuration.
+ *
+ * Deliberately an error rather than a quiet fallback to rules-only output.
+ * `mode: "cloud"` that silently returns rules-only results is the worst failure
+ * this library can have: the caller believes names, employers and diagnoses
+ * were checked, sees a plausible redacted document, and ships it with the PII
+ * still in it.
+ */
+class NotConfiguredError extends CloudError {
+    constructor(message) {
+        super(message ??
+            "Cloud tier not configured. Call euredact.configure({ apiKey }) first, " +
+                "or set EUREDACT_API_KEY.");
+        this.name = "NotConfiguredError";
+    }
+}
+exports.NotConfiguredError = NotConfiguredError;
+/** 429 after retries were exhausted. */
+class QuotaExceededError extends CloudError {
+    constructor(message, status, detail) {
+        super(message, status, detail);
+        this.name = "QuotaExceededError";
+    }
+}
+exports.QuotaExceededError = QuotaExceededError;
+/**
+ * 413. The document is over the service's input cap.
+ *
+ * Permanent and not retryable. The model has never seen a chunk boundary, so
+ * the service refuses oversized input rather than splitting it and changing the
+ * accuracy story silently.
+ */
+class TooLargeError extends CloudError {
+    constructor(message, status, detail) {
+        super(message, status, detail);
+        this.name = "TooLargeError";
+    }
+}
+exports.TooLargeError = TooLargeError;

package/dist/cjs/cloud/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * [CLOUD EXTENSION] Cloud tier — rules engine plus a fine-tuned model.
+ *
+ * The rule engine catches what has a shape: IBANs, national IDs, phone
+ * numbers, anything with a checksum. It cannot catch what does not — a
+ * person's name, an employer, a diagnosis, a job title. Those are what the
+ * cloud tier adds, and the `EntityType` members marked `[CLOUD EXTENSION]` are
+ * exactly that gap.
+ *
+ * ```ts
+ * import { configure, redactAsync } from "euredact";
+ *
+ * configure({ apiKey: "erk_..." });
+ * const result = await redactAsync(text, { countries: ["BE"], mode: "cloud" });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TooLargeError = exports.QuotaExceededError = exports.NotConfiguredError = exports.CloudError = exports.DEFAULT_BASE_URL = exports.reset = exports.getConfig = exports.configure = exports.CloudClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "CloudClient", { enumerable: true, get: function () { return client_js_1.CloudClient; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return config_js_1.configure; } });
+Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return config_js_1.getConfig; } });
+Object.defineProperty(exports, "reset", { enumerable: true, get: function () { return config_js_1.reset; } });
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return config_js_1.DEFAULT_BASE_URL; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "CloudError", { enumerable: true, get: function () { return errors_js_1.CloudError; } });
+Object.defineProperty(exports, "NotConfiguredError", { enumerable: true, get: function () { return errors_js_1.NotConfiguredError; } });
+Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return errors_js_1.QuotaExceededError; } });
+Object.defineProperty(exports, "TooLargeError", { enumerable: true, get: function () { return errors_js_1.TooLargeError; } });

package/dist/cjs/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEED_BIC6_PREFIXES = exports.getBicRegistry = exports.setBicRegistry = exports.COUNTRY_CONFIGS = exports.EuRedact = exports.DocumentContext = exports.LEGACY_TYPE_ALIASES = exports.DetectionSource = exports.EntityType = void 0;
+exports.TooLargeError = exports.QuotaExceededError = exports.NotConfiguredError = exports.CloudError = exports.CloudClient = exports.getConfig = exports.configure = exports.SEED_BIC6_PREFIXES = exports.getBicRegistry = exports.setBicRegistry = exports.COUNTRY_CONFIGS = exports.EuRedact = exports.DocumentContext = exports.canonicalType = exports.LEGACY_TYPE_ALIASES = exports.DetectionSource = exports.EntityType = void 0;
 exports.availableCountries = availableCountries;
 exports.redact = redact;
+exports.redactAsync = redactAsync;
 exports.addCustomPattern = addCustomPattern;
 exports.clear = clear;
 exports.redactBatch = redactBatch;
@@ -10,6 +11,7 @@ var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "EntityType", { enumerable: true, get: function () { return types_js_1.EntityType; } });
 Object.defineProperty(exports, "DetectionSource", { enumerable: true, get: function () { return types_js_1.DetectionSource; } });
 Object.defineProperty(exports, "LEGACY_TYPE_ALIASES", { enumerable: true, get: function () { return types_js_1.LEGACY_TYPE_ALIASES; } });
+Object.defineProperty(exports, "canonicalType", { enumerable: true, get: function () { return types_js_1.canonicalType; } });
 var context_js_1 = require("./rules/context.js");
 Object.defineProperty(exports, "DocumentContext", { enumerable: true, get: function () { return context_js_1.DocumentContext; } });
 var sdk_js_1 = require("./sdk.js");
@@ -20,8 +22,16 @@ var bicRegistry_js_1 = require("./rules/bicRegistry.js");
 Object.defineProperty(exports, "setBicRegistry", { enumerable: true, get: function () { return bicRegistry_js_1.setBicRegistry; } });
 Object.defineProperty(exports, "getBicRegistry", { enumerable: true, get: function () { return bicRegistry_js_1.getBicRegistry; } });
 Object.defineProperty(exports, "SEED_BIC6_PREFIXES", { enumerable: true, get: function () { return bicRegistry_js_1.SEED_BIC6_PREFIXES; } });
+var index_js_2 = require("./cloud/index.js");
+Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return index_js_2.configure; } });
+Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return index_js_2.getConfig; } });
+Object.defineProperty(exports, "CloudClient", { enumerable: true, get: function () { return index_js_2.CloudClient; } });
+Object.defineProperty(exports, "CloudError", { enumerable: true, get: function () { return index_js_2.CloudError; } });
+Object.defineProperty(exports, "NotConfiguredError", { enumerable: true, get: function () { return index_js_2.NotConfiguredError; } });
+Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return index_js_2.QuotaExceededError; } });
+Object.defineProperty(exports, "TooLargeError", { enumerable: true, get: function () { return index_js_2.TooLargeError; } });
 const sdk_js_2 = require("./sdk.js");
-const index_js_2 = require("./rules/countries/index.js");
+const index_js_3 = require("./rules/countries/index.js");
 let _instance = null;
 function getInstance() {
     if (_instance === null)
@@ -29,11 +39,20 @@ function getInstance() {
     return _instance;
 }
 function availableCountries() {
-    return Object.keys(index_js_2.COUNTRY_CONFIGS).filter(c => c !== "SHARED").sort();
+    return Object.keys(index_js_3.COUNTRY_CONFIGS).filter(c => c !== "SHARED").sort();
 }
 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.
+ */
+function redactAsync(text, options) {
+    return getInstance().redactAsync(text, options);
+}
 function addCustomPattern(name, pattern) {
     getInstance().addCustomPattern(name, pattern);
 }