chore(examples): Add example of testing APIs with Newman (#1083)

This adds an example to show how to leverage [newman](https://learning.postman.com/docs/collections/using-newman-cli/command-line-integration-with-newman/) with Postman Collections to test your API endpoints. 

I mostly hand-wrote the Postman Collections, but you could imagine them being maintained via the Postman application and saved to your test folder. Then newman can be run programmatically to verify the tests in CI, etc.

In the instructions, I also showed how to run `newman` from the CLI to test collections manually/individually to get more details about the tests that the automation provides.

This could further be expanded to combine newman's "iteration data" and something like [SecLists](https://github.com/danielmiessler/SecLists) to fuzz API endpoints.

In the interest of keeping the example focused, I removed some OpenAPI to Postman Collection code that I was experimenting with using the [openapi-to-postmanv2](https://www.npmjs.com/package/openapi-to-postmanv2) and [@wesleytodd/openapi](https://www.npmjs.com/package/@wesleytodd/openapi) packages, but those could be used to document and test the entire set of APIs with this same idea.

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);