@arcjet/bun 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -22,6 +22,9 @@ against common attacks.
 
 This is the [Arcjet][arcjet] SDK for [Bun.sh][bun-sh].
 
+- [npm package (`@arcjet/bun`)](https://www.npmjs.com/package/@arcjet/bun)
+- [GitHub source code (`arcjet-bun/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/arcjet-bun)
+
 ## Getting started
 
 Visit the [quick start guide][quick-start] to get started.
@@ -31,100 +34,76 @@ Visit the [quick start guide][quick-start] to get started.
 Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
 ([source code][example-source]).
 
-## Installation
+## What is this?
 
-```shell
-bun add @arcjet/bun
-```
+This is our adapter to integrate Arcjet into Bun.
+Arcjet helps you secure your Bun server.
+This package exists so that we can provide the best possible experience to
+Bun users.
 
-## Rate limit + bot detection example
+## When should I use this?
 
-The [Arcjet rate limit][rate-limit-concepts-docs] example below applies a token
-bucket rate limit rule to a route where we identify the user based on their ID
-e.g. if they are logged in. The bucket is configured with a maximum capacity of
-10 tokens and refills by 5 tokens every 10 seconds. Each request consumes 5
-tokens.
+You can use this if you are using Bun.
+See our [_Get started_ guide][arcjet-get-started] for other supported
+runtimes.
 
-```ts
-import arcjet, { tokenBucket, detectBot } from "@arcjet/bun";
+## Install
 
-const aj = arcjet({
-  key: Bun.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com
-  characteristics: ["userId"], // track requests by a custom user ID
-  rules: [
-    // Create a token bucket rate limit. Other algorithms are supported.
-    tokenBucket({
-      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-      refillRate: 5, // refill 5 tokens per interval
-      interval: 10, // refill every 10 seconds
-      capacity: 10, // bucket maximum capacity of 10 tokens
-    }),
-    detectBot({
-      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-      // configured with a list of bots to allow from
-      // https://arcjet.com/bot-list
-      allow: [], // "allow none" will block all detected bots
-    }),
-  ],
-});
-
-export default {
-  port: 8000,
-  fetch: aj.handler(async function (req: Request) {
-    const userId = "user123"; // Replace with your authenticated user ID
-    const decision = await aj.protect(req, { userId, requested: 5 }); // Deduct 5 tokens from the bucket
-    console.log("Arcjet decision", decision);
+This package is ESM only.
+Install with Bun:
 
-    if (decision.isDenied()) {
-      return Response.json({ error: "Forbidden" }, { status: 403 });
-    } else {
-      return Response.json({ message: "Hello world" });
-    }
-  }),
-};
+```sh
+bun add @arcjet/bun
 ```
 
-## Shield example
-
-[Arcjet Shield][shield-concepts-docs] protects your application against common
-attacks, including the OWASP Top 10. You can run Shield on every request with
-negligible performance impact.
+## Use
 
 ```ts
 import arcjet, { shield } from "@arcjet/bun";
 
+// Get your Arcjet key at <https://app.arcjet.com>.
+// Set it as an environment variable instead of hard coding it.
+const arcjetKey = Bun.env.ARCJET_KEY;
+
+if (!arcjetKey) {
+  throw new Error("Cannot find `ARCJET_KEY` environment variable");
+}
+
 const aj = arcjet({
-  key: Bun.env.ARCJET_KEY, // Get your site key from https://app.arcjet.com
+  key: arcjetKey,
   rules: [
-    shield({
-      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-    }),
+    // Shield protects your app from common attacks.
+    // Use `DRY_RUN` instead of `LIVE` to only log.
+    shield({ mode: "LIVE" }),
   ],
 });
 
 export default {
   port: 8000,
-  fetch: aj.handler(async function (req: Request) {
-    const decision = await aj.protect(req);
+  fetch: aj.handler(async function (request: Request) {
+    const decision = await aj.protect(request);
 
     if (decision.isDenied()) {
-      return Response.json({ error: "Forbidden" }, { status: 403 });
-    } else {
-      return Response.json({ message: "Hello world" });
+      return Response.json({ message: "Forbidden" }, { status: 403 });
     }
+
+    return Response.json({ message: "Hello world" });
   }),
 };
 ```
 
+For more on how to configure Arcjet with Bun and how to protect Bun,
+see the [Arcjet Bun SDK reference][arcjet-reference-bun] on our website.
+
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
+[arcjet-get-started]: https://docs.arcjet.com/get-started
+[arcjet-reference-bun]: https://docs.arcjet.com/reference/bun
 [arcjet]: https://arcjet.com
 [bun-sh]: https://bun.sh/
 [example-url]: https://example.arcjet.com
 [quick-start]: https://docs.arcjet.com/get-started/bun
 [example-source]: https://github.com/arcjet/arcjet-js-example
-[rate-limit-concepts-docs]: https://docs.arcjet.com/rate-limiting/concepts
-[shield-concepts-docs]: https://docs.arcjet.com/shield/concepts
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0

package/index.d.ts

@@ -11,58 +11,111 @@ 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;
 /**
- * The options used to configure an {@link ArcjetBun} client.
+ * Configuration for the Bun 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 ArcjetBun client provides a public `protect()` method to
- * make a decision about how a Bun.sh request should be handled.
+ * Instance of the Bun integration of Arcjet.
+ *
+ * Primarily has a `protect()` method to make a decision about how a Bun request
+ * should be handled.
+ *
+ * @template Props
+ *   Configuration.
  */
 export interface ArcjetBun<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.
      *
-     * @param request - A `Request` provided to the fetch handler.
-     * @param props - Additonal properties required for running rules against a request.
-     * @returns An {@link ArcjetDecision} indicating Arcjet's decision about the request.
+     * This will analyze the request locally where possible and otherwise call
+     * the Arcjet decision API.
+     *
+     * @param ctx
+     *   Additional context for this function call.
+     * @param request
+     *   Details about the {@linkcode Request} 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: Request, ...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.
+     *
+     * Useful for varying rules based on criteria in your handler such as
+     * different rate limit for logged in users.
      *
-     * @param rule The rule to add to this execution.
-     * @returns An augmented {@link ArcjetBun} client.
+     * @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): ArcjetBun<Simplify<Props & ExtraProps<Rule>>>;
     /**
-     * Wraps the Bun.sh `fetch` handler to provide additional Request details
-     * when calling the SDK's `protect()` function.
+     * Wrap the Bun `fetch` handler to provide additional details when calling
+     * the `protect()` method.
      *
-     * @param fetch: The user provided `fetch` handler
+     * @param fetch
+     *   Original `fetch` from Bun.
+     * @returns
+     *   Wrapped `fetch` handler.
      */
     handler(fetch: (this: Server, request: Request, server: Server) => Response | Promise<Response>): (this: Server, request: Request, server: Server) => Response | Promise<Response>;
 }
 /**
- * Create a new {@link ArcjetBun} 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 Bun integration of Arcjet.
  *
- * @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
+ *   Bun integration of Arcjet.
  */
 export default function arcjet<const Rules extends (Primitive | Product)[], const Characteristics extends readonly string[]>(options: ArcjetOptions<Rules, Characteristics>): ArcjetBun<Simplify<ExtraProps<Rules> & CharacteristicProps<Characteristics>>>;

package/index.js

@@ -1,14 +1,14 @@
 import core__default from 'arcjet';
 export * from 'arcjet';
-import findIP from '@arcjet/ip';
-import ArcjetHeaders from '@arcjet/headers';
+import findIp, { parseProxy } from '@arcjet/ip';
+import { ArcjetHeaders } from '@arcjet/headers';
 import { env } from 'bun';
-import { logLevel, baseUrl, isDevelopment, platform } from '@arcjet/env';
+import { logLevel, isDevelopment, baseUrl, platform } from '@arcjet/env';
 import { Logger } from '@arcjet/logger';
 import { createClient } from '@arcjet/protocol/client.js';
 import { createTransport } from '@arcjet/transport';
 
-/// <reference types="bun-types/bun.d.ts" />
+/// <reference types="bun-types" />
 // TODO: Deduplicate with other packages
 function errorMessage(err) {
     if (err) {
@@ -23,17 +23,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 = "BUN";
-    const sdkVersion = "1.0.0-beta.1";
+    const sdkVersion = "1.0.0-beta.11";
     return createClient({
         transport,
         baseUrl: url,
@@ -43,12 +47,16 @@ function createRemoteClient(options) {
     });
 }
 /**
- * Create a new {@link ArcjetBun} 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 Bun integration of Arcjet.
  *
- * @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
+ *   Bun integration of Arcjet.
  */
 function arcjet(options) {
     const client = options.client ?? createRemoteClient();
@@ -61,23 +69,28 @@ function arcjet(options) {
         : new Logger({
             level: logLevel(env),
         });
+    const proxies = Array.isArray(options.proxies)
+        ? options.proxies.map(parseProxy)
+        : undefined;
+    if (isDevelopment(process.env)) {
+        log.warn("Arcjet will use 127.0.0.1 when missing public IP address in development mode");
+    }
     function toArcjetRequest(request, props) {
         const cookies = request.headers.get("cookie") ?? undefined;
         // We construct an ArcjetHeaders to normalize over Headers
         const headers = new ArcjetHeaders(request.headers);
         const url = new URL(request.url);
-        let ip = findIP({
+        let ip = findIp({
             // This attempts to lookup the IP in the `ipCache`. This is primarily a
             // workaround to the API design in Bun that requires access to the
             // `Server` to lookup an IP.
             ip: ipCache.get(request),
             headers,
-        }, { platform: platform(env), proxies: options.proxies });
+        }, { platform: platform(env), proxies });
         if (ip === "") {
             // If the `ip` is empty but we're in development mode, we default the IP
             // so the request doesn't fail.
             if (isDevelopment(env)) {
-                log.warn("Using 127.0.0.1 as IP address in development mode");
                 ip = "127.0.0.1";
             }
             else {

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@arcjet/bun",
-  "version": "1.0.0-beta.1",
-  "description": "Arcjet SDK for Bun.sh",
+  "version": "1.0.0-beta.11",
+  "description": "Arcjet SDK for Bun",
+  "keywords": [
+    "analyze",
+    "arcjet",
+    "attack",
+    "bun.sh",
+    "bun",
+    "limit",
+    "protect",
+    "secure",
+    "security",
+    "verify"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
   "repository": {
@@ -23,37 +35,32 @@
   "main": "./index.js",
   "types": "./index.d.ts",
   "files": [
-    "LICENSE",
-    "README.md",
-    "*.js",
-    "*.d.ts",
-    "!*.config.js"
+    "index.d.ts",
+    "index.js"
   ],
   "scripts": {
-    "prepublishOnly": "npm run build",
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
-    "pretest": "npm run build",
-    "test": "node --test --experimental-test-coverage"
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && npm run lint"
   },
   "dependencies": {
-    "@arcjet/env": "1.0.0-beta.1",
-    "@arcjet/headers": "1.0.0-beta.1",
-    "@arcjet/ip": "1.0.0-beta.1",
-    "@arcjet/logger": "1.0.0-beta.1",
-    "@arcjet/protocol": "1.0.0-beta.1",
-    "@arcjet/transport": "1.0.0-beta.1",
-    "arcjet": "1.0.0-beta.1"
+    "@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": "1.0.0-beta.11"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-beta.1",
-    "@arcjet/rollup-config": "1.0.0-beta.1",
-    "@arcjet/tsconfig": "1.0.0-beta.1",
-    "@types/node": "20.12.12",
-    "@rollup/wasm-node": "4.30.1",
-    "bun-types": "1.1.43",
-    "expect": "29.7.0",
-    "typescript": "5.7.3"
+    "@arcjet/eslint-config": "1.0.0-beta.11",
+    "@arcjet/rollup-config": "1.0.0-beta.11",
+    "@rollup/wasm-node": "4.50.0",
+    "bun-types": "1.2.21",
+    "eslint": "9.34.0",
+    "typescript": "5.9.2",
+    "undici-types": "7.15.0"
   },
   "publishConfig": {
     "access": "public",