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

package/index.d.ts

@@ -10,66 +10,168 @@ type WithoutCustomProps = {
 type PlainObject = {
     [key: string]: unknown;
 };
+/**
+ * Configuration for {@linkcode createRemoteClient}.
+ */
 export type RemoteClientOptions = {
+    /**
+     * Base URI for HTTP requests to Decide API (optional).
+     *
+     * Defaults to the environment variable `ARCJET_BASE_URL` (if that value
+     * is known and allowed) and the standard production API otherwise.
+     */
     baseUrl?: string;
+    /**
+     * Timeout in milliseconds for the Decide API (optional).
+     *
+     * Defaults to `500` in production and `1000` in development.
+     */
     timeout?: number;
 };
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
 export declare function createRemoteClient(options?: RemoteClientOptions): import("@arcjet/protocol/client.js").Client;
 type EventHandlerLike = (event: string, listener: (...args: any[]) => void) => void;
+/**
+ * Request for the Node.js integration of Arcjet.
+ *
+ * This is the minimum interface similar to `http.IncomingMessage`.
+ */
 export interface ArcjetNodeRequest {
+    /**
+     * Headers of the request.
+     */
     headers?: Record<string, string | string[] | undefined>;
+    /**
+     * `net.Socket` object associated with the connection.
+     *
+     * See <https://nodejs.org/api/http.html#messagesocket>.
+     */
     socket?: Partial<{
         remoteAddress: string;
         encrypted: boolean;
     }>;
+    /**
+     * HTTP method of the request.
+     */
     method?: string;
+    /**
+     * HTTP version sent by the client.
+     *
+     * See <https://nodejs.org/api/http.html#messagehttpversion>.
+     */
     httpVersion?: string;
+    /**
+     * URL.
+     */
     url?: string;
+    /**
+     * Request body.
+     */
     body?: unknown;
+    /**
+     * Add event handlers.
+     *
+     * This field is available through `stream.Readable` from `EventEmitter`.
+     *
+     * See <https://nodejs.org/api/events.html#emitteroneventname-listener>.
+     */
     on?: EventHandlerLike;
+    /**
+     * Remove event handlers.
+     *
+     * This field is available through `stream.Readable` from `EventEmitter`.
+     *
+     * See <https://nodejs.org/api/events.html#emitterremovelistenereventname-listener>.
+     */
     removeListener?: EventHandlerLike;
+    /**
+     * Whether the readable stream is readable.
+     *
+     * This field is available from `stream.Readable`.
+     *
+     * See <https://nodejs.org/api/stream.html#readablereadable>.
+     */
     readable?: boolean;
 }
 /**
- * The options used to configure an {@link ArcjetNode} client.
+ * Configuration for the Node.js integration of Arcjet.
+ *
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
  */
 export type ArcjetOptions<Rules extends [...Array<Primitive | Product>], Characteristics extends readonly string[]> = Simplify<CoreOptions<Rules, Characteristics> & {
     /**
-     * One or more IP Address of trusted proxies in front of the application.
-     * These addresses will be excluded when Arcjet detects a public IP address.
+     * IP addresses and CIDR ranges of trusted load balancers and proxies
+     * (optional, example: `["100.100.100.100", "100.100.100.0/24"]`).
      */
     proxies?: Array<string>;
 }>;
 /**
- * The ArcjetNode client provides a public `protect()` method to
- * make a decision about how a Node.js request should be handled.
+ * Instance of the Node.js integration of Arcjet.
+ *
+ * Primarily has a `protect()` method to make a decision about how a Node request
+ * should be handled.
+ *
+ * @template Props
+ *   Configuration.
  */
 export interface ArcjetNode<Props extends PlainObject> {
     /**
-     * Runs a request through the configured protections. The request is
-     * analyzed and then a decision made on whether to allow, deny, or challenge
-     * the request.
+     * Make a decision about how to handle a request.
+     *
+     * This will analyze the request locally where possible and otherwise call
+     * the Arcjet decision API.
      *
-     * @param req - An `IncomingMessage` provided to the request handler.
-     * @param props - Additonal properties required for running rules against a request.
-     * @returns An {@link ArcjetDecision} indicating Arcjet's decision about the request.
+     * @param request
+     *   Details about the {@linkcode ArcjetNodeRequest} that Arcjet needs to make a
+     *   decision.
+     * @param props
+     *   Additional properties required for running rules against a request.
+     * @returns
+     *   Promise that resolves to an {@linkcode ArcjetDecision} indicating
+     *   Arcjet’s decision about the request.
      */
     protect(request: ArcjetNodeRequest, ...props: Props extends WithoutCustomProps ? [] : [Props]): Promise<ArcjetDecision>;
     /**
-     * Augments the client with another rule. Useful for varying rules based on
-     * criteria in your handler—e.g. different rate limit for logged in users.
+     * Augment the client with another rule.
      *
-     * @param rule The rule to add to this execution.
-     * @returns An augmented {@link ArcjetNode} client.
+     * Useful for varying rules based on criteria in your handler such as
+     * different rate limit for logged in users.
+     *
+     * @template Rule
+     *   Type of rule.
+     * @param rule
+     *   Rule to add to Arcjet.
+     * @returns
+     *   Arcjet instance augmented with the given rule.
      */
     withRule<Rule extends Primitive | Product>(rule: Rule): ArcjetNode<Simplify<Props & ExtraProps<Rule>>>;
 }
 /**
- * Create a new {@link ArcjetNode} client. Always build your initial client
- * outside of a request handler so it persists across requests. If you need to
- * augment a client inside a handler, call the `withRule()` function on the base
- * client.
+ * Create a new Node.js integration of Arcjet.
+ *
+ * > 👉 **Tip**:
+ * > build your initial base client with as many rules as possible outside of a
+ * > request handler;
+ * > if you need more rules inside handlers later then you can call `withRule()`
+ * > on that base client.
  *
- * @param options - Arcjet configuration options to apply to all requests.
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Node.js integration of Arcjet.
  */
 export default function arcjet<const Rules extends (Primitive | Product)[], const Characteristics extends readonly string[]>(options: ArcjetOptions<Rules, Characteristics>): ArcjetNode<Simplify<ExtraProps<Rules> & CharacteristicProps<Characteristics>>>;

package/index.js

@@ -1,7 +1,7 @@
 import core__default from 'arcjet';
 export * from 'arcjet';
-import findIP, { parseProxy } from '@arcjet/ip';
-import ArcjetHeaders from '@arcjet/headers';
+import findIp, { parseProxy } from '@arcjet/ip';
+import { ArcjetHeaders } from '@arcjet/headers';
 import { logLevel, isDevelopment, baseUrl, platform } from '@arcjet/env';
 import { Logger } from '@arcjet/logger';
 import { createClient } from '@arcjet/protocol/client.js';
@@ -54,17 +54,21 @@ function errorMessage(err) {
     }
     return "Unknown problem";
 }
