@epsilon-asi/actors 0.0.3 → 0.0.4

package/src/cli/run.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { ActorRegistry } from '../core/ActorRegistry.js';
+import { ActorRunner } from '../core/ActorRunner.js';
+import { exampleActor } from '../sites/example/example.actor.js';
+import type { ExistingChromeProfileConfig, RemoteDebuggingChromeConfig, RuntimeConfig, RunningChromeInstanceConfig } from '../browser/RuntimeConfig.js';
+
+async function main(): Promise<void> {
+  const [actorId, taskName, inputJson] = process.argv.slice(2);
+  if (actorId === undefined || taskName === undefined) {
+    console.error('Usage: paf <actorId> <taskName> [jsonInput]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const config = readRuntimeConfigFromEnv();
+  const registry = new ActorRegistry().register(exampleActor);
+  const runner = new ActorRunner({ config, registry });
+  const input = inputJson === undefined ? undefined : JSON.parse(inputJson);
+  const result = await runner.runRegistered(actorId, taskName, input);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function readRuntimeConfigFromEnv(): RuntimeConfig {
+  const userDataDir = process.env.CHROME_USER_DATA_DIR;
+  const profileDirectory = process.env.CHROME_PROFILE_DIRECTORY;
+  const browserURL = process.env.CHROME_REMOTE_DEBUGGING_URL;
+  const browserWSEndpoint = process.env.CHROME_WS_ENDPOINT ?? process.env.CHROME_BROWSER_WS_ENDPOINT ?? process.env.CHROME_REMOTE_DEBUGGING_WS_ENDPOINT;
+  const connectToDefaultEndpoint = process.env.CHROME_CONNECT === '1' || process.env.CHROME_CONNECT === 'true';
+  const remoteDebuggingHost = process.env.CHROME_REMOTE_DEBUGGING_HOST;
+  const remoteDebuggingPort = parseOptionalInteger(process.env.CHROME_REMOTE_DEBUGGING_PORT);
+  const reuseExistingPage = parseOptionalBoolean(process.env.CHROME_REUSE_EXISTING_PAGE);
+
+  if (userDataDir !== undefined && userDataDir.length > 0) {
+    const browser: ExistingChromeProfileConfig = {
+      mode: 'existing-profile',
+      userDataDir,
+      channel: 'chrome',
+      headless: false
+    };
+
+    if (profileDirectory !== undefined && profileDirectory.length > 0) browser.profileDirectory = profileDirectory;
+
+    const runningInstance = buildRunningInstanceConfig({
+      enabled: parseOptionalBoolean(process.env.CHROME_CONNECT_TO_RUNNING_PROFILE),
+      browserURL,
+      browserWSEndpoint,
+      remoteDebuggingHost,
+      remoteDebuggingPort,
+      reuseExistingPage
+    });
+    if (runningInstance !== undefined) browser.runningInstance = runningInstance;
+
+    return { browser };
+  }
+
+  if (connectToDefaultEndpoint || (browserURL !== undefined && browserURL.length > 0) || (browserWSEndpoint !== undefined && browserWSEndpoint.length > 0)) {
+    const browser: RemoteDebuggingChromeConfig = { mode: 'remote-debugging' };
+
+    if (browserURL !== undefined && browserURL.length > 0) browser.browserURL = browserURL;
+    if (browserWSEndpoint !== undefined && browserWSEndpoint.length > 0) browser.browserWSEndpoint = browserWSEndpoint;
+    if (remoteDebuggingHost !== undefined && remoteDebuggingHost.length > 0) browser.remoteDebuggingHost = remoteDebuggingHost;
+    if (remoteDebuggingPort !== undefined) browser.remoteDebuggingPort = remoteDebuggingPort;
+    if (reuseExistingPage !== undefined) browser.reuseExistingPage = reuseExistingPage;
+
+    return { browser };
+  }
+
+  throw new Error('Set CHROME_USER_DATA_DIR to launch/connect to a Chrome profile, or set CHROME_REMOTE_DEBUGGING_URL/CHROME_CONNECT to connect to an already-running Chrome.');
+}
+
+function parseOptionalInteger(value: string | undefined): number | undefined {
+  if (value === undefined || value.length === 0) return undefined;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed)) {
+    throw new Error(`Expected an integer for CHROME_REMOTE_DEBUGGING_PORT, got: ${value}`);
+  }
+  return parsed;
+}
+
+interface EnvRunningInstanceInput {
+  enabled?: boolean | undefined;
+  browserURL?: string | undefined;
+  browserWSEndpoint?: string | undefined;
+  remoteDebuggingHost?: string | undefined;
+  remoteDebuggingPort?: number | undefined;
+  reuseExistingPage?: boolean | undefined;
+}
+
+function buildRunningInstanceConfig(input: EnvRunningInstanceInput): RunningChromeInstanceConfig | undefined {
+  const config: RunningChromeInstanceConfig = {};
+
+  if (input.enabled !== undefined) config.enabled = input.enabled;
+  if (input.browserURL !== undefined && input.browserURL.length > 0) config.browserURL = input.browserURL;
+  if (input.browserWSEndpoint !== undefined && input.browserWSEndpoint.length > 0) config.browserWSEndpoint = input.browserWSEndpoint;
+  if (input.remoteDebuggingHost !== undefined && input.remoteDebuggingHost.length > 0) config.remoteDebuggingHost = input.remoteDebuggingHost;
+  if (input.remoteDebuggingPort !== undefined) config.remoteDebuggingPort = input.remoteDebuggingPort;
+  if (input.reuseExistingPage !== undefined) config.reuseExistingPage = input.reuseExistingPage;
+
+  return Object.keys(config).length === 0 ? undefined : config;
+}
+
+function parseOptionalBoolean(value: string | undefined): boolean | undefined {
+  if (value === undefined || value.length === 0) return undefined;
+  if (value === '1' || value.toLowerCase() === 'true') return true;
+  if (value === '0' || value.toLowerCase() === 'false') return false;
+  throw new Error(`Expected a boolean-like value for environment variable, got: ${value}`);
+}
+
+main().catch(error => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/src/core/Actor.ts

@@ -0,0 +1,167 @@
+import type { WaitForOptions } from 'puppeteer-core';
+import type { LoginFlowDefinition } from '../auth/LoginFlow.types.js';
+import type { ConfigError } from '../errors/ConfigError.js';
+import { ConfigError as RuntimeConfigError } from '../errors/ConfigError.js';
+import type { ClearFieldStrategy } from '../interaction/FieldClearer.js';
+import type { HumanTypingOptions } from '../interaction/HumanTyping.js';
+import type { ActorContext } from './ActorContext.js';
+
+export type ActorTask<TInput = any, TOutput = unknown> = (
+  context: ActorContext,
+  input: TInput
+) => Promise<TOutput> | TOutput;
+
+export type ActorTaskMap = Record<string, ActorTask<any, any>>;
+
+export interface ActorHooks {
+  beforeRun?: (context: ActorContext, taskName: string, input: unknown) => Promise<void> | void;
+  afterRun?: (context: ActorContext, taskName: string, output: unknown) => Promise<void> | void;
+  onError?: (context: ActorContext, taskName: string, error: unknown) => Promise<void> | void;
+}
+
+export interface Actor<TTasks extends ActorTaskMap = ActorTaskMap> {
+  id: string;
+  baseUrl: string;
+  auth?: LoginFlowDefinition;
+  tasks: TTasks;
+  hooks?: ActorHooks;
+}
+
+export type FormTaskValue = string | number | boolean;
+export type FormTaskValueResolver<TInput> = (
+  input: TInput,
+  context: ActorContext
+) => Promise<FormTaskValue | null | undefined> | FormTaskValue | null | undefined;
+
+export interface FormTaskFieldDefinition<TInput extends Record<string, unknown>> {
+  selector: string;
+  inputKey?: keyof TInput & string;
+  value?: FormTaskValue | FormTaskValueResolver<TInput>;
+  required?: boolean;
+  timeoutMs?: number;
+  clickBeforeTyping?: boolean;
+  clearFieldBeforeTyping?: boolean;
+  clearMethod?: ClearFieldStrategy;
+  typing?: HumanTypingOptions;
+}
+
+export interface FormTaskSubmitDefinition {
+  selector: string;
+  timeoutMs?: number;
+  waitForNavigation?: boolean;
+  navigationOptions?: WaitForOptions;
+}
+
+export interface FormTaskHooks<TInput extends Record<string, unknown>> {
+  beforeFill?: (context: ActorContext, input: TInput) => Promise<void> | void;
+  afterField?: (
+    context: ActorContext,
+    field: FormTaskFieldDefinition<TInput>,
+    input: TInput,
+    value: string
+  ) => Promise<void> | void;
+  beforeSubmit?: (context: ActorContext, input: TInput) => Promise<void> | void;
+  afterSubmit?: (context: ActorContext, input: TInput) => Promise<void> | void;
+}
+
+export interface FormTaskDefinition<TInput extends Record<string, unknown>, TOutput = void> {
+  url?: string;
+  fields: FormTaskFieldDefinition<TInput>[];
+  submit: FormTaskSubmitDefinition;
+  hooks?: FormTaskHooks<TInput>;
+  onComplete?: (context: ActorContext, input: TInput) => Promise<TOutput> | TOutput;
+}
+
+export function defineFormTask<TInput extends Record<string, unknown>, TOutput = void>(
+  definition: FormTaskDefinition<TInput, TOutput>
+): ActorTask<TInput, TOutput> {
+  return async (context, input) => {
+    if (definition.url !== undefined) {
+      await context.nav.goto(definition.url);
+    }
+
+    await definition.hooks?.beforeFill?.(context, input);
+
+    for (const field of definition.fields) {
+      const resolved = await resolveFormTaskValue(field, input, context);
+
+      if (resolved === null || resolved === undefined) {
+        if (field.required ?? true) {
+          throw new RuntimeConfigError(`Form task field ${field.selector} is missing a value.`);
+        }
+        continue;
+      }
+
+      const fillOptions: {
+        required: boolean;
+        timeoutMs?: number;
+        clickBeforeTyping?: boolean;
+        clear?: boolean;
+        clearMethod?: ClearFieldStrategy;
+        typing?: HumanTypingOptions;
+      } = {
+        required: field.required ?? true
+      };
+
+      if (field.timeoutMs !== undefined) fillOptions.timeoutMs = field.timeoutMs;
+      if (field.clickBeforeTyping !== undefined) fillOptions.clickBeforeTyping = field.clickBeforeTyping;
+      if (field.clearFieldBeforeTyping !== undefined) fillOptions.clear = field.clearFieldBeforeTyping;
+      if (field.clearMethod !== undefined) fillOptions.clearMethod = field.clearMethod;
+      if (field.typing !== undefined) fillOptions.typing = field.typing;
+
+      const textValue = String(resolved);
+      await context.forms.fillText(field.selector, textValue, fillOptions);
+      await definition.hooks?.afterField?.(context, field, input, textValue);
+    }
+
+    await definition.hooks?.beforeSubmit?.(context, input);
+
+    const clickOptions = definition.submit.timeoutMs === undefined
+      ? undefined
+      : { timeoutMs: definition.submit.timeoutMs };
+
+    if (definition.submit.waitForNavigation) {
+      await Promise.all([
+        context.page.waitForNavigation(definition.submit.navigationOptions ?? { waitUntil: 'domcontentloaded' }),
+        context.cursor.click(definition.submit.selector, clickOptions)
+      ]);
+    } else {
+      await context.cursor.click(definition.submit.selector, clickOptions);
+    }
+
+    await definition.hooks?.afterSubmit?.(context, input);
+
+    if (definition.onComplete !== undefined) {
+      return definition.onComplete(context, input);
+    }
+
+    return undefined as TOutput;
+  };
+}
+
+export function defineFormFillerTask<TInput extends Record<string, unknown>, TOutput = void>(
+  definition: FormTaskDefinition<TInput, TOutput>
+): ActorTask<TInput, TOutput> {
+  return defineFormTask(definition);
+}
+
+async function resolveFormTaskValue<TInput extends Record<string, unknown>>(
+  field: FormTaskFieldDefinition<TInput>,
+  input: TInput,
+  context: ActorContext
+): Promise<FormTaskValue | null | undefined> {
+  if (field.value !== undefined) {
+    if (typeof field.value === 'function') {
+      return field.value(input, context);
+    }
+    return field.value;
+  }
+
+  if (field.inputKey === undefined) {
+    throw new RuntimeConfigError(
+      `Form task field ${field.selector} requires either an inputKey or a value resolver.`
+    );
+  }
+
+  return input[field.inputKey] as FormTaskValue | null | undefined;
+}

package/src/core/ActorContext.ts

@@ -0,0 +1,34 @@
+import type { BrowserSession } from '../browser/BrowserSession.js';
+import type { RuntimeConfig } from '../browser/RuntimeConfig.js';
+import type { LoginFlowDefinition } from '../auth/LoginFlow.types.js';
+import type { Extractor } from '../extraction/Extractor.js';
+import type { Pagination } from '../extraction/Pagination.js';
+import type { FormFiller } from '../interaction/Forms.js';
+import type { HumanInteractor } from '../interaction/HumanInteractor.js';
+import type { Navigator } from '../interaction/Navigation.js';
+import type { PageAdapter } from '../interaction/PageAdapter.js';
+import type { Logger } from '../logging/Logger.js';
+
+export interface ActorMetadata {
+  id: string;
+  baseUrl: string;
+}
+
+export interface AuthController {
+  isLoggedIn(definition?: LoginFlowDefinition): Promise<boolean>;
+  ensureAuthenticated(definition?: LoginFlowDefinition): Promise<void>;
+}
+
+export interface ActorContext {
+  actor: ActorMetadata;
+  config: RuntimeConfig;
+  session: BrowserSession;
+  page: PageAdapter;
+  cursor: HumanInteractor;
+  forms: FormFiller;
+  nav: Navigator;
+  extract: Extractor;
+  pagination: Pagination;
+  auth: AuthController;
+  logger: Logger;
+}

package/src/core/ActorRegistry.ts

@@ -0,0 +1,26 @@
+import { ConfigError } from '../errors/ConfigError.js';
+import type { Actor, ActorTaskMap } from './Actor.js';
+
+export class ActorRegistry {
+  private readonly actors = new Map<string, Actor>();
+
+  register<TTasks extends ActorTaskMap>(actor: Actor<TTasks>): this {
+    if (this.actors.has(actor.id)) {
+      throw new ConfigError(`Actor already registered: ${actor.id}`);
+    }
+    this.actors.set(actor.id, actor as Actor);
+    return this;
+  }
+
+  get(actorId: string): Actor {
+    const actor = this.actors.get(actorId);
+    if (actor === undefined) {
+      throw new ConfigError(`No actor registered with id: ${actorId}`);
+    }
+    return actor;
+  }
+
+  list(): Actor[] {
+    return [...this.actors.values()];
+  }
+}

package/src/core/ActorRunner.ts

@@ -0,0 +1,240 @@
+import { EnvCredentialsProvider, type CredentialsProvider } from '../auth/CredentialsProvider.js';
+import { AuthStateDetector } from '../auth/AuthStateDetector.js';
+import { LoginFlow } from '../auth/LoginFlow.js';
+import type { LoginFlowDefinition } from '../auth/LoginFlow.types.js';
+import { BrowserFactory } from '../browser/BrowserFactory.js';
+import type { BrowserSession } from '../browser/BrowserSession.js';
+import type { PageLike } from '../browser/PuppeteerLike.js';
+import type { RuntimeConfig } from '../browser/RuntimeConfig.js';
+import { AutomationError } from '../errors/AutomationError.js';
+import { ConfigError } from '../errors/ConfigError.js';
+import { Extractor } from '../extraction/Extractor.js';
+import { Pagination } from '../extraction/Pagination.js';
+import { FormFiller } from '../interaction/Forms.js';
+import { GhostCursorAdapter } from '../interaction/GhostCursorAdapter.js';
+import type { HumanInteractor } from '../interaction/HumanInteractor.js';
+import { Navigator } from '../interaction/Navigation.js';
+import { PuppeteerPageAdapter, type PageAdapter } from '../interaction/PageAdapter.js';
+import type { Logger } from '../logging/Logger.js';
+import { ConsoleLogger } from '../logging/ConsoleLogger.js';
+import type { Actor, ActorTaskMap } from './Actor.js';
+import type { ActorContext, AuthController } from './ActorContext.js';
+import type { ActorRegistry } from './ActorRegistry.js';
+
+export interface ActorRunnerOptions {
+  config: RuntimeConfig;
+  browserFactory?: BrowserFactory;
+  credentialsProvider?: CredentialsProvider;
+  logger?: Logger;
+  interactorFactory?: (page: PageLike) => HumanInteractor;
+  pageAdapterFactory?: (page: PageLike) => PageAdapter;
+  loginFlow?: LoginFlow;
+  authStateDetector?: AuthStateDetector;
+  registry?: ActorRegistry;
+}
+
+type TaskName<TTasks extends ActorTaskMap> = keyof TTasks & string;
+type TaskInput<TTask> = TTask extends (...args: infer TArgs) => unknown
+  ? TArgs extends [unknown, infer TInput, ...unknown[]]
+    ? TInput
+    : undefined
+  : never;
+type TaskOutput<TTask> = TTask extends (...args: unknown[]) => infer TResult ? Awaited<TResult> : never;
+type SequenceOutputs<TTasks extends ActorTaskMap, TTaskNames extends readonly TaskName<TTasks>[]> = {
+  [TIndex in keyof TTaskNames]: TTaskNames[TIndex] extends TaskName<TTasks>
+    ? TaskOutput<TTasks[TTaskNames[TIndex]]>
+    : never;
+};
+
+export class ActorRunner {
+  private readonly browserFactory: BrowserFactory;
+  private readonly credentialsProvider: CredentialsProvider;
+  private readonly logger: Logger;
+  private readonly interactorFactory: (page: PageLike) => HumanInteractor;
+  private readonly pageAdapterFactory: (page: PageLike) => PageAdapter;
+  private readonly loginFlow: LoginFlow;
+  private readonly authStateDetector: AuthStateDetector;
+  protected readonly registry: ActorRegistry | undefined;
+  protected readonly options: ActorRunnerOptions;
+
+  constructor(options: ActorRunnerOptions) {
+    this.options = options;
+    this.browserFactory = options.browserFactory ?? new BrowserFactory();
+    this.credentialsProvider = options.credentialsProvider ?? new EnvCredentialsProvider();
+    this.logger = options.logger ?? new ConsoleLogger('info');
+    this.interactorFactory = options.interactorFactory ?? (page => new GhostCursorAdapter(
+      page,
+      options.config.interaction?.typing === undefined ? {} : { typing: options.config.interaction.typing }
+    ));
+    this.pageAdapterFactory = options.pageAdapterFactory ?? (page => new PuppeteerPageAdapter(page));
+    this.authStateDetector = options.authStateDetector ?? new AuthStateDetector();
+    this.loginFlow = options.loginFlow ?? new LoginFlow(this.credentialsProvider, this.authStateDetector);
+    this.registry = options.registry;
+  }
+
+  async run<TTasks extends ActorTaskMap, TTaskKey extends TaskName<TTasks>>(
+    actor: Actor<TTasks>,
+    taskName: TTaskKey,
+    input?: TaskInput<TTasks[TTaskKey]>
+  ): Promise<TaskOutput<TTasks[TTaskKey]>> {
+    const session = await this.createSession();
+    const context = this.createContext(actor, session);
+
+    try {
+      return await this.executeTask(actor, context, taskName, input, true);
+    } finally {
+      await this.closeSession(session);
+    }
+  }
+
+  async runRegistered<TOutput = unknown, TInput = unknown>(
+    actorId: string,
+    taskName: string,
+    input?: TInput
+  ): Promise<TOutput> {
+    const actor = this.getRegisteredActor(actorId) as Actor<ActorTaskMap>;
+    return this.run(actor, taskName, input as never) as Promise<TOutput>;
+  }
+
+  protected async createSession(): Promise<BrowserSession> {
+    return this.browserFactory.launch(this.options.config);
+  }
+
+  protected async closeSession(session: BrowserSession): Promise<void> {
+    if (session.shouldCloseOnFinish()) {
+      await session.close();
+    }
+  }
+
+  protected async executeTask<TTasks extends ActorTaskMap, TTaskKey extends TaskName<TTasks>>(
+    actor: Actor<TTasks>,
+    context: ActorContext,
+    taskName: TTaskKey,
+    input: TaskInput<TTasks[TTaskKey]> | undefined,
+    ensureAuthentication: boolean
+  ): Promise<TaskOutput<TTasks[TTaskKey]>> {
+    const task = this.getTask(actor, taskName);
+
+    try {
+      await actor.hooks?.beforeRun?.(context, taskName, input);
+
+      if (ensureAuthentication && actor.auth !== undefined) {
+        await context.auth.ensureAuthenticated(actor.auth);
+      }
+
+      const output = await task(context, input as never) as TaskOutput<TTasks[TTaskKey]>;
+      await actor.hooks?.afterRun?.(context, taskName, output);
+      return output;
+    } catch (error) {
+      await actor.hooks?.onError?.(context, taskName, error);
+      throw this.wrapError(error, actor.id, taskName, context.page.url());
+    }
+  }
+
+  protected getRegisteredActor(actorId: string): Actor {
+    if (this.registry === undefined) {
+      throw new ConfigError('runRegistered requires an ActorRegistry.');
+    }
+    return this.registry.get(actorId);
+  }
+
+  protected createContext(actor: Actor, session: BrowserSession): ActorContext {
+    const page = this.pageAdapterFactory(session.page);
+    const cursor = this.interactorFactory(session.page);
+    const forms = new FormFiller(page, cursor);
+    const nav = new Navigator(page, cursor, actor.baseUrl);
+    const extract = new Extractor(page);
+    const pagination = new Pagination(page, cursor);
+
+    let context!: ActorContext;
+
+    const auth: AuthController = {
+      isLoggedIn: async (definition?: LoginFlowDefinition) => {
+        const targetDefinition = definition ?? actor.auth;
+        if (targetDefinition === undefined) {
+          return false;
+        }
+        return this.authStateDetector.isLoggedIn(context, targetDefinition);
+      },
+      ensureAuthenticated: async (definition?: LoginFlowDefinition) => {
+        const targetDefinition = definition ?? actor.auth;
+        if (targetDefinition === undefined) {
+          return;
+        }
+        await this.loginFlow.ensureAuthenticated(context, targetDefinition);
+      }
+    };
+
+    context = {
+      actor: { id: actor.id, baseUrl: actor.baseUrl },
+      config: this.options.config,
+      session,
+      page,
+      cursor,
+      forms,
+      nav,
+      extract,
+      pagination,
+      auth,
+      logger: this.logger
+    };
+
+    return context;
+  }
+
+  protected getTask<TTasks extends ActorTaskMap, TTaskKey extends TaskName<TTasks>>(
+    actor: Actor<TTasks>,
+    taskName: TTaskKey
+  ): TTasks[TTaskKey] {
+    const task = actor.tasks[taskName];
+    if (task === undefined) {
+      throw new ConfigError(`Actor ${actor.id} does not define task: ${taskName}`);
+    }
+    return task;
+  }
+
+  protected wrapError(error: unknown, actorId: string, taskName: string, url?: string): Error {
+    if (error instanceof AutomationError) {
+      return error;
+    }
+
+    const meta = url === undefined ? { actorId, taskName, cause: error } : { actorId, taskName, url, cause: error };
+    return new AutomationError(`Actor ${actorId} task ${taskName} failed.`, meta);
+  }
+}
+
+export class ActorSequenceRunner extends ActorRunner {
+  async runSequence<TTasks extends ActorTaskMap, TTaskNames extends readonly TaskName<TTasks>[]>(
+    actor: Actor<TTasks>,
+    taskNames: [...TTaskNames],
+    input?: TaskInput<TTasks[TTaskNames[number]]>
+  ): Promise<SequenceOutputs<TTasks, TTaskNames>> {
+    if (taskNames.length === 0) {
+      throw new ConfigError('runSequence requires at least one task.');
+    }
+
+    const session = await this.createSession();
+    const context = this.createContext(actor, session);
+    const outputs: unknown[] = [];
+
+    try {
+      for (const [index, taskName] of taskNames.entries()) {
+        const output = await this.executeTask(actor, context, taskName, input as never, index === 0);
+        outputs.push(output);
+      }
+
+      return outputs as SequenceOutputs<TTasks, TTaskNames>;
+    } finally {
+      await this.closeSession(session);
+    }
+  }
+
+  async runRegisteredSequence<TOutput = unknown, TInput = unknown>(
+    actorId: string,
+    taskNames: string[],
+    input?: TInput
+  ): Promise<TOutput[]> {
+    const actor = this.getRegisteredActor(actorId) as Actor<ActorTaskMap>;
+    return this.runSequence(actor, taskNames, input as never) as Promise<TOutput[]>;
+  }
+}

package/src/core/defineActor.ts

@@ -0,0 +1,5 @@
+import type { Actor, ActorTaskMap } from './Actor.js';
+
+export function defineActor<TTasks extends ActorTaskMap>(actor: Actor<TTasks>): Actor<TTasks> {
+  return actor;
+}

package/src/core/index.ts

@@ -0,0 +1,5 @@
+export * from './Actor.js';
+export * from './ActorContext.js';
+export * from './ActorRegistry.js';
+export * from './ActorRunner.js';
+export * from './defineActor.js';

package/src/errors/AuthError.ts

@@ -0,0 +1,7 @@
+import { AutomationError, type AutomationErrorMeta } from './AutomationError.js';
+
+export class AuthError extends AutomationError {
+  constructor(message: string, meta: AutomationErrorMeta = {}) {
+    super(message, meta);
+  }
+}

package/src/errors/AutomationError.ts

@@ -0,0 +1,26 @@
+export interface AutomationErrorMeta {
+  actorId?: string;
+  taskName?: string;
+  url?: string;
+  screenshotPath?: string;
+  cause?: unknown;
+  details?: Record<string, unknown>;
+}
+
+export class AutomationError extends Error {
+  readonly actorId: string | undefined;
+  readonly taskName: string | undefined;
+  readonly url: string | undefined;
+  readonly screenshotPath: string | undefined;
+  readonly details: Record<string, unknown> | undefined;
+
+  constructor(message: string, meta: AutomationErrorMeta = {}) {
+    super(message, meta.cause instanceof Error ? { cause: meta.cause } : undefined);
+    this.name = new.target.name;
+    this.actorId = meta.actorId;
+    this.taskName = meta.taskName;
+    this.url = meta.url;
+    this.screenshotPath = meta.screenshotPath;
+    this.details = meta.details;
+  }
+}

package/src/errors/ConfigError.ts

@@ -0,0 +1,7 @@
+import { AutomationError, type AutomationErrorMeta } from './AutomationError.js';
+
+export class ConfigError extends AutomationError {
+  constructor(message: string, meta: AutomationErrorMeta = {}) {
+    super(message, meta);
+  }
+}

package/src/errors/ExtractionError.ts

@@ -0,0 +1,7 @@
+import { AutomationError, type AutomationErrorMeta } from './AutomationError.js';
+
+export class ExtractionError extends AutomationError {
+  constructor(message: string, meta: AutomationErrorMeta = {}) {
+    super(message, meta);
+  }
+}

package/src/errors/NavigationError.ts

@@ -0,0 +1,7 @@
+import { AutomationError, type AutomationErrorMeta } from './AutomationError.js';
+
+export class NavigationError extends AutomationError {
+  constructor(message: string, meta: AutomationErrorMeta = {}) {
+    super(message, meta);
+  }
+}

package/src/errors/SelectorError.ts

@@ -0,0 +1,10 @@
+import { AutomationError, type AutomationErrorMeta } from './AutomationError.js';
+
+export class SelectorError extends AutomationError {
+  readonly selector: string | undefined;
+
+  constructor(message: string, selector?: string, meta: AutomationErrorMeta = {}) {
+    super(message, meta);
+    this.selector = selector;
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,6 @@
+export * from './AutomationError.js';
+export * from './AuthError.js';
+export * from './ConfigError.js';
+export * from './ExtractionError.js';
+export * from './NavigationError.js';
+export * from './SelectorError.js';