@tvlabs/wdio-service 0.1.0 → 0.1.2

package/esm/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAwB3C,qBAAa,MAAM;IAEf,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,QAAQ;gBADR,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,QAAiB;IAGrC,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,aAAa;IAUrB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM9B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;CAKhC"}

package/esm/logger.js

@@ -0,0 +1,63 @@
+import chalk from 'chalk';
+const LOG_LEVEL_COLORS = {
+    error: chalk.red,
+    warn: chalk.yellow,
+    info: chalk.cyanBright,
+    debug: chalk.green,
+    trace: chalk.cyan,
+    silent: chalk.gray,
+};
+const LOG_LEVELS = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+    trace: 4,
+    silent: 5,
+};
+export class Logger {
+    name;
+    logLevel;
+    constructor(name, logLevel = 'info') {
+        this.name = name;
+        this.logLevel = logLevel;
+    }
+    shouldLog(level) {
+        if (this.logLevel === 'silent') {
+            return false;
+        }
+        return LOG_LEVELS[level] <= LOG_LEVELS[this.logLevel];
+    }
+    formatMessage(level, ...args) {
+        const timestamp = new Date().toISOString();
+        const levelColor = LOG_LEVEL_COLORS[level];
+        return `${chalk.gray(timestamp)} ${levelColor(level.toUpperCase())} ${chalk.white(this.name)}: ${args
+            .map((arg) => typeof arg === 'object' ? JSON.stringify(arg) : String(arg))
+            .join(' ')}`;
+    }
+    debug(...args) {
+        if (this.shouldLog('debug')) {
+            console.log(this.formatMessage('debug', ...args));
+        }
+    }
+    info(...args) {
+        if (this.shouldLog('info')) {
+            console.log(this.formatMessage('info', ...args));
+        }
+    }
+    warn(...args) {
+        if (this.shouldLog('warn')) {
+            console.warn(this.formatMessage('warn', ...args));
+        }
+    }
+    error(...args) {
+        if (this.shouldLog('error')) {
+            console.error(this.formatMessage('error', ...args));
+        }
+    }
+    trace(...args) {
+        if (this.shouldLog('trace')) {
+            console.trace(this.formatMessage('trace', ...args));
+        }
+    }
+}

package/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/esm/service.d.ts

@@ -0,0 +1,20 @@
+import type { Services, Capabilities, Options } from '@wdio/types';
+import type { TVLabsCapabilities, TVLabsServiceOptions } from './types.js';
+export default class TVLabsService implements Services.ServiceInstance {
+    private _options;
+    private _capabilities;
+    private _config;
+    private log;
+    constructor(_options: TVLabsServiceOptions, _capabilities: Capabilities.ResolvedTestrunnerCapabilities, _config: Options.WebdriverIO);
+    onPrepare(_config: Options.Testrunner, param: Capabilities.TestrunnerCapabilities): void;
+    beforeSession(_config: Omit<Options.Testrunner, 'capabilities'>, capabilities: TVLabsCapabilities, _specs: string[], _cid: string): Promise<void>;
+    private setupRequestId;
+    private setRequestHeader;
+    private endpoint;
+    private retries;
+    private apiKey;
+    private logLevel;
+    private attachRequestId;
+    private reconnectRetries;
+}
+//# sourceMappingURL=service.d.ts.map

package/esm/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAEpB,MAAM,CAAC,OAAO,OAAO,aAAc,YAAW,QAAQ,CAAC,eAAe;IAIlE,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,OAAO;IALjB,OAAO,CAAC,GAAG,CAAS;gBAGV,QAAQ,EAAE,oBAAoB,EAC9B,aAAa,EAAE,YAAY,CAAC,8BAA8B,EAC1D,OAAO,EAAE,OAAO,CAAC,WAAW;IAQtC,SAAS,CACP,OAAO,EAAE,OAAO,CAAC,UAAU,EAC3B,KAAK,EAAE,YAAY,CAAC,sBAAsB;IAStC,aAAa,CACjB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,cAAc,CAAC,EACjD,YAAY,EAAE,kBAAkB,EAChC,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,EAAE,MAAM;IAmBd,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;CAGzB"}

package/esm/service.js

