npm package: @silyze/browsary-session-manager
Description: Browsary Session Manager interface
Author: Mihail Mojsoski
Latest version: 1.1.0

# 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

```bash
npm install @silyze/browsary-session-manager
```

## Usage

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

```ts
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

```ts
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();
```