verani 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+ISC License
+
+Copyright (c) 2025, Verani contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

package/README.md

@@ -0,0 +1,212 @@
+# Verani
+
+> A simple, focused realtime SDK for Cloudflare Actors with Socket.io-like semantics
+
+Verani brings the familiar developer experience of Socket.io to Cloudflare's Durable Objects (Actors), with proper hibernation support and minimal overhead.
+
+## Why Verani?
+
+- **Familiar API**: If you've used Socket.io, you already know how to use Verani
+- **Hibernation Support**: Properly handles Cloudflare Actor hibernation out of the box
+- **Type Safe**: Built with TypeScript, full type safety throughout
+- **Simple Mental Model**: Rooms, channels, and broadcast semantics that just make sense
+- **Production Ready**: Automatic reconnection, error handling, and connection lifecycle management
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install verani @cloudflare/actors
+# or
+bun add verani @cloudflare/actors
+```
+
+### Server Side (Cloudflare Worker)
+
+```typescript
+import { defineRoom, createActorHandler } from "verani";
+
+// Define your room with lifecycle hooks
+export const chatRoom = defineRoom({
+  name: "chat",
+
+  onConnect(ctx) {
+    console.log(`User ${ctx.meta.userId} connected`);
+    ctx.actor.broadcast("default", {
+      type: "user.joined",
+      userId: ctx.meta.userId
+    });
+  },
+
+  onMessage(ctx, frame) {
+    if (frame.type === "chat.message") {
+      // Broadcast to everyone except sender
+      ctx.actor.broadcast("default", {
+        type: "chat.message",
+        from: ctx.meta.userId,
+        text: frame.data.text
+      }, { except: ctx.ws });
+    }
+  },
+
+  onDisconnect(ctx) {
+    console.log(`User ${ctx.meta.userId} disconnected`);
+  }
+});
+
+// Create the Durable Object class
+const ChatRoom = createActorHandler(chatRoom);
+
+// Export it - the name must match wrangler.jsonc
+export { ChatRoom };
+```
+
+### Wrangler Configuration
+
+**Critical**: Your Durable Object export names in `src/index.ts` **must match** the `class_name` in `wrangler.jsonc`:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {
+        "class_name": "ChatRoom",  // Must match export name
+        "name": "ChatRoom"              // Binding name in env
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "new_sqlite_classes": ["ChatRoom"],
+      "tag": "v1"
+    }
+  ]
+}
+```
+
+The three-way relationship:
+1. **Export** in `src/index.ts`: `export { ChatRoom }`
+2. **Class name** in `wrangler.jsonc`: `"class_name": "ChatRoom"`
+3. **Env binding**: Access via `env.CHAT` in your fetch handler
+
+### Client Side
+
+```typescript
+import { VeraniClient } from "verani";
+
+// Connect to your Cloudflare Worker
+const client = new VeraniClient("wss://your-worker.dev/ws?userId=alice");
+
+// Listen for messages
+client.on("chat.message", (data) => {
+  console.log(`${data.from}: ${data.text}`);
+});
+
+// Send messages
+client.emit("chat.message", { text: "Hello, world!" });
+
+// Handle connection lifecycle
+client.onOpen(() => {
+  console.log("Connected!");
+});
+
+client.onStateChange((state) => {
+  console.log("Connection state:", state);
+});
+```
+
+## Key Concepts
+
+### Actors = Rooms
+
+Each Cloudflare Actor instance represents a **logical container** for realtime communication:
+
+- **Chat room**: All users in the same chat share one Actor
+- **User notifications**: Each user gets their own Actor
+- **Game session**: Each game instance is one Actor
+
+### Channels
+
+Inside an Actor, connections can join **channels** for selective message routing:
+
+```typescript
+// Server: broadcast to specific channel
+ctx.actor.broadcast("game-updates", data);
+
+// Client: joins "default" channel automatically
+// You can implement join/leave for custom channels
+```
+
+### Hibernation
+
+Verani handles Cloudflare's hibernation automatically:
+
+- Connection metadata survives hibernation via WebSocket attachments
+- Sessions are restored when the Actor wakes up
+- No manual state management needed
+
+## Documentation
+
+- **[Getting Started](./docs/GETTING_STARTED.md)** - Step-by-step tutorial
+- **[Mental Model](./docs/MENTAL_MODEL.md)** - Understanding Verani's architecture
+- **[API Reference](./docs/API.md)** - Complete API documentation
+- **[Examples](./docs/EXAMPLES.md)** - Common usage patterns
+- **[Security Guide](./docs/SECURITY.md)** - Authentication, authorization, and best practices
+- **[Deployment](./docs/DEPLOYMENT.md)** - Deploy to Cloudflare Workers
+
+## Features
+
+### Server (Actor) Side
+
+- Room-based architecture with lifecycle hooks
+- WebSocket attachment management for hibernation
+- Selective broadcasting with filters
+- User and client ID tracking
+- Error boundaries and logging
+- Flexible metadata extraction from requests
+
+### Client Side
+
+- Automatic reconnection with exponential backoff
+- Connection state management
+- Message queueing when disconnected
+- Event-based API (on/off/once/emit)
+- Promise-based connection waiting
+- Lifecycle callbacks
+
+## Live Examples
+
+Try out Verani with working examples:
+
+```bash
+# Clone and run
+git clone https://github.com/your-org/verani
+cd verani
+bun install  # or npm install
+bun run dev  # or npm run dev
+
+# Open http://localhost:8787
+```
+
+See `examples/` for chat, presence, and notifications demos!
+
+## Project Status
+
+Verani is in active development. Current version is an MVP focused on core functionality:
+
+- Core realtime messaging
+- Hibernation support
+- Client reconnection
+- Presence protocol (coming soon)
+- Persistent storage integration (coming soon)
+- React/framework adapters (coming soon)
+
+## License
+
+ISC
+
+## Contributing
+
+Contributions welcome! Please read our contributing guidelines first.
+

package/dist/verani.cjs