@@ -0,0 +1,77 @@
+import { SevereServiceError } from 'webdriverio';
+import * as crypto from 'crypto';
+import chalk from 'chalk';
+import { TVLabsChannel } from './channel.js';
+import { Logger } from './logger.js';
+export default class TVLabsService {
+    _options;
+    _capabilities;
+    _config;
+    log;
+    constructor(_options, _capabilities, _config) {
+        this._options = _options;
+        this._capabilities = _capabilities;
+        this._config = _config;
+        this.log = new Logger('@tvlabs/wdio-server', this._config.logLevel);
+        if (this.attachRequestId()) {
+            this.setupRequestId();
+        }
+    }
+    onPrepare(_config, param) {
+        if (!Array.isArray(param)) {
+            throw new SevereServiceError('Multi-remote capabilities are not implemented. Contact TV Labs support if you are interested in this feature.');
+        }
+    }
+    async beforeSession(_config, capabilities, _specs, _cid) {
+        const channel = new TVLabsChannel(this.endpoint(), this.reconnectRetries(), this.apiKey(), this.logLevel());
+        await channel.connect();
+        capabilities['tvlabs:session_id'] = await channel.newSession(capabilities, this.retries());
+        await channel.disconnect();
+    }
+    setupRequestId() {
+        const originalTransformRequest = this._config.transformRequest;
+        this._config.transformRequest = (requestOptions) => {
+            const requestId = crypto.randomUUID();
+            const originalRequestOptions = typeof originalTransformRequest === 'function'
+                ? originalTransformRequest(requestOptions)
+                : requestOptions;
+            if (typeof originalRequestOptions.headers === 'undefined') {
+                originalRequestOptions.headers = {};
+            }
+            this.setRequestHeader(originalRequestOptions.headers, 'x-request-id', requestId);
+            this.log.info(chalk.blue('ATTACHED REQUEST ID'), requestId);
+            return originalRequestOptions;
+        };
+    }
+    setRequestHeader(headers, header, value) {
+        if (headers instanceof Headers) {
+            headers.set(header, value);
+        }
+        else if (typeof headers === 'object') {
+            if (Array.isArray(headers)) {
+                headers.push([header, value]);
+            }
+            else {
+                headers[header] = value;
+            }
+        }
+    }
+    endpoint() {
+        return this._options.endpoint ?? 'wss://tvlabs.ai/appium';
+    }
+    retries() {
+        return this._options.retries ?? 3;
+    }
+    apiKey() {
+        return this._options.apiKey;
+    }
+    logLevel() {
+        return this._config.logLevel ?? 'info';
+    }
+    attachRequestId() {
+        return this._options.attachRequestId ?? true;
+    }
+    reconnectRetries() {
+        return this._options.reconnectRetries ?? 5;
+    }
+}

package/esm/types.d.ts

@@ -0,0 +1,37 @@
+import type { Capabilities } from '@wdio/types';
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent';
+export type TVLabsServiceOptions = {
+    apiKey: string;
+    endpoint?: string;
+    retries?: number;
+    reconnectRetries?: number;
+    attachRequestId?: boolean;
+};
+export type TVLabsCapabilities = Capabilities.RequestedStandaloneCapabilities & {
+    'tvlabs:session_id'?: string;
+    'tvlabs:build'?: string;
+    'tvlabs:constraints'?: {
+        platform_key?: string;
+        device_type?: string;
+        make?: string;
+        model?: string;
+        year?: string;
+        minimum_chromedriver_major_version?: number;
+        supports_chromedriver?: boolean;
+    };
+    'tvlabs:match_timeout'?: number;
+    'tvlabs:device_timeout'?: number;
+};
+export type TVLabsSessionRequestEventHandler = (response: TVLabsSessionRequestUpdate) => void;
+export type TVLabsSessionRequestUpdate = {
+    request_id: string;
+    session_id: string;
+    reason: string;
+};
+export type TVLabsSessionRequestResponse = {
+    request_id: string;
+};
+export type TVLabsSessionChannelParams = {
+    api_key: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEhF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC5B,YAAY,CAAC,+BAA+B,GAAG;IAC7C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,kCAAkC,CAAC,EAAE,MAAM,CAAC;QAC5C,qBAAqB,CAAC,EAAE,OAAO,CAAC;KACjC,CAAC;IACF,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,CAAC;AAEJ,MAAM,MAAM,gCAAgC,GAAG,CAC7C,QAAQ,EAAE,0BAA0B,KACjC,IAAI,CAAC;AAEV,MAAM,MAAM,0BAA0B,GAAG;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tvlabs/wdio-service",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "WebdriverIO service that provides a better integration into TV Labs",
   "author": "Regan Karlewicz <regan@tvlabs.ai>",
   "license": "Apache-2.0",
@@ -22,46 +22,48 @@
     "url": "https://github.com/tv-labs/wdio-tvlabs-service/issues"
   },
   "scripts": {
-    "build": "tsc -p src",
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:cjs": "tsc -p src --module commonjs --moduleResolution node --outDir cjs && echo '{\"type\": \"commonjs\"}' > cjs/package.json",
+    "build:esm": "tsc -p src --outDir esm && echo '{\"type\": \"module\"}' > esm/package.json",
     "start": "ts-node src/index.ts",
     "dev": "ts-node --transpile-only src/index.ts",
-    "clean": "rm -rf dist",
+    "clean": "rm -rf cjs && rm -rf esm",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint",
-    "test": "vitest --config vitest.config.ts --coverage"
+    "test": "vitest --config vitest.config.ts --coverage",
+    "publish:dry": "npm publish --access public --provenance --dry-run"
   },
   "type": "module",
