Type Reference

interface RefrainConfig {
  ai: AIModelConfig;
  headless?: boolean;
  loggerFactory?: LoggerFactory;
  debug?: boolean;
  apiKey?: string;
  locale?: "en" | "ja";
  stealth?: boolean;
  proxy?: string | { server: string; username?: string; password?: string };
}

interface AIModelConfig {
  modelId: string;
  provider: ModelProvider;
  apiKey?: string;
  baseURL?: string;
  azureResourceName?: string;
  azureApiVersion?: string;
  bedrockRegion?: string;
  bedrockAccessKeyId?: string;
  bedrockSecretAccessKey?: string;
  bedrockSessionToken?: string;
  vertexProject?: string;
  vertexLocation?: string;
  modelOverrides?: Partial<Record<ModelPurpose, string>>;
}

type ModelProvider =
  | "anthropic"
  | "openai"
  | "openai-compatible"
  | "google"
  | "azure"
  | "bedrock"
  | "vertex";

type ModelPurpose =
  | "exploration"
  | "exploration-light"
  | "selector"
  | "extraction"
  | "review"
  | "fallback"
  | "vision";

interface ExecutionStrategy {
  maxRetries: number;
  changeTimeouts: number[];
  finalRetryStabilizeMs: number;
  domStabilityMs: number;
}

interface ExecutionReport {
  runbookTitle: string;
  startUrl: string;
  totalSteps: number;
  executed: number;
  succeeded: number;
  failed: number;
  skipped: number;
  aborted: boolean;
  steps: StepExecutionResult[];
  totalDurationMs: number;
  memoryCollections?: Record<string, number>;
  downloadedFiles?: string[];
  videoPaths?: string[];
  aiMetrics?: AIMetricsSummary;
}

interface StepExecutionResult {
  ordinal: number;
  description: string;
  status: StepStatus;
  durationMs: number;
  error?: string;
  capturedValues?: Record<string, string>;
  actionType?: string;

  // Conditional & loop fields
  conditionSkipped?: boolean;
  loopIterations?: number;
  subStepResults?: StepExecutionResult[][];
  branchMatch?: string;
  forEachItemCount?: number;

  // Self-healing fields
  retryCount?: number;
  retryDetails?: StepRetryDetail[];
  failureCategory?: FailureCategory;

  // Output fields
  extractedData?: string;
  downloadedFile?: string;
  exportedFile?: string;

  // Diagnostics
  diagnostics?: StepDiagnostics;

  // Telemetry
  resolveMethod?: "cache" | "deterministic" | "ai" | "scroll" | "vision" | "agent" | null;
  deterministicMatchType?: string;
  deterministicConfidence?: number;
  contextChunksUsed?: number;
  failureHintsProvided?: boolean;
  workingMemoryTokens?: number;
  snapshotElementCount?: number;
}

type StepStatus = "success" | "failed" | "skipped";

interface StepDiagnostics {
  lastSnapshotPreview?: string;
  failureHistory?: string[];
  lastAiResponseText?: string;
  recoveryHint?: string;
  deterministicResolveResult?: string;
  visionFallbackResult?: {
    annotationCount: number;
    reasoning: string;
    success: boolean;
  };
  agentFallbackResult?: {
    strategy: string;
    analysis: string;
    reasoning: string;
    success: boolean;
  };
  validationWarnings?: string[];
  validationErrors?: string[];
  executionStrategy?: ExecutionStrategy;
  stepAction?: { type: string; selector?: any; value?: string; url?: string };
  stepUrl?: string;
}

interface BatchExecutionReport {
  runbookTitle: string;
  totalRows: number;
  succeeded: number;
  failed: number;
  rows: {
    rowIndex: number;
    rowLabel: string;
    report: ExecutionReport;
  }[];
  totalDurationMs: number;
}

type ActionType =
  | "click" | "input" | "select" | "navigate"
  | "scroll" | "wait" | "hover" | "extract"
  | "download" | "export" | "memory" | "key";

type RiskLevel = "low" | "medium" | "high";

type VariableSource = "prompt" | "fixed" | "context" | "env" | "expression" | "data";

type CaptureStrategy = "snapshot" | "url" | "ai" | "expression" | "evaluate";

interface Logger {
  step(message: string): void;
  success(message: string): void;
  error(message: string): void;
  warn(message: string): void;
  info(message: string): void;
  debug(message: string): void;
}

interface LoggerFactory {
  createLogger(): Logger;
  createSpinner(): SpinnerLike;
}

interface SpinnerLike {
  start(message: string): void;
  stop(message: string): void;
}

import { CallbackLogger } from "@refrainai/sdk";

const logger = new CallbackLogger((level, message) => {
  // level: "step" | "success" | "error" | "warn" | "info" | "debug"
  console.log(`[${level}] ${message}`);
});

type LogLevel = "step" | "success" | "error" | "warn" | "info" | "debug";

interface ResolveVariablesInput {
  secrets?: Record<string, string>;
  contextMarkdown: string;
}

interface ResolveVariablesResult {
  variables: Record<string, string>;
  secrets: Record<string, string>;
}

interface Plan {
  tier: PlanTier;
  limits: PlanLimits;
  features: PlanFeatures;
}

type PlanTier = "community" | "pro" | "team" | "business" | "enterprise";

try {
  await client.execute(runbook, options);
} catch (e) {
  if (e instanceof PlanLimitError) {
    console.error(`Limit exceeded: ${e.limitType}`);
  }
  if (e instanceof PlanFeatureError) {
    console.error(`Feature not available: ${e.message}`);
  }
}