euredact 0.5.1 → 0.7.0

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
@@ -114,6 +114,7 @@ interface RedactOptions {
   allowlistDomains?: string[] | null; // domains never redacted (EMAIL/URL)
   detectDates?: boolean;            // include DOB / date of death
   cache?: boolean;                  // reuse results for identical input
+  idempotencyKey?: string;          // mode: "cloud" only; see the table below
 }
 ```
 
@@ -141,6 +142,7 @@ interface RedactOptions {
 | 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. |
@@ -248,10 +250,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
+  cloud?: CloudInfo;              // mode: "cloud" only: job id, model, cost, unplaced
+                                  // findings — see "What the service said"
 }
 ```
 
@@ -265,7 +275,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 +292,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 +305,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 +323,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
@@ -370,6 +368,87 @@ masked is unchanged either way.
 
 For custom patterns, `entityType` is a plain string (e.g. `"EMPLOYEE_ID"`).
 
+## Batch processing and concurrency
+
+`redactBatch` loads the country configurations once instead of per document,
+which is the whole reason to prefer it to a loop:
+
+```ts
+import { redactBatch } from "euredact";
+
+const docs = ["Mijn BSN is 111222333.", "IBAN NL91ABNA0417164300."];
+
+redactBatch(docs, { countries: ["NL"] }).map((r) => r.redactedText);
+// [ 'Mijn BSN is [NATIONAL_ID].', 'IBAN [BANK_ACCOUNT].' ]
+```
+
+`redactBatch` is **synchronous**, and deliberately so: the rules engine is
+CPU-bound, so wrapping it in a promise would add scheduling without adding
+parallelism. There is no `redactBatchAsync`. Where the Python SDK offers
+`aredact_batch(..., max_concurrency=n)` — it can offload to a thread pool —
+this SDK has one thread, so the honest equivalent is either `redactBatch` on the
+main thread or real workers:
+
+```ts
+// Keep the event loop responsive across a large batch.
+import { redactBatch } from "euredact";
+
+async function* redactInChunks(docs: string[], size = 200) {
+  for (let i = 0; i < docs.length; i += size) {
+    yield redactBatch(docs.slice(i, i + size), { countries: ["NL"] });
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+}
+```
+
+For genuine parallelism use `node:worker_threads` and give each worker its own
+`EuRedact`; for true throughput at scale that is the only thing that helps,
+because the cost is regex matching rather than waiting.
+
+`redactAsync` is for the **cloud tier**, not for parallelism — it exists because
+a network call cannot be synchronous. With `mode: "rules"` it resolves
+immediately with exactly what `redact()` returns. Cloud calls *are* I/O, so
+those parallelise properly:
+
+```ts
+import { redactAsync } from "euredact";
+
+const results = await Promise.all(
+  docs.map((d) => redactAsync(d, { countries: ["BE"], mode: "cloud" })),
+);
+```
+
+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
+
+The module-level functions share a single hidden instance, which is usually what
+you want. Construct your own when the configuration must be per-tenant: custom
+patterns, an allowlist and the result cache all live on the instance.
+
+```ts
+import { EuRedact } from "euredact";
+
+const engine = new EuRedact({ allowlist: ["ACME Corporation"] });
+engine.addCustomPattern("CASE_REF", String.raw`CASE-\d{8}`);
+
+engine.redactBatch(
+  ["ACME Corporation, ref CASE-20260401, BSN 111222333."],
+  { countries: ["NL"] },
+)[0].redactedText;
+// 'ACME Corporation, ref [CASE_REF], BSN [NATIONAL_ID].'
+```
+
+### Tokens and referential labels do not span a batch
+
+`tokenize: true` mints tokens **per call**, so item 3 of a batch does not share a
+token with item 1 even for the same value. If two documents must agree on a
+label, redact them as one text, or use `referentialIntegrity: true`, whose
+`TYPE_n` numbering is per instance rather than per call.
+
 ## Cloud tier
 
 > **Status: private alpha.** The cloud tier is in closed testing — it is **not**
@@ -394,6 +473,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
@@ -412,13 +496,439 @@ seen a chunk boundary.
 
 Options the service cannot honour reject rather than being ignored: multiple
 `countries`, `countryHint`, `context`/`chunkOffset` and `referentialIntegrity`.
