@http-forge/core 0.1.0 → 0.2.0

package/dist/types/platform.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Platform Abstraction Interfaces
+ *
+ * These interfaces decouple core business logic from platform-specific APIs
+ * (VS Code, Node.js CLI, browser, etc.), enabling the same logic to run
+ * in any environment by providing different implementations.
+ *
+ * Pattern:
+ *   - Extension: implements via vscode.* APIs
+ *   - CLI/Standalone: implements via chokidar, node-keytar, open, etc.
+ *   - Browser/Web: implements via browser APIs or server-side proxies
+ */
+/**
+ * Represents a resource that can be disposed/cleaned up.
+ */
+export interface IDisposable {
+    dispose(): void;
+}
+/**
+ * Callback type for file watcher events.
+ */
+export type FileWatcherCallback = (uri: string) => void;
+/**
+ * Watches a set of files for changes.
+ *
+ * VS Code impl: wraps `vscode.FileSystemWatcher`
+ * Node impl: wraps `chokidar` or `fs.watch`
+ */
+export interface IFileWatcher extends IDisposable {
+    onDidChange(callback: FileWatcherCallback): IDisposable;
+    onDidCreate(callback: FileWatcherCallback): IDisposable;
+    onDidDelete(callback: FileWatcherCallback): IDisposable;
+}
+/**
+ * Factory for creating file watchers.
+ *
+ * VS Code impl: `vscode.workspace.createFileSystemWatcher(new RelativePattern(base, glob))`
+ * Node impl: `chokidar.watch(path.join(base, glob))`
+ */
+export interface IFileWatcherFactory {
+    /**
+     * Create a watcher for files matching the glob pattern under the base directory.
+     * @param base - Base directory path
+     * @param glob - Glob pattern relative to base (e.g. `'**\/*.json'`)
+     */
+    createFileWatcher(base: string, glob: string): IFileWatcher;
+}
+/**
+ * Simple key-value store for persisting state.
+ *
+ * VS Code impl: wraps `ExtensionContext.globalState` or `.workspaceState`
+ * Node/CLI impl: wraps a JSON file or SQLite
+ * Browser impl: wraps localStorage or IndexedDB
+ */
+export interface IKeyValueStore {
+    /**
+     * Get a value by key. Returns `defaultValue` (or undefined) if not found.
+     */
+    get<T>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Set a value for a key. Pass `undefined` to delete.
+     */
+    update(key: string, value: any): Promise<void>;
+}
+/**
+ * Secure storage for sensitive data (tokens, passwords).
+ *
+ * VS Code impl: wraps `ExtensionContext.secrets`
+ * Node/CLI impl: wraps `keytar` or encrypted file store
+ * Browser impl: wraps server-side encrypted store via API
+ */
+export interface ISecretStore {
+    get(key: string): Promise<string | undefined>;
+    store(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Shows user-facing notifications/messages.
+ *
+ * VS Code impl: wraps `vscode.window.show{Information,Warning,Error}Message`
+ * CLI impl: console.log / chalk
+ * Browser impl: toast / alert
+ */
+export interface INotificationService {
+    showInformation(message: string): Promise<string | undefined>;
+    showWarning(message: string): Promise<string | undefined>;
+    showError(message: string): Promise<string | undefined>;
+}
+/**
+ * A named output channel for structured logging with UI controls.
+ * Extends ILogger with show/clear/dispose capabilities.
+ *
+ * VS Code impl: wraps `vscode.LogOutputChannel`
+ * CLI impl: writes to a log file or stdout with prefixed channel name
+ * Browser impl: writes to a panel or developer console
+ */
+export interface IOutputChannel extends IDisposable {
+    readonly name: string;
+    trace(message: string): void;
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    /** Show/focus the output channel */
+    show(preserveFocus?: boolean): void;
+    /** Clear all output */
+    clear(): void;
+}
+/**
+ * Factory for creating named output channels.
+ *
+ * VS Code impl: wraps `vscode.window.createOutputChannel(name, { log: true })`
+ * Node/CLI impl: creates file-backed or console-backed loggers
+ */
+export interface IOutputChannelFactory {
+    createOutputChannel(name: string): IOutputChannel;
+}
+/**
+ * Service for interacting with the system browser.
+ * Used primarily for OAuth2 authorization flows.
+ *
+ * VS Code impl: wraps `vscode.env.openExternal`, `.uriScheme`, `.asExternalUri`
+ * Node/CLI impl: wraps `open` package + local HTTP callback server
+ * Browser impl: `window.open()` + `postMessage` callback
+ */
+export interface IExternalBrowserService {
+    /**
+     * The URI scheme for this platform (e.g. 'vscode', 'http-forge', 'http').
+     */
+    readonly uriScheme: string;
+    /**
+     * Open a URL in the system's default browser.
+     */
+    openExternal(url: string): Promise<boolean>;
+    /**
+     * Convert a local URI to an externally accessible URI.
+     * Used for OAuth2 callback URLs.
+     */
+    asExternalUri(uri: string): Promise<string>;
+}
+/**
+ * Metadata about the running application/extension.
+ * Used for User-Agent headers, telemetry, etc.
+ *
+ * VS Code impl: reads from `vscode.extensions.getExtension(id)?.packageJSON`
+ * CLI impl: reads from package.json
+ */
+export interface IApplicationInfo {
+    readonly name: string;
+    readonly version: string;
+    readonly displayName?: string;
+}
+/**
+ * Aggregate interface providing all platform-specific services.
+ * Consumers that need multiple platform services can depend on this
+ * instead of injecting each service individually.
+ *
+ * All properties are optional — consumers should only use what they need.
+ */
+export interface IPlatformContext {
+    /** Factory for creating file watchers */
+    readonly fileWatcherFactory?: IFileWatcherFactory;
+    /** Workspace-scoped key-value store (per-workspace state) */
+    readonly workspaceStore?: IKeyValueStore;
+    /** Global key-value store (cross-workspace state) */
+    readonly globalStore?: IKeyValueStore;
+    /** Secure storage for tokens and credentials */
+    readonly secretStore?: ISecretStore;
+    /** User-facing notifications */
+    readonly notifications?: INotificationService;
+    /** Output channel factory for structured logging */
+    readonly outputChannelFactory?: IOutputChannelFactory;
+    /** External browser interaction (OAuth2, etc.) */
+    readonly browser?: IExternalBrowserService;
+    /** Application metadata */
+    readonly appInfo?: IApplicationInfo;
+}
+/**
+ * Interface for file system operations.
+ * Allows mocking in tests and platform-agnostic code.
+ */
+export interface IFileSystem {
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    exists(filePath: string): Promise<boolean>;
+    mkdir(dirPath: string): Promise<void>;
+    glob(patterns: string[], cwd?: string): Promise<string[]>;
+    readDir(dirPath: string): Promise<string[]>;
+    isDirectory(filePath: string): Promise<boolean>;
+}
+import { HttpRequestOptions, HttpResponse } from './types';
+/**
+ * Interface for executing HTTP requests.
+ */
+export interface IHttpClient {
+    send(options: HttpRequestOptions): Promise<HttpResponse>;
+}
+/**
+ * Interface for logging.
+ */
+export interface ILogger {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}

package/dist/{interfaces → types}/types.d.ts

@@ -4,6 +4,8 @@
  * Core data types used throughout the framework.
  * Simplified design for maximum compatibility.
  */
+import { ParsedCookie } from '../cookie/interfaces';
+export type { ParsedCookie };
 /**
  * Unified Collection - the common format all parsers produce
  */
@@ -108,6 +110,31 @@ export interface RequestBody {
     format?: RawFormat;
     content?: any;
 }
+/**
+ * Form data entry for multipart form-data bodies
+ */
+export interface FormDataEntry {
+    key: string;
+    value: string;
+    type?: 'text' | 'file';
+    enabled?: boolean;
+}
+/**
+ * URL-encoded form entry
+ */
+export interface UrlEncodedEntry {
+    key: string;
+    value: string;
+    enabled?: boolean;
+}
+/**
+ * GraphQL request content
+ */
+export interface GraphQLContent {
+    query: string;
+    variables?: Record<string, unknown>;
+    operationName?: string;
+}
 /**
  * Request settings
  */
@@ -127,41 +154,67 @@ export interface RequestSettings {
 export interface HttpRequest {
     method: string;
     url: string;
-    headers: Record<string, string>;
+    headers?: Record<string, string>;
     body?: any;
     timeout?: number;
+    signal?: AbortSignal;
     settings?: RequestSettings;
 }
+/**
+ * HTTP request options (alias for HttpRequest)
+ * Matches extension's HttpRequestOptions interface
+ */
+export type HttpRequestOptions = HttpRequest;
 /**
  * HTTP response from execution
  */
 export interface HttpResponse {
     status: number;
     statusText: string;
-    headers: Record<string, string>;
+    headers: Record<string, string | string[]>;
+    cookies: ParsedCookie[];
     body: any;
     time: number;
     size?: number;
-    /** Parsed cookies from Set-Cookie headers */
-    cookies?: Record<string, string>;
 }
 /**
- * Environment configuration
+ * Normalized request ready for execution pipeline.
+ * Contains unresolved variables — the executor resolves them before sending.
+ * Matches extension's ExecutionRequest.
  */
-export interface Environment {
+export interface ExecutionRequest {
+    id: string;
     name: string;
-    description?: string;
-    variables: Record<string, string>;
+    method: string;
+    url: string;
     headers?: Record<string, string>;
+    query?: Record<string, string>;
+    body?: RequestBody | null;
+    bodyContentType?: string;
+    params?: Record<string, string>;
+    settings?: RequestSettings;
+    scripts?: RequestScripts;
+    auth?: RequestAuth;
+}
+/**
+ * Variable scopes for script/request execution.
+ * Matches extension's ExecutionVariables.
+ */
+export interface ExecutionVariables {
+    variables: Record<string, string>;
+    collectionVariables?: Record<string, string>;
+    globals?: Record<string, string>;
+    sessionVariables?: Record<string, string>;
+    environmentVariables?: Record<string, string>;
 }
 /**
- * Resolved environment with all inherited values merged
+ * Environment configuration
  */
-export interface ResolvedEnvironment {
+export interface Environment {
     name: string;
     description?: string;
     variables: Record<string, string>;
-    headers: Record<string, string>;
+    headers?: Record<string, string>;
 }
 /**
  * Context available to scripts during execution
@@ -183,6 +236,8 @@ export interface ScriptContext {
     variables: Record<string, string>;
     /** Information about the current execution */
     info?: ScriptInfo;
+    /** Cookie jar for accessing/modifying cookies in scripts */
+    cookieJar?: any;
 }
 /**
  * Script execution metadata
@@ -193,6 +248,7 @@ export interface ScriptInfo {
     iterationCount?: number;
     requestName?: string;
     requestId?: string;
+    collectionName?: string;
 }
 /**
  * Result of script execution
@@ -305,4 +361,218 @@ export interface ForgeConfig {
     /** Whether to verify SSL certificates */
     strictSSL?: boolean;
 }
-//# sourceMappingURL=types.d.ts.map
+/**
+ * JSON Schema compatible type (OAS 3.0 subset)
+ */
+export type JSONSchema7 = Record<string, any>;
+/**
+ * JSON-compatible value types (for response body)
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Header/Query entry with enabled flag (for CollectionRequest Array format)
+ */
+export interface KeyValueEntry {
+    key: string;
+    value: string;
+    enabled?: boolean;
+    type?: 'string' | 'integer' | 'number' | 'boolean' | 'array';
+    required?: boolean;
+    description?: string;
+    format?: string;
+    enum?: string[];
+    deprecated?: boolean;
+}
+/**
+ * Path parameter entry with OpenAPI metadata
+ */
+export interface PathParamEntry {
+    value: string;
+    type?: 'string' | 'integer' | 'number' | 'boolean';
+    description?: string;
+    format?: string;
+    enum?: string[];
+    deprecated?: boolean;
+}
+/**
+ * Per-property encoding metadata for multipart/form-data request bodies.
+ * Mirrors the OpenAPI 3.0 Encoding Object.
+ */
+export interface EncodingDefinition {
+    contentType?: string;
+    style?: 'form' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+    explode?: boolean;
+    allowReserved?: boolean;
+    headers?: Record<string, {
+        description?: string;
+        schema: JSONSchema7;
+    }>;
+}
+/**
+ * Content definition for a single media type.
+ */
+export interface ContentDefinition {
+    schema?: JSONSchema7;
+    examples?: Record<string, {
+        summary?: string;
+        value: any;
+    }>;
+    encoding?: Record<string, EncodingDefinition>;
+}
+/**
+ * Response definition for a specific HTTP status code.
+ */
+export interface ResponseDefinition {
+    description?: string;
+    contentType?: string;
+    schema?: JSONSchema7;
+    examples?: Record<string, {
+        summary?: string;
+        value: any;
+    }>;
+    content?: Record<string, ContentDefinition>;
+    headers?: Record<string, {
+        description?: string;
+        schema: JSONSchema7;
+    }>;
+}
+/**
+ * Response schema definition with per-status response schemas.
+ */
+export interface ResponseSchemaDefinition {
+    responses: Record<string, ResponseDefinition>;
+    components?: Record<string, JSONSchema7>;
+}
+/**
+ * Body schema definition for request bodies.
+ */
+export interface BodySchemaDefinition {
+    contentType?: string;
+    schema: JSONSchema7;
+    components?: Record<string, JSONSchema7>;
+    content?: Record<string, ContentDefinition>;
+    encoding?: Record<string, EncodingDefinition>;
+}
+/**
+ * Basic authentication configuration
+ */
+export interface BasicAuthConfig {
+    username: string;
+    password: string;
+}
+/**
+ * API Key authentication configuration
+ */
+export interface ApiKeyConfig {
+    key: string;
+    value: string;
+    in?: 'header' | 'query';
+}
+/**
+ * OAuth2 authentication configuration
+ */
+export interface OAuth2Config {
+    grantType: 'authorization_code' | 'client_credentials' | 'password' | 'implicit';
+    tokenUrl?: string;
+    authUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+    scope?: string;
+    username?: string;
+    password?: string;
+    accessToken?: string;
+    refreshToken?: string;
+    tokenPrefix?: string;
+    tokenField?: string;
+    callbackUrl?: string;
+    usePkce?: boolean;
+    pkceMethod?: 'S256' | 'plain';
+    audience?: string;
+    resource?: string;
+    extraParams?: Record<string, string>;
+    clientAuthentication?: 'header' | 'body';
+    state?: string;
+}
+/**
+ * Full request authentication configuration (matches extension's RequestAuth)
+ */
+export interface RequestAuth {
+    type?: 'none' | 'inherit' | 'basic' | 'bearer' | 'apikey' | 'oauth2';
+    bearerToken?: string;
+    basicAuth?: BasicAuthConfig;
+    apikey?: ApiKeyConfig;
+    oauth2?: OAuth2Config;
+}
+/**
+ * Request scripts configuration
+ */
+export interface RequestScripts {
+    preRequest?: string;
+    postResponse?: string;
+}
+/**
+ * Collection request - the on-disk/storage format
+ */
+export interface CollectionRequest {
+    id: string;
+    name: string;
+    method: string;
+    url: string;
+    headers?: KeyValueEntry[];
+    query?: KeyValueEntry[];
+    body?: RequestBody | null;
+    bodyContentType?: string;
+    params?: Record<string, string | PathParamEntry>;
+    settings?: RequestSettings;
+    scripts?: RequestScripts;
+    auth?: RequestAuth;
+    description?: string;
+    disabled?: boolean;
+    deprecated?: boolean;
+    responseSchema?: ResponseSchemaDefinition;
+    bodySchema?: BodySchemaDefinition;
+}
+/**
+ * Encoded request body ready for HTTP transmission
+ */
+export type RequestBodyEncoded = string | Buffer | null;
+/**
+ * Resolved body ready for HTTP transmission
+ */
+export interface ResolvedBody {
+    type: BodyType;
+    format?: RawFormat;
+    content: RequestBodyEncoded;
+}
+/**
+ * Fully prepared request ready for execution (all variables resolved)
+ */
+export interface PreparedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: ResolvedBody;
+    params: Record<string, string>;
+    query: Record<string, string>;
+}
+/**
+ * Complete execution result from running a request
+ */
+export interface ExecutionResult {
+    requestId: string;
+    name: string;
+    executedRequest: PreparedRequest;
+    response: HttpResponse;
+    duration: number;
+    timestamp: number;
+    passed: boolean;
+    assertions: TestAssertion[];
+    consoleOutput?: string[];
+    modifiedVariables?: Record<string, string>;
+    modifiedEnvironmentVariables?: Record<string, string>;
+    modifiedCollectionVariables?: Record<string, string>;
+    modifiedSessionVariables?: Record<string, string>;
+    error?: string;
+}

package/dist/utils/dynamic-variables.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Dynamic Variables Utility
+ *
+ * Single Responsibility: Generate Postman-compatible dynamic variable values
+ * Handles: $randomInt, $timestamp, $guid, $uuid, $randomString, $randomHexadecimal, etc.
+ */
+/**
+ * Dynamic variables supported by HTTP Forge (Postman-compatible)
+ */
+export declare const DYNAMIC_VARIABLES: Record<string, (...args: any[]) => any>;
+/**
+ * Check if a variable name is a dynamic variable
+ * @param varName - Variable name (without $ prefix)
+ * @returns True if this is a recognized dynamic variable
+ */
+export declare function isDynamicVariable(varName: string): boolean;
+/**
+ * Resolve a dynamic variable to its value
+ * @param varName - Variable name (without $ prefix)
+ * @param args - Optional arguments for parameterized variables
+ * @returns The generated value for the dynamic variable, or null if not recognized
+ */
+export declare function resolveDynamicVariable(varName: string, args?: any[]): any;
+/**
+ * Resolve all dynamic variables in a string
+ * @param text - Text containing {{$variableName}} patterns
+ * @returns Text with all dynamic variables replaced
+ */
+export declare function resolveDynamicVariablesInString(text: string): string;
+/**
+ * Scan an expression for $varName references and pre-resolve them as dynamic variables.
+ * Returns an augmented variables object so JS expressions like `$timestamp ?? 1` work
+ * (the sandbox needs `$timestamp` to be a defined identifier, not a ReferenceError).
+ *
+ * Only resolves simple $varName references (no parameterized args).
+ * Returns the original variables object unchanged if no dynamic vars are found.
+ */
+export declare function augmentWithDynamicVars(expression: string, variables: Record<string, any>): Record<string, any>;

package/dist/utils/expression-evaluator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Expression Evaluator
+ *
+ * Single Responsibility: Evaluate JavaScript expressions within {{ }} templates
+ * Uses Node.js vm module for sandboxed execution with timeout protection
+ *
+ * Supports:
+ * - Simple expressions: {{ var1 + 'abc' }}
+ * - Math operations: {{ price * quantity }}
+ * - Ternary: {{ status === 'active' ? 'yes' : 'no' }}
+ * - String methods: {{ name.toUpperCase() }}
+ * - Template literals: {{ `Hello ${name}` }}
+ * - Built-in functions: Math.*, Date.now(), JSON.stringify(), etc.
+ *
+ * Security:
+ * - Sandboxed execution via vm.createContext (no access to require, process, fs, etc.)
+ * - 100ms timeout to prevent infinite loops
+ * - Only variables and safe built-ins are available
+ */
+/**
+ * Check if an expression looks like a JS expression (not a simple variable name)
+ *
+ * Simple variable names like "myVar" or "$timestamp" should NOT be treated as expressions.
+ * Expressions contain operators, function calls, property access, etc.
+ */
+export declare function isExpression(content: string): boolean;
+/**
+ * Evaluate a JavaScript expression with the given variables in a sandboxed context
+ *
+ * @param expression - The JavaScript expression to evaluate
+ * @param variables - Variables available as bare identifiers in the expression
+ * @returns The result of the expression, or undefined if evaluation fails
+ */
+export declare function evaluateExpression(expression: string, variables?: Record<string, any>): any;

package/dist/utils/filter-engine.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Filter Engine
+ *
+ * Single Responsibility: Parse and apply pipe-based filters to values
+ * Thunder Client-compatible filter syntax: {{variable | filter1 | filter2(args)}}
+ *
+ * Supports:
+ * - Chained filters: {{variable | upper | substring(0, 5)}}
+ * - No-input filters using @: {{@ | filter1}}
+ * - Dynamic variable input: {{$guid | upper}}
+ * - Filter arguments: {{variable | replace("old", "new")}}
+ * - Variable references in args: {{number | add("otherVar")}}
+ */
+/**
+ * Parsed filter with name and arguments
+ */
+interface ParsedFilter {
+    name: string;
+    args: string[];
+}
+/**
+ * Result of parsing a template expression containing pipes
+ */
+export interface ParsedFilterChain {
+    /** The input portion (variable name, $dynamic, or @ for no-input) */
+    input: string;
+    /** Ordered list of filters to apply */
+    filters: ParsedFilter[];
+}
+/**
+ * Parse a filter chain from a template expression
+ * e.g. "variable | upper | substring(0, 5)" → { input: "variable", filters: [...] }
+ *
+ * @param expression - The content inside {{ }}, e.g. "myVar | upper | replace('a', 'b')"
+ * @returns Parsed filter chain, or null if no filters present
+ */
+export declare function parseFilterChain(expression: string): ParsedFilterChain | null;
+/**
+ * Apply a chain of filters to a value
+ *
+ * @param value - The input value (resolved variable value)
+ * @param filters - Array of parsed filters to apply in order
+ * @param variables - Available variables (for variable reference args like add("otherVar"))
+ * @returns The filtered result
+ */
+export declare function applyFilterChain(value: any, filters: ParsedFilter[], variables?: Record<string, any>): any;
+export {};