euredact 0.5.1 → 0.7.0

package/dist/cjs/cache.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResultCache = void 0;
 exports.resultChars = resultChars;
-const node_crypto_1 = require("node:crypto");
+const platform_js_1 = require("./platform.js");
 // Default ceiling on retained characters, not entries. A count-only cap of
 // 1024 entries says nothing about memory: 1024 cached 1 MB documents is a
 // gigabyte of PII-bearing text held live. ~16M characters is a few tens of MB.
@@ -37,13 +37,7 @@ class ResultCache {
         // deployment an attacker who can guess a victim's document could submit a
         // same-length colliding one and be served the victim's cached result,
         // detections and raw matched PII included.
-        return (0, node_crypto_1.createHash)("sha256")
-            .update(text)
-            .update("|")
-            .update(sorted.join("|"))
-            .update("|")
-            .update(mode)
-            .digest("hex");
+        return (0, platform_js_1.sha256Hex)([text, "|", sorted.join("|"), "|", mode]);
     }
     get(key) {
         if (!this.enabled)

package/dist/cjs/cloud/account.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * [CLOUD EXTENSION] The account and job endpoints an API key may call.
+ *
+ * Everything a customer's key can do on the service is reachable from the SDK
+ * (rules-engine#89): redaction (`CloudClient`, `redactAsync`), batches
+ * (`Batches`), a past job (`Jobs`) and the account itself (`Account`). What
+ * needs a signed-in person -- logging in, minting keys, changing settings,
+ * members, accepting terms -- is not here, because a key cannot do it.
+ *
+ * Every typed value carries `raw`, the service's JSON, so a field the SDK does
+ * not know yet is still reachable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Jobs = exports.Account = void 0;
+const config_js_1 = require("./config.js");
+const errors_js_1 = require("./errors.js");
+const client_js_1 = require("./client.js");
+const str = (v) => (typeof v === "string" ? v : null);
+const int = (v) => ((0, client_js_1.isInteger)(v) ? v : null);
+const bool = (v) => (typeof v === "boolean" ? v : null);
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
+const objects = (v) => (Array.isArray(v) ? v : []).filter((x) => !!x && typeof x === "object" && !Array.isArray(x));
+const usageDay = (r) => ({
+    day: str(r.day), documents: int(r.documents), tokens: int(r.tokens),
+    failures: int(r.failures), rulesOnly: int(r.rules_only), raw: r,
+});
+/** A JSON client: GETs are retried like the redact call; writes are sent once. */
+class ApiClient {
+    config;
+    fetchImpl;
+    constructor(config, options = {}) {
+        const resolved = config ?? (0, config_js_1.getConfig)();
+        if (resolved === null)
+            throw new errors_js_1.NotConfiguredError();
+        (0, config_js_1.requireSecureBaseUrl)(resolved.baseUrl);
+        this.config = resolved;
+        this.fetchImpl = options.fetchImpl;
+    }
+    async call(method, path, params = {}, retry = method === "GET") {
+        const doFetch = (0, client_js_1.requireFetch)(this.fetchImpl);
+        const query = Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&");
+        const url = `${this.config.baseUrl}${path}${query ? `?${query}` : ""}`;
+        const maxRetries = retry ? this.config.maxRetries : 0;
+        for (let attempt = 0;; attempt++) {
+            let response;
+            let payload = {};
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+            try {
+                response = await doFetch(url, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.config.apiKey}`,
+                        "Idempotency-Key": (0, client_js_1.uuid)(),
+                        ...this.config.headers,
+                    },
+                    signal: controller.signal,
+                });
+                payload = (await (0, client_js_1.readJson)(response));
+            }
+            catch (e) {
+                if (attempt >= maxRetries) {
+                    throw new errors_js_1.CloudError(`cloud request failed: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (response) {
+                if (response.status === 200)
+                    return payload;
+                if (!client_js_1.RETRY_STATUS.has(response.status) || attempt >= maxRetries
+                    || (response.status === 429 && (0, client_js_1.isQuota)(payload))) {
+                    throw (0, client_js_1.cloudErrorFor)(response.status, payload);
+                }
+            }
+            await (0, client_js_1.sleep)((0, client_js_1.backoffMs)(attempt, (0, client_js_1.retryAfterMs)(response?.headers)));
+        }
+    }
+}
+/**
+ * The account an API key belongs to: summary, credits, usage and keys.
+ *
+ * These calls pass with an API key while the service accepts account calls
+ * without a browser `Origin` (its `EUREDACT_CONSOLE_REQUIRE_ORIGIN=0`); a
+ * refusal arrives as a `CloudError` with status 403.
+ */
+class Account extends ApiClient {
+    async summary() {
+        const raw = await this.call("GET", "/v1/account");
+        const tenant = obj(raw.tenant), retention = obj(raw.retention), usage = obj(raw.usage);
+        return {
+            tenantId: str(tenant.id), tenantName: str(tenant.name), active: bool(tenant.active),
+            memberSince: str(tenant.member_since), role: str(raw.role),
+            retentionMode: str(retention.mode), payloadTtlHours: int(retention.payload_ttl_hours),
+            documentsToday: int(usage.documents_today), documentsThisMonth: int(usage.documents_this_month),
+            tokensThisMonth: int(usage.tokens_this_month), failures24h: int(usage.failures_24h),
+            dailyQuota: int(usage.daily_quota), quotaRemaining: int(usage.quota_remaining),
+            activeKeys: int(obj(raw.keys).active), batchesAvailable: bool(obj(raw.batches).available),
+            raw,
+        };
+    }
+    async credits() {
+        const raw = await this.call("GET", "/v1/account/credits");
+        return { balance: int(raw.balance), granted: int(raw.granted), spent: int(raw.spent),
+            unit: str(raw.unit), raw };
+    }
+    /** Recent credit movements, newest first (1-500). */
+    async creditHistory(limit = 50) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
+            throw new RangeError("limit must be between 1 and 500");
+        }
+        const data = await this.call("GET", "/v1/account/credits/history", { limit });
+        return objects(data.entries).map(r => ({
+            at: str(r.at), delta: int(r.delta), reason: str(r.reason), count: int(r.count),
+            jobId: str(r.job_id), sourceRef: str(r.source_ref), raw: r,
+        }));
+    }
+    /** Documents, tokens and failures per day over the last `days`. */
+    async usage(days = 30) {
+        if (!Number.isInteger(days) || days < 1)
+            throw new RangeError("days must be at least 1");
+        const data = await this.call("GET", "/v1/account/usage", { days });
+        return objects(data.series).map(usageDay);
+    }
+    /** The same window, split by the key that submitted the work. */
+    async usageByKey(days = 30) {
+        if (!Number.isInteger(days) || days < 1)
+            throw new RangeError("days must be at least 1");
+        const data = await this.call("GET", "/v1/account/usage/by-key", { days });
+        return objects(data.keys).map(r => ({
+            keyId: int(r.key_id), name: str(r.name), documents: int(r.documents),
+            tokens: int(r.tokens), failures: int(r.failures), series: objects(r.series).map(usageDay), raw: r,
+        }));
+    }
+    async keys() {
+        const data = await this.call("GET", "/v1/account/keys");
+        return objects(data.keys).map(r => ({
+            id: int(r.id), name: str(r.name), createdBy: str(r.created_by), createdAt: str(r.created_at),
+            lastUsedAt: str(r.last_used_at), revokedAt: str(r.revoked_at), active: bool(r.active), raw: r,
+        }));
+    }
+    /**
+     * Revoke a key, e.g. one that leaked: the one write a key may make. Sent once,
+     * never retried. Already revoked throws a `CloudError` with status 409; a key
+     * that does not exist, or is another account's, throws `NotFoundError`.
+     * Revoking the key this client uses works, and is reported by `selfRevoked`.
+     */
+    async revokeKey(keyId) {
+        if (!Number.isInteger(keyId))
+            throw new RangeError("keyId must be an integer");
+        const raw = await this.call("POST", `/v1/account/keys/${keyId}/revoke`);
+        return { id: int(raw.id), keysRemaining: int(raw.keys_remaining), lockedOut: bool(raw.locked_out),
+            selfRevoked: bool(raw.self_revoked), raw };
+    }
+}
+exports.Account = Account;
+/** Past jobs, by id. */
+class Jobs extends ApiClient {
+    /**
+     * A job's state, and its result if it has one. Throws `ResultExpiredError`
+     * when the job succeeded but its result is no longer retained, and
+     * `NotFoundError` for an unknown job (or another account's).
+     */
+    async retrieve(jobId) {
+        const raw = await this.call("GET", `/v1/jobs/${encodeURIComponent(jobId)}`);
+        const result = typeof raw.redacted_text === "string"
+            ? (0, client_js_1.toResult)(raw, raw.redacted_text)
+            : null;
+        return {
+            jobId: str(raw.job_id) ?? jobId,
+            status: str(raw.status) ?? (result ? "succeeded" : ""),
+            createdAt: str(raw.created_at),
+            result,
+            raw,
+        };
+    }
+}
+exports.Jobs = Jobs;

package/dist/cjs/cloud/batches.js

@@ -0,0 +1,469 @@
+"use strict";
+/**
+ * [CLOUD EXTENSION] Batches: cloud mode, with hours between masking and mapping
+ * (rules-engine#84; the gateway side is `docs/BATCHES.md` in euredact-inference).
+ *
+ * Cloud mode masks a document here, sends only the masked text and maps the
+ * service's answer back onto the original, all in one call. A batch returns up
+ * to 24 h later, so `create()` writes one **local batch file** per batch: each
+ * original, its local detections and the SHA-256 of the masked text that was
+ * sent. None of it is uploaded. `results()` maps the service's spans back from
+ * that file, checking the hash before placing a span, then wipes the originals
+ * and leaves a text-free receipt.
+ *
+ * The file format is shared with the Python SDK, offsets counted in code points,
+ * so a batch created by one can be resolved by the other.
+ *
+ * In Node the file is `~/.euredact/batches/<batchId>.json` (`0600` in a `0700`
+ * directory); `batchDir` moves it. A page has no filesystem, so there `store`
+ * is required: any object with async `read`, `write`, `delete` and `list`.
+ * `cipher` encrypts the file at rest with a key the caller holds.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Batches = exports.BatchError = exports.FILE_FORMAT = exports.MAX_DOCUMENT_TOKENS = exports.MAX_BODY_BYTES = exports.CUSTOM_ID = exports.MAX_CUSTOM_ID = exports.MAX_DOCUMENTS = void 0;
+const sdk_js_1 = require("../sdk.js");
+const platform_js_1 = require("../platform.js");
+const client_js_1 = require("./client.js");
+const config_js_1 = require("./config.js");
+const errors_js_1 = require("./errors.js");
+/** The gateway's limits (docs/BATCHES.md §2-§3), checked before upload. */
+exports.MAX_DOCUMENTS = 5000;
+exports.MAX_CUSTOM_ID = 64;
+/** The gateway's customId rule (euredact-inference gateway/batches.py), whole string. */
+exports.CUSTOM_ID = /^[A-Za-z0-9_.:\-]{1,64}$/;
+exports.MAX_BODY_BYTES = 128 * 1024 * 1024;
+/**
+ * Per document, counted by the model's tokenizer on the gateway. The SDK has no
+ * copy of it and no character count decides it, so it is **not** checked before
+ * upload: a document over it comes back as an error with code `too_long`.
+ */
+exports.MAX_DOCUMENT_TOKENS = 5000;
+exports.FILE_FORMAT = "euredact-batch/1";
+class BatchError extends errors_js_1.CloudError {
+    constructor(message) {
+        super(message);
+        this.name = "BatchError";
+    }
+}
+exports.BatchError = BatchError;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function now() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** UTF-16 offset -> code point offset, for writing the shared file format. */
+function utf16ToCodePoints(text) {
+    if (!/[\uD800-\uDBFF]/.test(text))
+        return unit => unit;
+    const map = new Map();
+    let cp = 0;
+    let unit = 0;
+    for (const ch of text) {
+        map.set(unit, cp);
+        unit += ch.length;
+        cp += 1;
+    }
+    map.set(unit, cp);
+    return u => map.get(u) ?? u;
+}
+function toStored(d, cp) {
+    return {
+        type: String(d.entityType), start: cp(d.start), end: cp(d.end), text: d.text,
+        source: String(d.source), country: d.country ?? null, confidence: d.confidence ?? "high",
+        country_confidence: d.countryConfidence ?? 0, out_of_scope: d.outOfScope ?? false,
+    };
+}
+function fromStored(raw, unit) {
+    return {
+        entityType: raw.type, start: unit(raw.start), end: unit(raw.end),
+        text: raw.text, source: raw.source, country: raw.country,
+        confidence: raw.confidence, countryConfidence: raw.country_confidence,
+        outOfScope: raw.out_of_scope,
+    };
+}
+// ── the client ────────────────────────────────────────────────────────────
+class Batches {
+    config;
+    store;
+    cipher;
+    fetchImpl;
+    sdk;
+    constructor(options = {}) {
+        const config = options.config ?? (0, config_js_1.getConfig)();
+        if (config === null)
+            throw new errors_js_1.NotConfiguredError();
+        (0, config_js_1.requireSecureBaseUrl)(config.baseUrl);
+        this.config = config;
+        if (options.batchDir !== undefined && options.store !== undefined) {
+            throw new Error("pass batchDir or store, not both");
+        }
+        const store = options.store ?? (0, platform_js_1.defaultBatchStore)(options.batchDir);
+        if (store === null) {
+            throw new Error("no filesystem here: pass a store ({ read, write, delete, list }) to Batches");
+        }
+        this.store = store;
+        this.cipher = options.cipher ?? null;
+        this.fetchImpl = options.fetchImpl;
+        this.sdk = options.sdk ?? null;
+    }
+    // -- plumbing ---------------------------------------------------------
+    engine() {
+        if (this.sdk === null)
+            this.sdk = new sdk_js_1.EuRedact();
+        return this.sdk;
+    }
+    async request(method, path, body, headers = {}) {
+        const impl = this.fetchImpl ?? globalThis.fetch;
+        if (!impl)
+            throw new errors_js_1.CloudError("no fetch implementation available");
+        try {
+            return await impl(`${this.config.baseUrl}${path}`, {
+                method,
+                body: body,
+                headers: {
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                    "Idempotency-Key": headers["Idempotency-Key"] ?? crypto.randomUUID(),
+                    ...this.config.headers,
+                    ...headers,
+                },
+            });
+        }
+        catch (err) {
+            throw new errors_js_1.CloudError(`batch request failed: ${err.message}`);
+        }
+    }
+    async json(resp) {
+        try {
+            return (await resp.json());
+        }
+        catch {
+            return {};
+        }
+    }
+    raiseFor(status, payload) {
+        throw (0, client_js_1.cloudErrorFor)(status, payload);
+    }
+    async load(batchId) {
+        let data = await this.store.read(batchId);
+        if (data === null)
+            return null;
+        if (this.cipher)
+            data = await this.cipher.decrypt(data);
+        const state = JSON.parse(decoder.decode(data));
+        if (state.format !== exports.FILE_FORMAT) {
+            throw new BatchError(`local batch file ${batchId}: unknown format ${JSON.stringify(state.format)}`);
+        }
+        return state;
+    }
+    async save(state) {
+        let data = encoder.encode(JSON.stringify(state));
+        if (this.cipher)
+            data = await this.cipher.encrypt(data);
+        await this.store.write(state.batch_id, data);
+    }
+    static batch(raw) {
+        const str = (k) => (typeof raw[k] === "string" ? raw[k] : null);
+        return {
+            id: str("id") ?? "", status: str("status") ?? "",
+            createdAt: str("created_at"), expiresAt: str("expires_at"), endedAt: str("ended_at"),
+            resultsExpireAt: str("results_expire_at"),
+            counts: { ...(raw.counts ?? {}) },
+            documents: (0, client_js_1.isInteger)(raw.documents) ? raw.documents : null,
+            tokens: Object.fromEntries(Object.entries(raw.tokens && typeof raw.tokens === "object" ? raw.tokens : {}).filter((e) => (0, client_js_1.isInteger)(e[1]))),
+            creditsCharged: (0, client_js_1.isInteger)(raw.credits_charged) ? raw.credits_charged : null,
+            billingRate: typeof raw.billing_rate === "number" ? raw.billing_rate : null,
+            raw,
+        };
+    }
+    // -- create -----------------------------------------------------------
+    /**
+     * Mask every document here, upload only the masked text, keep the rest in
+     * the local batch file. The document count, `customId`s, countries and body
+     * size are checked before anything is uploaded or written. The 5,000-token
+     * limit per document is **not**: it is counted by the model's tokenizer on
+     * the gateway, which the SDK does not have, so a document over it comes back
+     * from `results()` as an error with code `too_long` that says so.
+     */
+    async create(documents, options = {}) {
+        if (documents.length === 0)
+            throw new BatchError("a batch needs at least one document");
+        if (documents.length > exports.MAX_DOCUMENTS) {
+            throw new BatchError(`${documents.length.toLocaleString("en-US")} documents; a batch holds at most ` +
+                `${exports.MAX_DOCUMENTS.toLocaleString("en-US")}`);
+        }
+        // Every document is checked before any is masked: masking 5,000 documents
+        // and then learning that the gateway refuses the batch for one bad customId
+        // wastes the whole pass (rules-engine#88).
+        const seen = new Set();
+        const checked = [];
+        documents.forEach((doc, index) => {
+            const number = index + 1;
+            const customId = doc.customId;
+            if (typeof customId !== "string" || !exports.CUSTOM_ID.test(customId)) {
+                throw new BatchError(`document ${number}: customId must be 1-${exports.MAX_CUSTOM_ID} characters of A-Z a-z 0-9 _ . : -`);
+            }
+            if (seen.has(customId)) {
+                throw new BatchError(`document ${number}: duplicate customId ${JSON.stringify(customId)}`);
+            }
+            seen.add(customId);
+            if (typeof doc.text !== "string")
+                throw new BatchError(`document ${number}: text must be a string`);
+            const countries = (doc.countries ?? []).map(c => c.toUpperCase());
+            if (countries.length !== 1) {
+                throw new BatchError(`document ${number}: exactly one country is needed, as in cloud mode`);
+            }
+            checked.push({ customId, text: doc.text, countries, language: doc.language ?? "" });
+        });
+        const lines = [];
+        const entries = {};
+        const engine = this.engine();
+        for (const { customId, text, countries, language } of checked) {
+            // The same local pass as redactAsync(..., { mode: "cloud" }): dates on, no
+            // allowlist, no tokens. What is sent is what cloud mode would send.
+            const local = engine.redact(text, { countries, detectDates: true, cache: false });
+            const [masked] = (0, sdk_js_1.maskForCloud)(text, local.detections);
+            const line = { custom_id: customId, text: masked, countries };
+            if (language)
+                line.language = language;
+            lines.push(JSON.stringify(line));
+            const cp = utf16ToCodePoints(text);
+            entries[customId] = {
+                text: text,
+                masked_sha256: (0, platform_js_1.sha256Hex)([masked]),
+                countries,
+                language,
+                detections: local.detections.map(d => toStored(d, cp)),
+                detection_mode: local.detectionMode,
+                inferred_countries: local.inferredCountries,
+            };
+        }
+        const body = encoder.encode(lines.join("\n") + "\n");
+        if (body.length > exports.MAX_BODY_BYTES) {
+            throw new BatchError(`the masked batch is ${body.length.toLocaleString("en-US")} bytes; the limit is ` +
+                `${exports.MAX_BODY_BYTES.toLocaleString("en-US")}`);
+        }
+        const compressed = (0, platform_js_1.gzip)(body);
+        const headers = {
+            "Content-Type": "application/x-ndjson",
+            "Idempotency-Key": options.idempotencyKey ?? crypto.randomUUID(),
+        };
+        if (compressed !== null)
+            headers["Content-Encoding"] = "gzip";
+        const resp = await this.request("POST", "/v1/batches", compressed ?? body, headers);
+        const payload = await this.json(resp);
+        if (resp.status !== 200 && resp.status !== 201)
+            this.raiseFor(resp.status, payload);
+        const batch = Batches.batch(payload);
+        if (!batch.id)
+            throw new BatchError("the gateway accepted the batch but returned no id");
+        await this.save({
+            format: exports.FILE_FORMAT,
+            batch_id: batch.id,
+            status: "pending",
+            created_at: batch.createdAt ?? now(),
+            expires_at: batch.expiresAt,
+            results_expire_at: null,
+            resolved_at: null,
+            engine: "euredact-ts",
+            engine_version: null,
+            counts: { documents: Object.keys(entries).length },
+            entries,
+        });
+        return batch;
+    }
+    // -- retrieve, cancel, pending, purge, sweep ------------------------------
+    /** The gateway's view: status, counts and timestamps. */
+    async retrieve(batchId) {
+        await this.sweep();
+        const resp = await this.request("GET", `/v1/batches/${encodeURIComponent(batchId)}`);
+        const payload = await this.json(resp);
+        if (resp.status !== 200)
+            this.raiseFor(resp.status, payload);
+        const batch = Batches.batch(payload);
+        const state = await this.load(batchId);
+        if (state !== null && batch.resultsExpireAt && state.results_expire_at !== batch.resultsExpireAt) {
+            state.results_expire_at = batch.resultsExpireAt;
+            await this.save(state);
+        }
+        return batch;
+    }
+    /**
+     * This account's batches, newest first (1-100, the gateway's bound). The
+     * gateway's view only: `pending()` lists the ones with a local file here.
+     */
+    async list(limit = 20) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+            throw new RangeError("limit must be between 1 and 100");
+        }
+        const resp = await this.request("GET", `/v1/batches?limit=${limit}`);
+        const payload = await this.json(resp);
+        if (resp.status !== 200)
+            this.raiseFor(resp.status, payload);
+        const raw = Array.isArray(payload.batches) ? payload.batches : [];
+        return raw.filter((b) => !!b && typeof b === "object" && !Array.isArray(b))
+            .map(b => Batches.batch(b));
+    }
+    /** Cancel queued documents; the local file stays pending until the finished
+     *  ones are mapped by `results()`. */
+    async cancel(batchId) {
+        const resp = await this.request("POST", `/v1/batches/${encodeURIComponent(batchId)}/cancel`);
+        const payload = await this.json(resp);
+        if (resp.status !== 200 && resp.status !== 202)
+            this.raiseFor(resp.status, payload);
+        return Batches.batch(payload);
+    }
+    /** Batch ids whose local file still waits to be mapped. Reads files only. */
+    async pending() {
+        await this.sweep();
+        const out = [];
+        for (const id of await this.store.list()) {
+            const state = await this.load(id);
+            if (state !== null && state.status === "pending")
+                out.push(id);
+        }
+        return out;
+    }
+    /** Delete the local file, whatever its status. */
+    async purge(batchId) {
+        await this.store.delete(batchId);
+    }
+    /**
+     * Delete receipts and expire pending files past `results_expire_at`. Runs at
+     * the start of the calls that look in the store, so nothing has to be
+     * scheduled. A pending file past that time can never be mapped -- the gateway
+     * has swept the results -- so its originals are wiped.
+     */
+    async sweep(at = new Date()) {
+        for (const id of await this.store.list()) {
+            let state;
+            try {
+                state = await this.load(id);
+            }
+            catch {
+                continue;
+            }
+            if (state === null || !state.results_expire_at)
+                continue;
+            if (at < new Date(state.results_expire_at))
+                continue;
+            if (state.status === "pending")
+                await this.wipe(state, "expired");
+            else
+                await this.store.delete(id);
+        }
+    }
+    async wipe(state, status) {
+        state.entries = {};
+        state.status = status;
+        state.resolved_at = now();
+        await this.save(state);
+    }
+    // -- results ----------------------------------------------------------
+    /**
+     * Map an ended batch back onto the originals in its local file. Each
+     * document's masked text is rebuilt from the file and must hash to both the
+     * stored SHA-256 and the gateway's `masked_sha256` before a span is placed.
+     * Anything that cannot be mapped is a per-document error, never the masked
+     * text passed off as a result.
+     */
+    async results(batchId) {
+        const state = await this.load(batchId);
+        if (state !== null && (state.status === "resolved" || state.status === "expired")) {
+            return {
+                batchId, documents: {}, batch: null,
+                status: state.status === "resolved" ? "already_resolved" : "expired",
+            };
+        }
+        const batch = await this.retrieve(batchId);
+        if (batch.status !== "ended")
+            return { batchId, status: "not_ended", documents: {}, batch };
+        const resp = await this.request("GET", `/v1/batches/${encodeURIComponent(batchId)}/results`);
+        if (resp.status === 410) {
+            if (state !== null)
+                await this.wipe(state, "expired");
+            return { batchId, status: "expired", documents: {}, batch };
+        }
+        if (resp.status === 409)
+            return { batchId, status: "not_ended", documents: {}, batch };
+        if (resp.status !== 200)
+            this.raiseFor(resp.status, await this.json(resp));
+        const entries = state?.entries ?? {};
+        const documents = {};
+        for (const line of (await resp.text()).split("\n")) {
+            if (!line.trim())
+                continue;
+            const row = JSON.parse(line);
+            const customId = row.custom_id ?? "";
+            documents[customId] = this.outcome(customId, row.result ?? {}, entries[customId], state !== null);
+        }
+        if (state !== null) {
+            const counts = {
+                documents: Object.keys(documents).length,
+                mapped: Object.values(documents).filter(o => o.ok).length,
+            };
+            for (const o of Object.values(documents)) {
+                if (o.error)
+                    counts[o.error] = (counts[o.error] ?? 0) + 1;
+            }
+            state.counts = counts;
+            await this.wipe(state, "resolved");
+        }
+        return { batchId, status: "resolved", documents, batch };
+    }
+    outcome(customId, result, entry, fileExists) {
+        const fail = (error, message) => ({ customId, ok: false, result: null, error, message });
+        if (result.type !== "succeeded") {
+            const err = result.error ?? {};
+            const code = err.code ?? result.type ?? "errored";
+            let message = err.message ?? "";
+            if (code === "too_long") {
+                message = `${message}. The ${exports.MAX_DOCUMENT_TOKENS.toLocaleString("en-US")}-token limit is ` +
+                    "counted by the model's tokenizer on the gateway; the SDK cannot check it before " +
+                    "upload. Split the document and submit the parts.";
+                message = message.replace(/^\. /, "");
+            }
+            return fail(code, message);
+        }
+        if (entry === undefined) {
+            return fail("missing_local_entry", fileExists
+                ? "no entry for this document in the local batch file"
+                : "no local batch file on this machine");
+        }
+        const text = entry.text;
+        const unit = (0, client_js_1.codePointOffsets)(text);
+        const local = entry.detections.map(d => fromStored(d, unit));
+        const [masked, labels] = (0, sdk_js_1.maskForCloud)(text, local);
+        if ((0, platform_js_1.sha256Hex)([masked]) !== entry.masked_sha256 || result.masked_sha256 !== entry.masked_sha256) {
+            return fail("local_mismatch", "the local batch file does not match what was sent");
+        }
+        // The gateway's offsets count code points of the masked text; toResult
+        // converts them to UTF-16 units, as the cloud client does for redactAsync.
+        const remote = (0, client_js_1.toResult)({ entities: result.entities }, masked);
+        let placed;
+        try {
+            placed = (0, sdk_js_1.ontoOriginal)(remote.detections, masked, text, labels, errors_js_1.CloudError);
+        }
+        catch (err) {
+            return fail("local_mismatch", err.message);
+        }
+        const detections = [...local, ...placed].sort((a, b) => a.start - b.start || b.end - a.end);
+        return {
+            customId, ok: true, error: null, message: "",
+            result: {
+                redactedText: (0, sdk_js_1.applyReplacements)(text, detections, det => `[${det.entityType}]`),
+                detections,
+                source: "cloud",
+                degraded: false,
+                inferredCountries: entry.inferred_countries,
+                evidence: [],
+                detectionMode: entry.detection_mode,
+                tokens: {},
+                exempted: [],
+                // A batch line carries the model and anything unplaced; it has no job
+                // id and no usage of its own (the batch carries those).
+                cloud: (0, client_js_1.toCloudInfo)({ model_version: result.model_version, unlocated: result.unlocated }),
+            },
+        };
+    }
+}
+exports.Batches = Batches;