Merging f53e28d into trunk-temp/pr-1083/2c8d97ff-4603-4ac8-acab-a3993…

…f11f155

examples/express-newman/.env.local.example

@@ -0,0 +1,6 @@
+# NODE_ENV is not set by the environment
+ARCJET_ENV=development
+# Add your Arcjet key from https://app.arcjet.com
+ARCJET_KEY=
+# Silence Arcjet SDK logs for our testing
+ARCJET_LOG_LEVEL=error

examples/express-newman/README.md

@@ -0,0 +1,51 @@
+<a href="https://arcjet.com" target="_arcjet-home">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://arcjet.com/logo/arcjet-dark-lockup-voyage-horizontal.svg">
+    <img src="https://arcjet.com/logo/arcjet-light-lockup-voyage-horizontal.svg" alt="Arcjet Logo" height="128" width="auto">
+  </picture>
+</a>
+
+# Testing Arcjet with Express and Newman
+
+This example shows how to test your [Express][express-docs] API routes are
+protected by Arcjet using [Newman][newman-docs].
+
+## How to use
+
+1. From the root of the project, install the SDK dependencies.
+
+   ```bash
+   npm ci
+   ```
+
+2. Enter this directory and install the example's dependencies.
+
+   ```bash
+   cd examples/express-newman
+   npm ci
+   ```
+
+3. Rename `.env.local.example` to `.env.local` and add your Arcjet key.
+
+4. Start the server.
+
+   ```bash
+   npm start
+   ```
+
+   This assumes you're using Node.js 20 or later because the `start` script
+   loads a local environment file with `--env-file`. If you're using an older
+   version of Node.js, you can use a package like
+   [dotenv](https://www.npmjs.com/package/dotenv) to load the environment file.
+
+5. In another terminal, run the included Postman Collections as tests:
+
+   - `npx newman run tests/low-rate-limit.json`
+   - `npx newman run tests/high-rate-limit.json -n 51`
+   - `npx newman run tests/bots.json`
+
+6. You can also stop your server and run them as part of your test suite via
+   `npm test`.
+
+[express-docs]: https://expressjs.com/
+[newman-docs]: https://learning.postman.com/docs/collections/using-newman-cli/command-line-integration-with-newman/

examples/express-newman/index.js

@@ -0,0 +1,56 @@
+import express from "express";
+import arcjet, { detectBot, fixedWindow } from "@arcjet/node";
+
+const aj = arcjet({
+  key: process.env.ARCJET_KEY,
+  rules: [],
+});
+
+const app = express();
+
+app.get("/api/low-rate-limit", async (req, res) => {
+  const decision = await aj
+    // Only inline to self-contain the sample code.
+    // Static rules should be defined outside the handler for performance.
+    .withRule(fixedWindow({ mode: "LIVE", window: "1s", max: 1 }))
+    .protect(req);
+
+  if (decision.isDenied()) {
+    res.status(429).json({ error: "rate limited" });
+  } else {
+    res.json({ hello: "world" });
+  }
+});
+
+app.get("/api/high-rate-limit", async (req, res) => {
+  const decision = await aj
+    // Only inline to self-contain the sample code.
+    // Static rules should be defined outside the handler for performance.
+    .withRule(fixedWindow({ mode: "LIVE", window: "3s", max: 50 }))
+    .protect(req);
+
+  if (decision.isDenied()) {
+    res.status(429).json({ error: "rate limited" });
+  } else {
+    res.json({ hello: "world" });
+  }
+});
+
+app.get("/api/bots", async (req, res) => {
+  const decision = await aj
+    // Only inline to self-contain the sample code.
+    // Static rules should be defined outside the handler for performance.
+    .withRule(detectBot({ mode: "LIVE" }))
+    .protect(req);
+
+  if (decision.isDenied()) {
+    res.status(403).json({ error: "bot detected" });
+  } else {
+    res.json({ hello: "world" });
+  }
+});
+
+const server = app.listen(8080);
+
+// Export the server close function so we can shut it down in our tests
+export const close = server.close.bind(server);