euredact 0.6.0 → 0.7.1

package/dist/esm/cloud/account.js

@@ -0,0 +1,175 @@
+/**
+ * [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.
+ */
+import { getConfig, requireSecureBaseUrl } from "./config.js";
+import { CloudError, NotConfiguredError } from "./errors.js";
+import { RETRY_STATUS, backoffMs, cloudErrorFor, isInteger, isQuota, readJson, requireFetch, retryAfterMs, sleep, toResult, uuid, } from "./client.js";
+const str = (v) => (typeof v === "string" ? v : null);
+const int = (v) => (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 ?? getConfig();
+        if (resolved === null)
+            throw new NotConfiguredError();
+        requireSecureBaseUrl(resolved.baseUrl);
+        this.config = resolved;
+        this.fetchImpl = options.fetchImpl;
+    }
+    async call(method, path, params = {}, retry = method === "GET") {
+        const doFetch = 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": uuid(),
+                        ...this.config.headers,
+                    },
+                    signal: controller.signal,
+                });
+                payload = (await readJson(response));
+            }
+            catch (e) {
+                if (attempt >= maxRetries) {
+                    throw new CloudError(`cloud request failed: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (response) {
+                if (response.status === 200)
+                    return payload;
+                if (!RETRY_STATUS.has(response.status) || attempt >= maxRetries
+                    || (response.status === 429 && isQuota(payload))) {
+                    throw cloudErrorFor(response.status, payload);
+                }
+            }
+            await sleep(backoffMs(attempt, 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.
+ */
+export 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 };
+    }
+}
+/** Past jobs, by id. */
+export 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"
+            ? 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,
+        };
+    }
+}

package/dist/esm/cloud/batches.d.ts

@@ -0,0 +1,166 @@
+/**
+ * [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.
+ */
+import type { RedactResult } from "../types.js";
+import { EuRedact } from "../sdk.js";
+import { type CloudConfig } from "./config.js";
+import { CloudError } from "./errors.js";
+/** The gateway's limits (docs/BATCHES.md §2-§3), checked before upload. */
+export declare const MAX_DOCUMENTS = 5000;
+export declare const MAX_CUSTOM_ID = 64;
+/** The gateway's customId rule (euredact-inference gateway/batches.py), whole string. */
+export declare const CUSTOM_ID: RegExp;
+export declare const MAX_BODY_BYTES: number;
+/**
+ * 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`.
+ */
+export declare const MAX_DOCUMENT_TOKENS = 5000;
+export declare const FILE_FORMAT = "euredact-batch/1";
+export declare class BatchError extends CloudError {
+    constructor(message: string);
+}
+/** Where local batch files live. One opaque blob per batch id. */
+export interface BatchStore {
+    read(batchId: string): Promise<Uint8Array | null>;
+    write(batchId: string, data: Uint8Array): Promise<void>;
+    delete(batchId: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+/** Encryption at rest, with a key the caller holds. The SDK does not pick a scheme. */
+export interface Cipher {
+    encrypt(data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+    decrypt(data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+}
+export interface BatchDocument {
+    customId: string;
+    text: string;
+    /** Exactly one, as in cloud mode. */
+    countries: string[];
+    language?: string;
+}
+export interface Batch {
+    id: string;
+    status: string;
+    createdAt: string | null;
+    expiresAt: string | null;
+    endedAt: string | null;
+    resultsExpireAt: string | null;
+    counts: Record<string, number>;
+    documents: number | null;
+    /** `{ prompt, completion }` tokens so far (rules-engine#89). */
+    tokens: Record<string, number>;
+    /** Credits debited for the batch so far, at `billingRate`. */
+    creditsCharged: number | null;
+    /** The batch rate, e.g. `0.75`: batches are billed at their own rate. */
+    billingRate: number | null;
+    raw: Record<string, unknown>;
+}
+/** One document of a resolved batch: a result, or why there is none. */
+export interface DocumentOutcome {
+    customId: string;
+    ok: boolean;
+    result: RedactResult | null;
+    /**
+     * `null` on success. Otherwise a code: the gateway's (`too_long`, …),
+     * `expired`, `cancelled`, or the SDK's own `local_mismatch` (the local file
+     * does not match what was sent) or `missing_local_entry`.
+     */
+    error: string | null;
+    message: string;
+}
+/**
+ * `status`: `not_ended` (nothing changed locally), `resolved` (mapped now; the
+ * file is a text-free receipt), `already_resolved` (never mapped twice), or
+ * `expired` (the gateway no longer holds the results; the entries are wiped).
+ */
+export interface BatchResults {
+    batchId: string;
+    status: "not_ended" | "resolved" | "already_resolved" | "expired";
+    documents: Record<string, DocumentOutcome>;
+    batch: Batch | null;
+}
+export interface BatchesOptions {
+    config?: CloudConfig | null;
+    batchDir?: string;
+    store?: BatchStore;
+    cipher?: Cipher;
+    sdk?: EuRedact;
+    /** Injectable for tests. Defaults to the platform `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class Batches {
+    readonly config: CloudConfig;
+    readonly store: BatchStore;
+    private readonly cipher;
+    private readonly fetchImpl;
+    private sdk;
+    constructor(options?: BatchesOptions);
+    private engine;
+    private request;
+    private json;
+    private raiseFor;
+    private load;
+    private save;
+    private static batch;
+    /**
+     * 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.
+     */
+    create(documents: BatchDocument[], options?: {
+        idempotencyKey?: string;
+    }): Promise<Batch>;
+    /** The gateway's view: status, counts and timestamps. */
+    retrieve(batchId: string): Promise<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.
+     */
+    list(limit?: number): Promise<Batch[]>;
+    /** Cancel queued documents; the local file stays pending until the finished
+     *  ones are mapped by `results()`. */
+    cancel(batchId: string): Promise<Batch>;
+    /** Batch ids whose local file still waits to be mapped. Reads files only. */
+    pending(): Promise<string[]>;
+    /** Delete the local file, whatever its status. */
+    purge(batchId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    sweep(at?: Date): Promise<void>;
+    private wipe;
+    /**
+     * 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.
+     */
+    results(batchId: string): Promise<BatchResults>;
+    private outcome;
+}