Browsary Session Manager Interface

A generic interface for managing browser-based sessions and their associated resources in Browsary Cloud environments. Provides abstractions for session lifecycle, event dispatching, and resource management (e.g., cookies, captures).

Installation

npm install @silyze/browsary-session-manager

Usage

Import and implement the abstract classes to integrate with your application’s session and resource logic.

import {
  SessionManager,
  Session,
  SessionResource,
  ResourceEvent,
} from "@silyze/browsary-session-manager";
import BrowserClient from "@silyze/browsary-cloud-client";

interface MySessionData {
  userId: string;
  cookies: Cookie[];
}

interface MyResourceData {
  captureId: string;
}

class MyResource extends SessionResource<MyResourceData> {
  get id() {
    /* return resource id */
  }
  get client() {
    return new BrowserClient(new URL(process.env.BROWSER_SERVER_URL!));
  }
  get coordinator() {
    return new MyCoordinator("...");
  }
  async getInfo() {
    /* fetch resource info */
  }
  async stop() {
    /* stop resource */
  }
  async *capture() {
    /* yield Cookie objects */
  }
}

class MySession extends Session<MySessionData, MyResourceData> {
  get id() {
    /* session id */
  }
  get cookies() {
    /* async iterable of Cookie */
  }
  async update(sessionUpdate: Partial<MySessionData & { cookies: Cookie[] }>) {
    /* update logic */
  }
  async start() {
    /* create a resource and dispatch event */
  }
  async getInfo() {
    /* fetch session info */
  }
  async getResource(resourceId: string) {
    /* fetch specific resource */
  }
  async *resources(offset?: number, limit?: number) {
    /* yield resources */
  }
}

class MySessionManager extends SessionManager<MySessionData, MyResourceData> {
  async getById(id: string) {
    /* return MySession */
  }
  async delete(idOrSession: string | MySession) {
    /* delete session */
  }
  async *sessions(offset?: number, limit?: number) {
    /* yield sessions */
  }
  async create(session: MySessionData & { cookies: Cookie[] }) {
    /* create new session */
  }
}

Concepts

SessionResource<TResource>

Abstract base class for a resource tied to a browser session.

• id: Unique resource identifier.
• client: Instance of BrowserClient for container operations.
• coordinator: Coordinator instance for service coordination.
• getInfo(): Promise<TResource>: Fetch resource metadata.
• stop(): Promise<void>: Terminate or stop the resource.
• capture(): AsyncIterable<Cookie>: Stream browser cookies or other capture data.

ResourceEvent<TSession, TResource>

Custom event emitted by a Session when resources start.

• type: Currently only "start".
• resource: The SessionResource instance.
• session: The parent Session instance.

Session<TSessionData, TResource>

Abstract base class managing session lifecycle and events.

• id: Unique session identifier.
• cookies: Async iterable of Cookie from Puppeteer.
• update(update: Partial<TSessionData & { cookies: Cookie[] }>): Promise<void>: Modify session data.
• start(): Promise<SessionResource<TResource>>: Launch a new resource and emit a ResourceEvent.
• getInfo(): Promise<TSessionData>: Fetch session metadata.
• getResource(resourceId: string): Promise<SessionResource<TResource>>: Retrieve a specific resource.
• resources(offset?: number, limit?: number): AsyncIterable<SessionResource<TResource>>: Iterate over resources.
• Event handling: Inherits from TypedEventTarget to listen for ResourceEvent.

SessionManager<TSessionData, TResource>

Abstract class for creating, retrieving, and deleting sessions.

• getById(id: string): Promise<Session<TSessionData, TResource>>: Fetch a session by ID.
• delete(idOrSession: string | Session<TSessionData, TResource>): Promise<void>: Remove a session.
• sessions(offset?: number, limit?: number): AsyncIterable<Session<TSessionData, TResource>>: Iterate sessions.
• create(session: TSessionData & { cookies: Cookie[] }): Promise<Session<TSessionData, TResource>>: Instantiate a new session.

Example: Listening for Resource Start

const manager = new MySessionManager();
const session = await manager.create({ userId: "user123", cookies: [] });

session.addEventListener("start", (event) => {
  console.log(`Resource started: ${event.resource.id}`);
});

// Starting a resource triggers the event
const resource = await session.start();