-`tokenize`, `allowlist` and `allowlistDomains` are honoured: the SDK applies them to the spans the
-service returns and rebuilds the text from those.
+`tokenize`, `allowlist` and `allowlistDomains` are honoured: the SDK applies
+them locally, after the response, to its own spans and the service's.
+
+`CloudClient` is the transport underneath. It sends exactly the text it is
+given and returns spans relative to it: the local masking happens in
+`redactAsync()`, not in the client. Use it directly only with text you have
+already masked.
 
 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.
 
+### What leaves your machine
+
+Be precise about this, because it is the question a security review asks first.
+
+In `mode: "cloud"` the rules engine runs **on your machine first**, and only
+the text it leaves behind is sent to the service over TLS. Every value it finds
+is already a `[TYPE]` placeholder by the time the request is built:
+
+```
+your text      IBAN NL91 ABNA 0417 1643 00 belongs to Nick Bols, tel +31 6 12345678
+                 │  rules engine, on your machine
+what is sent   IBAN [BANK_ACCOUNT] belongs to Nick Bols, tel [PHONE]
+                 │  TLS ──▶ service (model) ──▶ spans relative to the masked text
+what you get   IBAN [BANK_ACCOUNT] belongs to [PERSON_NAME], tel [PHONE]
+```
+
+The request body is that one `text` field plus the country. No list of types,
+no offsets and no original values travel beside it. The service answers with
+spans that index the masked text, and the SDK maps them back onto your
+original, so `detections` always index the document you passed in. Service offsets count
+code points and JavaScript slices UTF-16 units; the client converts.
+
+**This is minimisation, not an exemption.** Three things still leave:
+
+- what the model is there to find — names, employers, job titles, diagnoses;
+- anything the rules engine missed, such as an identifier in a format it does
+  not know;
+- the surrounding prose.
+
+So the service still processes personal data on your behalf, and a DPIA should
+say so. What it no longer receives is every IBAN, national ID, phone number and
+email address the local engine could place.
+
+Three things behave differently here than in rules mode:
+
+- `detectDates` has no effect. The local pass always runs with dates on,
+  because that is the rules output the model was trained against. It can only
+  cause more to be masked, never less.
+- `tokenize` and the allowlists are applied locally, after the response, and do
+  not change what is sent: placeholders on the wire are always `[TYPE]`, and an
+  allowlisted value is masked in the request and put back in your result.
+- [Custom patterns](#custom-patterns) run in the local pass, so a value only
+  you know how to recognise is masked before the request too.
+
+Every span the service returns is checked against the text that was sent. One
+that does not match raises `CloudError` rather than being placed by guesswork.
+
+### Keeping identifiers local
+
+`mode: "cloud"` does this for you with our model. The same pattern works with
+any other model — your own, or a general-purpose LLM — and that is what
+`tokenize` is for:
+
+```ts
+import { redact, restore } from "euredact";
+
+const prompt = "Stuur een mail naar Bas Verhoeven (bas@example.nl) over NL91ABNA0417164300.";
+
+// 1. Mask locally. Nothing has left the process.
+const local = redact(prompt, { countries: ["NL"], tokenize: true });
+local.redactedText;
+// 'Stuur een mail naar Bas Verhoeven (EMAIL_S5SH) over BANK_ACCOUNT_5XXR.'
+local.tokens;
+// { BANK_ACCOUNT_5XXR: 'NL91ABNA0417164300', EMAIL_S5SH: 'bas@example.nl' }
+
+// 2. Send only the masked text to any model, ours or someone else's.
+const answer = await callYourModel(local.redactedText);
+
+// 3. Put the real values back locally.
+restore(answer, local.tokens);
+```
+
+The token suffixes are random per call, so yours will differ.
+
+**Read that output carefully: `Bas Verhoeven` is still there.** That is the whole
+trade-off and it is why the cloud tier exists. The local engine masks what has a
+shape — the IBAN and the address — and cannot mask a name, an employer or a
+diagnosis, because it cannot find them. So this pattern keeps every identifier
+the engine detects inside your process and sends the prose, names included.
+`mode: "cloud"` sends that same masked prose to a model trained to find the
+names in it.
+
+Either way the prose leaves. If names must not leave your infrastructure
+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
@@ -431,6 +941,82 @@ 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.
 
+## What `countries` actually controls
+
+This is the parameter most often misread, and reading it wrongly leads to
+under-redaction in exactly the case you care about — a foreign identifier in a
+domestic document. So, precisely:
+
+> `countries` decides how a detection is **attributed and scored**.
+> It does **not** decide what gets **found**.
+
+Country-specific patterns for every supported country run on every document,
+whatever you declare. Declaring `countries: ["NL"]` does not switch the Belgian
+patterns off; it says "this document is Dutch", and anything Belgian that turns
+up is still detected and still masked — it is just flagged as sitting outside
+what you declared.
+
+The same Belgian national number, under four different calls:
+
+```ts
+import { redact } from "euredact";
+
+const text = "Rijksregisternummer 85.07.30-033.61 van onze klant.";
+
+for (const options of [{ countries: ["NL"] },
+                       { countries: ["BE"] },
+                       {},
+                       { countries: ["NL"], countryHint: ["BE"] }]) {
+  const result = redact(text, options);
+  const [detection] = result.detections;
+  console.log(result.redactedText, "|", result.detectionMode,
+              "| country:", detection.country,
+              "| countryConfidence:", detection.countryConfidence,
+              "| outOfScope:", detection.outOfScope);
+}
+```
+
+```
+Rijksregisternummer [NATIONAL_ID] van onze klant. | declared | country: BE | countryConfidence: 0 | outOfScope: true
+Rijksregisternummer [NATIONAL_ID] van onze klant. | declared | country: BE | countryConfidence: 0.8807970779778823 | outOfScope: false
+Rijksregisternummer [NATIONAL_ID] van onze klant. | inferred | country: BE | countryConfidence: 0 | outOfScope: false
+Rijksregisternummer [NATIONAL_ID] van onze klant. | declared | country: BE | countryConfidence: 0.8807970779778823 | outOfScope: true
+```
+
+**The masked output is byte-identical in all four.** What moved is the metadata.
+
+| You pass | Effect on what is found | Effect on labelling |
+|---|---|---|
+| `countries: ["NL"]` | None — every country's patterns still run | Attributed normally; a non-Dutch hit gets `outOfScope: true` and `countryConfidence: 0` |
+| `countries: ["BE"]` | None | The Belgian hit is corroborated: `countryConfidence` ~0.88, `outOfScope: false` |
+| `countries` omitted | None | `detectionMode: "inferred"`; the country is inferred from the document and nothing is out of scope, because nothing was declared |
+| `countryHint: ["BE"]` | None | A *prior*: it corroborates Belgian attribution **without** widening or narrowing scope, so `out_of_scope` still reflects `countries` alone |
+
+### How to use each one
+
+- **`countries: [...]`** — you know where the document is from. Use it. It
+  improves attribution and makes `out_of_scope` meaningful, and it is the
+  cheapest path because country inference is skipped.
+- **`countries` omitted** — you do not know. The engine infers from the document
+  and reports `inferredCountries` with confidences.
+- **`countryHint: [...]`** — you have a weak signal (the customer's billing
+  country, the mailbox a document arrived in) that should resolve ambiguity
+  without declaring scope. Added in 0.3.2 precisely so that a hint could not be
+  mistaken for a scope restriction.
+
+### Why it works this way
+
+Until 0.3.2, `countries` *did* gate detection, and 0.3.3 fixed the remaining
+case where it "could change which spans were found, not just how they were
+labelled". Both were changed deliberately: a redaction library that hides a
+Belgian national number because you told it the document was Dutch has failed
+at the only job it has. Scoping is a reporting concern; masking is not.
+
+The practical consequence: **do not use `countries` as a filter.** If you only
+want Dutch detections in your output, filter on
+`detection.country === "NL"` or on `detection.outOfScope` after the call —
+the value was still masked in the text either way.
+
 ## Country codes
 
 `countries` accepts **ISO 3166-1 alpha-2** codes. The two EU/VAT spellings are
@@ -555,14 +1141,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";
@@ -572,10 +1167,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`
 
@@ -749,16 +1344,16 @@ 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
 characters (`EMAIL_P4RTs`) — leaving a token behind is the worse failure.
 
-Works in cloud mode via `redactAsync`: the SDK rebuilds the text from the spans
-the service returns, which is exactly what the service built its own output
-from.
+Works in cloud mode via `redactAsync`: tokens are minted locally, after the
+response, over the local spans and the service's. What is sent to the service
+always carries `[TYPE]` placeholders, never tokens.
 
 ## Allowlist
 
@@ -926,19 +1521,37 @@ 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 | |
+|---|---:|
+| Tarball | 232 kB |
+| Unpacked | 817 kB |
+| Runtime dependencies | **0** |
+
+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.
+
 ## CommonJS
 
 ```js
 const { redact } = require("euredact");
 ```
 
-## Performance
+## Browsers
 
-| Metric | Value |
-|---|---|
-| Latency per redaction | ~0.02 ms |
-| Package size | ~86 KB |
-| Runtime dependencies | 0 |
+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