chore!: deprecate reason for ArcjetAllowDecision

decorate/index.ts

@@ -122,9 +122,9 @@ function extractReason(result: ArcjetRuleResult): ArcjetReason {
 }
 
 function isRateLimitReason(
-  reason: ArcjetReason,
+  reason?: ArcjetReason,
 ): reason is ArcjetRateLimitReason {
-  return reason.isRateLimit();
+  return typeof reason !== "undefined" && reason.isRateLimit();
 }
 
 function nearestLimit(

examples/nextjs-bot-categories/app/api/arcjet/route.ts

@@ -1,4 +1,4 @@
-import arcjet, { botCategories, detectBot } from "@arcjet/next";
+import arcjet, { ArcjetRuleResult, botCategories, detectBot } from "@arcjet/next";
 import { NextResponse } from "next/server";
 
 const aj = arcjet({
@@ -23,6 +23,26 @@ const aj = arcjet({
   ],
 });
 
+function reduceAllowedBots(bots: string[], rule: ArcjetRuleResult) {
+  if (rule.reason.isBot()) {
+    return [...bots, ...rule.reason.allowed]
+  } else {
+    return bots;
+  }
+}
+
+function reduceDeniedBots(bots: string[], rule: ArcjetRuleResult) {
+  if (rule.reason.isBot()) {
+    return [...bots, ...rule.reason.denied]
+  } else {
+    return bots;
+  }
+}
+
+function checkSpoofed(rule: ArcjetRuleResult) {
+  return rule.reason.isBot() && rule.reason.isSpoofed()
+}
+
 export async function GET(req: Request) {
   const decision = await aj.protect(req);
 
@@ -33,20 +53,27 @@ export async function GET(req: Request) {
     )
   }
 
-  const headers = new Headers();
-  if (decision.reason.isBot()) {
-    // WARNING: This is illustrative! Don't share this metadata with users;
-    // otherwise they may use it to subvert bot detection!
-    headers.set("X-Arcjet-Bot-Allowed", decision.reason.allowed.join(", "))
-    headers.set("X-Arcjet-Bot-Denied", decision.reason.denied.join(", "))
-
-    // We need to check that the bot is who they say they are.
-    if (decision.reason.isSpoofed()) {
-      return NextResponse.json(
-        { error: "You are pretending to be a good bot!" },
-        { status: 403, headers },
-      );
-    }
+  const allowedBots = decision.results.reduce<string[]>(reduceAllowedBots, []);
+
+  const deniedBots = decision.results.reduce<string[]>(reduceDeniedBots, []);
+
+  const isSpoofed = decision.results.some(checkSpoofed);
+
+  // WARNING: This is illustrative! Don't share this metadata with users;
+  // otherwise they may use it to subvert bot detection!
+  const headers = new Headers({
+    "X-Arcjet-Bot-Allowed": allowedBots.join(", "),
+    "X-Arcjet-Bot-Denied": deniedBots.join(", "),
+  });
+  headers.set("X-Arcjet-Bot-Allowed", allowedBots.join(", "))
+  headers.set("X-Arcjet-Bot-Denied", deniedBots.join(", "))
+
+  // We need to check that the bot is who they say they are.
+  if (isSpoofed) {
+    return NextResponse.json(
+      { error: "You are pretending to be a good bot!" },
+      { status: 403, headers },
+    );
   }
 
   if (decision.isDenied()) {

examples/nextjs-clerk-rate-limit/app/api/arcjet/route.ts

@@ -1,4 +1,5 @@
-import arcjet, { ArcjetDecision, tokenBucket, shield } from "@arcjet/next";
+import arcjet, { ArcjetDecision, tokenBucket, shield, ArcjetRateLimitReason, ArcjetReason, ArcjetRuleResult } from "@arcjet/next";
+import format from "@arcjet/sprintf";
 import { NextRequest, NextResponse } from "next/server";
 import { currentUser } from "@clerk/nextjs/server";
 import ip from "@arcjet/ip";
@@ -16,6 +17,47 @@ const aj = arcjet({
   ],
 });
 
+function extractReason(result: ArcjetRuleResult): ArcjetReason {
+  return result.reason;
+}
+
+function isRateLimitReason(
+  reason?: ArcjetReason,
+): reason is ArcjetRateLimitReason {
+  return typeof reason !== "undefined" && reason.isRateLimit();
+}
+
+function nearestLimit(
+  current: ArcjetRateLimitReason,
+  next: ArcjetRateLimitReason,
+) {
+  if (current.remaining < next.remaining) {
+    return current;
+  }
+
+  if (current.remaining > next.remaining) {
+    return next;
+  }
+
+  // Reaching here means `remaining` is equal so prioritize closest reset
+  if (current.reset < next.reset) {
+    return current;
+  }
+
+  if (current.reset > next.reset) {
+    return next;
+  }
+
+  // Reaching here means that `remaining` and `reset` are equal, so prioritize
+  // the smallest `max`
+  if (current.max < next.max) {
+    return current;
+  }
+
+  // All else equal, just return the next item in the list
+  return next;
+}
+
 export async function GET(req: NextRequest) {
   // Get the current user from Clerk
   // See https://clerk.com/docs/references/nextjs/current-user
@@ -69,13 +111,40 @@ export async function GET(req: NextRequest) {
       );
     }
   }
-  
+
   let reset: Date | undefined;
   let remaining: number | undefined;
 
-  if (decision.reason.isRateLimit()) {
-    reset = decision.reason.resetTime;
-    remaining = decision.reason.remaining;
+  const rateLimitReasons = decision.results
+    .map(extractReason)
+    .filter(isRateLimitReason);
+
+  if (rateLimitReasons.length > 0) {
+    const policies = new Map<number, number>();
+    for (const reason of rateLimitReasons) {
+      if (policies.has(reason.max)) {
+        console.error(
+          "Invalid rate limit policy—two policies should not share the same limit",
+        );
+      }
+
+      if (
+        typeof reason.max !== "number" ||
+        typeof reason.window !== "number" ||
+        typeof reason.remaining !== "number" ||
+        typeof reason.reset !== "number"
+      ) {
+        console.error(format("Invalid rate limit encountered: %o", reason));
+      }
+
+      policies.set(reason.max, reason.window);
+    }
+
+    const rl = rateLimitReasons.reduce(nearestLimit);
+
+    reset = rl.resetTime;
+    remaining = rl.remaining;
   }
 
-  return NextResponse.json({ message: "Hello World", reset, remaining });}
+  return NextResponse.json({ message: "Hello World", reset, remaining });
+}

examples/nextjs-clerk-rate-limit/package.json

@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@arcjet/next": "file:../../arcjet-next",
+    "@arcjet/sprintf": "file:../../sprintf",
     "@clerk/nextjs": "^6.9.1",
     "next": "15.1.0",
     "react": "^19",
@@ -26,4 +27,4 @@
     "tailwindcss": "^3.4.16",
     "typescript": "^5"
   }
