@anuma/sdk 1.0.0 → 1.1.1

package/dist/next/index.cjs

@@ -27,8 +27,12 @@ var withAnuma = (nextConfig = {}) => {
   return {
     ...nextConfig,
     serverExternalPackages: [
-      ...nextConfig.serverExternalPackages || [],
-      "sharp"
+      ...nextConfig.serverExternalPackages ?? [],
+      "sharp",
+      // exceljs pulls in unzipper → fstream which calls process.umask() at
+      // module init time, crashing Cloudflare Workers and other edge runtimes.
+      // Externalizing prevents the server bundler from including it in SSR.
+      "exceljs"
     ],
     webpack: (config, options) => {
       const { isServer } = options;

package/dist/next/index.d.mts

@@ -18,6 +18,29 @@
  *
  * @module
  */
-declare const withAnuma: (nextConfig?: any) => any;
+/** Minimal Webpack configuration shape used by the SDK plugin. */
+interface WebpackConfig {
+    resolve: {
+        alias: Record<string, unknown>;
+        fallback: Record<string, unknown>;
+    };
+    module: {
+        rules: Array<Record<string, unknown>>;
+    };
+}
+/** Webpack compiler options passed by Next.js. */
+interface WebpackOptions {
+    isServer: boolean;
+}
+/** Next.js configuration object shape used by the SDK plugin. */
+interface NextConfig {
+    serverExternalPackages?: string[];
+    webpack?: (config: WebpackConfig, options: WebpackOptions) => WebpackConfig;
+    [key: string]: unknown;
+}
+declare const withAnuma: (nextConfig?: NextConfig) => {
+    serverExternalPackages: string[];
+    webpack: (config: WebpackConfig, options: WebpackOptions) => WebpackConfig;
+};
 
 export { withAnuma };

package/dist/next/index.d.ts

@@ -18,6 +18,29 @@
  *
  * @module
  */
-declare const withAnuma: (nextConfig?: any) => any;
+/** Minimal Webpack configuration shape used by the SDK plugin. */
+interface WebpackConfig {
+    resolve: {
+        alias: Record<string, unknown>;
+        fallback: Record<string, unknown>;
+    };
+    module: {
+        rules: Array<Record<string, unknown>>;
+    };
+}
+/** Webpack compiler options passed by Next.js. */
+interface WebpackOptions {
+    isServer: boolean;
+}
+/** Next.js configuration object shape used by the SDK plugin. */
+interface NextConfig {
+    serverExternalPackages?: string[];
+    webpack?: (config: WebpackConfig, options: WebpackOptions) => WebpackConfig;
+    [key: string]: unknown;
+}
+declare const withAnuma: (nextConfig?: NextConfig) => {
+    serverExternalPackages: string[];
+    webpack: (config: WebpackConfig, options: WebpackOptions) => WebpackConfig;
+};
 
 export { withAnuma };

package/dist/next/index.mjs

@@ -3,8 +3,12 @@ var withAnuma = (nextConfig = {}) => {
   return {
     ...nextConfig,
     serverExternalPackages: [
-      ...nextConfig.serverExternalPackages || [],
-      "sharp"
+      ...nextConfig.serverExternalPackages ?? [],
+      "sharp",
+      // exceljs pulls in unzipper → fstream which calls process.umask() at
+      // module init time, crashing Cloudflare Workers and other edge runtimes.
+      // Externalizing prevents the server bundler from including it in SSR.
+      "exceljs"
     ],
     webpack: (config, options) => {
       const { isServer } = options;

package/dist/pii/transformers.cjs

@@ -0,0 +1,126 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/pii/detectors/transformers.ts
+var transformers_exports = {};
+__export(transformers_exports, {
+  aggregateTokens: () => aggregateTokens,
+  createTransformersNerDetector: () => createTransformersNerDetector
+});
+module.exports = __toCommonJS(transformers_exports);
+var DEFAULT_MODEL = "Xenova/bert-base-NER";
+var DEFAULT_TAG_MAP = {
+  PER: "PERSON",
+  LOC: "LOCATION",
+  ORG: "ORG",
+  MISC: void 0
+};
+function placeTokens(tokens, text) {
+  const placed = [];
+  let cursor = 0;
+  for (const t of tokens) {
+    const surface = t.word.startsWith("##") ? t.word.slice(2) : t.word;
+    const start = text.indexOf(surface, cursor);
+    if (start < 0) {
+      placed.push({ ...t, start: -1, end: -1 });
+      continue;
+    }
+    const end = start + surface.length;
+    placed.push({ ...t, start, end });
+    cursor = end;
+  }
+  return placed;
+}
+function aggregateTokens(tokens, text, tagMap, minScore) {
+  const placed = placeTokens(tokens, text);
+  const spans = [];
+  let cur = null;
+  const flush = () => {
+    if (!cur) return;
+    const category = cur.valid ? tagMap[cur.base] : void 0;
+    if (category) {
+      const score = cur.scores.reduce((a, b) => a + b, 0) / cur.scores.length;
+      if (score >= minScore) spans.push({ start: cur.start, end: cur.end, category, score });
+    }
+    cur = null;
+  };
+  for (const t of placed) {
+    const dash = t.entity.indexOf("-");
+    const prefix = dash >= 0 ? t.entity.slice(0, dash) : t.entity;
+    const base = dash >= 0 ? t.entity.slice(dash + 1) : t.entity;
+    const isContinuation = t.word.startsWith("##");
+    const unplaceable = t.start < 0;
+    const continues = cur !== null && base === cur.base && (prefix === "I" || isContinuation) && (unplaceable || t.start - cur.end <= 1);
+    if (continues) {
+      if (unplaceable) cur.valid = false;
+      else {
+        cur.end = t.end;
+        cur.scores.push(t.score);
+      }
+    } else {
+      flush();
+      cur = unplaceable ? null : { base, start: t.start, end: t.end, scores: [t.score], valid: true };
+    }
+  }
+  flush();
+  return spans;
+}
+function createTransformersNerDetector(options = {}) {
+  const model = options.model ?? DEFAULT_MODEL;
+  const dtype = options.dtype ?? "q8";
+  const minScore = options.minScore ?? 0.5;
+  const tagMap = options.tagMap ?? DEFAULT_TAG_MAP;
+  let pipePromise = null;
+  const load = () => {
+    if (!pipePromise) {
+      const loading = (async () => {
+        const transformers = await import("@huggingface/transformers");
+        return transformers.pipeline("token-classification", model, { dtype });
+      })();
+      pipePromise = loading;
+      loading.catch(() => {
+        if (pipePromise === loading) pipePromise = null;
+      });
+    }
+    return pipePromise;
+  };
+  return {
+    async detect(text) {
+      if (!text) return [];
+      const classify = await load();
+      const tokens = await classify(text);
+      return aggregateTokens(tokens, text, tagMap, minScore);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  aggregateTokens,
+  createTransformersNerDetector
+});

package/dist/pii/transformers.d.mts

@@ -0,0 +1,103 @@
+/**
+ * PII detection patterns for structured data types.
+ *
+ * Each pattern has a category (used for placeholder tags like [EMAIL_1]),
+ * a regex, and an optional validator for reducing false positives.
+ */
+type PiiCategory = "EMAIL" | "PHONE" | "SSN" | "CREDIT_CARD" | "IP_ADDRESS" | "API_KEY" | "US_ADDRESS" | "DATE_OF_BIRTH";
+
+/**
+ * NER detector contract for PII redaction.
+ *
+ * The regex layer in {@link ./patterns} handles *structured* PII (email, phone,
+ * SSN, credit card, …). It cannot detect *unstructured* PII — person names,
+ * locations, organizations — which need a named-entity-recognition model.
+ *
+ * Rather than bundle a model (and a runtime) into the SDK, we define a small
+ * runtime-agnostic contract: a {@link NerDetector} takes text and returns the
+ * spans it found. Consumers supply an implementation appropriate to their
+ * platform — a Transformers.js model in the browser/Node (see
+ * `./detectors/transformers`), an `onnxruntime-react-native` model on mobile,
+ * a remote service, or a fake in tests. The SDK keeps detection *on-device* by
+ * never calling out itself; it only consumes the spans a detector returns and
+ * merges them into the existing placeholder map.
+ */
+
+/**
+ * A character-offset span of detected PII. `start`/`end` are indices into the
+ * text passed to {@link NerDetector.detect} (`end` exclusive). `category`
+ * becomes the placeholder tag prefix (e.g. "PERSON" → `[PERSON_1]`); it may be
+ * any string, conventionally `PERSON` / `LOCATION` / `ORG` for NER entities.
+ */
+interface PiiSpan {
+    start: number;
+    end: number;
+    category: PiiCategory | (string & {});
+    /** Optional model confidence in [0,1]; informational (filter in the detector). */
+    score?: number;
+}
+/**
+ * Detects unstructured PII in text. Implementations run a model (or service)
+ * and return spans. The SDK defensively clamps spans to the text bounds and
+ * snaps them to whole-word boundaries before use, so a detector returning a
+ * sub-word span cannot corrupt the output — but a detector should still return
+ * its cleanest spans.
+ *
+ * `detect` should be deterministic (same text → same spans): the redactor uses
+ * the returned order as a placeholder-numbering tiebreak, so a nondeterministic
+ * detector can produce unstable placeholder numbers across runs.
+ */
+interface NerDetector {
+    detect(text: string): Promise<PiiSpan[]>;
+}
+
+/**
+ * Reference {@link NerDetector} backed by Transformers.js (`@huggingface/transformers`).
+ *
+ * Runs a quantized BERT NER model fully on-device (browser via the
+ * onnxruntime-web/WASM backend, or Node) — no network call, so PII never leaves
+ * the device. The model is loaded lazily on first `detect()` and cached, so
+ * importing this module is cheap and apps that never enable NER pay nothing.
+ *
+ * `@huggingface/transformers` is an OPTIONAL peer dependency: it is `import()`-ed
+ * dynamically (matching `lib/memory/reranker.ts`) so it is only required when a
+ * caller actually constructs this detector. React Native cannot use this
+ * detector (its WASM backend doesn't run under Hermes) — supply an
+ * `onnxruntime-react-native`-based {@link NerDetector} there instead.
+ */
+
+interface TransformersNerDetectorOptions {
+    /** Hugging Face model id. Default: `Xenova/bert-base-NER`. */
+    model?: string;
+    /** Weight precision passed to the pipeline. Default: `q8` (smallest). */
+    dtype?: "fp32" | "fp16" | "q8" | "int8" | "uint8" | "q4" | (string & {});
+    /** Drop entities below this confidence in [0,1]. Default: `0.5`. */
+    minScore?: number;
+    /**
+     * Map raw NER tags (without the `B-`/`I-` prefix) to PII categories. A tag
+     * mapped to `undefined` is dropped. Default maps PER→PERSON, LOC→LOCATION,
+     * ORG→ORG and drops MISC (noisy and not reliably PII).
+     */
+    tagMap?: Record<string, string | undefined>;
+}
+/** Raw per-token output of a Transformers.js `token-classification` pipeline. */
+interface RawToken {
+    entity: string;
+    score: number;
+    index: number;
+    word: string;
+}
+/**
+ * Aggregate B-/I- subword tokens into whole-entity spans. A new entity starts
+ * on a `B-` tag or a tag change; contiguous `I-` tokens (and WordPiece "##"
+ * continuations) of the same base tag extend it. (The SDK additionally snaps
+ * spans to word boundaries, so dropped trailing subwords are recovered there.)
+ */
+declare function aggregateTokens(tokens: RawToken[], text: string, tagMap: Record<string, string | undefined>, minScore: number): PiiSpan[];
+/**
+ * Create a Transformers.js-backed {@link NerDetector}. The returned detector
+ * loads the model lazily on first use and caches it for the process/page.
+ */
+declare function createTransformersNerDetector(options?: TransformersNerDetectorOptions): NerDetector;
+
+export { type TransformersNerDetectorOptions, aggregateTokens, createTransformersNerDetector };

package/dist/pii/transformers.d.ts

@@ -0,0 +1,103 @@
+/**
+ * PII detection patterns for structured data types.
+ *
+ * Each pattern has a category (used for placeholder tags like [EMAIL_1]),
+ * a regex, and an optional validator for reducing false positives.
+ */
+type PiiCategory = "EMAIL" | "PHONE" | "SSN" | "CREDIT_CARD" | "IP_ADDRESS" | "API_KEY" | "US_ADDRESS" | "DATE_OF_BIRTH";
+
+/**
+ * NER detector contract for PII redaction.
+ *
+ * The regex layer in {@link ./patterns} handles *structured* PII (email, phone,
+ * SSN, credit card, …). It cannot detect *unstructured* PII — person names,
+ * locations, organizations — which need a named-entity-recognition model.
+ *
+ * Rather than bundle a model (and a runtime) into the SDK, we define a small
+ * runtime-agnostic contract: a {@link NerDetector} takes text and returns the
+ * spans it found. Consumers supply an implementation appropriate to their
+ * platform — a Transformers.js model in the browser/Node (see
+ * `./detectors/transformers`), an `onnxruntime-react-native` model on mobile,
+ * a remote service, or a fake in tests. The SDK keeps detection *on-device* by
+ * never calling out itself; it only consumes the spans a detector returns and
+ * merges them into the existing placeholder map.
+ */
+
+/**
+ * A character-offset span of detected PII. `start`/`end` are indices into the
+ * text passed to {@link NerDetector.detect} (`end` exclusive). `category`
+ * becomes the placeholder tag prefix (e.g. "PERSON" → `[PERSON_1]`); it may be
+ * any string, conventionally `PERSON` / `LOCATION` / `ORG` for NER entities.
+ */
+interface PiiSpan {
+    start: number;
+    end: number;
+    category: PiiCategory | (string & {});
+    /** Optional model confidence in [0,1]; informational (filter in the detector). */
+    score?: number;
+}
+/**
+ * Detects unstructured PII in text. Implementations run a model (or service)
+ * and return spans. The SDK defensively clamps spans to the text bounds and
+ * snaps them to whole-word boundaries before use, so a detector returning a
+ * sub-word span cannot corrupt the output — but a detector should still return
+ * its cleanest spans.
+ *
+ * `detect` should be deterministic (same text → same spans): the redactor uses
+ * the returned order as a placeholder-numbering tiebreak, so a nondeterministic
+ * detector can produce unstable placeholder numbers across runs.
+ */
+interface NerDetector {
+    detect(text: string): Promise<PiiSpan[]>;
+}
+
+/**
+ * Reference {@link NerDetector} backed by Transformers.js (`@huggingface/transformers`).
+ *
+ * Runs a quantized BERT NER model fully on-device (browser via the
+ * onnxruntime-web/WASM backend, or Node) — no network call, so PII never leaves
+ * the device. The model is loaded lazily on first `detect()` and cached, so
+ * importing this module is cheap and apps that never enable NER pay nothing.
+ *
+ * `@huggingface/transformers` is an OPTIONAL peer dependency: it is `import()`-ed
+ * dynamically (matching `lib/memory/reranker.ts`) so it is only required when a
+ * caller actually constructs this detector. React Native cannot use this
+ * detector (its WASM backend doesn't run under Hermes) — supply an
+ * `onnxruntime-react-native`-based {@link NerDetector} there instead.
+ */
+
+interface TransformersNerDetectorOptions {
+    /** Hugging Face model id. Default: `Xenova/bert-base-NER`. */
+    model?: string;
+    /** Weight precision passed to the pipeline. Default: `q8` (smallest). */
+    dtype?: "fp32" | "fp16" | "q8" | "int8" | "uint8" | "q4" | (string & {});
+    /** Drop entities below this confidence in [0,1]. Default: `0.5`. */
+    minScore?: number;
+    /**
+     * Map raw NER tags (without the `B-`/`I-` prefix) to PII categories. A tag
+     * mapped to `undefined` is dropped. Default maps PER→PERSON, LOC→LOCATION,
+     * ORG→ORG and drops MISC (noisy and not reliably PII).
+     */
+    tagMap?: Record<string, string | undefined>;
+}
+/** Raw per-token output of a Transformers.js `token-classification` pipeline. */
+interface RawToken {
+    entity: string;
+    score: number;
+    index: number;
+    word: string;
+}
+/**
+ * Aggregate B-/I- subword tokens into whole-entity spans. A new entity starts
+ * on a `B-` tag or a tag change; contiguous `I-` tokens (and WordPiece "##"
+ * continuations) of the same base tag extend it. (The SDK additionally snaps
+ * spans to word boundaries, so dropped trailing subwords are recovered there.)
+ */
+declare function aggregateTokens(tokens: RawToken[], text: string, tagMap: Record<string, string | undefined>, minScore: number): PiiSpan[];
+/**
+ * Create a Transformers.js-backed {@link NerDetector}. The returned detector
+ * loads the model lazily on first use and caches it for the process/page.
+ */
+declare function createTransformersNerDetector(options?: TransformersNerDetectorOptions): NerDetector;
+
+export { type TransformersNerDetectorOptions, aggregateTokens, createTransformersNerDetector };

package/dist/pii/transformers.mjs

@@ -0,0 +1,90 @@
+// src/lib/pii/detectors/transformers.ts
+var DEFAULT_MODEL = "Xenova/bert-base-NER";
+var DEFAULT_TAG_MAP = {
+  PER: "PERSON",
+  LOC: "LOCATION",
+  ORG: "ORG",
+  MISC: void 0
+};
+function placeTokens(tokens, text) {
+  const placed = [];
+  let cursor = 0;
+  for (const t of tokens) {
+    const surface = t.word.startsWith("##") ? t.word.slice(2) : t.word;
+    const start = text.indexOf(surface, cursor);
+    if (start < 0) {
+      placed.push({ ...t, start: -1, end: -1 });
+      continue;
+    }
+    const end = start + surface.length;
+    placed.push({ ...t, start, end });
+    cursor = end;
+  }
+  return placed;
+}
+function aggregateTokens(tokens, text, tagMap, minScore) {
+  const placed = placeTokens(tokens, text);
+  const spans = [];
+  let cur = null;
+  const flush = () => {
+    if (!cur) return;
+    const category = cur.valid ? tagMap[cur.base] : void 0;
+    if (category) {
+      const score = cur.scores.reduce((a, b) => a + b, 0) / cur.scores.length;
+      if (score >= minScore) spans.push({ start: cur.start, end: cur.end, category, score });
+    }
+    cur = null;
+  };
+  for (const t of placed) {
+    const dash = t.entity.indexOf("-");
+    const prefix = dash >= 0 ? t.entity.slice(0, dash) : t.entity;
+    const base = dash >= 0 ? t.entity.slice(dash + 1) : t.entity;
+    const isContinuation = t.word.startsWith("##");
+    const unplaceable = t.start < 0;
+    const continues = cur !== null && base === cur.base && (prefix === "I" || isContinuation) && (unplaceable || t.start - cur.end <= 1);
+    if (continues) {
+      if (unplaceable) cur.valid = false;
+      else {
+        cur.end = t.end;
+        cur.scores.push(t.score);
+      }
+    } else {
+      flush();
+      cur = unplaceable ? null : { base, start: t.start, end: t.end, scores: [t.score], valid: true };
+    }
+  }
+  flush();
+  return spans;
+}
+function createTransformersNerDetector(options = {}) {
+  const model = options.model ?? DEFAULT_MODEL;
+  const dtype = options.dtype ?? "q8";
+  const minScore = options.minScore ?? 0.5;
+  const tagMap = options.tagMap ?? DEFAULT_TAG_MAP;
+  let pipePromise = null;
+  const load = () => {
+    if (!pipePromise) {
+      const loading = (async () => {
+        const transformers = await import("@huggingface/transformers");
+        return transformers.pipeline("token-classification", model, { dtype });
+      })();
+      pipePromise = loading;
+      loading.catch(() => {
+        if (pipePromise === loading) pipePromise = null;
+      });
+    }
+    return pipePromise;
+  };
+  return {
+    async detect(text) {
+      if (!text) return [];
+      const classify = await load();
+      const tokens = await classify(text);
+      return aggregateTokens(tokens, text, tagMap, minScore);
+    }
+  };
+}
+export {
+  aggregateTokens,
+  createTransformersNerDetector
+};