reqon-dsl 0.2.0 → 0.3.0

package/docusaurus/docs/api-reference.md

@@ -1,443 +0,0 @@
----
-sidebar_position: 21
----
-
-# API Reference
-
-Reqon's programmatic API for advanced usage.
-
-## Core Functions
-
-### parse
-
-Parse a Reqon source string into an AST.
-
-```typescript
-import { parse } from 'reqon';
-
-const ast = parse(`
-  mission Example {
-    source API { auth: bearer, base: "https://api.example.com" }
-    store data: file("data")
-    action Fetch { get "/data" }
-    run Fetch
-  }
-`);
-
-console.log(ast.missions[0].name); // "Example"
-```
-
-**Parameters:**
-- `source: string` - Reqon source code
-
-**Returns:** `ReqonProgram` - The parsed AST
-
-### execute
-
-Execute a Reqon mission from source code.
-
-```typescript
-import { execute } from 'reqon';
-
-const result = await execute(`
-  mission Example {
-    source API { auth: none, base: "https://jsonplaceholder.typicode.com" }
-    store posts: memory("posts")
-    action Fetch {
-      get "/posts"
-      store response -> posts { key: .id }
-    }
-    run Fetch
-  }
-`);
-
-console.log(result.success); // true
-console.log(result.duration); // 234
-console.log(result.actionsRun); // ["Fetch"]
-```
-
-**Parameters:**
-- `source: string` - Reqon source code
-- `config?: ExecutorConfig` - Optional configuration
-
-**Returns:** `Promise<ExecutionResult>`
-
-### fromFile
-
-Execute a mission from a file.
-
-```typescript
-import { fromFile } from 'reqon';
-
-const result = await fromFile('./mission.vague', {
-  auth: {
-    API: { type: 'bearer', token: 'xxx' }
-  }
-});
-```
-
-**Parameters:**
-- `filePath: string` - Path to .vague file
-- `config?: ExecutorConfig` - Optional configuration
-
-**Returns:** `Promise<ExecutionResult>`
-
-### fromPath
-
-Execute a mission from a file or folder.
-
-```typescript
-import { fromPath } from 'reqon';
-
-// Single file
-const result1 = await fromPath('./mission.vague');
-
-// Folder (multi-file mission)
-const result2 = await fromPath('./missions/customer-sync/');
-```
-
-**Parameters:**
-- `path: string` - Path to file or folder
-- `config?: ExecutorConfig` - Optional configuration
-
-**Returns:** `Promise<ExecutionResult>`
-
-### reqon (Tagged Template)
-
-Create a parsed program using a tagged template literal.
-
-```typescript
-import { reqon } from 'reqon';
-
-const program = reqon`
-  mission Example {
-    source API { auth: bearer, base: "https://api.example.com" }
-    store data: file("data")
-    action Fetch { get "/data" }
-    run Fetch
-  }
-`;
-
-// Execute the program
-const result = await program.execute();
-```
-
-## Configuration
-
-### ExecutorConfig
-
-```typescript
-interface ExecutorConfig {
-  // Skip actual HTTP requests
-  dryRun?: boolean;
-
-  // Enable verbose logging
-  verbose?: boolean;
-
-  // Authentication credentials
-  auth?: Record<string, AuthConfig>;
-
-  // Store configuration
-  storeConfig?: Record<string, StoreConfig>;
-
-  // State directory
-  stateDir?: string;
-
-  // Progress callbacks
-  progressCallbacks?: ProgressCallbacks;
-}
-```
-
-### AuthConfig
-
-```typescript
-type AuthConfig =
-  | { type: 'none' }
-  | { type: 'bearer'; token: string }
-  | { type: 'basic'; username: string; password: string }
-  | { type: 'api_key'; key: string; header?: string; query?: string; prefix?: string }
-  | {
-      type: 'oauth2';
-      clientId: string;
-      clientSecret: string;
-      accessToken: string;
-      refreshToken: string;
-      tokenUrl: string;
-      scopes?: string[];
-      expiresAt?: string;
-    };
-```
-
-### ProgressCallbacks
-
-```typescript
-interface ProgressCallbacks {
-  onMissionStart?: (mission: string) => void;
-  onMissionComplete?: (mission: string, result: ExecutionResult) => void;
-  onActionStart?: (action: string) => void;
-  onActionComplete?: (action: string, duration: number) => void;
-  onProgress?: (progress: ProgressInfo) => void;
-  onError?: (error: ExecutionError) => void;
-}
-
-interface ProgressInfo {
-  action: string;
-  step: string;
-  current: number;
-  total?: number;
-}
-```
-
-## Results
-
-### ExecutionResult
-
-```typescript
-interface ExecutionResult {
-  // Whether execution completed successfully
-  success: boolean;
-
-  // Total duration in milliseconds
-  duration: number;
-
-  // Actions that were executed
-  actionsRun: string[];
-
-  // Errors encountered
-  errors: ExecutionError[];
-
-  // Access to stores
-  stores: Map<string, StoreAdapter>;
-
-  // Execution ID (for state tracking)
-  executionId?: string;
-
-  // Execution state (for resume)
-  state?: ExecutionState;
-}
-```
-
-### ExecutionError
-
-```typescript
-interface ExecutionError {
-  action: string;
-  step: string;
-  message: string;
-  details?: unknown;
-}
-```
-
-## Store Adapter Interface
-
-```typescript
-interface StoreAdapter {
-  get(key: string): Promise<Record<string, unknown> | null>;
-  set(key: string, value: Record<string, unknown>): Promise<void>;
-  update(key: string, partial: Record<string, unknown>): Promise<void>;
-  delete(key: string): Promise<void>;
-  list(filter?: FilterOptions): Promise<Record<string, unknown>[]>;
-  clear(): Promise<void>;
-}
-
-interface FilterOptions {
-  where?: WhereClause[];
-  limit?: number;
-  offset?: number;
-}
-
-interface WhereClause {
-  field: string;
-  operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains';
-  value: unknown;
-}
-```
-
-## Registration Functions
-
-### registerFunction
-
-Register a custom function.
-
-```typescript
-import { registerFunction } from 'reqon';
-
-registerFunction('myFunc', (arg1: string, arg2: number) => {
-  return `${arg1}: ${arg2}`;
-});
-```
-
-### registerStoreAdapter
-
-Register a custom store adapter.
-
-```typescript
-import { registerStoreAdapter } from 'reqon';
-
-registerStoreAdapter('mystore', (name: string, config: any) => {
-  return new MyStoreAdapter(name, config);
-});
-```
-
-### registerAuthProvider
-
-Register a custom auth provider.
-
-```typescript
-import { registerAuthProvider } from 'reqon';
-
-registerAuthProvider('myauth', (config: any) => {
-  return new MyAuthProvider(config);
-});
-```
-
-### registerPaginationStrategy
-
-Register a custom pagination strategy.
-
-```typescript
-import { registerPaginationStrategy } from 'reqon';
-
-registerPaginationStrategy('linkheader', () => {
-  return new LinkHeaderPaginationStrategy();
-});
-```
-
-## State Management
-
-### getExecutionState
-
-Get execution state for a mission.
-
-```typescript
-import { getExecutionState } from 'reqon';
-
-const state = await getExecutionState('CustomerSync');
-console.log(state.status); // "completed"
-console.log(state.lastRun); // "2024-01-20T09:00:00Z"
-```
-
-### getExecutionHistory
-
-Get execution history.
-
-```typescript
-import { getExecutionHistory } from 'reqon';
-
-const history = await getExecutionHistory('CustomerSync', {
-  limit: 10,
-  since: '2024-01-01'
-});
-```
-
-### clearSyncCheckpoints
-
-Clear sync checkpoints.
-
-```typescript
-import { clearSyncCheckpoints, clearSyncCheckpoint } from 'reqon';
-
-// Clear all
-await clearSyncCheckpoints();
-
-// Clear specific
-await clearSyncCheckpoint('API-/customers');
-```
-
-## AST Types
-
-### ReqonProgram
-
-```typescript
-interface ReqonProgram {
-  missions: MissionDefinition[];
-}
-```
-
-### MissionDefinition
-
-```typescript
-interface MissionDefinition {
-  type: 'MissionDefinition';
-  name: string;
-  schedule?: ScheduleConfig;
-  sources: SourceDefinition[];
-  stores: StoreDefinition[];
-  schemas: SchemaDefinition[];
-  actions: ActionDefinition[];
-  pipeline: PipelineDefinition;
-}
-```
-
-### ActionDefinition
-
-```typescript
-interface ActionDefinition {
-  type: 'ActionDefinition';
-  name: string;
-  steps: ActionStep[];
-}
-```
-
-### ActionStep
-
-```typescript
-type ActionStep =
-  | FetchStep
-  | CallStep
-  | ForStep
-  | MapStep
-  | ValidateStep
-  | StoreStep
-  | MatchStep;
-```
-
-## CLI Programmatic Usage
-
-```typescript
-import { CLI } from 'reqon/cli';
-
-const cli = new CLI();
-
-// Run mission
-await cli.run(['./mission.vague', '--verbose']);
-
-// Daemon mode
-await cli.run(['./missions/', '--daemon']);
-
-// With auth
-await cli.run(['./mission.vague', '--auth', './credentials.json']);
-```
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `REQON_STATE_DIR` | State directory (default: `.vague-data`) |
-| `REQON_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, `error` |
-| `REQON_LOG_FORMAT` | Log format: `text`, `json` |
-| `REQON_DRY_RUN` | Enable dry-run mode |
-
-## Error Classes
-
-```typescript
-import {
-  ParseError,
-  RuntimeError,
-  ValidationError,
-  AuthenticationError,
-  StoreError
-} from 'reqon/errors';
-
-try {
-  await execute(source);
-} catch (error) {
-  if (error instanceof ParseError) {
-    console.error(`Parse error at line ${error.line}: ${error.message}`);
-  } else if (error instanceof AuthenticationError) {
-    console.error(`Auth failed for ${error.source}: ${error.message}`);
-  }
-}
-```
-
-For more details, see the [source code](https://github.com/mcclowes/reqon) and [Vague documentation](https://github.com/mcclowes/vague) for expression syntax.