feat: allow string for host connection

client/interfaces/IHeroCreateOptions.ts

@@ -7,5 +7,5 @@ export default interface IHeroCreateOptions
     Omit<ISessionCreateOptions, 'scriptInstanceMeta' | 'sessionName' | 'dependencyMap'>
   > {
   name?: string;
-  connectionToCore?: IConnectionToCoreOptions | ConnectionToHeroCore;
+  connectionToCore?: IConnectionToCoreOptions | ConnectionToHeroCore | string;
 }

client/lib/Hero.ts

@@ -41,6 +41,7 @@ import {
 } from '@ulixee/unblocked-specification/agent/interact/IInteractions';
 import IDomState, { IDomStateAllFn } from '@ulixee/hero-interfaces/IDomState';
 import IResourceFilterProperties from '@ulixee/hero-interfaces/IResourceFilterProperties';
+import { CanceledPromiseError } from '@ulixee/commons/interfaces/IPendingWaitEvent';
 import WebsocketResource from './WebsocketResource';
 import IWaitForResourceFilter from '../interfaces/IWaitForResourceFilter';
 import Resource from './Resource';
@@ -133,9 +134,11 @@ export default class Hero extends AwaitedEventTarget<{
       corePluginPaths: [],
     } as ISessionOptions;
 
-    this.#connectionToCore = ConnectionFactory.createConnection(connectionToCore ?? {});
+    let connect = connectionToCore;
+    if (typeof connect === 'string') connect = { host: connect };
+    this.#connectionToCore = ConnectionFactory.createConnection(connect ?? {});
 
-    this.#didAutoCreateConnection = this.#connectionToCore !== connectionToCore;
+    this.#didAutoCreateConnection = this.#connectionToCore !== connect;
   }
 
   public get activeTab(): Tab {
@@ -594,6 +597,7 @@ export default class Hero extends AwaitedEventTarget<{
       const coreTab = this.#coreSessionPromise
         .then(x => {
           if (x instanceof Error) throw x;
+          if (!x) throw new CanceledPromiseError('No connection to Hero Core established.');
           return x.firstTab;
         })
         .catch(err => err);

docs/main/BasicClient/Hero.md

@@ -53,7 +53,7 @@ const Hero = require('@ulixee/hero-playground');
 #### **Arguments**:
 
 - options `object` Accepts any of the following:
-  - connectionToCore `options | ConnectionToCore`. An object containing `IConnectionToCoreOptions` used to connect, or an already created `ConnectionToCore` instance. Defaults to automatically booting up and connecting to a local `Core`.
+  - connectionToCore `options | ConnectionToCore | 'string'`. An object containing `IConnectionToCoreOptions` used to connect, or an already created `ConnectionToCore` instance. A host may be provided directly as a string. Defaults to automatically booting up and connecting to a local `Core`.
   - name `string`. This is used to generate a unique sessionName.
   - userAgent `strong`. This sets your browser's user agent string. Prefixing this string with a tilde (`~`) allows for dynamic options. Details can be found [here](/docs/hero/advanced-client/user-agents).
   - browserEmulatorId `string` defaults to `default-browser-emulator`. Chooses the BrowserEmulator plugin which emulates the properties that help Hero look like a normal browser.