+/**
+ * Create a remote client.
+ *
+ * @param options
+ *   Configuration (optional).
+ * @returns
+ *   Client.
+ */
 function createRemoteClient(options) {
-    // The base URL for the Arcjet API. Will default to the standard production
-    // API unless environment variable `ARCJET_BASE_URL` is set.
     const url = options?.baseUrl ?? baseUrl(env);
-    // The timeout for the Arcjet API in milliseconds. This is set to a low value
-    // in production so calls fail open.
     const timeout = options?.timeout ?? (isDevelopment(env) ? 1000 : 500);
     // Transport is the HTTP client that the client uses to make requests.
     const transport = createTransport(url);
     const sdkStack = "NODEJS";
-    const sdkVersion = "1.0.0-beta.10";
+    const sdkVersion = "1.0.0-beta.11";
     return createClient({
         transport,
         baseUrl: url,
@@ -84,12 +88,22 @@ function cookiesToString(cookies) {
     return cookies;
 }
 /**
- * Create a new {@link ArcjetNode} client. Always build your initial client
- * outside of a request handler so it persists across requests. If you need to
- * augment a client inside a handler, call the `withRule()` function on the base
- * client.
+ * Create a new Node.js integration of Arcjet.
+ *
+ * > 👉 **Tip**:
+ * > build your initial base client with as many rules as possible outside of a
+ * > request handler;
+ * > if you need more rules inside handlers later then you can call `withRule()`
+ * > on that base client.
  *
- * @param options - Arcjet configuration options to apply to all requests.
+ * @template Rules
+ *   List of rules.
+ * @template Characteristics
+ *   Characteristics to track a user by.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Node.js integration of Arcjet.
  */
 function arcjet(options) {
     const client = options.client ?? createRemoteClient();
@@ -109,7 +123,7 @@ function arcjet(options) {
         const cookies = cookiesToString(request.headers?.cookie);
         // We construct an ArcjetHeaders to normalize over Headers
         const headers = new ArcjetHeaders(request.headers);
-        let ip = findIP({
+        let ip = findIp({
             socket: request.socket,
             headers,
         }, { platform: platform(env), proxies });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcjet/node",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.11",
   "description": "Arcjet SDK for Node.js",
   "keywords": [
     "analyze",
@@ -47,22 +47,21 @@
     "test": "npm run build && npm run lint"
   },
   "dependencies": {
-    "@arcjet/env": "1.0.0-beta.10",
-    "@arcjet/headers": "1.0.0-beta.10",
-    "@arcjet/ip": "1.0.0-beta.10",
-    "@arcjet/logger": "1.0.0-beta.10",
-    "@arcjet/protocol": "1.0.0-beta.10",
-    "@arcjet/transport": "1.0.0-beta.10",
-    "@arcjet/body": "1.0.0-beta.10",
-    "arcjet": "1.0.0-beta.10"
+    "@arcjet/env": "1.0.0-beta.11",
+    "@arcjet/headers": "1.0.0-beta.11",
+    "@arcjet/ip": "1.0.0-beta.11",
+    "@arcjet/logger": "1.0.0-beta.11",
+    "@arcjet/protocol": "1.0.0-beta.11",
+    "@arcjet/transport": "1.0.0-beta.11",
+    "@arcjet/body": "1.0.0-beta.11",
+    "arcjet": "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",
-    "@types/node": "18.18.0",
-    "@rollup/wasm-node": "4.46.2",
-    "eslint": "9.32.0",
+    "@arcjet/eslint-config": "1.0.0-beta.11",
+    "@arcjet/rollup-config": "1.0.0-beta.11",
+    "@types/node": "24.3.0",
+    "@rollup/wasm-node": "4.50.0",
+    "eslint": "9.34.0",
     "typescript": "5.9.2"
   },
   "publishConfig": {