-}
+}

examples/nextjs-openai/app/api/chat/route.ts

@@ -15,7 +15,8 @@
  adding custom characteristics so you could use a user ID to track authenticated
  users instead. See the `chat_userid` example for an example of this.
 */
-import arcjet, { shield, tokenBucket } from "@arcjet/next";
+import arcjet, { ArcjetRateLimitReason, ArcjetReason, ArcjetRuleResult, shield, tokenBucket } from "@arcjet/next";
+import format from "@arcjet/sprintf";
 import { openai } from '@ai-sdk/openai';
 import { streamText } from 'ai';
 import { promptTokensEstimate } from "openai-chat-tokens";
@@ -39,6 +40,47 @@ const aj = arcjet({
   ],
 });
 
+function extractReason(result: ArcjetRuleResult): ArcjetReason {
+  return result.reason;
+}
+
+function isRateLimitReason(
+  reason?: ArcjetReason,
+): reason is ArcjetRateLimitReason {
+  return typeof reason !== "undefined" && reason.isRateLimit();
+}
+
+function nearestLimit(
+  current: ArcjetRateLimitReason,
+  next: ArcjetRateLimitReason,
+) {
+  if (current.remaining < next.remaining) {
+    return current;
+  }
+
+  if (current.remaining > next.remaining) {
+    return next;
+  }
+
+  // Reaching here means `remaining` is equal so prioritize closest reset
+  if (current.reset < next.reset) {
+    return current;
+  }
+
+  if (current.reset > next.reset) {
+    return next;
+  }
+
+  // Reaching here means that `remaining` and `reset` are equal, so prioritize
+  // the smallest `max`
+  if (current.max < next.max) {
+    return current;
+  }
+
+  // All else equal, just return the next item in the list
+  return next;
+}
+
 // Allow streaming responses up to 30 seconds
 export const maxDuration = 30;
 
@@ -48,7 +90,7 @@ export const runtime = "edge";
 export async function POST(req: Request) {
   const { messages } = await req.json();
 
-   // Estimate the number of tokens required to process the request
+  // Estimate the number of tokens required to process the request
   const estimate = promptTokensEstimate({
     messages,
   });
@@ -59,8 +101,40 @@ export async function POST(req: Request) {
   const decision = await aj.protect(req, { requested: estimate });
   console.log("Arcjet decision", decision.conclusion);
 
-  if (decision.reason.isRateLimit()) {
-    console.log("Requests remaining", decision.reason.remaining);
+  const rateLimitReasons = decision.results
+    .map(extractReason)
+    .filter(isRateLimitReason);
+
+  let remaining: number | undefined;
+
+  if (rateLimitReasons.length > 0) {
+    const policies = new Map<number, number>();
+    for (const reason of rateLimitReasons) {
+      if (policies.has(reason.max)) {
+        console.error(
+          "Invalid rate limit policy—two policies should not share the same limit",
+        );
+      }
+
+      if (
+        typeof reason.max !== "number" ||
+        typeof reason.window !== "number" ||
+        typeof reason.remaining !== "number" ||
+        typeof reason.reset !== "number"
+      ) {
+        console.error(format("Invalid rate limit encountered: %o", reason));
+      }
+
+      policies.set(reason.max, reason.window);
+    }
+
+    const rl = rateLimitReasons.reduce(nearestLimit);
+
+    remaining = rl.remaining;
+  }
+
+  if (typeof remaining !== "undefined") {
+    console.log("Requests remaining", remaining);
   }
 
   // If the request is denied, return a 429
@@ -83,4 +157,4 @@ export async function POST(req: Request) {
   });
 
   return result.toDataStreamResponse();
-}
+}