chore: Update READMEs with latest examples (#1542)

* chore: Update READMEs with latest examples

* Characteristics

README.md

@@ -73,11 +73,11 @@ import { NextResponse } from "next/server";
 
 const aj = arcjet({
   key: process.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
-      characteristics: ["userId"], // track requests by a custom user ID
       refillRate: 5, // refill 5 tokens per interval
       interval: 10, // refill every 10 seconds
       capacity: 10, // bucket maximum capacity of 10 tokens
@@ -119,7 +119,9 @@ const aj = arcjet({
   rules: [
     detectBot({
       mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-      block: ["AUTOMATED"], // blocks all automated clients
+      // configured with a list of bots to allow from
+      // https://arcjet.com/bot-list
+      allow: [], // "allow none" will block all detected bots
     }),
   ],
 });

arcjet-bun/README.md

@@ -37,7 +37,7 @@ Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
 bun add @arcjet/bun
 ```
 
-## Rate limit example
+## Rate limit + bot detection example
 
 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
@@ -46,19 +46,25 @@ e.g. if they are logged in. The bucket is configured with a maximum capacity of
 tokens.
 
 ```ts
-import arcjet, { tokenBucket } from "@arcjet/bun";
+import arcjet, { tokenBucket, detectBot } from "@arcjet/bun";
 
 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
-      characteristics: ["userId"], // track requests by a custom user ID
       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
+    }),
   ],
 });
 
@@ -70,10 +76,7 @@ export default {
     console.log("Arcjet decision", decision);
 
     if (decision.isDenied()) {
-      return Response.json(
-        { error: "Too Many Requests", reason: decision.reason },
-        { status: 429 },
-      );
+      return Response.json({ error: "Forbidden" }, { status: 403 });
     } else {
       return Response.json({ message: "Hello world" });
     }

arcjet-next/README.md

@@ -40,31 +40,36 @@ Try an Arcjet protected app live at [https://example.arcjet.com][example-url]
 npm install -S @arcjet/next
 ```
 
-## Rate limit example
+## Rate limit + bot detection example
 
-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.
+The 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.
 
-See the [Arcjet rate limit documentation][rate-limit-quick-start] for details.
+Bot detection is also enabled to block requests from known bots.
 
 ```ts
-import arcjet, { tokenBucket } from "@arcjet/next";
+import arcjet, { tokenBucket, detectBot } from "@arcjet/next";
 import { NextResponse } from "next/server";
 
 const aj = arcjet({
   key: process.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
-      characteristics: ["userId"], // track requests by a custom user ID
       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
+    }),
   ],
 });
 
@@ -74,10 +79,7 @@ export async function GET(req: Request) {
   console.log("Arcjet decision", decision);
 
   if (decision.isDenied()) {
-    return NextResponse.json(
-      { error: "Too Many Requests", reason: decision.reason },
-      { status: 429 },
-    );
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
   }
 
   return NextResponse.json({ message: "Hello world" });
@@ -134,8 +136,6 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 [next-sdk-docs]: https://docs.arcjet.com/reference/nextjs
 [example-url]: https://example.arcjet.com
 [example-source]: https://github.com/arcjet/arcjet-js-example
-[rate-limit-concepts-docs]: https://docs.arcjet.com/rate-limiting/concepts
-[rate-limit-quick-start]: https://docs.arcjet.com/rate-limiting/quick-start/nextjs
 [shield-concepts-docs]: https://docs.arcjet.com/shield/concepts
 [shield-quick-start]: https://docs.arcjet.com/shield/quick-start/nextjs
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0

arcjet-node/README.md

@@ -42,27 +42,34 @@ npm install -S @arcjet/node
 
 ## Rate limit example
 
-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.
+The 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.
+
+Bot detection is also enabled to block requests from known bots.
 
 ```ts
-import arcjet, { tokenBucket } from "@arcjet/node";
+import arcjet, { tokenBucket, detectBot } from "@arcjet/node";
 import http from "node:http";
 
 const aj = arcjet({
   key: process.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
-      characteristics: ["userId"], // track requests by a custom user ID
       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
+    }),
   ],
 });
 
@@ -75,10 +82,8 @@ const server = http.createServer(async function (
   console.log("Arcjet decision", decision);
 
   if (decision.isDenied()) {
-    res.writeHead(429, { "Content-Type": "application/json" });
-    res.end(
-      JSON.stringify({ error: "Too Many Requests", reason: decision.reason }),
-    );
+    res.writeHead(403, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Forbidden" }));
   } else {
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ message: "Hello world" }));
@@ -135,6 +140,5 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 [example-url]: https://example.arcjet.com
 [quick-start]: https://docs.arcjet.com/get-started/nodejs
 [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

arcjet-sveltekit/README.md

@@ -39,29 +39,36 @@ npm install -S @arcjet/sveltekit
 
 ## Rate limit example
 
-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.
+The 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.
+
+Bot detection is also enabled to block requests from known bots.
 
 ```ts
 // In your `+page.server.ts` file
-import arcjet, { tokenBucket } from "@arcjet/sveltekit";
+import arcjet, { tokenBucket, detectBot } from "@arcjet/sveltekit";
 import { error, type RequestEvent } from "@sveltejs/kit";
 import { env } from "$env/dynamic/private";
 
 const aj = arcjet({
   key: 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
-      characteristics: ["userId"], // track requests by a custom user ID
       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
+    }),
   ],
 });
 
@@ -71,7 +78,7 @@ export async function load(event: RequestEvent) {
   console.log("Arcjet decision", decision);
 
   if (decision.isDenied()) {
-    return error(429, "Too Many Requests");
+    return error(403, "Forbidden");
   }
 
   return { message: "Hello world" };
@@ -133,6 +140,5 @@ Licensed under the [Apache License, Version 2.0][apache-license].
 [example-url]: https://example.arcjet.com
 [quick-start]: https://docs.arcjet.com/get-started/sveltekit
 [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

arcjet/README.md

@@ -37,11 +37,18 @@ integration.
 npm install -S arcjet
 ```
 
-## Example
+## Rate limit + bot detection example
+
+The 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.
+
+Bot detection is also enabled to block requests from known bots.
 
 ```ts
 import http from "http";
-import arcjet, { createRemoteClient } from "arcjet";
+import arcjet, { createRemoteClient, tokenBucket, detectBot } from "arcjet";
 import { baseUrl } from "@arcjet/env";
 import { createConnectTransport } from "@connectrpc/connect-node";
 
@@ -50,7 +57,22 @@ const aj = arcjet({
   // and set it as an environment variable rather than hard coding.
   // See: https://www.npmjs.com/package/dotenv
   key: process.env.ARCJET_KEY,
-  rules: [],
+  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
+    }),
+  ],
   client: createRemoteClient({
     transport: createConnectTransport({
       baseUrl: baseUrl(process.env),
@@ -76,7 +98,7 @@ const server = http.createServer(async function (
     path: path.pathname,
   };
 
-  const decision = await aj.protect(ctx, details);
+  const decision = await aj.protect(ctx, details, { requested: 5 }); // Deduct 5 tokens from the bucket
   console.log(decision);
 
   if (decision.isDenied()) {