@@ -0,0 +1 @@
+let __cloudflare_actors=require(`@cloudflare/actors`);function extractUserId(e){let b=new URL(e.url),x=b.searchParams.get(`userId`)||b.searchParams.get(`user_id`);if(x)return x;let S=e.headers.get(`Authorization`);return S?.startsWith(`Bearer `)?S.substring(7):e.headers.get(`X-User-ID`)||`anonymous`}function extractClientId(e){let b=new URL(e.url);return b.searchParams.get(`clientId`)||b.searchParams.get(`client_id`)||e.headers.get(`X-Client-ID`)||crypto.randomUUID()}function defaultExtractMeta(e){let S=extractUserId(e),C=extractClientId(e),w=new URL(e.url).searchParams.get(`channels`);return{userId:S,clientId:C,channels:w?w.split(`,`).map(e=>e.trim()).filter(Boolean):[`default`]}}function defineRoom(e){return{name:e.name,websocketPath:e.websocketPath,extractMeta:e.extractMeta||defaultExtractMeta,onConnect:e.onConnect,onDisconnect:e.onDisconnect,onMessage:e.onMessage,onError:e.onError}}function parseJWT(e){try{let b=e.split(`.`);if(b.length!==3)return null;let x=b[1],S=atob(x.replace(/-/g,`+`).replace(/_/g,`/`));return JSON.parse(S)}catch{return null}}function storeAttachment(e,b){e.serializeAttachment(b)}function restoreSessions(e){let b=0;for(let x of e.ctx.getWebSockets()){let S=x.deserializeAttachment();S&&(e.sessions.set(x,{ws:x,meta:S}),b++)}}function isValidFrame(e){return e&&typeof e==`object`&&typeof e.type==`string`&&(e.channel===void 0||typeof e.channel==`string`)}function decodeFrame(e){try{let b=typeof e==`string`?e:e.toString(),x=JSON.parse(b);return isValidFrame(x)?x:null}catch{return null}}function decodeClientMessage(e){return decodeFrame(e)}function decodeServerMessage(e){return decodeFrame(e)}function encodeFrame(e){try{return JSON.stringify(e)}catch(e){throw Error(`Failed to encode frame: ${e instanceof Error?e.message:`unknown error`}`)}}function encodeClientMessage(e){return encodeFrame(e)}function encodeServerMessage(e){return encodeFrame(e)}function decodeFrame$1(e){return decodeFrame(e)??{type:`invalid`}}function encodeFrame$1(e){return encodeFrame(e)}function sanitizeToClassName(e){return e.replace(/^\/+/,``).split(/[-_\/\s]+/).map(e=>e.replace(/[^a-zA-Z0-9]/g,``)).filter(e=>e.length>0).map(e=>e.charAt(0).toUpperCase()+e.slice(1).toLowerCase()).join(``)||`VeraniActor`}function createActorHandler(b){let x=sanitizeToClassName(b.name||b.websocketPath||`VeraniActor`);class S extends __cloudflare_actors.Actor{constructor(...e){super(...e),this.sessions=new Map}static configuration(e){return{locationHint:`me`,sockets:{upgradePath:b.websocketPath,autoResponse:{ping:`ping`,pong:`pong`}}}}async shouldUpgradeWebSocket(e){return!0}async fetch(e){let x=new URL(e.url),S=e.headers.get(`Upgrade`);return x.pathname===b.websocketPath&&S===`websocket`&&await this.shouldUpgradeWebSocket(e)?this.onWebSocketUpgrade(e):this.onRequest(e)}async onInit(){try{restoreSessions(this),b.onHibernationRestore&&this.sessions.size>0&&await b.onHibernationRestore(this)}catch{}}onWebSocketConnect(e,x){try{let S;if(S=b.extractMeta?b.extractMeta(x):{userId:`anonymous`,clientId:crypto.randomUUID(),channels:[`default`]},storeAttachment(e,S),this.sessions.set(e,{ws:e,meta:S}),b.onConnect){let x={actor:this,ws:e,meta:S};b.onConnect(x)}}catch(x){if(b.onError)try{b.onError(x,{actor:this,ws:e,meta:{userId:`unknown`,clientId:`unknown`,channels:[]}})}catch{}e.close(1011,`Internal server error`)}}onWebSocketMessage(e,x){let S;try{let C=decodeFrame$1(x);if(S=this.sessions.get(e),!S)return;if(b.onMessage){let x={actor:this,ws:e,meta:S.meta,frame:C};b.onMessage(x,C)}}catch(x){if(b.onError&&S)try{b.onError(x,{actor:this,ws:e,meta:S.meta})}catch{}}}onWebSocketDisconnect(e){try{let x=this.sessions.get(e);if(this.sessions.delete(e),x&&b.onDisconnect){let S={actor:this,ws:e,meta:x.meta};b.onDisconnect(S)}}catch{}}broadcast(e,b,x){let S=0,C=encodeFrame$1({type:`event`,channel:e,data:b});for(let{ws:b,meta:w}of this.sessions.values())if(w.channels.includes(e)&&!(x?.except&&b===x.except)&&!(x?.userIds&&!x.userIds.includes(w.userId))&&!(x?.clientIds&&!x.clientIds.includes(w.clientId)))try{b.send(C),S++}catch{}return S}getSessionCount(){return this.sessions.size}getConnectedUserIds(){let e=new Set;for(let{meta:b}of this.sessions.values())e.add(b.userId);return Array.from(e)}getUserSessions(e){let b=[];for(let{ws:x,meta:S}of this.sessions.values())S.userId===e&&b.push(x);return b}sendToUser(e,b,x){let S=0,C=encodeFrame$1({type:b,data:x});for(let{ws:b,meta:x}of this.sessions.values())if(x.userId===e)try{b.send(C),S++}catch{}return S}getStorage(){return this.ctx.storage}}return Object.defineProperty(S,`name`,{value:x,writable:!1,configurable:!0}),S}function encodeClientMessage$1(e){return encodeClientMessage(e)}function decodeServerMessage$1(e){return decodeServerMessage(e)}const DEFAULT_RECONNECTION_CONFIG={enabled:!0,maxAttempts:10,initialDelay:1e3,maxDelay:3e4,backoffMultiplier:1.5};var ConnectionManager=class{constructor(e=DEFAULT_RECONNECTION_CONFIG,b){this.config=e,this.onStateChange=b,this.state=`disconnected`,this.reconnectAttempts=0,this.currentDelay=e.initialDelay}getState(){return this.state}setState(e){this.state!==e&&(this.state=e,this.onStateChange?.(e))}resetReconnection(){this.reconnectAttempts=0,this.currentDelay=this.config.initialDelay,this.clearReconnectTimer()}scheduleReconnect(e){return this.config.enabled?this.config.maxAttempts>0&&this.reconnectAttempts>=this.config.maxAttempts?(this.setState(`error`),!1):(this.clearReconnectTimer(),this.setState(`reconnecting`),this.reconnectAttempts++,this.reconnectTimer=setTimeout(()=>{e(),this.currentDelay=Math.min(this.currentDelay*this.config.backoffMultiplier,this.config.maxDelay)},this.currentDelay),!0):!1}cancelReconnect(){this.clearReconnectTimer(),this.state===`reconnecting`&&this.setState(`disconnected`)}clearReconnectTimer(){this.reconnectTimer!==void 0&&(clearTimeout(this.reconnectTimer),this.reconnectTimer=void 0)}getReconnectAttempts(){return this.reconnectAttempts}getNextDelay(){return this.currentDelay}destroy(){this.clearReconnectTimer()}},VeraniClient=class{constructor(e,b={}){this.url=e,this.listeners=new Map,this.messageQueue=[],this.options={reconnection:{enabled:b.reconnection?.enabled??DEFAULT_RECONNECTION_CONFIG.enabled,maxAttempts:b.reconnection?.maxAttempts??DEFAULT_RECONNECTION_CONFIG.maxAttempts,initialDelay:b.reconnection?.initialDelay??DEFAULT_RECONNECTION_CONFIG.initialDelay,maxDelay:b.reconnection?.maxDelay??DEFAULT_RECONNECTION_CONFIG.maxDelay,backoffMultiplier:b.reconnection?.backoffMultiplier??DEFAULT_RECONNECTION_CONFIG.backoffMultiplier},maxQueueSize:b.maxQueueSize??100,connectionTimeout:b.connectionTimeout??1e4},this.connectionManager=new ConnectionManager(this.options.reconnection,e=>{this.onStateChangeCallback?.(e)}),this.connect()}connect(){try{this.connectionManager.setState(`connecting`),this.ws=new WebSocket(this.url);let e=setTimeout(()=>{this.connectionManager.getState()===`connecting`&&(this.ws?.close(),this.handleConnectionError(Error(`Connection timeout`)))},this.options.connectionTimeout);this.ws.addEventListener(`open`,()=>{clearTimeout(e),this.handleOpen()}),this.ws.addEventListener(`message`,e=>{this.handleMessage(e)}),this.ws.addEventListener(`close`,b=>{clearTimeout(e),this.handleClose(b)}),this.ws.addEventListener(`error`,b=>{clearTimeout(e),this.handleError(b)})}catch(e){this.handleConnectionError(e)}}handleOpen(){this.connectionManager.setState(`connected`),this.connectionManager.resetReconnection(),this.flushMessageQueue(),this.connectionResolve&&(this.connectionResolve(),this.connectionPromise=void 0,this.connectionResolve=void 0,this.connectionReject=void 0),this.onOpenCallback?.()}handleMessage(e){let b=decodeServerMessage$1(e.data);if(!b)return;let x=b.type,S=b.data;b.type===`event`&&b.data&&typeof b.data==`object`&&`type`in b.data&&(x=b.data.type,S=b.data);let C=this.listeners.get(x);if(C)for(let e of C)try{e(S)}catch{}}handleClose(e){this.connectionManager.setState(`disconnected`),this.connectionReject&&=(this.connectionReject(Error(`Connection closed: ${e.reason||`Unknown reason`}`)),this.connectionPromise=void 0,this.connectionResolve=void 0,void 0),this.onCloseCallback?.(e),e.code!==1e3&&e.code!==1001&&this.connectionManager.scheduleReconnect(()=>this.connect())}handleError(e){this.onErrorCallback?.(e)}handleConnectionError(e){this.connectionReject&&=(this.connectionReject(e),this.connectionPromise=void 0,this.connectionResolve=void 0,void 0),this.connectionManager.scheduleReconnect(()=>this.connect())}flushMessageQueue(){if(!(!this.ws||this.ws.readyState!==WebSocket.OPEN))for(;this.messageQueue.length>0;){let e=this.messageQueue.shift();try{this.ws.send(encodeClientMessage$1(e))}catch{}}}getState(){return this.connectionManager.getState()}isConnected(){return this.ws?.readyState===WebSocket.OPEN}waitForConnection(){return this.isConnected()?Promise.resolve():(this.connectionPromise||=new Promise((e,b)=>{this.connectionResolve=e,this.connectionReject=b}),this.connectionPromise)}on(e,b){this.listeners.has(e)||this.listeners.set(e,new Set),this.listeners.get(e).add(b)}off(e,b){let x=this.listeners.get(e);x&&(x.delete(b),x.size===0&&this.listeners.delete(e))}once(e,b){let x=S=>{this.off(e,x),b(S)};this.on(e,x)}emit(e,b){let x={type:e,data:b};if(this.isConnected())try{this.ws.send(encodeClientMessage$1(x))}catch{this.queueMessage(x)}else this.queueMessage(x)}queueMessage(e){this.messageQueue.length>=this.options.maxQueueSize&&this.messageQueue.shift(),this.messageQueue.push(e)}onOpen(e){this.onOpenCallback=e}onClose(e){this.onCloseCallback=e}onError(e){this.onErrorCallback=e}onStateChange(e){this.onStateChangeCallback=e}reconnect(){this.disconnect(),this.connect()}disconnect(){this.connectionManager.cancelReconnect(),this.ws&&=(this.ws.close(1e3,`Client disconnect`),void 0)}close(){this.disconnect(),this.listeners.clear(),this.messageQueue=[],this.connectionManager.destroy()}};const PROTOCOL_VERSION=`1.0.0`;exports.ConnectionManager=ConnectionManager,exports.DEFAULT_RECONNECTION_CONFIG=DEFAULT_RECONNECTION_CONFIG,exports.PROTOCOL_VERSION=`1.0.0`,exports.VeraniClient=VeraniClient,exports.createActorHandler=createActorHandler,exports.decodeClientMessage=decodeClientMessage,exports.decodeFrame=decodeFrame,exports.decodeServerMessage=decodeServerMessage,exports.defineRoom=defineRoom,exports.encodeClientMessage=encodeClientMessage,exports.encodeFrame=encodeFrame,exports.encodeServerMessage=encodeServerMessage,exports.parseJWT=parseJWT,exports.restoreSessions=restoreSessions,exports.storeAttachment=storeAttachment;

