@arcjet/analyze 1.0.0-beta.10 → 1.0.0-beta.11

package/index.d.ts

@@ -1,4 +1,4 @@
-import type { BotConfig, BotResult, DetectedSensitiveInfoEntity, DetectSensitiveInfoFunction, EmailValidationConfig, EmailValidationResult, SensitiveInfoEntities, SensitiveInfoEntity, SensitiveInfoResult } from "@arcjet/analyze-wasm";
+import type { BotConfig, BotResult, DetectedSensitiveInfoEntity, DetectSensitiveInfoFunction, EmailValidationConfig, EmailValidationResult, FilterResult, SensitiveInfoEntities, SensitiveInfoEntity, SensitiveInfoResult } from "@arcjet/analyze-wasm";
 import type { ArcjetLogger } from "@arcjet/protocol";
 interface AnalyzeContext {
     log: ArcjetLogger;
@@ -15,15 +15,81 @@ type AnalyzeRequest = {
     query?: string;
     extra?: Record<string, string>;
 };
-export { type EmailValidationConfig, type BotConfig, type SensitiveInfoEntity, type DetectedSensitiveInfoEntity, };
+export { type EmailValidationConfig, type BotConfig, type FilterResult, type SensitiveInfoEntity, type DetectedSensitiveInfoEntity, };
 /**
- * Generate a fingerprint for the client. This is used to identify the client
- * across multiple requests.
- * @param context - The Arcjet Analyze context.
- * @param request - The request to fingerprint.
- * @returns A SHA-256 string fingerprint.
+ * Generate a fingerprint.
+ *
+ * Fingerprints can be used to identify the client across multiple requests.
+ *
+ * This considers different things on the `request` based on the passed
+ * `context.characteristics`.
+ *
+ * See [*Fingerprints* on
+ * `docs.arcjet.com`](https://docs.arcjet.com/fingerprints/) for more info.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @returns
+ *   Promise for a SHA-256 fingerprint.
  */
 export declare function generateFingerprint(context: AnalyzeContext, request: AnalyzeRequest): Promise<string>;
-export declare function isValidEmail(context: AnalyzeContext, candidate: string, options: EmailValidationConfig): Promise<EmailValidationResult>;
+/**
+ * Check whether an email is valid.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
+export declare function isValidEmail(context: AnalyzeContext, value: string, options: EmailValidationConfig): Promise<EmailValidationResult>;
+/**
+ * Detect whether a request is by a bot.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
 export declare function detectBot(context: AnalyzeContext, request: AnalyzeRequest, options: BotConfig): Promise<BotResult>;
-export declare function detectSensitiveInfo(context: AnalyzeContext, candidate: string, entities: SensitiveInfoEntities, contextWindowSize: number, detect?: DetectSensitiveInfoFunction): Promise<SensitiveInfoResult>;
+/**
+ * Detect sensitive info in a value.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param entities
+ *   Strategy to use for detecting sensitive info;
+ *   either by denying everything and allowing certain tags or by allowing
+ *   everything and denying certain tags.
+ * @param contextWindowSize
+ *   Number of tokens to pass to `detect`.
+ * @param detect
+ *   Function to detect sensitive info (optional).
+ * @returns
+ *   Promise for a result.
+ */
+export declare function detectSensitiveInfo(context: AnalyzeContext, value: string, entities: SensitiveInfoEntities, contextWindowSize: number, detect?: DetectSensitiveInfoFunction): Promise<SensitiveInfoResult>;
+/**
+ * Check if a filter matches a request.
+ *
+ * @param context
+ *   Arcjet context.
+ * @param request
+ *   Request.
+ * @param expressions
+ *   Filter expressions.
+ * @returns
+ *   Promise to whether the filter matches the request.
+ */
+export declare function matchFilters(context: AnalyzeContext, request: AnalyzeRequest, expressions: ReadonlyArray<string>, allowIfMatch: boolean): Promise<FilterResult>;

package/index.js

@@ -50,13 +50,23 @@ function createCoreImports(detect) {
         },
     };
 }
-// TODO(@wooorm-arcjet): document what is used to fingerprint.
 /**
- * Generate a fingerprint for the client. This is used to identify the client
- * across multiple requests.
- * @param context - The Arcjet Analyze context.
- * @param request - The request to fingerprint.
- * @returns A SHA-256 string fingerprint.
+ * Generate a fingerprint.
+ *
+ * Fingerprints can be used to identify the client across multiple requests.
+ *
+ * This considers different things on the `request` based on the passed
+ * `context.characteristics`.
+ *
+ * See [*Fingerprints* on
+ * `docs.arcjet.com`](https://docs.arcjet.com/fingerprints/) for more info.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @returns
+ *   Promise for a SHA-256 fingerprint.
  */
 async function generateFingerprint(context, request) {
     const { log } = context;
@@ -70,20 +80,42 @@ async function generateFingerprint(context, request) {
     log.debug("WebAssembly is not supported in this runtime");
     return "";
 }
-// TODO(@wooorm-arcjet): docs.
-async function isValidEmail(context, candidate, options) {
+/**
+ * Check whether an email is valid.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
+async function isValidEmail(context, value, options) {
     const { log } = context;
     const coreImports = createCoreImports();
     const analyze = await initializeWasm(coreImports);
     if (typeof analyze !== "undefined") {
-        return analyze.isValidEmail(candidate, options);
+        return analyze.isValidEmail(value, options);
         // Ignore the `else` branch as we test in places that have WebAssembly.
         /* node:coverage ignore next 4 */
     }
     log.debug("WebAssembly is not supported in this runtime");
     return { blocked: [], validity: "valid" };
 }
