Core concepts

Bridge

PlayclawBridge is the main class. It wires your message handler into PlayClaw audit sessions via a Supabase Realtime channel.

Constructor

Create a bridge instance with your token. All options except token are optional.

bridge.js

1const bridge = new PlayclawBridge({
2  token: process.env.PC_TOKEN,   // required — your PC-XXXX token
3  auditTurns: 5,                 // optional — default 5
4  logLevel: "info",              // optional — debug|info|warn|error|silent
5  rateLimit: {                   // optional — see Rate Limiting
6    maxPerWindow: 100,
7    windowMs: 60_000,
8    maxConcurrent: 5,
9  },
10});

Option	Type	Default	Description
token	string	—	Required. Your PlayClaw project token (PC-XXXX-…).
auditTurns	number	5	Max turns per audit session.
logLevel	string	"info"	debug \| info \| warn \| error \| silent.
rateLimit	RateLimitOptions	none	Sliding window rate limiter. See Rate Limiting docs.

Connect & disconnect

bridge.connect() opens the Supabase Realtime channel and starts listening for audit turns. Call bridge.disconnect() for a graceful shutdown.

bridge.js

1// Connects and starts listening
2await bridge.connect();
3 
4// Gracefully disconnects
5await bridge.disconnect();
6 
7// Read state
8console.log(bridge.isConnected);   // boolean
9console.log(bridge.sessionInfo);   // current session or null
10console.log(bridge.stats);         // { sessionsHandled, messagesHandled, errorsCount, reconnectsCount }

Auto-reconnect

If the channel drops, the bridge retries automatically using exponential backoff. You don't need to handle reconnection logic in your code.

bridge.js

1// Auto-reconnect is built in with exponential backoff:
2// 5s → 10s → 20s → 40s → 60s
3// You don't need to handle this manually.
4 
5bridge.onDisconnect(() => {
6  console.log("Bridge dropped. Auto-reconnect will retry.");
7});

Note

The bridge emits onConnect and onDisconnect hooks on every state change so you can log or monitor the connection from your infrastructure.

Stats

Read live stats from bridge.stats at any time:

Property	Type	Description
sessionsHandled	number	Total audit sessions processed since connect().
messagesHandled	number	Total individual turns processed.
errorsCount	number	Total errors caught by the bridge.
reconnectsCount	number	Number of auto-reconnect attempts made.

PreviousInstallation

Next Session context