package/dist/verani.d.cts

@@ -0,0 +1,399 @@
+import { Actor, ActorConfiguration } from "@cloudflare/actors";
+
+//#region src/shared/types.d.ts
+
+/**
+ * Core message types shared between client and server
+ */
+/**
+ * Base message frame structure used for all WebSocket communication
+ */
+interface MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Message sent from client to server
+ */
+interface ClientMessage extends MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Message sent from server to client
+ */
+interface ServerMessage extends MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Connection metadata attached to each WebSocket
+ */
+interface ConnectionMeta {
+  userId: string;
+  clientId: string;
+  channels: string[];
+}
+/**
+ * Unified message type for both directions
+ */
+type VeraniMessage = ClientMessage | ServerMessage;
+/**
+ * Protocol version for future compatibility
+ */
+declare const PROTOCOL_VERSION = "1.0.0";
+//#endregion
+//#region src/actor/types.d.ts
+/**
+ * Options for broadcasting messages to connections
+ */
+interface BroadcastOptions {
+  /** Exclude specific WebSocket from receiving the broadcast */
+  except?: WebSocket;
+  /** Only send to specific user IDs */
+  userIds?: string[];
+  /** Only send to specific client IDs */
+  clientIds?: string[];
+}
+/**
+ * Extended Actor interface with Verani-specific methods
+ */
+interface VeraniActor<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> extends Actor<E> {
+  sessions: Map<WebSocket, {
+    ws: WebSocket;
+    meta: TMeta;
+  }>;
+  broadcast(channel: string, data: any, opts?: BroadcastOptions): number;
+  getSessionCount(): number;
+  getConnectedUserIds(): string[];
+  getUserSessions(userId: string): WebSocket[];
+  sendToUser(userId: string, type: string, data?: any): number;
+  getStorage(): DurableObjectStorage;
+}
+/**
+ * Context provided to room lifecycle hooks
+ */
+interface RoomContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /** The actor instance handling this connection */
+  actor: VeraniActor<TMeta, E>;
+  /** The WebSocket connection */
+  ws: WebSocket;
+  /** Connection metadata */
+  meta: TMeta;
+}
+/**
+ * Context for onMessage hook with frame included
+ */
+interface MessageContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> extends RoomContext<TMeta, E> {
+  /** The received message frame */
+  frame: MessageFrame;
+}
+/**
+ * Room definition with lifecycle hooks
+ */
+interface RoomDefinition<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /** Optional room name for debugging */
+  name?: string;
+  /** WebSocket upgrade path (default: "/ws") */
+  websocketPath: string;
+  /** Extract metadata from the connection request */
+  extractMeta?(req: Request): TMeta | Promise<TMeta>;
+  /** Called when a new WebSocket connection is established */
+  onConnect?(ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /** Called when a WebSocket connection is closed */
+  onDisconnect?(ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /** Called when a message is received from a connection */
+  onMessage?(ctx: MessageContext<TMeta, E>, frame: MessageFrame): void | Promise<void>;
+  /** Called when an error occurs in a lifecycle hook */
+  onError?(error: Error, ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /** Called after actor wakes from hibernation and sessions are restored */
+  onHibernationRestore?(actor: VeraniActor<TMeta, E>): void | Promise<void>;
+}
+//#endregion
+//#region src/actor/router.d.ts
+/**
+ * Defines a room with lifecycle hooks and metadata extraction
+ * @param def - Room definition with optional hooks
+ * @returns Normalized room definition with defaults
+ */
+declare function defineRoom<TMeta extends ConnectionMeta = ConnectionMeta>(def: RoomDefinition<TMeta>): RoomDefinition<TMeta>;
+/**
+ * Helper to parse JWT tokens (basic implementation)
+ * In production, use a proper JWT library
+ * @param token - JWT token string
+ * @returns Decoded payload or null if invalid
+ */
+declare function parseJWT(token: string): any;
+//#endregion
+//#region src/actor/actor-runtime.d.ts
+/**
+ * Actor stub interface returned by .get() method
+ */
+interface ActorStub {
+  fetch(request: Request): Promise<Response>;
+}
+/**
+ * Return type for createActorHandler - represents an Actor class constructor
+ */
+type ActorHandlerClass<E = unknown> = {
+  new (state: any, env: E): Actor<E>;
+  get(id: string): ActorStub;
+  configuration(request?: Request): ActorConfiguration;
+};
+/**
+ * Creates an Actor handler from a room definition
+ * @param room - The room definition with lifecycle hooks
+ * @returns Actor class for Cloudflare Workers (extends DurableObject)
+ */
+declare function createActorHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown>(room: RoomDefinition<TMeta, E>): ActorHandlerClass<E>;
+//#endregion
+//#region src/actor/attachment.d.ts
+declare function storeAttachment(ws: WebSocket, meta: ConnectionMeta): void;
+declare function restoreSessions(actor: any): void;
+//#endregion
+//#region src/client/connection.d.ts
+/**
+ * Connection state management for Verani client
+ */
+type ConnectionState = "connecting" | "connected" | "disconnected" | "reconnecting" | "error";
+interface ReconnectionConfig {
+  /** Enable automatic reconnection */
+  enabled: boolean;
+  /** Maximum number of reconnection attempts (0 = infinite) */
+  maxAttempts: number;
+  /** Initial delay in milliseconds */
+  initialDelay: number;
+  /** Maximum delay in milliseconds */
+  maxDelay: number;
+  /** Backoff multiplier for exponential backoff */
+  backoffMultiplier: number;
+}
+declare const DEFAULT_RECONNECTION_CONFIG: ReconnectionConfig;
+/**
+ * Manages WebSocket connection lifecycle and reconnection logic
+ */
+declare class ConnectionManager {
+  private config;
+  private onStateChange?;
+  private state;
+  private reconnectAttempts;
+  private reconnectTimer?;
+  private currentDelay;
+  constructor(config?: ReconnectionConfig, onStateChange?: ((state: ConnectionState) => void) | undefined);
+  /**
+   * Gets the current connection state
+   */
+  getState(): ConnectionState;
+  /**
+   * Updates the connection state and notifies listeners
+   */
+  setState(newState: ConnectionState): void;
+  /**
+   * Resets reconnection state (called on successful connection)
+   */
+  resetReconnection(): void;
+  /**
+   * Schedules a reconnection attempt
+   */
+  scheduleReconnect(connectFn: () => void): boolean;
+  /**
+   * Cancels any pending reconnection
+   */
+  cancelReconnect(): void;
+  /**
+   * Clears the reconnect timer
+   */
+  private clearReconnectTimer;
+  /**
+   * Gets the current reconnection attempt count
+   */
+  getReconnectAttempts(): number;
+  /**
+   * Gets the next reconnection delay
+   */
+  getNextDelay(): number;
+  /**
+   * Cleanup method
+   */
+  destroy(): void;
+}
+//#endregion
+//#region src/client/client.d.ts
+/**
+ * Client options for configuring the Verani client
+ */
+interface VeraniClientOptions {
+  /** Reconnection configuration */
+  reconnection?: Partial<ReconnectionConfig>;
+  /** Maximum number of messages to queue when disconnected */
+  maxQueueSize?: number;
+  /** Connection timeout in milliseconds */
+  connectionTimeout?: number;
+}
+/**
+ * Verani WebSocket client with automatic reconnection and lifecycle management
+ */
+declare class VeraniClient {
+  private url;
+  private ws?;
+  private listeners;
+  private connectionManager;
+  private messageQueue;
+  private options;
+  private onOpenCallback?;
+  private onCloseCallback?;
+  private onErrorCallback?;
+  private onStateChangeCallback?;
+  private connectionPromise?;
+  private connectionResolve?;
+  private connectionReject?;
+  /**
+   * Creates a new Verani client
+   * @param url - WebSocket URL to connect to
+   * @param options - Client configuration options
+   */
+  constructor(url: string, options?: VeraniClientOptions);
+  /**
+   * Establishes WebSocket connection
+   */
+  private connect;
+  /**
+   * Handles successful WebSocket connection
+   */
+  private handleOpen;
+  /**
+   * Handles incoming WebSocket messages
+   */
+  private handleMessage;
+  /**
+   * Handles WebSocket closure
+   */
+  private handleClose;
+  /**
+   * Handles WebSocket errors
+   */
+  private handleError;
+  /**
+   * Handles connection errors
+   */
+  private handleConnectionError;
+  /**
+   * Flushes queued messages when connection is established
+   */
+  private flushMessageQueue;
+  /**
+   * Gets the current connection state
+   */
+  getState(): ConnectionState;
+  /**
+   * Checks if the client is currently connected
+   */
+  isConnected(): boolean;
+  /**
+   * Waits for the connection to be established
+   * @returns Promise that resolves when connected
+   */
+  waitForConnection(): Promise<void>;
+  /**
+   * Registers an event listener
+   * @param event - Event type to listen for
+   * @param callback - Callback function to invoke when event is received
+   */
+  on(event: string, callback: (data: any) => void): void;
+  /**
+   * Removes an event listener
+   * @param event - Event type to remove listener from
+   * @param callback - Callback function to remove
+   */
+  off(event: string, callback: (data: any) => void): void;
+  /**
+   * Registers a one-time event listener
+   * @param event - Event type to listen for
+   * @param callback - Callback function to invoke once
+   */
+  once(event: string, callback: (data: any) => void): void;
+  /**
+   * Sends a message to the server
+   * @param type - Message type
+   * @param data - Optional message data
+   */
+  emit(type: string, data?: any): void;
+  /**
+   * Queues a message for sending when connected
+   */
+  private queueMessage;
+  /**
+   * Registers lifecycle callback for connection open
+   */
+  onOpen(callback: () => void): void;
+  /**
+   * Registers lifecycle callback for connection close
+   */
+  onClose(callback: (event: CloseEvent) => void): void;
+  /**
+   * Registers lifecycle callback for connection error
+   */
+  onError(callback: (error: Event) => void): void;
+  /**
+   * Registers lifecycle callback for state changes
+   */
+  onStateChange(callback: (state: ConnectionState) => void): void;
+  /**
+   * Manually triggers a reconnection
+   */
+  reconnect(): void;
+  /**
+   * Closes the connection without reconnecting
+   */
+  disconnect(): void;
+  /**
+   * Closes the connection and cleans up resources
+   */
+  close(): void;
+}
+//#endregion
+//#region src/shared/encode.d.ts
+/**
+ * Encodes a message frame to JSON string for transmission
+ * @param frame - The message frame to encode
+ * @returns JSON string representation of the frame
+ * @throws Error if encoding fails
+ */
+declare function encodeFrame(frame: MessageFrame): string;
+/**
+ * Encodes a client message to JSON string
+ * @param message - The client message to encode
+ * @returns JSON string representation
+ */
+declare function encodeClientMessage(message: MessageFrame): string;
+/**
+ * Encodes a server message to JSON string
+ * @param message - The server message to encode
+ * @returns JSON string representation
+ */
+declare function encodeServerMessage(message: MessageFrame): string;
+//#endregion
+//#region src/shared/decode.d.ts
+/**
+ * Decodes a raw message into a MessageFrame
+ * @param raw - Raw data from WebSocket (string, ArrayBuffer, etc)
+ * @returns Decoded MessageFrame or null if invalid
+ */
+declare function decodeFrame(raw: any): MessageFrame | null;
+/**
+ * Decodes a client message
+ * @param raw - Raw data from client WebSocket
+ * @returns Decoded message or null if invalid
+ */
+declare function decodeClientMessage(raw: any): MessageFrame | null;
+/**
+ * Decodes a server message
+ * @param raw - Raw data from server WebSocket
+ * @returns Decoded message or null if invalid
+ */
+declare function decodeServerMessage(raw: any): MessageFrame | null;
+//#endregion
+export { type BroadcastOptions, type ClientMessage, ConnectionManager, type ConnectionMeta, type ConnectionState, DEFAULT_RECONNECTION_CONFIG, type MessageContext, type MessageFrame, PROTOCOL_VERSION, type ReconnectionConfig, type RoomContext, type RoomDefinition, type ServerMessage, type VeraniActor, VeraniClient, type VeraniClientOptions, type VeraniMessage, createActorHandler, decodeClientMessage, decodeFrame, decodeServerMessage, defineRoom, encodeClientMessage, encodeFrame, encodeServerMessage, parseJWT, restoreSessions, storeAttachment };

package/dist/verani.d.mts

@@ -0,0 +1,399 @@
+import { Actor, ActorConfiguration } from "@cloudflare/actors";
+
+//#region src/shared/types.d.ts
+
+/**
+ * Core message types shared between client and server
+ */
+/**
+ * Base message frame structure used for all WebSocket communication
+ */
+interface MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Message sent from client to server
+ */
+interface ClientMessage extends MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Message sent from server to client
+ */
+interface ServerMessage extends MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Connection metadata attached to each WebSocket
+ */
+interface ConnectionMeta {
+  userId: string;
+  clientId: string;
+  channels: string[];
+}
+/**
+ * Unified message type for both directions
+ */
+type VeraniMessage = ClientMessage | ServerMessage;
+/**
+ * Protocol version for future compatibility
+ */
+declare const PROTOCOL_VERSION = "1.0.0";
+//#endregion
+//#region src/actor/types.d.ts
+/**
+ * Options for broadcasting messages to connections
+ */
+interface BroadcastOptions {
+  /** Exclude specific WebSocket from receiving the broadcast */
+  except?: WebSocket;
+  /** Only send to specific user IDs */
+  userIds?: string[];
+  /** Only send to specific client IDs */
+  clientIds?: string[];
+}
+/**
+ * Extended Actor interface with Verani-specific methods
+ */
+interface VeraniActor<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> extends Actor<E> {
+  sessions: Map<WebSocket, {
+    ws: WebSocket;
+    meta: TMeta;
+  }>;
+  broadcast(channel: string, data: any, opts?: BroadcastOptions): number;
+  getSessionCount(): number;
+  getConnectedUserIds(): string[];
+  getUserSessions(userId: string): WebSocket[];
+  sendToUser(userId: string, type: string, data?: any): number;
+  getStorage(): DurableObjectStorage;
+}
+/**
+ * Context provided to room lifecycle hooks
+ */
+interface RoomContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /** The actor instance handling this connection */
+  actor: VeraniActor<TMeta, E>;
+  /** The WebSocket connection */
+  ws: WebSocket;
+  /** Connection metadata */
+  meta: TMeta;
+}
+/**
+ * Context for onMessage hook with frame included
+ */
+interface MessageContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> extends RoomContext<TMeta, E> {
+  /** The received message frame */
+  frame: MessageFrame;
+}
+/**
+ * Room definition with lifecycle hooks
+ */
+interface RoomDefinition<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /** Optional room name for debugging */
+  name?: string;
+  /** WebSocket upgrade path (default: "/ws") */
+  websocketPath: string;
+  /** Extract metadata from the connection request */
+  extractMeta?(req: Request): TMeta | Promise<TMeta>;
+  /** Called when a new WebSocket connection is established */
+  onConnect?(ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /** Called when a WebSocket connection is closed */
+  onDisconnect?(ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /** Called when a message is received from a connection */
+  onMessage?(ctx: MessageContext<TMeta, E>, frame: MessageFrame): void | Promise<void>;
+  /** Called when an error occurs in a lifecycle hook */
+  onError?(error: Error, ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  /** Called after actor wakes from hibernation and sessions are restored */
+  onHibernationRestore?(actor: VeraniActor<TMeta, E>): void | Promise<void>;
+}
+//#endregion
+//#region src/actor/router.d.ts
+/**
+ * Defines a room with lifecycle hooks and metadata extraction
+ * @param def - Room definition with optional hooks
+ * @returns Normalized room definition with defaults
+ */
+declare function defineRoom<TMeta extends ConnectionMeta = ConnectionMeta>(def: RoomDefinition<TMeta>): RoomDefinition<TMeta>;
+/**
+ * Helper to parse JWT tokens (basic implementation)
+ * In production, use a proper JWT library
+ * @param token - JWT token string
+ * @returns Decoded payload or null if invalid
+ */
+declare function parseJWT(token: string): any;
+//#endregion
+//#region src/actor/actor-runtime.d.ts
+/**
+ * Actor stub interface returned by .get() method
+ */
+interface ActorStub {
+  fetch(request: Request): Promise<Response>;
+}
+/**
+ * Return type for createActorHandler - represents an Actor class constructor
+ */
+type ActorHandlerClass<E = unknown> = {
+  new (state: any, env: E): Actor<E>;
+  get(id: string): ActorStub;
+  configuration(request?: Request): ActorConfiguration;
+};
+/**
+ * Creates an Actor handler from a room definition
+ * @param room - The room definition with lifecycle hooks
+ * @returns Actor class for Cloudflare Workers (extends DurableObject)
+ */
+declare function createActorHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown>(room: RoomDefinition<TMeta, E>): ActorHandlerClass<E>;
+//#endregion
+//#region src/actor/attachment.d.ts
+declare function storeAttachment(ws: WebSocket, meta: ConnectionMeta): void;
+declare function restoreSessions(actor: any): void;
+//#endregion
+//#region src/client/connection.d.ts
+/**
+ * Connection state management for Verani client
+ */
+type ConnectionState = "connecting" | "connected" | "disconnected" | "reconnecting" | "error";
+interface ReconnectionConfig {
+  /** Enable automatic reconnection */
+  enabled: boolean;
+  /** Maximum number of reconnection attempts (0 = infinite) */
+  maxAttempts: number;
+  /** Initial delay in milliseconds */
+  initialDelay: number;
+  /** Maximum delay in milliseconds */
+  maxDelay: number;
+  /** Backoff multiplier for exponential backoff */
+  backoffMultiplier: number;
+}
+declare const DEFAULT_RECONNECTION_CONFIG: ReconnectionConfig;
+/**
+ * Manages WebSocket connection lifecycle and reconnection logic
+ */
+declare class ConnectionManager {
+  private config;
+  private onStateChange?;
+  private state;
+  private reconnectAttempts;
+  private reconnectTimer?;
+  private currentDelay;
+  constructor(config?: ReconnectionConfig, onStateChange?: ((state: ConnectionState) => void) | undefined);
+  /**
+   * Gets the current connection state
+   */
+  getState(): ConnectionState;
+  /**
+   * Updates the connection state and notifies listeners
+   */
+  setState(newState: ConnectionState): void;
+  /**
+   * Resets reconnection state (called on successful connection)
+   */
+  resetReconnection(): void;
+  /**
+   * Schedules a reconnection attempt
+   */
+  scheduleReconnect(connectFn: () => void): boolean;
+  /**
+   * Cancels any pending reconnection
+   */
+  cancelReconnect(): void;
+  /**
+   * Clears the reconnect timer
+   */
+  private clearReconnectTimer;
+  /**
+   * Gets the current reconnection attempt count
+   */
+  getReconnectAttempts(): number;
+  /**
+   * Gets the next reconnection delay
+   */
+  getNextDelay(): number;
+  /**
+   * Cleanup method
+   */
+  destroy(): void;
+}
+//#endregion
+//#region src/client/client.d.ts
+/**
+ * Client options for configuring the Verani client
+ */
+interface VeraniClientOptions {
+  /** Reconnection configuration */
+  reconnection?: Partial<ReconnectionConfig>;
+  /** Maximum number of messages to queue when disconnected */
+  maxQueueSize?: number;
+  /** Connection timeout in milliseconds */
+  connectionTimeout?: number;
+}
+/**
+ * Verani WebSocket client with automatic reconnection and lifecycle management
+ */
+declare class VeraniClient {
+  private url;
+  private ws?;
+  private listeners;
+  private connectionManager;
+  private messageQueue;
+  private options;
+  private onOpenCallback?;
+  private onCloseCallback?;
+  private onErrorCallback?;
+  private onStateChangeCallback?;
+  private connectionPromise?;
+  private connectionResolve?;
+  private connectionReject?;
+  /**
+   * Creates a new Verani client
+   * @param url - WebSocket URL to connect to
+   * @param options - Client configuration options
+   */
+  constructor(url: string, options?: VeraniClientOptions);
+  /**
+   * Establishes WebSocket connection
+   */
+  private connect;
+  /**
+   * Handles successful WebSocket connection
+   */
+  private handleOpen;
+  /**
+   * Handles incoming WebSocket messages
+   */
+  private handleMessage;
+  /**
+   * Handles WebSocket closure
+   */
+  private handleClose;
+  /**
+   * Handles WebSocket errors
+   */
+  private handleError;
+  /**
+   * Handles connection errors
+   */
+  private handleConnectionError;
+  /**
+   * Flushes queued messages when connection is established
+   */
+  private flushMessageQueue;
+  /**
+   * Gets the current connection state
+   */
+  getState(): ConnectionState;
+  /**
+   * Checks if the client is currently connected
+   */
+  isConnected(): boolean;
+  /**
+   * Waits for the connection to be established
+   * @returns Promise that resolves when connected
+   */
+  waitForConnection(): Promise<void>;
+  /**
+   * Registers an event listener
+   * @param event - Event type to listen for
+   * @param callback - Callback function to invoke when event is received
+   */
+  on(event: string, callback: (data: any) => void): void;
+  /**
+   * Removes an event listener
+   * @param event - Event type to remove listener from
+   * @param callback - Callback function to remove
+   */
+  off(event: string, callback: (data: any) => void): void;
+  /**
+   * Registers a one-time event listener
+   * @param event - Event type to listen for
+   * @param callback - Callback function to invoke once
+   */
+  once(event: string, callback: (data: any) => void): void;
+  /**
+   * Sends a message to the server
+   * @param type - Message type
+   * @param data - Optional message data
+   */
+  emit(type: string, data?: any): void;
+  /**
+   * Queues a message for sending when connected
+   */
+  private queueMessage;
+  /**
+   * Registers lifecycle callback for connection open
+   */
+  onOpen(callback: () => void): void;
+  /**
+   * Registers lifecycle callback for connection close
+   */
+  onClose(callback: (event: CloseEvent) => void): void;
+  /**
+   * Registers lifecycle callback for connection error
+   */
+  onError(callback: (error: Event) => void): void;
+  /**
+   * Registers lifecycle callback for state changes
+   */
+  onStateChange(callback: (state: ConnectionState) => void): void;
+  /**
+   * Manually triggers a reconnection
+   */
+  reconnect(): void;
+  /**
+   * Closes the connection without reconnecting
+   */
+  disconnect(): void;
+  /**
+   * Closes the connection and cleans up resources
+   */
+  close(): void;
+}
+//#endregion
+//#region src/shared/encode.d.ts
+/**
+ * Encodes a message frame to JSON string for transmission
+ * @param frame - The message frame to encode
+ * @returns JSON string representation of the frame
+ * @throws Error if encoding fails
+ */
+declare function encodeFrame(frame: MessageFrame): string;
+/**
+ * Encodes a client message to JSON string
+ * @param message - The client message to encode
+ * @returns JSON string representation
+ */
+declare function encodeClientMessage(message: MessageFrame): string;
+/**
+ * Encodes a server message to JSON string
+ * @param message - The server message to encode
+ * @returns JSON string representation
+ */
+declare function encodeServerMessage(message: MessageFrame): string;
+//#endregion
+//#region src/shared/decode.d.ts
+/**
+ * Decodes a raw message into a MessageFrame
+ * @param raw - Raw data from WebSocket (string, ArrayBuffer, etc)
+ * @returns Decoded MessageFrame or null if invalid
+ */
+declare function decodeFrame(raw: any): MessageFrame | null;
+/**
+ * Decodes a client message
+ * @param raw - Raw data from client WebSocket
+ * @returns Decoded message or null if invalid
+ */
+declare function decodeClientMessage(raw: any): MessageFrame | null;
+/**
+ * Decodes a server message
+ * @param raw - Raw data from server WebSocket
+ * @returns Decoded message or null if invalid
+ */
+declare function decodeServerMessage(raw: any): MessageFrame | null;
+//#endregion
+export { type BroadcastOptions, type ClientMessage, ConnectionManager, type ConnectionMeta, type ConnectionState, DEFAULT_RECONNECTION_CONFIG, type MessageContext, type MessageFrame, PROTOCOL_VERSION, type ReconnectionConfig, type RoomContext, type RoomDefinition, type ServerMessage, type VeraniActor, VeraniClient, type VeraniClientOptions, type VeraniMessage, createActorHandler, decodeClientMessage, decodeFrame, decodeServerMessage, defineRoom, encodeClientMessage, encodeFrame, encodeServerMessage, parseJWT, restoreSessions, storeAttachment };

package/dist/verani.mjs

@@ -0,0 +1 @@
+import{Actor}from"@cloudflare/actors";function extractUserId(e){let b=new URL(e.url),x=b.searchParams.get(`userId`)||b.searchParams.get(`user_id`);if(x)return x;let S=e.headers.get(`Authorization`);return S?.startsWith(`Bearer `)?S.substring(7):e.headers.get(`X-User-ID`)||`anonymous`}function extractClientId(e){let b=new URL(e.url);return b.searchParams.get(`clientId`)||b.searchParams.get(`client_id`)||e.headers.get(`X-Client-ID`)||crypto.randomUUID()}function defaultExtractMeta(e){let S=extractUserId(e),C=extractClientId(e),w=new URL(e.url).searchParams.get(`channels`);return{userId:S,clientId:C,channels:w?w.split(`,`).map(e=>e.trim()).filter(Boolean):[`default`]}}function defineRoom(e){return{name:e.name,websocketPath:e.websocketPath,extractMeta:e.extractMeta||defaultExtractMeta,onConnect:e.onConnect,onDisconnect:e.onDisconnect,onMessage:e.onMessage,onError:e.onError}}function parseJWT(e){try{let b=e.split(`.`);if(b.length!==3)return null;let x=b[1],S=atob(x.replace(/-/g,`+`).replace(/_/g,`/`));return JSON.parse(S)}catch{return null}}function storeAttachment(e,b){e.serializeAttachment(b)}function restoreSessions(e){let b=0;for(let x of e.ctx.getWebSockets()){let S=x.deserializeAttachment();S&&(e.sessions.set(x,{ws:x,meta:S}),b++)}}function isValidFrame(e){return e&&typeof e==`object`&&typeof e.type==`string`&&(e.channel===void 0||typeof e.channel==`string`)}function decodeFrame(e){try{let b=typeof e==`string`?e:e.toString(),x=JSON.parse(b);return isValidFrame(x)?x:null}catch{return null}}function decodeClientMessage(e){return decodeFrame(e)}function decodeServerMessage(e){return decodeFrame(e)}function encodeFrame(e){try{return JSON.stringify(e)}catch(e){throw Error(`Failed to encode frame: ${e instanceof Error?e.message:`unknown error`}`)}}function encodeClientMessage(e){return encodeFrame(e)}function encodeServerMessage(e){return encodeFrame(e)}function decodeFrame$1(e){return decodeFrame(e)??{type:`invalid`}}function encodeFrame$1(e){return encodeFrame(e)}function sanitizeToClassName(e){return e.replace(/^\/+/,``).split(/[-_\/\s]+/).map(e=>e.replace(/[^a-zA-Z0-9]/g,``)).filter(e=>e.length>0).map(e=>e.charAt(0).toUpperCase()+e.slice(1).toLowerCase()).join(``)||`VeraniActor`}function createActorHandler(b){let x=sanitizeToClassName(b.name||b.websocketPath||`VeraniActor`);class S extends Actor{constructor(...e){super(...e),this.sessions=new Map}static configuration(e){return{locationHint:`me`,sockets:{upgradePath:b.websocketPath,autoResponse:{ping:`ping`,pong:`pong`}}}}async shouldUpgradeWebSocket(e){return!0}async fetch(e){let x=new URL(e.url),S=e.headers.get(`Upgrade`);return x.pathname===b.websocketPath&&S===`websocket`&&await this.shouldUpgradeWebSocket(e)?this.onWebSocketUpgrade(e):this.onRequest(e)}async onInit(){try{restoreSessions(this),b.onHibernationRestore&&this.sessions.size>0&&await b.onHibernationRestore(this)}catch{}}onWebSocketConnect(e,x){try{let S;if(S=b.extractMeta?b.extractMeta(x):{userId:`anonymous`,clientId:crypto.randomUUID(),channels:[`default`]},storeAttachment(e,S),this.sessions.set(e,{ws:e,meta:S}),b.onConnect){let x={actor:this,ws:e,meta:S};b.onConnect(x)}}catch(x){if(b.onError)try{b.onError(x,{actor:this,ws:e,meta:{userId:`unknown`,clientId:`unknown`,channels:[]}})}catch{}e.close(1011,`Internal server error`)}}onWebSocketMessage(e,x){let S;try{let C=decodeFrame$1(x);if(S=this.sessions.get(e),!S)return;if(b.onMessage){let x={actor:this,ws:e,meta:S.meta,frame:C};b.onMessage(x,C)}}catch(x){if(b.onError&&S)try{b.onError(x,{actor:this,ws:e,meta:S.meta})}catch{}}}onWebSocketDisconnect(e){try{let x=this.sessions.get(e);if(this.sessions.delete(e),x&&b.onDisconnect){let S={actor:this,ws:e,meta:x.meta};b.onDisconnect(S)}}catch{}}broadcast(e,b,x){let S=0,C=encodeFrame$1({type:`event`,channel:e,data:b});for(let{ws:b,meta:w}of this.sessions.values())if(w.channels.includes(e)&&!(x?.except&&b===x.except)&&!(x?.userIds&&!x.userIds.includes(w.userId))&&!(x?.clientIds&&!x.clientIds.includes(w.clientId)))try{b.send(C),S++}catch{}return S}getSessionCount(){return this.sessions.size}getConnectedUserIds(){let e=new Set;for(let{meta:b}of this.sessions.values())e.add(b.userId);return Array.from(e)}getUserSessions(e){let b=[];for(let{ws:x,meta:S}of this.sessions.values())S.userId===e&&b.push(x);return b}sendToUser(e,b,x){let S=0,C=encodeFrame$1({type:b,data:x});for(let{ws:b,meta:x}of this.sessions.values())if(x.userId===e)try{b.send(C),S++}catch{}return S}getStorage(){return this.ctx.storage}}return Object.defineProperty(S,`name`,{value:x,writable:!1,configurable:!0}),S}function encodeClientMessage$1(e){return encodeClientMessage(e)}function decodeServerMessage$1(e){return decodeServerMessage(e)}const DEFAULT_RECONNECTION_CONFIG={enabled:!0,maxAttempts:10,initialDelay:1e3,maxDelay:3e4,backoffMultiplier:1.5};var ConnectionManager=class{constructor(e=DEFAULT_RECONNECTION_CONFIG,b){this.config=e,this.onStateChange=b,this.state=`disconnected`,this.reconnectAttempts=0,this.currentDelay=e.initialDelay}getState(){return this.state}setState(e){this.state!==e&&(this.state=e,this.onStateChange?.(e))}resetReconnection(){this.reconnectAttempts=0,this.currentDelay=this.config.initialDelay,this.clearReconnectTimer()}scheduleReconnect(e){return this.config.enabled?this.config.maxAttempts>0&&this.reconnectAttempts>=this.config.maxAttempts?(this.setState(`error`),!1):(this.clearReconnectTimer(),this.setState(`reconnecting`),this.reconnectAttempts++,this.reconnectTimer=setTimeout(()=>{e(),this.currentDelay=Math.min(this.currentDelay*this.config.backoffMultiplier,this.config.maxDelay)},this.currentDelay),!0):!1}cancelReconnect(){this.clearReconnectTimer(),this.state===`reconnecting`&&this.setState(`disconnected`)}clearReconnectTimer(){this.reconnectTimer!==void 0&&(clearTimeout(this.reconnectTimer),this.reconnectTimer=void 0)}getReconnectAttempts(){return this.reconnectAttempts}getNextDelay(){return this.currentDelay}destroy(){this.clearReconnectTimer()}},VeraniClient=class{constructor(e,b={}){this.url=e,this.listeners=new Map,this.messageQueue=[],this.options={reconnection:{enabled:b.reconnection?.enabled??DEFAULT_RECONNECTION_CONFIG.enabled,maxAttempts:b.reconnection?.maxAttempts??DEFAULT_RECONNECTION_CONFIG.maxAttempts,initialDelay:b.reconnection?.initialDelay??DEFAULT_RECONNECTION_CONFIG.initialDelay,maxDelay:b.reconnection?.maxDelay??DEFAULT_RECONNECTION_CONFIG.maxDelay,backoffMultiplier:b.reconnection?.backoffMultiplier??DEFAULT_RECONNECTION_CONFIG.backoffMultiplier},maxQueueSize:b.maxQueueSize??100,connectionTimeout:b.connectionTimeout??1e4},this.connectionManager=new ConnectionManager(this.options.reconnection,e=>{this.onStateChangeCallback?.(e)}),this.connect()}connect(){try{this.connectionManager.setState(`connecting`),this.ws=new WebSocket(this.url);let e=setTimeout(()=>{this.connectionManager.getState()===`connecting`&&(this.ws?.close(),this.handleConnectionError(Error(`Connection timeout`)))},this.options.connectionTimeout);this.ws.addEventListener(`open`,()=>{clearTimeout(e),this.handleOpen()}),this.ws.addEventListener(`message`,e=>{this.handleMessage(e)}),this.ws.addEventListener(`close`,b=>{clearTimeout(e),this.handleClose(b)}),this.ws.addEventListener(`error`,b=>{clearTimeout(e),this.handleError(b)})}catch(e){this.handleConnectionError(e)}}handleOpen(){this.connectionManager.setState(`connected`),this.connectionManager.resetReconnection(),this.flushMessageQueue(),this.connectionResolve&&(this.connectionResolve(),this.connectionPromise=void 0,this.connectionResolve=void 0,this.connectionReject=void 0),this.onOpenCallback?.()}handleMessage(e){let b=decodeServerMessage$1(e.data);if(!b)return;let x=b.type,S=b.data;b.type===`event`&&b.data&&typeof b.data==`object`&&`type`in b.data&&(x=b.data.type,S=b.data);let C=this.listeners.get(x);if(C)for(let e of C)try{e(S)}catch{}}handleClose(e){this.connectionManager.setState(`disconnected`),this.connectionReject&&=(this.connectionReject(Error(`Connection closed: ${e.reason||`Unknown reason`}`)),this.connectionPromise=void 0,this.connectionResolve=void 0,void 0),this.onCloseCallback?.(e),e.code!==1e3&&e.code!==1001&&this.connectionManager.scheduleReconnect(()=>this.connect())}handleError(e){this.onErrorCallback?.(e)}handleConnectionError(e){this.connectionReject&&=(this.connectionReject(e),this.connectionPromise=void 0,this.connectionResolve=void 0,void 0),this.connectionManager.scheduleReconnect(()=>this.connect())}flushMessageQueue(){if(!(!this.ws||this.ws.readyState!==WebSocket.OPEN))for(;this.messageQueue.length>0;){let e=this.messageQueue.shift();try{this.ws.send(encodeClientMessage$1(e))}catch{}}}getState(){return this.connectionManager.getState()}isConnected(){return this.ws?.readyState===WebSocket.OPEN}waitForConnection(){return this.isConnected()?Promise.resolve():(this.connectionPromise||=new Promise((e,b)=>{this.connectionResolve=e,this.connectionReject=b}),this.connectionPromise)}on(e,b){this.listeners.has(e)||this.listeners.set(e,new Set),this.listeners.get(e).add(b)}off(e,b){let x=this.listeners.get(e);x&&(x.delete(b),x.size===0&&this.listeners.delete(e))}once(e,b){let x=S=>{this.off(e,x),b(S)};this.on(e,x)}emit(e,b){let x={type:e,data:b};if(this.isConnected())try{this.ws.send(encodeClientMessage$1(x))}catch{this.queueMessage(x)}else this.queueMessage(x)}queueMessage(e){this.messageQueue.length>=this.options.maxQueueSize&&this.messageQueue.shift(),this.messageQueue.push(e)}onOpen(e){this.onOpenCallback=e}onClose(e){this.onCloseCallback=e}onError(e){this.onErrorCallback=e}onStateChange(e){this.onStateChangeCallback=e}reconnect(){this.disconnect(),this.connect()}disconnect(){this.connectionManager.cancelReconnect(),this.ws&&=(this.ws.close(1e3,`Client disconnect`),void 0)}close(){this.disconnect(),this.listeners.clear(),this.messageQueue=[],this.connectionManager.destroy()}};const PROTOCOL_VERSION=`1.0.0`;export{ConnectionManager,DEFAULT_RECONNECTION_CONFIG,PROTOCOL_VERSION,VeraniClient,createActorHandler,decodeClientMessage,decodeFrame,decodeServerMessage,defineRoom,encodeClientMessage,encodeFrame,encodeServerMessage,parseJWT,restoreSessions,storeAttachment};

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "verani",
+	"version": "0.1.0",
+	"description": "A simple, focused realtime SDK for Cloudflare Actors with Socket.io-like semantics",
+	"license": "ISC",
+	"keywords": [
+		"cloudflare",
+		"actors",
+		"durable-objects",
+		"realtime",
+		"websocket",
+		"socket.io"
+	],
+	"main": "./dist/verani.cjs",
+	"module": "./dist/verani.mjs",
+	"types": "./dist/verani.d.cts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/verani.d.mts",
+				"default": "./dist/verani.mjs"
+			},
+			"require": {
+				"types": "./dist/verani.d.cts",
+				"default": "./dist/verani.cjs"
+			}
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsdown",
+		"prepublishOnly": "npm run build",
+		"deploy": "wrangler deploy",
+		"dev": "wrangler dev",
+		"start": "wrangler dev",
+		"test": "vitest",
+		"cf-typegen": "wrangler types"
+	},
+	"devDependencies": {
+		"@cloudflare/vitest-pool-workers": "^0.8.19",
+		"esbuild-fix-imports-plugin": "^1.0.23",
+		"tsdown": "^0.16.7",
+		"typescript": "^5",
+		"vitest": "~3.2.0",
+		"wrangler": "4.51.0"
+	},
+	"peerDependencies": {
+		"typescript": "^5",
+		"@cloudflare/actors": "^0.0.1-beta.6"
+	}
+}