-// TODO(@wooorm-arcjet): docs.
+/**
+ * Detect whether a request is by a bot.
+ *
+ * @param context
+ *   Context.
+ * @param request
+ *   Request.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise for a result.
+ */
 async function detectBot(context, request, options) {
     const { log } = context;
     const coreImports = createCoreImports();
@@ -96,14 +128,31 @@ async function detectBot(context, request, options) {
     log.debug("WebAssembly is not supported in this runtime");
     return { allowed: [], denied: [], spoofed: false, verified: false };
 }
-// TODO(@wooorm-arcjet): docs.
-async function detectSensitiveInfo(context, candidate, entities, contextWindowSize, detect) {
+/**
+ * Detect sensitive info in a value.
+ *
+ * @param context
+ *   Context.
+ * @param value
+ *   Value.
+ * @param entities
+ *   Strategy to use for detecting sensitive info;
+ *   either by denying everything and allowing certain tags or by allowing
+ *   everything and denying certain tags.
+ * @param contextWindowSize
+ *   Number of tokens to pass to `detect`.
+ * @param detect
+ *   Function to detect sensitive info (optional).
+ * @returns
+ *   Promise for a result.
+ */
+async function detectSensitiveInfo(context, value, entities, contextWindowSize, detect) {
     const { log } = context;
     const coreImports = createCoreImports(detect);
     const analyze = await initializeWasm(coreImports);
     if (typeof analyze !== "undefined") {
         const skipCustomDetect = typeof detect !== "function";
-        return analyze.detectSensitiveInfo(candidate, {
+        return analyze.detectSensitiveInfo(value, {
             entities,
             contextWindowSize,
             skipCustomDetect,
@@ -114,5 +163,30 @@ async function detectSensitiveInfo(context, candidate, entities, contextWindowSi
     log.debug("WebAssembly is not supported in this runtime");
     throw new Error("SENSITIVE_INFO rule failed to run because Wasm is not supported in this environment.");
 }
+/**
+ * Check if a filter matches a request.
+ *
+ * @param context
+ *   Arcjet context.
+ * @param request
+ *   Request.
+ * @param expressions
+ *   Filter expressions.
+ * @returns
+ *   Promise to whether the filter matches the request.
+ */
+async function matchFilters(context, request, expressions, allowIfMatch) {
+    const coreImports = createCoreImports();
+    const analyze = await initializeWasm(coreImports);
+    if (typeof analyze !== "undefined") {
+        return analyze.matchFilters(JSON.stringify(request), 
+        // @ts-expect-error: WebAssembly does not support readonly values.
+        expressions, allowIfMatch);
+        // Ignore the `else` branch as we test in places that have WebAssembly.
+        /* node:coverage ignore next 4 */
+    }
+    context.log.debug("WebAssembly is not supported in this runtime");
+    throw new Error("FILTER rule failed to run because Wasm is not supported in this environment.");
+}
 
-export { detectBot, detectSensitiveInfo, generateFingerprint, isValidEmail };
+export { detectBot, detectSensitiveInfo, generateFingerprint, isValidEmail, matchFilters };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcjet/analyze",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.11",
   "description": "Arcjet local analysis engine",
   "keywords": [
     "analyze",
@@ -45,17 +45,16 @@
     "test": "npm run build && npm run lint && npm run test-coverage"
   },
   "dependencies": {
-    "@arcjet/analyze-wasm": "1.0.0-beta.10",
-    "@arcjet/protocol": "1.0.0-beta.10"
+    "@arcjet/analyze-wasm": "1.0.0-beta.11",
+    "@arcjet/protocol": "1.0.0-beta.11"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-beta.10",
-    "@arcjet/rollup-config": "1.0.0-beta.10",
-    "@arcjet/tsconfig": "1.0.0-beta.10",
+    "@arcjet/eslint-config": "1.0.0-beta.11",
+    "@arcjet/rollup-config": "1.0.0-beta.11",
     "@bytecodealliance/jco": "1.5.0",
-    "@rollup/wasm-node": "4.46.2",
-    "@types/node": "18.18.0",
-    "eslint": "9.32.0",
+    "@rollup/wasm-node": "4.50.0",
+    "@types/node": "24.3.0",
+    "eslint": "9.34.0",
     "typescript": "5.9.2"
   },
   "publishConfig": {