> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Type Reference

> All exported types from the Refrain SDK.

## Configuration types

### RefrainConfig

Alias for `LocalConfig`. See [Local Execution](/sdk/local-execution) for full property table.

```typescript theme={null}
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 };
}
```

### AIModelConfig

```typescript theme={null}
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>>;
}
```

### ModelProvider

```typescript theme={null}
type ModelProvider =
  | "anthropic"
  | "openai"
  | "openai-compatible"
  | "google"
  | "azure"
  | "bedrock"
  | "vertex";
```

### ModelPurpose

```typescript theme={null}
type ModelPurpose =
  | "exploration"
  | "exploration-light"
  | "selector"
  | "extraction"
  | "review"
  | "fallback"
  | "vision";
```

### ExecuteOptions

See [Local Execution](/sdk/local-execution#executeoptions) for full property table.

### ExecutionStrategy

```typescript theme={null}
interface ExecutionStrategy {
  maxRetries: number;
  changeTimeouts: number[];
  finalRetryStabilizeMs: number;
  domStabilityMs: number;
}
```

## Result types

### ExecutionReport

```typescript theme={null}
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;
}
```

### StepExecutionResult

```typescript theme={null}
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;
}
```

### StepStatus

```typescript theme={null}
type StepStatus = "success" | "failed" | "skipped";
```

### StepDiagnostics

Attached to failed steps with detailed failure information:

```typescript theme={null}
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;
}
```

### BatchExecutionReport

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

## Runbook types

### ParsedRunbook

Inferred from the Zod schema. See [Runbook YAML](/yaml/overview) for field descriptions.

### ParsedStep / StepAction / Selector

See [Actions](/yaml/actions), [Selectors](/yaml/selectors).

### ActionType

```typescript theme={null}
type ActionType =
  | "click" | "input" | "select" | "navigate"
  | "scroll" | "wait" | "hover" | "extract"
  | "download" | "export" | "memory" | "key";
```

### RiskLevel

```typescript theme={null}
type RiskLevel = "low" | "medium" | "high";
```

### VariableSource

```typescript theme={null}
type VariableSource = "prompt" | "fixed" | "context" | "env" | "expression" | "data";
```

### CaptureStrategy

```typescript theme={null}
type CaptureStrategy = "snapshot" | "url" | "ai" | "expression" | "evaluate";
```

## Logger types

### Logger

```typescript theme={null}
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;
}
```

### LoggerFactory

```typescript theme={null}
interface LoggerFactory {
  createLogger(): Logger;
  createSpinner(): SpinnerLike;
}
```

### SpinnerLike

```typescript theme={null}
interface SpinnerLike {
  start(message: string): void;
  stop(message: string): void;
}
```

### CallbackLogger

Custom logger that forwards all messages to a callback:

```typescript theme={null}
import { CallbackLogger } from "@refrainai/sdk";

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

### LogLevel

```typescript theme={null}
type LogLevel = "step" | "success" | "error" | "warn" | "info" | "debug";
```

## Utility types

### ResolveVariablesInput

```typescript theme={null}
interface ResolveVariablesInput {
  secrets?: Record<string, string>;
  contextMarkdown: string;
}
```

### ResolveVariablesResult

```typescript theme={null}
interface ResolveVariablesResult {
  variables: Record<string, string>;
  secrets: Record<string, string>;
}
```

## Plan types

### Plan

```typescript theme={null}
interface Plan {
  tier: PlanTier;
  limits: PlanLimits;
  features: PlanFeatures;
}
```

### PlanTier

```typescript theme={null}
type PlanTier = "community" | "pro" | "team" | "business" | "enterprise";
```

### PlanLimitError / PlanFeatureError

Thrown when a plan limit or feature gate is hit:

```typescript theme={null}
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}`);
  }
}
```

## Other types

| Type                    | Description                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `DataStore`             | Interface for memory data collection                                                    |
| `DataAggregator`        | Interface for data aggregation queries                                                  |
| `InMemoryDataStore`     | Built-in in-memory data store                                                           |
| `DownloadManager`       | File download and CSV merge utility                                                     |
| `DownloadRecord`        | Download metadata                                                                       |
| `AggregateOperation`    | `"sum"` \| `"count"` \| `"concat"` \| `"min"` \| `"max"` \| `"avg"` \| `"unique_count"` |
| `Locale`                | `"en"` \| `"ja"`                                                                        |
| `MeteringCollector`     | Usage metering interface                                                                |
| `NoopMeteringCollector` | No-op metering implementation                                                           |