-  "types": "./dist/index.d.ts",
+  "types": "./esm/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+    "require": "./cjs/index.js",
+    "import": "./esm/index.js"
   },
+  "main": "cjs/index.js",
   "typeScriptVersion": "5.8.2",
   "devDependencies": {
     "@eslint/js": "^9.22.0",
     "@types/node": "^22.13.10",
     "@types/phoenix": "^1.6.6",
     "@types/ws": "^8.18.0",
-    "@typescript-eslint/eslint-plugin": "^8.27.0",
-    "@typescript-eslint/parser": "^8.27.0",
+    "@typescript-eslint/eslint-plugin": "^8.36.0",
+    "@typescript-eslint/parser": "^8.36.0",
     "@vitest/coverage-v8": "^3.0.9",
     "@wdio/globals": "^9.12.1",
-    "@wdio/logger": "^9.4.4",
     "@wdio/types": "^9.10.1",
-    "eslint": "^9.22.0",
+    "eslint": "^9.30.1",
     "globals": "^16.0.0",
     "jiti": "^2.4.2",
     "prettier": "^3.5.3",
     "typescript": "^5.8.2",
-    "typescript-eslint": "^8.27.0",
+    "typescript-eslint": "^8.36.0",
     "vitest": "^3.0.9",
     "webdriverio": "^9.12.1"
   },
   "dependencies": {
+    "chalk": "^5.1.2",
     "phoenix": "^1.7.20",
-    "ws": "^8.18.1"
+    "ws": "^8.18.3"
   }
 }

package/src/channel.ts

