API Reference

Full API Reference

All classes, methods, and options exported from playclaw-sdk.

PlayclawBridge

Method	Returns	Description
new PlayclawBridge(options)	PlayclawBridge	Create a bridge. Only token is required.
bridge.connect()	Promise<void>	Open channel and start listening for audit turns.
bridge.disconnect()	Promise<void>	Gracefully close the channel.
bridge.onMessage(fn)	void	Register message handler. fn(message, context) → string.
bridge.onSessionStart(fn)	void	fn(sessionId) — fires when a new audit session opens.
bridge.onSessionEnd(fn)	void	fn(sessionId, history) — fires when session completes.
bridge.onConnect(fn)	void	fn() — fires when channel is live.
bridge.onDisconnect(fn)	void	fn() — fires when channel drops.
bridge.onError(fn)	void	fn(error, sessionId?) — fires on any error.
bridge.use(fn)	void	Add pre-message middleware. Return transformed string or throw.
bridge.useReply(fn)	void	Add post-reply middleware. Return transformed string.
bridge.stats	BridgeStats	{ sessionsHandled, messagesHandled, errorsCount, reconnectsCount }
bridge.isConnected	boolean	True if the channel is currently live.
bridge.sessionInfo	SessionInfo \| null	Current session state or null between sessions.

PlayclawLogger

Method	Description
new PlayclawLogger({ level, prefix, output })	Create a logger. All options are optional.
logger.debug(msg)	Log at debug level.
logger.info(msg)	Log at info level.
logger.warn(msg)	Log at warn level.
logger.error(msg)	Log at error level.
logger.child(name)	Create a child logger with a nested prefix.
logger.setLevel(l)	Change log level at runtime.

PlayclawRateLimiter

Method	Description
new PlayclawRateLimiter({ maxPerWindow, windowMs, maxConcurrent })	Create a rate limiter.
limiter.isAllowed(sessionId)	Returns true if the request should proceed.
limiter.recordStart(sessionId)	Mark a session as processing.
limiter.recordEnd(sessionId)	Mark a session as done.
limiter.status()	Returns { count, windowMs, concurrent }.
limiter.middleware()	Returns a bridge.use()-compatible middleware function.

MockTransport (testing)

Import from playclaw-sdk/test/transport.mock. Swaps out the real Supabase transport so your tests run without a network connection.

bridge.test.js

1import { PlayclawBridge } from "playclaw-sdk";
2import { MockTransport } from "playclaw-sdk/test/transport.mock";
3import assert from "node:assert";
4 
5const bridge = new PlayclawBridge({ token: "PC-TEST", logLevel: "silent" });
6const mock = new MockTransport();
7 
8// Swap the real Supabase transport with the mock
9bridge._transport = mock;
10mock._messageHandler = bridge._handleIncoming.bind(bridge);
11 
12bridge.onMessage(async (msg) => `echo: ${msg}`);
13 
14await mock.simulateMessage({ content: "hello", session_id: "s1" });
15 
16assert.strictEqual(mock.responses[0].payload.content, "echo: hello");

Property / Method	Description
mock.simulateMessage(payload)	Trigger an incoming message as if PlayClaw sent it.
mock.simulateDisconnect()	Simulate a channel drop.
mock.simulateError()	Simulate a transport error.
mock.responses	Array of agent:response events sent by the bridge.
mock.errors	Array of agent:error events sent by the bridge.
mock.sentEvents	Raw array of all outgoing events.
mock.reset()	Clear all recorded events.

PreviousLogger