@http-forge/core 0.1.0 → 0.2.0

package/README.md

@@ -1,26 +1,29 @@
 # @http-forge/core
 
-**Lightweight, VS Code-independent HTTP API testing engine** - The execution core of HTTP Forge.
+**Standalone HTTP testing engine with Postman collection support and JavaScript-based automation.**
 
 [![npm version](https://img.shields.io/npm/v/@http-forge/core.svg)](https://www.npmjs.com/package/@http-forge/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## 📦 What is @http-forge/core?
 
-`@http-forge/core` is a standalone, dependency-injection-based HTTP execution engine that powers HTTP Forge. It provides a clean API for:
+`@http-forge/core` is a headless, framework-agnostic HTTP execution engine with **full Postman collection compatibility**. Execute complex API workflows, test suites, and automated flows without the overhead of a UI.
 
-- 🚀 Executing HTTP requests with full HTTP Forge collection support
-- 🔄 Running pre-request and post-response scripts
-- 🌍 Managing environments and variables
-- 🍪 Automatic cookie handling
-- 📊 Test assertions and validations
-- 🔌 Extensible via interceptors and custom implementations
+**Core Features:**
+- 🚀 **Postman Collections** - Load and execute `.postman_collection.json` and `.forge.json` files
+- 📝 **JavaScript Scripting** - Pre-request and post-response scripts with `pm.*` API (events, variables, assertions)
+- 🔄 **Dynamic Variables** - Built-in generators: `{{$randomInt}}`, `{{$timestamp}}`, `{{$uuid}}`, `{{$guid}}`, etc.
+- 🌍 **Environments** - Full variable scoping (globals, collection, environment, session, flow-level)
+- 🍪 **Cookie Persistence** - Automatic cookie storage and reuse across request sequences
+- 📊 **Test Assertions** - BDD-style testing with `pm.test()` and `expect()` chains
+- 🔌 **Extensible** - Custom interceptors, HTTP clients, and module loaders
 
-**Perfect for:**
-- Building custom API testing tools
-- Integrating HTTP Forge into CI/CD pipelines
-- Creating CLI tools for API testing
-- Headless API testing automation
+**Ideal for:**
+- CI/CD pipeline integration (GitHub Actions, GitLab CI, Jenkins)
+- Headless API testing and contract validation
+- Building custom API testing CLIs
+- Load testing and performance monitoring
+- Automated integration test suites
 
 ## 🎯 Installation
 
@@ -141,29 +144,79 @@ console.log(result.preRequestResult);   // Pre-request script output
 console.log(result.postResponseResult); // Test results
 ```
 
+### Dynamic Variables
+
+Automatic variable generation within request templates:
+
+```javascript
+// URL with dynamic timestamp
+https://api.example.com/events?timestamp={{$timestamp}}
+
+// Headers with unique ID
+X-Request-ID: {{$uuid}}
+
+// Query parameters with random value
+?page=1&seed={{$randomInt:1:100}}
+```
+
+**Supported dynamic variables:**
+- `{{$randomInt}}` - Random integer (0-2147483647)
+- `{{$randomInt:min:max}}` - Random integer in range
+- `{{$timestamp}}` - Current Unix timestamp (seconds)
+- `{{$uuid}}` - UUID v4
+- `{{$guid}}` - GUID (alias for uuid)
+- `{{$randomString}}` - 10-char alphanumeric string
+- `{{$randomHexadecimal}}` - Random hex string
+- `{{$isoTimestamp}}` - ISO 8601 timestamp
+
 ### Script Execution
 
-Run pre-request and post-response scripts:
+Run pre-request and post-response scripts with full Postman API compatibility:
 
-**Pre-request script:**
+**Pre-request script - Set variables & modify request:**
 ```javascript
-// Set variables before request
-forge.env.set('timestamp', Date.now());
-forge.env.set('requestId', forge.uuid());
+// Set variables across scopes
+pm.variables.set('requestId', pm.variables.randomUUID());
+pm.environment.set('token', 'abc-123');
+pm.collectionVariables.set('counter', '1');
+
+// Modify request headers
+pm.request.headers.add({
+    name: 'X-Request-ID',
+    value: pm.variables.get('requestId')
+});
+pm.request.headers.update({
+    name: 'Authorization',
+    value: 'Bearer ' + pm.environment.get('token')
+});
+
+// Modify URL and body
+pm.request.url = 'https://api.example.com' + pm.request.url;
+pm.request.body.raw = JSON.stringify({ timestamp: Date.now() });
 
-// Modify request
-forge.request.headers['X-Request-ID'] = forge.env.get('requestId');
+// Set cookies for next request
+pm.cookies.set('sessionId', 'sess_abc123');
 ```
 
-**Post-response script:**
+**Post-response script - Test & extract data:**
 ```javascript
-// Run tests
-forge.expect(forge.response.status).toBe(200);
-forge.expect(forge.response.body.success).toBeTruthy();
+// Run assertions
+pm.test('Status is 200', () => {
+    pm.expect(pm.response.code).to.equal(200);
+});
+pm.test('Response time under 1s', () => {
+    pm.expect(pm.response.responseTime).to.be.below(1000);
+});
+
+// Extract data for next request
+const data = pm.response.json();
+pm.environment.set('userId', data.id);
+pm.environment.set('authToken', data.token);
 
-// Extract data from response
-const token = forge.response.body.token;
-forge.env.set('authToken', token);
+// Store cookies from response
+if (pm.response.headers.has('Set-Cookie')) {
+    pm.cookies.set('authCookie', data.authCookie);
+}
 ```
 
 ### Environment Management
@@ -240,21 +293,49 @@ const forge = new ForgeContainer({
 });
 ```
 
-### Cookie Management
+### Cookie Management & Persistence
 
-Automatic cookie handling across requests:
+Automatic cookie storage and reuse across multi-request flows:
 
 ```typescript
 const forge = new ForgeContainer({
-    enableCookies: true
+    enableCookies: true  // Cookies persist across requests in session
 });
 
-// Cookies are automatically stored and sent
+// Login - response sets Session-ID cookie
 const loginResult = await forge.execute(loginRequest, collection);
-// Session cookie from login is automatically included in next request
+
+// Subsequent requests automatically include Session-ID
+// No need to manually extract and re-add cookies
 const dataResult = await forge.execute(dataRequest, collection);
+const updateResult = await forge.execute(updateRequest, collection);
 ```
 
+**Access cookies in scripts:**
+```javascript
+// Pre-request script - read stored cookies
+if (pm.cookies.has('sessionId')) {
+    const sid = pm.cookies.get('sessionId');
+    pm.request.headers.add({
+        name: 'Cookie',
+        value: 'sessionId=' + sid
+    });
+}
+
+// Post-response script - store new cookies
+pm.response.cookies.forEach(cookie => {
+    pm.cookies.set(cookie.name, cookie.value);
+});
+
+// List all active cookies
+const allCookies = pm.cookies.list();  // [{name, value}, ...]
+
+// Clear cookies
+pm.cookies.clear();  // When switching users/sessions
+```
+
+Cookies are automatically extracted from `Set-Cookie` response headers and reused in subsequent `Cookie` request headers.
+
 ### Request History
 
 Track all executed requests:
@@ -450,6 +531,72 @@ class ApiTestRunner {
 }
 ```
 
+### Multi-Request Workflows
+
+Execute dependent request chains with automatic cookie and variable management:
+
+```typescript
+import { ForgeContainer } from '@http-forge/core';
+
+async function apiAuthWorkflow() {
+    const forge = new ForgeContainer({
+        enableCookies: true,  // Cookies persist across requests
+        enableHistory: true
+    });
+
+    // Request 1: Login (sets session cookie)
+    const loginReq = {
+        name: 'Login',
+        method: 'POST',
+        url: 'https://api.example.com/auth/login',
+        body: { type: 'raw', content: JSON.stringify({ 
+            username: '{{email}}',
+            password: '{{password}}'
+        })},
+        scripts: {
+            postResponse: `
+                const { token, userId } = pm.response.json();
+                pm.environment.set('authToken', token);
+                pm.environment.set('userId', userId);
+            `
+        }
+    };
+    
+    const loginResult = await forge.execute(loginReq, collection);
+    console.log('✓ Logged in, token:', forge.getResolvedEnvironment()['authToken']);
+    
+    // Request 2: Fetch user profile (uses session cookie automatically)
+    const profileReq = {
+        name: 'Get Profile',
+        method: 'GET',
+        url: 'https://api.example.com/users/{{userId}}',
+        headers: {
+            'Authorization': 'Bearer {{authToken}}'  // Uses token from login
+        }
+    };
+    
+    const profileResult = await forge.execute(profileReq, collection);
+    console.log('✓ Profile:', profileResult.response.body);
+    
+    // Request 3: Update profile (session cookie still active)
+    const updateReq = {
+        name: 'Update Profile',
+        method: 'PATCH',
+        url: 'https://api.example.com/users/{{userId}}',
+        headers: {
+            'Authorization': 'Bearer {{authToken}}'
+        },
+        body: { type: 'raw', content: JSON.stringify({ status: 'active' })}
+    };
+    
+    const updateResult = await forge.execute(updateReq, collection);
+    console.log('✓ Updated profile');
+    
+    // Session automatically logged out - cookies cleared
+    forge.getRequestHistory().clear();
+}
+```
+
 ## 📦 Storage Formats
 
 ### File Format (Single JSON)
@@ -489,12 +636,18 @@ MIT © Henry Huang
 
 ### 0.1.0 (Initial Release)
 
-- ✅ Core request execution engine
-- ✅ Environment and variable management
-- ✅ Pre-request and post-response scripts
-- ✅ Cookie jar support
-- ✅ Request/response interceptors
-- ✅ Request history tracking
-- ✅ File and folder collection formats
-- ✅ Full TypeScript support
-- ✅ Comprehensive test coverage
+- ✅ **Core request execution** with Postman collection support
+- ✅ **Dynamic variables** - 7 generators for on-the-fly value generation
+- ✅ **Postman-compatible scripting** - `pm.*` API with full feature parity
+- ✅ **Variable scoping** - globals, collection, environment, session, flow-level
+- ✅ **Cookie persistence** - automatic storage and reuse across request chains
+- ✅ **Pre-request & post-response scripts** with shared VM context
+- ✅ **Test assertions** with BDD-style `pm.test()` and expect chains
+- ✅ **Environment management** with variable substitution
+- ✅ **Cookie jar** with domain-aware matching
+- ✅ **Request/response interceptors** for customization
+- ✅ **Request history** tracking
+- ✅ **File and folder collection formats** (Postman-compatible)
+- ✅ **Full TypeScript support** with comprehensive types
+- ✅ **Dependency injection** for extensibility
+- ✅ **Comprehensive test coverage**

package/dist/auth/interfaces.d.ts

@@ -0,0 +1,63 @@
+/**
+ * OAuth2 Token Manager Interface
+ *
+ * Platform-independent interface for OAuth2 token management.
+ * Handles all grant types: client_credentials, password, authorization_code, implicit.
+ *
+ * VS Code impl: uses vscode.env.openExternal, vscode.SecretStorage
+ * CLI/Standalone impl: uses system browser + local HTTP callback server
+ * Browser impl: uses window.open() + postMessage
+ */
+import { OAuth2Config } from '../types/types';
+export interface TokenInfo {
+    accessToken: string;
+    /** e.g. "Bearer" */
+    tokenType: string;
+    /** Unix timestamp (ms) */
+    expiresAt?: number;
+    refreshToken?: string;
+    scope?: string;
+    /** Original token response */
+    raw: Record<string, unknown>;
+}
+export interface TokenCacheKey {
+    tokenUrl: string;
+    clientId: string;
+    scope?: string;
+    grantType: string;
+}
+export interface IOAuth2TokenManager {
+    /**
+     * Get a valid access token for the given OAuth2 configuration.
+     * May return a cached token, refresh an expired token, or initiate a new flow.
+     */
+    getToken(config: OAuth2Config, environment: string): Promise<TokenInfo>;
+    /**
+     * Refresh an expired token using the refresh token.
+     */
+    refreshToken(config: OAuth2Config, currentRefreshToken: string, environment: string): Promise<TokenInfo>;
+    /**
+     * Initiate the authorization code flow (opens browser, waits for callback).
+     */
+    authorizationCodeFlow(config: OAuth2Config, environment: string): Promise<TokenInfo>;
+    /**
+     * Initiate the implicit flow (opens browser, waits for callback).
+     */
+    implicitFlow(config: OAuth2Config, environment: string): Promise<TokenInfo>;
+    /**
+     * Clear a cached token.
+     */
+    clearToken(cacheKey: TokenCacheKey): void;
+    /**
+     * Clear all cached tokens.
+     */
+    clearAllTokens(): void;
+    /**
+     * Handle authorization code callback (from browser redirect).
+     */
+    handleAuthorizationCallback(code: string | undefined, state: string | undefined, error?: string): void;
+    /**
+     * Handle implicit flow callback (from browser redirect with token in fragment).
+     */
+    handleImplicitCallback(accessToken: string, tokenType: string | undefined, expiresIn: number | undefined, state: string | undefined): void;
+}

package/dist/auth/oauth2-token-manager.d.ts

@@ -0,0 +1,103 @@
+/**
+ * OAuth2 Token Manager
+ *
+ * Platform-independent implementation of OAuth2 token lifecycle management:
+ *  - Token caching with expiration
+ *  - PKCE (S256 / plain) challenge generation
+ *  - Authorization Code flow via system browser + URI handler callback
+ *  - Implicit flow via system browser
+ *  - Client Credentials and Password grant token fetching
+ *  - Token refresh with automatic retry
+ *  - Secure storage for refresh tokens via ISecretStore
+ *
+ * Platform-specific behaviour (browser opening, secret storage, callback URIs)
+ * is injected via IExternalBrowserService and ISecretStore interfaces.
+ */
+import { IEnvironmentConfigService } from '../environment/interfaces';
+import { IHttpRequestService } from '../http/interfaces';
+import { IOAuth2TokenManager, TokenCacheKey, TokenInfo } from './interfaces';
+import { IExternalBrowserService, ISecretStore } from '../types/platform';
+import { OAuth2Config } from '../types/types';
+export declare class OAuth2TokenManager implements IOAuth2TokenManager {
+    private readonly secretStore;
+    private readonly browserService;
+    private readonly envConfigService;
+    private readonly httpService;
+    private readonly callbackPath;
+    private tokenCache;
+    /**
+     * Pending authorization-code resolve/reject.
+     * Set when we launch the browser; resolved when the URI handler fires.
+     */
+    private pendingAuthCallback;
+    /**
+     * Pending implicit-flow resolve/reject.
+     */
+    private pendingImplicitCallback;
+    /**
+     * @param secretStore       Secure storage for refresh tokens (wraps vscode.SecretStorage, keytar, etc.)
+     * @param browserService    External browser interaction (wraps vscode.env.openExternal, etc.)
+     * @param envConfigService  Environment variable resolution
+     * @param httpService       HTTP client for token endpoint calls
+     * @param callbackPath      Platform-specific callback path (e.g. "henry-huang.http-forge/oauth2/callback")
+     */
+    constructor(secretStore: ISecretStore, browserService: IExternalBrowserService, envConfigService: IEnvironmentConfigService, httpService: IHttpRequestService, callbackPath?: string);
+    /**
+     * Get a valid token — uses cache, refresh, or full re-auth as needed.
+     */
+    getToken(config: OAuth2Config, environment: string): Promise<TokenInfo>;
+    /**
+     * Refresh an existing token.
+     */
+    refreshToken(config: OAuth2Config, currentRefreshToken: string, environment: string): Promise<TokenInfo>;
+    /**
+     * Authorization Code + PKCE flow.
+     *
+     * 1. Generate code_verifier & code_challenge (S256)
+     * 2. Open system browser with authorize URL
+     * 3. Wait for URI handler callback with ?code=xxx&state=yyy
+     * 4. Exchange code + code_verifier for token
+     */
+    authorizationCodeFlow(config: OAuth2Config, environment: string): Promise<TokenInfo>;
+    /**
+     * Implicit flow — opens browser, waits for hash fragment with access_token.
+     * Since the URI handler receives query params (not fragments), a small
+     * redirect page is needed to convert fragment → query. We handle both cases.
+     */
+    implicitFlow(config: OAuth2Config, environment: string): Promise<TokenInfo>;
+    /**
+     * Called by the URI handler when browser redirects back.
+     * Handles both authorization_code (?code=) and implicit (?access_token=) callbacks.
+     */
+    handleAuthorizationCallback(code: string | undefined, state: string | undefined, error?: string): void;
+    /**
+     * Handle implicit callback with access_token directly.
+     */
+    handleImplicitCallback(accessToken: string, tokenType: string | undefined, expiresIn: number | undefined, state: string | undefined): void;
+    clearToken(cacheKey: TokenCacheKey): void;
+    clearAllTokens(): void;
+    /**
+     * Fetch token using client_credentials or password grant.
+     */
+    private fetchToken;
+    /**
+     * Apply client authentication to the request (body or Basic Auth header).
+     */
+    private applyClientAuth;
+    /**
+     * Parse token endpoint response body into TokenInfo.
+     */
+    private parseTokenResponse;
+    private isExpired;
+    private buildCacheKeyString;
+    /**
+     * Get the callback URI for OAuth2 redirects.
+     * Uses the browser service to create a valid, externally accessible callback URI.
+     */
+    private getCallbackUri;
+    /** Resolve environment variables in a string */
+    private resolve;
+    private generateCodeVerifier;
+    private generateCodeChallengeS256;
+    private storeRefreshToken;
+}

package/dist/collection/collection-loader-factory.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Collection Loader Factory
+ *
+ * Factory Pattern: Creates appropriate loader based on configuration
+ */
+import { ICollectionStore } from './collection-store';
+import { IConfigService } from '../config';
+/**
+ * Factory for creating collection loaders
+ */
+export declare class CollectionLoaderFactory {
+    /**
+     * Create a collection loader based on configuration
+     */
+    static create(configService: IConfigService): ICollectionStore;
+    /**
+     * Create a loader for a specific format
+     */
+    static createForFormat(format: 'folder' | 'json', collectionsPath: string): ICollectionStore;
+}

package/dist/{services → collection}/collection-loader.d.ts

@@ -4,8 +4,9 @@
  * Single Responsibility: Load collections from file system
  * Dependency Inversion: Uses IFileSystem and ParserRegistry abstractions
  */
-import { ICollectionLoader, IFileSystem } from '../interfaces';
-import { UnifiedCollection } from '../interfaces/types';
+import { IFileSystem } from '../types/platform';
+import { UnifiedCollection } from '../types/types';
+import { ICollectionLoader } from './interfaces';
 import { ParserRegistry } from './parser-registry';
 /**
  * Options for loading a collection
@@ -49,4 +50,3 @@ export declare class CollectionLoader implements ICollectionLoader {
      */
     getSupportedFormats(): string[];
 }
-//# sourceMappingURL=collection-loader.d.ts.map

package/dist/collection/collection-service-interfaces.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Collection Service Interface
+ *
+ * Interface Segregation: Separated into focused sub-interfaces
+ * Dependency Inversion: Consumers depend on this abstraction
+ */
+import { CollectionRequest, KeyValueEntry, RequestAuth, RequestScripts, RequestSettings } from '../types/types';
+export type { CollectionRequest, KeyValueEntry, RequestAuth, RequestScripts, RequestSettings };
+/**
+ * Request item in a collection - CollectionRequest with type discriminator
+ */
+export type CollectionRequestItem = CollectionRequest & {
+    type: 'request';
+};
+/**
+ * Folder item in a collection
+ */
+export interface CollectionFolderItem {
+    type: 'folder';
+    id: string;
+    name: string;
+    description?: string;
+    auth?: RequestAuth;
+    scripts?: RequestScripts;
+    items?: CollectionItem[];
+}
+/**
+ * Collection item - discriminated union of request or folder
+ */
+export type CollectionItem = CollectionRequestItem | CollectionFolderItem;
+/**
+ * Collection definition
+ */
+export interface Collection {
+    id: string;
+    name: string;
+    description?: string;
+    version?: string;
+    variables?: Record<string, string>;
+    auth?: RequestAuth;
+    scripts?: RequestScripts;
+    items: CollectionItem[];
+}
+/**
+ * Options for creating a request in a collection
+ */
+export type CreateRequestOptions = Omit<CollectionRequest, 'id'> & {
+    collectionId: string;
+    parentId?: string;
+    id?: string;
+};
+/**
+ * Options for creating a folder
+ */
+export interface CreateFolderOptions {
+    name: string;
+    collectionId: string;
+    parentId?: string;
+}
+/**
+ * Read-only collection operations
+ */
+export interface ICollectionReader {
+    getAllCollections(): Collection[];
+    getCollection(id: string): Collection | undefined;
+    getCollectionById(id: string): Collection | undefined;
+    getCollectionByName(name: string): Collection | undefined;
+    findRequest(collectionId: string, requestId: string): CollectionRequestItem | undefined;
+    getCollectionVariables(collectionId: string): Record<string, string>;
+}
+/**
+ * Collection modification operations
+ */
+export interface ICollectionWriter {
+    createCollection(name: string): Promise<Collection>;
+    saveCollection(collection: Collection): Promise<void>;
+    deleteCollection(id: string): Promise<boolean>;
+    renameCollection(id: string, newName: string): Promise<boolean>;
+}
+/**
+ * Request management operations
+ */
+export interface IRequestManager {
+    createRequest(options: CreateRequestOptions): Promise<CollectionItem>;
+    updateRequest(collectionId: string, requestId: string, updates: Partial<CollectionItem>): Promise<boolean>;
+    deleteRequest(collectionId: string, requestId: string): Promise<boolean>;
+    renameRequest(collectionId: string, requestId: string, newName: string): Promise<boolean>;
+}
+/**
+ * Folder management operations
+ */
+export interface IFolderManager {
+    createFolder(options: CreateFolderOptions): Promise<CollectionItem>;
+    deleteFolder(collectionId: string, folderId: string): Promise<boolean>;
+    renameFolder(collectionId: string, folderId: string, newName: string): Promise<boolean>;
+}
+/**
+ * Collection variable management
+ */
+export interface ICollectionVariableManager {
+    setCollectionVariable(collectionId: string, key: string, value: unknown): void;
+    deleteCollectionVariable(collectionId: string, key: string): void;
+    clearCollectionVariables(collectionId: string): void;
+    getCollectionVariableLocals(collectionId: string): Record<string, string>;
+}
+/**
+ * Collection import/export operations
+ */
+export interface ICollectionImportExport {
+    importCollection(filePath: string): Promise<Collection>;
+    exportCollection(id: string, filePath: string): Promise<void>;
+    exportCollectionAsRestClientFolder(id: string, outDir: string): Promise<void>;
+}
+/**
+ * Full collection service interface
+ */
+export interface ICollectionService extends ICollectionReader, ICollectionWriter, IRequestManager, IFolderManager, ICollectionVariableManager, ICollectionImportExport {
+    dispose(): void;
+}