Core concepts

Rate limiting

Pass a rateLimit config to PlayclawBridge to automatically guard against burst traffic. The limiter is the first middleware in the chain.

Basic setup

Pass a rateLimit object to the constructor. The limiter is inserted as the first middleware automatically — it runs before your custom bridge.use() chain.

bridge.js

1const bridge = new PlayclawBridge({
2  token: process.env.PC_TOKEN,
3  rateLimit: {
4    maxPerWindow: 100,   // max messages across all sessions per window
5    windowMs: 60_000,    // window size in ms (here: 1 minute)
6    maxConcurrent: 5,    // max sessions handled simultaneously
7  },
8});

Option	Type	Description
maxPerWindow	number	Max total messages across all sessions within the time window.
windowMs	number	Sliding window size in milliseconds.
maxConcurrent	number	Max number of sessions that can be processed simultaneously.

Note

When the rate limit is exceeded, the turn is cancelled and your onError hook receives a PlayclawError with code RATE_LIMITED.

Standalone usage

You can also instantiate PlayclawRateLimiter directly to use it outside the bridge (e.g. in an HTTP middleware or external service).

limiter.js

1import { PlayclawRateLimiter } from "playclaw-sdk";
2 
3const limiter = new PlayclawRateLimiter({
4  maxPerWindow: 200,
5  windowMs: 60_000,
6  maxConcurrent: 10,
7});
8 
9// Check status at any time
10console.log(limiter.status());
11// { count: 42, windowMs: 60000, concurrent: { "sess_abc": 1 } }

PreviousMiddleware

Next Logger