euredact 0.6.0 → 0.7.1

package/README.md

@@ -34,7 +34,7 @@ console.log(result.detections);
 ## Features
 
 - **31 European countries** with country-specific patterns
-- **41 PII entity types** (30 from the rules engine, 11 from the
+- **40 PII entity types** (30 from the rules engine, 10 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
@@ -82,7 +82,8 @@ console.log(result.detections);
 | keep relationships visible across a whole session | `{ referentialIntegrity: true }` |
 | never redact my own company name or addresses | `{ allowlist: [...] }`, or `new EuRedact({ allowlist })` |
 | never redact anything at my own domain | `{ allowlistDomains: ["acme.be"] }` |
-| audit what the allowlist kept in the document | `result.exempted` |
+| leave whole types in the text (job titles, amounts) | `{ excludeTypes: ["JOB_TITLE", "FINANCIAL_AMOUNT"] }`, or `new EuRedact({ excludeTypes })` — see [Excluding entity types](#excluding-entity-types) |
+| audit what the allowlist or `excludeTypes` kept in the document | `result.exempted` |
 | catch person names, employers, job titles, diagnoses | `redactAsync(text, { mode: "cloud" })` — see [Cloud tier](#cloud-tier) |
 | include dates of birth | `{ detectDates: true }` |
 | redact a document too large for one call | `context` + `chunkOffset` — see [Chunked documents](#chunked-documents) |
@@ -112,8 +113,10 @@ interface RedactOptions {
   tokenize?: boolean;               // reversible tokens, EMAIL_K7Q2
   allowlist?: string[] | null;      // values never redacted
   allowlistDomains?: string[] | null; // domains never redacted (EMAIL/URL)
+  excludeTypes?: string[] | null;   // entity types neither reported nor masked
   detectDates?: boolean;            // include DOB / date of death
   cache?: boolean;                  // reuse results for identical input
+  idempotencyKey?: string;          // mode: "cloud" only; see the table below
 }
 ```
 
@@ -135,12 +138,14 @@ interface RedactOptions {
 | `tokenize` | `false` | Reversible token per value (`EMAIL_K7Q2`), with the mapping in `result.tokens` for [`restore()`](#restoretext-tokens). Unique to the **call**. Cannot be combined with `referentialIntegrity`. See [Reversible tokenization](#reversible-tokenization). |
 | `allowlist` | `null` | Values never to redact, whole-span and case-insensitive, merged with the instance's list. Structured identifiers (IBAN, phone, VAT, …) also match across spacing and hyphenation. Applies to cloud-tier types too. See [Allowlist](#allowlist). |
 | `allowlistDomains` | `null` | Domains whose addresses are never redacted, e.g. `["acme.be"]`. Applies to `EMAIL` and `URL` only, and covers subdomains. See [Allowlist](#allowlist). |
+| `excludeTypes` | `null` | Entity types neither reported nor masked, e.g. `["JOB_TITLE"]`; merged with the instance's list. Unknown names throw. See [Excluding entity types](#excluding-entity-types). |
 
 **Long documents and tiers**
 
 | Parameter | Default | Description |
 |---|---|---|
 | `mode` | `"rules"` | `"rules"` runs locally and synchronously. `"cloud"` must go through [`redactAsync()`](#redactasynctext-options) — `redact()` is synchronous and a network call cannot be. See [Cloud tier](#cloud-tier). |
+| `idempotencyKey` | generated | `mode: "cloud"` only (through `redactAsync`): sent as the request's `Idempotency-Key`, so the same key returns the same job instead of running and billing the document again. Throws in rules mode. See [What the service said](#what-the-service-said-resultcloud). |
 | `context` | `null` | Share country evidence across the chunks of one document. Pass the same `DocumentContext` to every chunk. Disables the cache. See [Chunked documents](#chunked-documents). |
 | `chunkOffset` | `0` | Where this chunk starts in the whole document. Only rebases spans recorded in `context`; returned detections stay relative to `text`. |
 | `cache` | `true` | Reuse the result for an identical input and configuration. |
@@ -227,6 +232,8 @@ The `EuRedact` class exposes `redact()`, `redactAsync()`, `redactBatch()`,
 new EuRedact({
   maxInputLength?: number,   // default 10_485_760 (~10 MB)
   allowlist?: string[] | null,
+  allowlistDomains?: string[] | null,
+  excludeTypes?: string[] | null,
 })
 ```
 
@@ -235,6 +242,7 @@ new EuRedact({
 | `maxInputLength` | `10_485_760` | Longest document `redact()` accepts, in characters. Above it, it throws — split the input or raise the ceiling. |
 | `allowlist` | `null` | Values never to redact, for every call on this instance. Merged with the per-call `allowlist`. See [Allowlist](#allowlist). |
 | `allowlistDomains` | `null` | Domains never to redact, for every call on this instance. |
+| `excludeTypes` | `null` | Entity types never reported or masked, for every call on this instance. See [Excluding entity types](#excluding-entity-types). |
 
 The result cache, referential-integrity labels and custom patterns are all per
 instance, which is what makes one instance per tenant the right default.
@@ -248,10 +256,18 @@ instance, which is what makes one instance per tenant the right default.
 interface RedactResult {
   redactedText: string;       // The input text with PII replaced
   detections: Detection[];    // All PII spans found
-  source: string;             // Detection backend ("rules")
+  source: string;             // "rules" or "cloud"
   degraded: boolean;          // True if the engine fell back to a simpler mode
+
+  // Country inference — see "Country-independent detection"
+  inferredCountries: Array<[string, number]>; // [country, confidence], strongest first
+  evidence: CountryEvidence[];                // every signal, with the span behind it
+  detectionMode: string;                      // "declared" if countries was passed,
+                                              // "inferred" otherwise
   tokens: Record<string, string>; // token -> original value; only with tokenize: true
-  exempted: Exemption[];          // spans the allowlist kept, with the rule that matched
+  exempted: Exemption[];          // spans the allowlist or excludeTypes kept, with the rule
+  cloud?: CloudInfo;              // mode: "cloud" only: job id, model, cost, unplaced
+                                  // findings — see "What the service said"
 }
 ```
 
@@ -265,7 +281,7 @@ interface Detection {
   text: string;                    // The matched substring
   source: DetectionSource;         // "rules" or "cloud"
   country: string | null;          // ISO code or null for shared/custom patterns
-  confidence: string;              // "high" | "medium" | "low" — see below
+  confidence: string | null;       // "high" | "medium" | "low"; null for a cloud-model span — see below
   countryConfidence?: number;      // How strongly the document supports `country`,
                                    // in [0, 1]. 0 means the attribution rests on
                                    // a checksum alone.
@@ -282,6 +298,7 @@ about whether the span is masked — every detection is, at every level.
 | `"high"` | a pattern matched and, where one exists, its checksum passed |
 | `"medium"` | the type comes from a label touching the span, because no pattern of that type claimed it — `Αρ. Ταυτότητας: 00892341` is a `NATIONAL_ID` although nothing can checksum it |
 | `"low"` | a pattern matched, its checksum *failed*, and the document labels the span as that very type — `Rijksregisternummer: 85.03.19-284.73` is a national number with a bad check digit |
+| `null` | a span the cloud model found (`source` is `cloud`). The model reports no confidence, so none is invented: a model span is not checksum-backed, and filtering on `"high"` keeps rules detections only *(rules-engine#108)* |
 
 Filter on it when you need only checksum-backed detections:
 
@@ -294,24 +311,6 @@ identifier: the shape and the label agree, the check digit does not. Earlier
 versions dropped these, which meant a redaction library printed in full an
 identifier it had recognised and rejected.
 
-#### `RedactResult`
-
-```ts
-interface RedactResult {
-  redactedText: string;
-  detections: Detection[];
-  source: string;
-  degraded: boolean;
-
-  // Country inference — see "Country-independent detection"
-  inferredCountries: Array<[string, number]>; // [country, confidence], strongest first
-  evidence: CountryEvidence[];                // every signal, with the span behind it
-  detectionMode: string;                      // "declared" if countries was passed,
-                                              // "inferred" otherwise
-  tokens: Record<string, string>;             // token -> original value; only with tokenize: true
-}
-```
-
 #### `EntityType`
 
 String enum with all supported PII categories:
@@ -330,10 +329,15 @@ 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
+BIOMETRIC_REF     FINANCIAL_AMOUNT  QUASI_IDENTIFIER  URL
 ```
 
+`SECRET` is the one type for credentials, whichever layer finds them: the rules
+engine's shaped keys and tokens, and the cloud model's prose passwords and
+connection-string secrets, which the service labels `CREDENTIAL`. The SDK
+reports those as `SECRET`, and `CREDENTIAL` remains only as a legacy alias of
+it (rules-engine#111).
+
 `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:`, `Betriebsstättennr.`, `Badge`). There is no
@@ -420,8 +424,10 @@ const results = await Promise.all(
 );
 ```
 
-Bound that yourself if the batch is large — the service enforces quotas and will
-answer `429`, which the client honours via `Retry-After`.
+Bound that yourself if the batch is large. The service's rate limit answers
+`429`, which the client retries, honouring `Retry-After`, before throwing
+`RateLimitedError`. A `429` for the daily quota throws `QuotaExceededError`
+at once: it will not clear before the day does.
 
 ### Reuse one instance
 
@@ -473,6 +479,11 @@ result.detections.map(d => [d.entityType, d.text]);
 // [["PERSON_NAME", "Bas Verhoeven"], ["PHONE", "+32 ..."]]
 ```
 
+The endpoint defaults to `https://api.euredact.dev`; `baseUrl` (or
+`EUREDACT_BASE_URL`) overrides it. It must be `https://`: plain `http://` is
+refused except to `localhost`, `127.0.0.1` or `::1`, so the key and the text
+never travel unencrypted.
+
 **`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
@@ -590,6 +601,340 @@ either, no hosted model can help; run one yourself against
 `local.redactedText`.
 
 
+### What the service said: `result.cloud`
+
+A cloud result carries `cloud`, what the service reported beside the spans;
+it is absent on a rules-only result.
+
+```ts
+const result = await redactAsync(text, {
+  countries: ["BE"], mode: "cloud", idempotencyKey: "invoice-2291-v1",
+});
+result.cloud?.jobId;         // support, Jobs.retrieve, replays
+result.cloud?.modelVersion;  // the model that answered; null when only rules ran
+for (const item of result.cloud?.unlocated ?? []) console.log(item.entityType, item.text);
+const usage = result.cloud?.usage;
+if (usage) {
+  const { tokens, billingRate, credits, factors } = usage;
+  for (const f of factors) console.log(f.code, f.types ?? "", f.detail);
+}
+```
+
+- **`idempotencyKey`** is sent as the request's `Idempotency-Key`: the same key
+  returns the same job instead of running and billing the document again. One
+  is generated per call when omitted. It applies to `mode: "cloud"` only.
+- **`usage`** is the total the request was charged and the reasons for it, never
+  a cost per step. `credits` is `round(tokens × billingRate)`, the formula the
+  service debits by. The factor codes are `rules_only`, `document_length`,
+  `instructions`, `dense_document`, `special_category_check` (with the `types`
+  that triggered it), `long_document` and `batch_rate`; a code added later
+  still arrives, as its string. Absent when the service does not report it or
+  reported it malformed: a cost report never fails a redaction.
+- **`unlocated`** lists what the model found but could not match to a position
+  in the text it was sent. Nothing was masked for these.
+- **Batch documents** carry `modelVersion` and `unlocated`; no `jobId` or
+  `usage`, which belong to the batch (`batch.tokens`, `batch.creditsCharged`,
+  `batch.billingRate`).
+
+All four types are exported from `euredact`:
+
+```ts
+interface CloudInfo {
+  jobId: string | null;          // null for a batch document
+  modelVersion: string | null;   // null when only rules ran
+  usage?: Usage;                 // absent from older services, batch documents, or a malformed block
+  unlocated: Unlocated[];
+}
+
+interface Unlocated {
+  text: string;                  // what the model reported
+  entityType: EntityType | string; // e.g. "PERSON_NAME"; unknown types stay strings
+}
+
+interface Usage {
+  tokens: number;                // every model call the document triggered
+  billingRate: number;           // 1, or e.g. 0.75 for a batch
+  credits: number;               // round(tokens * billingRate): what was debited
+  factors: UsageFactor[];
+}
+
+interface UsageFactor {
+  code: string;                  // see the list above; new codes arrive as strings
+  detail: string;                // one sentence from the service ("" if none)
+  types?: string[];              // special_category_check only
+}
+```
+
+**Retrying safely.** Pass your own `idempotencyKey` when your code may send the
+same document twice: after a timeout of your own, from a retried queue message
+or a restarted worker. Derive it from something stable (an invoice number plus
+a version), not from a random value per attempt. A replay returns the same
+`result.cloud.jobId` and is not billed again.
+
+### Account, past jobs and the batch list
+
+Everything an API key may do on the service is reachable from the SDK. What
+needs a signed-in person (logging in, minting keys, settings, members, terms)
+is not, because a key cannot do it. Every call returns a `Promise`.
+
+| Call | Service endpoint | Resolves to |
+|---|---|---|
+| `new Account().summary()` | `GET /v1/account` | `AccountSummary` |
+| `new Account().credits()` | `GET /v1/account/credits` | `Credits` |
+| `new Account().creditHistory(limit = 50)` | `GET /v1/account/credits/history` | `CreditEntry[]`, newest first; `limit` 1–500 |
+| `new Account().usage(days = 30)` | `GET /v1/account/usage` | `UsageDay[]` |
+| `new Account().usageByKey(days = 30)` | `GET /v1/account/usage/by-key` | `KeyUsage[]` |
+| `new Account().keys()` | `GET /v1/account/keys` | `ApiKey[]` |
+| `new Account().revokeKey(keyId)` | `POST /v1/account/keys/{id}/revoke` | `KeyRevocation` |
+| `new Jobs().retrieve(jobId)` | `GET /v1/jobs/{id}` | `Job` |
+| `new Batches().list(limit = 20)` | `GET /v1/batches` | `Batch[]`, newest first; `limit` 1–100 |
+
+```ts
+import { Account, Batches, Jobs } from "euredact";
+
+const account = new Account();
+const summary = await account.summary();
+if (summary.quotaRemaining !== null && summary.quotaRemaining < 100) {
+  console.log(`${summary.quotaRemaining} documents left today`);
+}
+console.log((await account.credits()).balance);
+for (const day of await account.usage(7)) console.log(day.day, day.documents, day.tokens);
+for (const key of await account.keys()) console.log(key.id, key.name, key.active, key.lastUsedAt);
+
+const job = await new Jobs().retrieve("job-7f3a…");
+if (job.result) console.log(job.result.redactedText);
+
+for (const batch of await new Batches().list(20)) {
+  console.log(batch.id, batch.status, batch.documents, batch.creditsCharged);
+}
+```
+
+#### Creating the clients
+
+`Account` and `Jobs` read the configuration `configure()` set (or
+`EUREDACT_API_KEY`). Both take two optional arguments:
+`new Account(config?, { fetchImpl? })`. `config` is a `CloudConfig` of its own,
+for a second key or another endpoint: a plain object with `apiKey`, `baseUrl`,
+`timeoutMs`, `pollTimeoutMs`, `maxRetries` and `headers`, checked for an
+`https://` base URL like `configure()` does; `fetchImpl` replaces the platform `fetch`,
+for a proxy or a mock in your tests. (`Batches` takes the same two inside its
+options object: `new Batches({ config, fetchImpl })`.) There is nothing to close.
+They need a global `fetch`: Node 18+, or a browser, or pass `fetchImpl`.
+
+#### What each call resolves to
+
+Each value has `raw`, the service's JSON as received, so a field the SDK does
+not type yet is still reachable; every field is `null` when the service left
+it out or sent the wrong type, rather than the call failing.
+
+```ts
+interface AccountSummary {
+  tenantId: string | null; tenantName: string | null; active: boolean | null;
+  memberSince: string | null;        // ISO date
+  role: string | null;
+  retentionMode: string | null;      // "ttl", or "none": text discarded on delivery
+  payloadTtlHours: number | null;    // 0 under "none"
+  documentsToday: number | null; documentsThisMonth: number | null;
+  tokensThisMonth: number | null; failures24h: number | null;
+  dailyQuota: number | null;         // null: no daily quota on this account
+  quotaRemaining: number | null;
+  activeKeys: number | null;
+  batchesAvailable: boolean | null;  // batches need retention ("ttl")
+  raw: Record<string, unknown>;
+}
+interface Credits { balance: number | null; granted: number | null; spent: number | null;
+                    unit: string | null /* "tokens" */; raw: Record<string, unknown> }
+interface CreditEntry {              // rolled up per minute, reason and direction
+  at: string | null; delta: number | null /* negative for a debit */;
+  reason: string | null; count: number | null; jobId: string | null; sourceRef: string | null;
+  raw: Record<string, unknown>;
+}
+interface UsageDay { day: string | null; documents: number | null; tokens: number | null;
+                     failures: number | null; rulesOnly: number | null; raw: Record<string, unknown> }
+interface KeyUsage {                 // the busiest keys one by one; the rest in one entry, keyId null
+  keyId: number | null; name: string | null;
+  documents: number | null; tokens: number | null; failures: number | null;
+  series: UsageDay[]; raw: Record<string, unknown>;
+}
+interface ApiKey {                   // never the secret: shown once, when minted
+  id: number | null; name: string | null; createdBy: string | null;
+  createdAt: string | null; lastUsedAt: string | null; revokedAt: string | null;
+  active: boolean | null; raw: Record<string, unknown>;
+}
+interface KeyRevocation {
+  id: number | null; keysRemaining: number | null;
+  lockedOut: boolean | null;         // true: no active key left; mint one in the console
+  selfRevoked: boolean | null;       // true: you revoked the key this client uses
+  raw: Record<string, unknown>;
+}
+interface Job {
+  jobId: string;
+  status: string;                    // "queued", "running" or "succeeded"
+  createdAt: string | null;
+  result: RedactResult | null;       // set once succeeded
+  raw: Record<string, unknown>;
+}
+```
+
+`Batch` gained four fields beside `id`, `status`, `counts` and the timestamps:
+`documents`, `tokens` (`{ prompt, completion }`), `creditsCharged` and
+`billingRate` (e.g. `0.75`).
+
+#### Retrieving a job
+
+`redactAsync(text, { mode: "cloud" })` already waits for its job, polling past
+the service's synchronous window, so most code never needs `Jobs`. It is for
+support and audits (look up `result.cloud.jobId` later) and for a job the
+client gave up polling on (`pollTimeoutMs`), which may still finish.
+
+A failed or rejected job throws (`CloudError` with status 502, `TooLargeError`)
+rather than resolving with a status. The result is over the text the service
+received: under `mode: "cloud"` that is the locally masked text, so its offsets
+and `redactedText` are not your original's. Results are kept for the account's
+retention period (`AccountSummary.payloadTtlHours`), and not at all under
+`retentionMode === "none"`; after that, `ResultExpiredError`.
+
+#### Revoking a key
+
+`revokeKey` is the one write an API key may make, for a key that leaked. It is
+sent once and never retried. Revoking the key the client itself uses succeeds
+and reports `selfRevoked: true`; every later call with it fails with status
+401. When `lockedOut` is `true`, no active key is left and only a person in the
+console can mint one.
+
+#### Handling errors
+
+All errors extend `CloudError`, which carries `status` (the HTTP status, or
+`undefined` for a network failure) and `detail` (the service's JSON detail).
+Test the specific ones first: `RateLimitedError` extends `QuotaExceededError`.
+
+```ts
+import {
+  CloudError, QuotaExceededError, RateLimitedError, TooLargeError, redactAsync,
+} from "euredact";
+
+try {
+  const result = await redactAsync(text, {
+    countries: ["BE"], mode: "cloud", idempotencyKey: `invoice-${invoice.id}-v${invoice.version}`,
+  });
+} catch (err) {
+  if (err instanceof RateLimitedError) {
+    // rate limit still hit after every retry: back off, then retry with the same key
+  } else if (err instanceof QuotaExceededError) {
+    // daily quota used up (err.detail.used, err.detail.limit): wait for tomorrow
+  } else if (err instanceof TooLargeError) {
+    // over the input cap: split the document and send the parts
+  } else if (err instanceof CloudError) {
+    // anything else; err.status says what
+  } else {
+    throw err;
+  }
+}
+```
+
+| Error | Status | When | Retried by the SDK |
+|---|---|---|---|
+| `NotConfiguredError` | — | no API key configured, or no global `fetch` | no |
+| `CloudError` | 401 | the key is wrong or revoked | no |
+| `CloudError` | 403 | the service refused the call. Account calls are accepted with an API key while the service does not require a browser `Origin`; if that changes they answer 403 | no |
+| `CloudError` | 403 | `Batches.create` on a workspace without retention: `detail.code === "retention_required"` (see [Batches](#batches)) | no |
+| `NotFoundError` | 404 | no such job, batch or key — or another account's; also every batch call, `list()` included, while batches are not enabled on the service (`batches_not_enabled`) | no |
+| `CloudError` | 409 | `revokeKey` on a key already revoked | no |
+| `ResultExpiredError` | 410 | the job's result is past retention | no |
+| `TooLargeError` | 413 | the document is over the input cap; also a rejected job | no |
+| `QuotaExceededError` | 429 | the daily document quota is used up | **no**: it will not clear before the day does |
+| `RateLimitedError` | 429 | the edge's rate limit, still hit after every retry | yes, `maxRetries` times with backoff |
+| `CloudError` | 5xx, `undefined` | the service or the network failed | yes for reads and `redactAsync`; never for `revokeKey` |
+
+`NotFoundError`, `ResultExpiredError` and `RateLimitedError` are exported from
+`euredact` alongside the others.
+
+**Availability:** like the rest of the cloud tier, these calls are in private
+alpha, and the response shapes may still change between releases. The batch
+calls, `list()` included, answer `NotFoundError` until batches are enabled on
+the service (see [Batches](#batches)).
+
+### Batches
+
+> **Availability:** private alpha, like the rest of the cloud tier. Batches
+> need **retention** on the workspace (see below); while batches are not
+> enabled on the service, every batch call answers `NotFoundError`
+> (`batches_not_enabled`).
+
+A batch hands up to 5,000 documents to the cloud tier and collects the answers
+within 24 hours, at a lower price and without your plan's concurrency limit.
+It keeps the same promise as `mode: "cloud"`: each document is masked **on
+your machine**, and only the masked text is uploaded. What is needed to map the
+answers back stays in a **local batch file**, `~/.euredact/batches/<batchId>.json`
+(directory `0700`, file `0600`): the originals, their local detections and a
+SHA-256 of the masked text sent. The file format is shared with the Python SDK,
+so a batch created by one can be resolved by the other.
+
+```ts
+import { configure, Batches } from "euredact";
+
+configure({ apiKey: "erk_..." });
+const batches = new Batches();
+const batch = await batches.create([
+  { customId: "invoice-2291", text: invoiceText, countries: ["BE"] },
+  { customId: "memo-17", text: memoText, countries: ["NL"] },
+]);
+
+// Later, possibly in another process:
+const outcome = await batches.results(batch.id);
+if (outcome.status === "resolved") {
+  for (const [customId, doc] of Object.entries(outcome.documents)) {
+    console.log(customId, doc.ok ? doc.result!.redactedText : `${doc.error}: ${doc.message}`);
+  }
+}
+```
+
+**Batches need retention.** The service holds each document until it is
+processed and each result until you fetch it, so a workspace that erases
+documents on delivery (`retentionMode === "none"`, or 0 hours of retention)
+cannot create one. `create()` then throws `CloudError` with status 403 and
+`detail.code === "retention_required"`, before anything is uploaded or written
+locally. The workspace owner turns retention on in the console, on the
+**Account** tab. To check first:
+
+```ts
+import { Account, CloudError } from "euredact";
+
+if (!(await new Account().summary()).batchesAvailable) {
+  // no retention on this workspace: send the documents with mode: "cloud"
+}
+
+try {
+  await batches.create(documents);
+} catch (err) {
+  if (err instanceof CloudError && err.status === 403 && err.detail?.code === "retention_required") {
+    // ask the workspace owner to turn retention on
+  }
+  throw err;
+}
+```
+
+- **`results()`** returns `not_ended` while the batch runs and changes nothing.
+  Once it has ended it maps every document, wipes the originals and leaves a
+  text-free receipt; a second call returns `already_resolved`.
+- **Integrity.** Each masked text is rebuilt from the file and must match the
+  hash the gateway reports before a span is placed. An edited file, a missing
+  entry or no file is an error for that document (`local_mismatch`,
+  `missing_local_entry`), never the masked text passed off as a result.
+- **`pending()`**, **`retrieve(id)`**, **`cancel(id)`** (the file stays until
+  the finished documents are mapped) and **`purge(id)`**. Receipts and
+  unmapped files are cleaned up once the gateway's results expire.
+- **In a browser** there is no filesystem: pass `store`, any object with async
+  `read`, `write`, `delete` and `list`. In Node, `batchDir` moves the
+  directory. `cipher` (`encrypt`/`decrypt`) encrypts the file at rest with a
+  key you hold.
+- **Limits** checked before anything is masked or uploaded: 5,000 documents,
+  unique `customId`s of 1-64 characters from `A-Z a-z 0-9 _ . : -` (the
+  gateway's rule, exported as `CUSTOM_ID`), one country each, a 128 MB body. The 5,000-token limit
+  per document is **not** checked by the SDK: it is counted by the model's
+  tokenizer on the gateway. A document over it comes back as `too_long`, whose
+  message says so; split it and submit the parts.
+
 ## `NAME` is now `PERSON_NAME`
 
 The canonical type name is `PERSON_NAME`; `NAME` is a legacy alias, exactly as
@@ -802,14 +1147,23 @@ BIC is the only bank identifier here with **no check digit**, and characters
 | Stage | Condition | Result |
 |---|---|---|
 | Gate 0 | the token also occurs as an ordinary lowercase word in the same document | never emitted |
-| Tier 1 | registry hit on the BIC6 institution+country prefix | emitted |
+| Tier 1 | registry hit on the BIC6 institution+country prefix (your registry, or the bundled seed of major banks) | emitted |
 | Gate 2 | heading / shouted-word shape | never emitted |
-| Tier 2 | `BIC`/`SWIFT` keyword, an IBAN, or a bank block in the enclosing line, record or paragraph | emitted |
+| Tier 2 | `BIC`/`SWIFT` keyword, an IBAN, or a bank block in the enclosing line, record or paragraph | emitted — but a **letters-only** code (`BETALING`, `HOFFMANN`), unless the bundled GLEIF mapping knows the institution, also needs a `BIC`/`SWIFT` label touching it |
 | — | none of the above | never emitted |
 
-The package bundles **no licensed BIC data** — only a small seed list of BIC6
-prefixes compiled from publicly published bank data. Deployments holding a
-licensed directory install it at startup:
+The package bundles about **10,400 BIC6 prefixes** for the 31 supported countries,
+derived from the [GLEIF BIC-to-LEI mapping](https://www.gleif.org/en/lei-data/lei-mapping/download-bic-to-lei-relationship-files),
+which SWIFT develops and licenses for redistribution under the BIC/LEI Mapping
+Table License Agreement; its required notice is in `NOTICE`. They tell a real
+bank from an ordinary word next to an IBAN, but do not by themselves license a
+code in bare prose: with that many real prefixes, some words begin with one
+(`DERNIERS` → `DERN`+`IE`, an Irish institution). `scripts/refresh_bic_registry.py`
+regenerates the list; GLEIF publishes the mapping monthly.
+
+The complete SWIFTRef BIC Directory is a commercial product and is not
+bundled. Deployments holding it install it at startup, where it works like the
+seed — a hit is emitted without context:
 
 ```ts
 import { setBicRegistry } from "euredact";
@@ -819,10 +1173,10 @@ setBicRegistry(bic => myDirectory.has(bic));          // membership callable
 setBicRegistry(null);                                 // remove
 ```
 
-The registry is an **accept** signal, never a filter: a code missing from it
-falls through to the context gate and is still detected when banking context is
-present. A stale list costs a little recall on bare, contextless BICs — it
-never causes a leak. Annual review is sufficient.
+The registry is mostly an **accept** signal: a code missing from it falls
+through to the context gate and is still detected when banking context is
+present — except a letters-only code, the only shape an ordinary word can take,
+which then also needs a `BIC`/`SWIFT` label touching it (rules-engine#57).
 
 ## `IBAN` is now `BANK_ACCOUNT`
 
@@ -996,8 +1350,8 @@ and two tokenized documents never reveal that they share a value. That is the
 opposite retention model from `referentialIntegrity`, which is why the two
 cannot be combined. `redactBatch` tokenizes each text on its own.
 
-A token is `TYPE_` plus four characters from `ABCDEFGHJKLMNPQRSTUVWXYZ23456789`
-(no vowels, no `0`/`1`/`I`/`O`). Tokens are kept clear of any token-shaped
+A token is `TYPE_` plus four characters from `BCDFGHJKLMNPQRSTVWXZ23456789`
+(no vowels or `Y`, no `0`/`1`/`I`/`O`), about 615,000 suffixes. Tokens are kept clear of any token-shaped
 string already in the document, so an LLM's reply to a tokenized prompt can
 itself be redacted without `restore()` putting the wrong value back.
 `restore()` replaces every occurrence, including a token an LLM glued to other
@@ -1061,8 +1415,8 @@ sdk.redact("Mail jan@acme.be or piet@acme.be", { countries: ["NL"] }).redactedTe
 label boundary, so `acme.be` does **not** exempt `evilacme.be`. Entries may be
 written `acme.be`, `@acme.be` or `.acme.be`.
 
-There are deliberately **no wildcards**. The allowlist is the only option that
-turns redaction *off*, so an over-broad entry fails toward under-redaction and
+There are deliberately **no wildcards**. The allowlist and `excludeTypes` are
+the only options that turn redaction *off*, so an over-broad entry fails toward under-redaction and
 does so silently.
 
 ### What was exempted
@@ -1074,10 +1428,51 @@ for (const e of r.exempted) console.log(e.entityType, e.text, e.rule, e.ruleKind
 ```
 
 `Exemption` carries `entityType`, `start`, `end`, `text`, the `rule` that
-matched as you wrote it, and `ruleKind` (`"value"` or `"domain"`). An exempted
+matched as you wrote it, and `ruleKind` (`"value"`, `"domain"` or `"type"`). An exempted
 span is absent from `detections`, so `exempted` is the only record that it was
 found at all.
 
+## Excluding entity types
+
+A deployment whose taxonomy is narrower than euRedact's can switch whole types
+off instead of filtering every result itself. Excluded types are neither in
+`detections` nor masked:
+
+```ts
+const r = redact("Mail anna@acme.be or call +32 470 12 34 56.", {
+  countries: ["BE"], excludeTypes: ["PHONE"],
+});
+r.redactedText;
+// 'Mail [EMAIL] or call +32 470 12 34 56.'
+for (const e of r.exempted) console.log(e.entityType, e.text, e.rule, e.ruleKind);
+// PHONE +32 470 12 34 56 PHONE type
+```
+
+Set it once for a deployment with `new EuRedact({ excludeTypes: [...] })`; a per-call
+list is merged with it.
+
+- **Nothing is excluded by default.** Every type is detected and redacted
+  unless you name it.
+- **Names are checked.** They are case-insensitive, and legacy names resolve
+  (`IBAN` is `BANK_ACCOUNT`, `CREDENTIAL` is `SECRET`). A registered custom
+  pattern's name works too. An unknown name throws, so a typo
+  cannot silently switch nothing off.
+- **It applies to each span's final type.** In
+  `NHS Number: 5556953627` the digits also pass the Austrian SVNr check.
+  Excluding `HEALTH_INSURANCE` leaves them in the text; it does not let them
+  be masked as an `SSN` instead.
+- **Every excluded detection is recorded** in `result.exempted`, with
+  `ruleKind: "type"` and the type's name as `rule`, so an audit can see what
+  was deliberately left in.
+- **In `mode: "cloud"`** an excluded rules type is still masked in the text
+  sent to the service. The option decides what comes back, not what may leave
+  your machine. Model types (`JOB_TITLE`, `FINANCIAL_AMOUNT`, …) are filtered
+  from the merged result.
+- **There is no include-list.** A list of types to keep would leave every type
+  a later release adds unmasked for you, without notice.
+- **A type is one switch.** `INTERNAL_ID` covers employee and customer numbers
+  as well as ticket and case numbers; excluding it leaves all of them in.
+
 ## Architecture
 
 ```
@@ -1175,11 +1570,12 @@ bundler, edge-runtime and Deno compatibility — would buy nothing.
 
 | Package | |
 |---|---:|
-| Tarball | 150 kB |
-| Unpacked | 629 kB |
+| Tarball | 232 kB |
+| Unpacked | 817 kB |
 | Runtime dependencies | **0** |
 
-Measured with `npm pack --dry-run` at 0.5.1. A stale duplicate of this section
+Measured with `npm pack --dry-run` with the bundled BIC prefix list, which
+accounts for about 60 kB of the tarball (shipped in both the ESM and CJS builds). A stale duplicate of this section
 previously quoted 0.02 ms and 86 KB; both were wrong, and the figures above are
 the measured ones.
 
@@ -1189,6 +1585,21 @@ the measured ones.
 const { redact } = require("euredact");
 ```
 
+## Browsers
+
+The package bundles for a page as published. Its only platform dependency is a
+SHA-256 digest (the result-cache key) and a random index (token suffixes); on
+Node both come from `node:crypto`, and a bundler targeting the browser (esbuild,
+webpack, Rollup, Vite) follows the `browser` field in `package.json` to a build
+that uses `crypto.getRandomValues` and a synchronous SHA-256 of its own, checked
+against `node:crypto` byte for byte. `redact` runs entirely in the page, and so
+does the local half of `redactAsync({ mode: "cloud" })`: only the masked text
+leaves it.
+
+```js
+import { redact } from "euredact";   // esbuild --platform=browser, webpack, Vite
+```
+
 ## License
 
 Apache-2.0