@@ -0,0 +1,265 @@
+import { WebSocket } from 'ws';
+import { Socket, type Channel } from 'phoenix';
+import { SevereServiceError } from 'webdriverio';
+import { Logger } from './logger.js';
+
+import type {
+  TVLabsCapabilities,
+  TVLabsSessionChannelParams,
+  TVLabsSessionRequestEventHandler,
+  TVLabsSessionRequestResponse,
+  LogLevel,
+} from './types.js';
+import type { PhoenixChannelJoinResponse } from './phoenix.js';
+
+export class TVLabsChannel {
+  private socket: Socket;
+  private lobbyTopic: Channel;
+  private requestTopic?: Channel;
+  private log: Logger;
+
+  private readonly events = {
+    SESSION_READY: 'session:ready',
+    SESSION_FAILED: 'session:failed',
+    REQUEST_CANCELED: 'request:canceled',
+    REQUEST_FAILED: 'request:failed',
+    REQUEST_FILLED: 'request:filled',
+    REQUEST_MATCHING: 'request:matching',
+  } as const;
+
+  constructor(
+    private endpoint: string,
+    private maxReconnectRetries: number,
+    private key: string,
+    private logLevel: LogLevel,
+  ) {
+    this.log = new Logger('@tvlabs/wdio-channel', this.logLevel);
+    this.socket = new Socket(this.endpoint, {
+      transport: WebSocket,
+      params: this.params(),
+      reconnectAfterMs: this.reconnectAfterMs.bind(this),
+    });
+
+    this.socket.onError(this.logSocketError);
+
+    this.lobbyTopic = this.socket.channel('requests:lobby');
+  }
+
+  async disconnect(): Promise<void> {
+    return new Promise((res, _rej) => {
+      this.lobbyTopic.leave();
+      this.requestTopic?.leave();
+      this.socket.disconnect(() => res());
+    });
+  }
+
+  async connect(): Promise<void> {
+    try {
+      this.log.debug('Connecting to TV Labs...');
+
+      this.socket.connect();
+
+      await this.join(this.lobbyTopic);
+
+      this.log.debug('Connected to TV Labs!');
+    } catch (error) {
+      this.log.error('Error connecting to TV Labs:', error);
+      throw new SevereServiceError(
+        'Could not connect to TV Labs, please check your connection.',
+      );
+    }
+  }
+
+  async newSession(
+    capabilities: TVLabsCapabilities,
+    maxRetries: number,
+    retry = 0,
+  ): Promise<string> {
+    try {
+      const requestId = await this.requestSession(capabilities);
+      const sessionId = await this.observeRequest(requestId);
+
+      return sessionId;
+    } catch {
+      return this.handleRetry(capabilities, maxRetries, retry);
+    }
+  }
+
+  private async handleRetry(
+    capabilities: TVLabsCapabilities,
+    maxRetries: number,
+    retry: number,
+  ): Promise<string> {
+    if (retry < maxRetries) {
+      this.log.warn(
+        `Could not create a session, retrying (${retry + 1}/${maxRetries})`,
+      );
+
+      return this.newSession(capabilities, maxRetries, retry + 1);
+    } else {
+      throw new SevereServiceError(
+        `Could not create a session after ${maxRetries} attempts.`,
+      );
+    }
+  }
+
+  private async observeRequest(requestId: string): Promise<string> {
+    const cleanup = () => this.unobserveRequest();
+
+    return new Promise<string>((res, rej) => {
+      this.requestTopic = this.socket.channel(`requests:${requestId}`);
+
+      const eventHandlers: Record<string, TVLabsSessionRequestEventHandler> = {
+        // Information events
+        [this.events.REQUEST_MATCHING]: ({ request_id }) => {
+          this.log.info(`Session request ${request_id} matching...`);
+        },
+        [this.events.REQUEST_FILLED]: ({ session_id, request_id }) => {
+          this.log.info(
+            `Session request ${request_id} filled: ${this.tvlabsSessionLink(session_id)}`,
+          );
+
+          this.log.info('Waiting for device to be ready...');
+        },
+
+        // Failure events
+        [this.events.SESSION_FAILED]: ({ session_id, reason }) => {
+          this.log.error(`Session ${session_id} failed, reason: ${reason}`);
+          rej(reason);
+        },
+        [this.events.REQUEST_CANCELED]: ({ request_id, reason }) => {
+          this.log.info(
+            `Session request ${request_id} canceled, reason: ${reason}`,
+          );
+          rej(reason);
+        },
+        [this.events.REQUEST_FAILED]: ({ request_id, reason }) => {
+          this.log.info(
+            `Session request ${request_id} failed, reason: ${reason}`,
+          );
+          rej(reason);
+        },
+
+        // Ready event
+        [this.events.SESSION_READY]: ({ session_id }) => {
+          this.log.info(`Session ${session_id} ready!`);
+          res(session_id);
+        },
+      };
+
+      Object.entries(eventHandlers).forEach(([event, handler]) => {
+        this.requestTopic?.on(event, handler);
+      });
+
+      this.join(this.requestTopic).catch((err) => {
+        rej(err);
+      });
+    }).finally(cleanup);
+  }
+
+  private unobserveRequest() {
+    Object.values(this.events).forEach((event) => {
+      this.requestTopic?.off(event);
+    });
+
+    this.requestTopic?.leave();
+
+    this.requestTopic = undefined;
+  }
+
+  private async requestSession(
+    capabilities: TVLabsCapabilities,
+  ): Promise<string> {
+    this.log.info('Requesting TV Labs session');
+
+    try {
+      const response = await this.push<TVLabsSessionRequestResponse>(
+        this.lobbyTopic,
+        'requests:create',
+        { capabilities },
+      );
+
+      this.log.info(
+        `Received session request ID: ${response.request_id}. Waiting for a match...`,
+      );
+
+      return response.request_id;
+    } catch (error) {
+      this.log.error('Error requesting session:', error);
+      throw error;
+    }
+  }
+
+  private async join(topic: Channel): Promise<void> {
+    return new Promise((res, rej) => {
+      topic
+        .join()
+        .receive('ok', (_resp: PhoenixChannelJoinResponse) => {
+          res();
+        })
+        .receive('error', ({ response }: PhoenixChannelJoinResponse) => {
+          rej('Failed to join topic: ' + response);
+        })
+        .receive('timeout', () => {
+          rej('timeout');
+        });
+    });
+  }
+
+  private async push<T>(
+    topic: Channel,
+    event: string,
+    payload: object,
+  ): Promise<T> {
+    return new Promise((res, rej) => {
+      topic
+        .push(event, payload)
+        .receive('ok', (msg: T) => {
+          res(msg);
+        })
+        .receive('error', (reason: string) => {
+          rej(reason);
+        })
+        .receive('timeout', () => {
+          rej('timeout');
+        });
+    });
+  }
+
+  private params(): TVLabsSessionChannelParams {
+    return {
+      api_key: this.key,
+    };
+  }
+
+  private reconnectAfterMs(tries: number) {
+    if (tries > this.maxReconnectRetries) {
+      throw new SevereServiceError(
+        'Could not connect to TV Labs, please check your connection.',
+      );
+    }
+
+    const wait = [0, 1000, 3000, 5000][tries] || 10000;
+
+    this.log.info(
+      `[${tries}/${this.maxReconnectRetries}] Waiting ${wait}ms before re-attempting to connect...`,
+    );
+
+    return wait;
+  }
+
+  private logSocketError(
+    event: ErrorEvent,
+    _transport: new (endpoint: string) => object,
+    _establishedConnections: number,
+  ) {
+    const error = event.error;
+    const code = error && error.code;
+
+    this.log.error('Socket error:', code || error || event);
+  }
+
+  private tvlabsSessionLink(sessionId: string) {
+    return `https://tvlabs.ai/app/sessions/${sessionId}`;
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+import TVLabsService from './service.js';
+
+export default TVLabsService;
+export * from './types.js';

package/src/logger.ts

@@ -0,0 +1,77 @@
+import type { LogLevel } from './types.js';
+import chalk from 'chalk';
+
+// TODO: Replace this with @wdio/logger
+// It is currently not compatible with CJS
+
+const LOG_LEVEL_COLORS: Record<LogLevel, typeof chalk> = {
+  error: chalk.red,
+  warn: chalk.yellow,
+  info: chalk.cyanBright,
+  debug: chalk.green,
+  trace: chalk.cyan,
+  silent: chalk.gray,
+};
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+  trace: 4,
+  silent: 5,
+};
+
+export class Logger {
+  constructor(
+    private name: string,
+    private logLevel: LogLevel = 'info',
+  ) {}
+
+  private shouldLog(level: LogLevel): boolean {
+    if (this.logLevel === 'silent') {
+      return false;
+    }
+    return LOG_LEVELS[level] <= LOG_LEVELS[this.logLevel];
+  }
+
+  private formatMessage(level: LogLevel, ...args: unknown[]): string {
+    const timestamp = new Date().toISOString();
+    const levelColor = LOG_LEVEL_COLORS[level];
+    return `${chalk.gray(timestamp)} ${levelColor(level.toUpperCase())} ${chalk.white(this.name)}: ${args
+      .map((arg) =>
+        typeof arg === 'object' ? JSON.stringify(arg) : String(arg),
+      )
+      .join(' ')}`;
+  }
+
+  debug(...args: unknown[]): void {
+    if (this.shouldLog('debug')) {
+      console.log(this.formatMessage('debug', ...args));
+    }
+  }
+
+  info(...args: unknown[]): void {
+    if (this.shouldLog('info')) {
+      console.log(this.formatMessage('info', ...args));
+    }
+  }
+
+  warn(...args: unknown[]): void {
+    if (this.shouldLog('warn')) {
+      console.warn(this.formatMessage('warn', ...args));
+    }
+  }
+
+  error(...args: unknown[]): void {
+    if (this.shouldLog('error')) {
+      console.error(this.formatMessage('error', ...args));
+    }
+  }
+
+  trace(...args: unknown[]): void {
+    if (this.shouldLog('trace')) {
+      console.trace(this.formatMessage('trace', ...args));
+    }
+  }
+}

package/src/phoenix.d.ts

@@ -0,0 +1,18 @@
+import type { Socket as PhoenixSocket, MessageRef } from 'phoenix';
+
+declare module 'phoenix' {
+  interface Socket extends PhoenixSocket {
+    onError(
+      callback: (
+        error: ErrorEvent,
+        transport: new (endpoint: string) => object,
+        establishedConnections: number,
+      ) => void | Promise<void>,
+    ): MessageRef;
+  }
+}
+
+export type PhoenixChannelJoinResponse = {
+  status?: string;
+  response?: unknown;
+};