@qaick/http-executor 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,38 @@
+# `@qaick/http-executor`
+
+Reusable QAick HTTP Action execution for browser, Desktop, Server and CLI/CI hosts.
+
+The package keeps HTTP Action semantics behind QAick Executor's generic Action Executor boundary. Choose the transport at the host boundary:
+
+```ts
+import { createExecutor } from '@qaick/executor';
+import { HttpActionExecutor } from '@qaick/http-executor';
+import { NodeHttpTransport } from '@qaick/http-executor/node';
+
+const executor = createExecutor({
+  actionExecutors: [new HttpActionExecutor(new NodeHttpTransport())],
+});
+```
+
+`NodeHttpTransport` uses Node's standard `http` and `https` modules. It is the unrestricted host transport and does not apply browser CORS or preflight rules. `FetchHttpTransport` is available for browser environments and reports browser network and CORS failures through the HTTP error boundary.
+
+The transport is injected into `HttpActionExecutor`, so host code can provide a deterministic fake transport for tests or another transport implementation without changing HTTP Action request construction, response parsing, extraction, timing, or failure classification.
+
+The package requires Node 20 or newer for native Node transport support. `@qaick/executor` is a peer dependency and must be registered by the host application.
+
+## Public exports
+
+- `HttpActionExecutor`
+- `HttpActionError` and `HttpActionErrorCode`
+- `HttpTransport` and `HttpResponse`
+- `FetchHttpTransport`
+- `NodeHttpTransport`
+
+## Development
+
+```sh
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```

package/dist/http-action-executor.d.ts

@@ -0,0 +1,36 @@
+import type { ActionExecutionContext, ActionExecutionResult, ActionExecutor } from '@qaick/executor';
+export interface HttpResponse {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+}
+export interface HttpTransport {
+    request(url: string, init: {
+        method: string;
+        body?: unknown;
+        headers?: Record<string, string>;
+        signal: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<HttpResponse>;
+}
+export type HttpActionErrorCode = 'HTTP_INVALID_URL' | 'HTTP_REQUEST_CONSTRUCTION_ERROR' | 'HTTP_ABORTED' | 'HTTP_TIMEOUT' | 'HTTP_NETWORK_ERROR' | 'HTTP_RESPONSE_PARSE_ERROR' | 'HTTP_STATUS_ERROR';
+export declare class HttpActionError extends Error {
+    readonly code: HttpActionErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: HttpActionErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+export declare class FetchHttpTransport implements HttpTransport {
+    request(url: string, init: {
+        method: string;
+        body?: unknown;
+        headers?: Record<string, string>;
+        signal: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<HttpResponse>;
+}
+export declare class HttpActionExecutor implements ActionExecutor {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    supports(action: string): boolean;
+    execute(context: ActionExecutionContext): Promise<ActionExecutionResult>;
+}

package/dist/http-action-executor.js

@@ -0,0 +1,146 @@
+export class HttpActionError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'HttpActionError';
+    }
+}
+export class FetchHttpTransport {
+    async request(url, init) {
+        const headers = { ...init.headers };
+        let body;
+        if (init.body !== undefined && init.body !== null) {
+            body = typeof init.body === 'string' ? init.body : JSON.stringify(init.body);
+            if (!Object.keys(headers).some(name => name.toLowerCase() === 'content-type'))
+                headers['content-type'] = 'application/json';
+        }
+        if (!/^https?:\/\//i.test(url))
+            throw new HttpActionError('HTTP_INVALID_URL', `HTTP Action URL is invalid: ${url || '(empty URL)'}.`);
+        const controller = new AbortController();
+        const abortFromCaller = () => controller.abort();
+        init.signal.addEventListener('abort', abortFromCaller, { once: true });
+        const timeout = init.timeoutMs === undefined ? undefined : setTimeout(() => controller.abort(), init.timeoutMs);
+        let response;
+        try {
+            response = await fetch(url, { method: init.method, headers, body, signal: controller.signal });
+        }
+        catch (error) {
+            if (init.signal.aborted)
+                throw new HttpActionError('HTTP_ABORTED', 'HTTP Action was cancelled before a response was received.');
+            if (controller.signal.aborted && init.timeoutMs !== undefined)
+                throw new HttpActionError('HTTP_TIMEOUT', `HTTP Action exceeded its ${init.timeoutMs}ms timeout.`);
+            const detail = error instanceof Error ? error.message : 'The browser could not reach the target.';
+            throw new HttpActionError('HTTP_NETWORK_ERROR', `HTTP Action could not reach ${url}. This may be a network or browser CORS failure. ${detail}`);
+        }
+        finally {
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            init.signal.removeEventListener('abort', abortFromCaller);
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        let responseBody;
+        try {
+            responseBody = contentType.includes('application/json') ? await response.json() : await response.text();
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : 'The response body could not be read.';
+            throw new HttpActionError('HTTP_RESPONSE_PARSE_ERROR', `HTTP Action received status ${response.status}, but the response body could not be parsed. ${detail}`);
+        }
+        return { status: response.status, body: responseBody, headers: Object.fromEntries(response.headers.entries()) };
+    }
+}
+export class HttpActionExecutor {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    supports(action) { return action.startsWith('http.'); }
+    async execute(context) {
+        const startedAt = new Date().toISOString();
+        const startedMs = Date.now();
+        let request;
+        try {
+            const url = substituteTemplate(String(context.inputs.url ?? ''), context.inputs);
+            request = {
+                url: appendQuery(url, substituteTemplateValue(context.inputs.query, context.inputs)),
+                method: substituteTemplate(String(context.inputs.method ?? 'GET'), context.inputs),
+                ...(context.inputs.body !== undefined ? { body: substituteTemplateValue(context.inputs.body, context.inputs) } : {}),
+                ...(isRecord(context.inputs.headers) ? { headers: Object.fromEntries(Object.entries(substituteTemplateValue(context.inputs.headers, context.inputs)).map(([name, value]) => [name, String(value)])) } : {}),
+            };
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : 'The request template could not be resolved.';
+            throw new HttpActionError('HTTP_REQUEST_CONSTRUCTION_ERROR', `HTTP Action request could not be constructed. ${detail}`);
+        }
+        const timeoutMs = typeof context.step.adapterConfig?.timeoutMs === 'number' ? context.step.adapterConfig.timeoutMs : undefined;
+        const response = await this.transport.request(request.url, { ...request, signal: context.signal, ...(timeoutMs !== undefined ? { timeoutMs } : {}) });
+        if (response.status < 200 || response.status >= 300) {
+            const serializedBody = typeof response.body === 'string' ? response.body : JSON.stringify(response.body) ?? '';
+            throw new HttpActionError('HTTP_STATUS_ERROR', `HTTP Action returned status ${response.status}.${serializedBody ? ` Response: ${serializedBody.slice(0, 500)}` : ''}`, { status: response.status });
+        }
+        const outputs = { status: response.status, body: response.body, ...(response.headers ? { headers: response.headers } : {}) };
+        const responseFields = isRecord(context.step.adapterConfig?.responseFields) ? context.step.adapterConfig.responseFields : undefined;
+        if (responseFields)
+            for (const [name, path] of Object.entries(responseFields))
+                if (typeof path === 'string')
+                    outputs[name] = readJsonPath(response.body, path);
+        if (typeof context.step.adapterConfig?.responseBodyName === 'string')
+            outputs[context.step.adapterConfig.responseBodyName] = response.body;
+        const finishedAt = new Date().toISOString();
+        return { outputs, evidence: { request: { url: request.url, method: request.method, headers: request.headers }, response: { status: response.status, headers: response.headers, body: response.body } }, timing: { startedAt, finishedAt, durationMs: Date.now() - startedMs } };
+    }
+}
+function appendQuery(url, query) {
+    if (query === undefined || query === null)
+        return url;
+    if (!isRecord(query))
+        throw new Error('Query parameters must be an object.');
+    const parsed = new URL(url);
+    for (const [name, value] of Object.entries(query))
+        for (const item of (Array.isArray(value) ? value : [value])) {
+            if (item !== undefined && item !== null)
+                parsed.searchParams.append(name, typeof item === 'object' ? JSON.stringify(item) : String(item));
+        }
+    return parsed.toString();
+}
+function substituteTemplateValue(value, inputs) {
+    if (typeof value === 'string')
+        return substituteTemplate(value, inputs);
+    if (Array.isArray(value))
+        return value.map(item => substituteTemplateValue(item, inputs));
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteTemplateValue(item, inputs)]));
+    return value;
+}
+function substituteTemplate(value, inputs) {
+    const exact = /^\s*\{\{\s*(?:\$?(?:inputs\.)?)?([^{}]+?)\s*\}\}\s*$/.exec(value);
+    if (exact)
+        return stringifyTemplateValue(resolveTemplateValue(exact[1], inputs));
+    return value.replace(/\{\{\s*(?:\$?(?:inputs\.)?)?([^{}]+?)\s*\}\}/g, (_match, path) => stringifyTemplateValue(resolveTemplateValue(path, inputs)));
+}
+function resolveTemplateValue(path, inputs) {
+    const normalized = path.trim().replace(/^\$?(?:inputs\.)?/, '');
+    const value = normalized.split('.').reduce((current, segment) => isRecord(current) ? current[segment] : undefined, inputs);
+    if (value === undefined)
+        throw new Error(`Template value '${path.trim()}' is missing.`);
+    return value;
+}
+function stringifyTemplateValue(value) { return typeof value === 'string' ? value : value === undefined ? '' : JSON.stringify(value) ?? String(value); }
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+function readJsonPath(value, path) {
+    if (path === '$' || path === '')
+        return value;
+    if (!path.startsWith('$.'))
+        return undefined;
+    return path.slice(2).split('.').reduce((current, segment) => {
+        if (current === null || current === undefined)
+            return undefined;
+        const match = /^(.*)\[(\d+)\]$/.exec(segment);
+        if (match)
+            return Array.isArray(isRecord(current) ? current[match[1]] : current) ? (isRecord(current) ? current[match[1]] : current)[Number(match[2])] : undefined;
+        return isRecord(current) ? current[segment] : undefined;
+    }, value);
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './http-action-executor.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './http-action-executor.js';

package/dist/node-http-transport.d.ts

@@ -0,0 +1,10 @@
+import type { HttpResponse, HttpTransport } from './http-action-executor.js';
+export declare class NodeHttpTransport implements HttpTransport {
+    request(url: string, init: {
+        method: string;
+        body?: unknown;
+        headers?: Record<string, string>;
+        signal: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<HttpResponse>;
+}

package/dist/node-http-transport.js

@@ -0,0 +1,84 @@
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { FetchHttpTransport, HttpActionError } from './http-action-executor.js';
+export class NodeHttpTransport {
+    request(url, init) {
+        if (!/^https?:\/\//i.test(url))
+            throw new HttpActionError('HTTP_INVALID_URL', `HTTP Action URL is invalid: ${url || '(empty URL)'}.`);
+        if (init.signal.aborted)
+            return Promise.reject(new HttpActionError('HTTP_ABORTED', 'HTTP Action was cancelled before a response was received.'));
+        const parsed = new URL(url);
+        const headers = { ...init.headers };
+        let body;
+        if (init.body !== undefined && init.body !== null) {
+            body = typeof init.body === 'string' ? init.body : JSON.stringify(init.body);
+            if (!Object.keys(headers).some(name => name.toLowerCase() === 'content-type'))
+                headers['content-type'] = 'application/json';
+            if (!Object.keys(headers).some(name => name.toLowerCase() === 'content-length'))
+                headers['content-length'] = String(Buffer.byteLength(body));
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timedOut = false;
+            let timeout;
+            let request;
+            const finish = (error, response) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                init.signal.removeEventListener('abort', abort);
+                if (error)
+                    reject(error);
+                else
+                    resolve(response);
+            };
+            const abort = () => {
+                request.destroy();
+                finish(new HttpActionError('HTTP_ABORTED', 'HTTP Action was cancelled before a response was received.'));
+            };
+            const transport = parsed.protocol === 'https:' ? https : http;
+            request = transport.request({ protocol: parsed.protocol, hostname: parsed.hostname, port: parsed.port || undefined, path: `${parsed.pathname}${parsed.search}`, method: init.method, headers }, response => {
+                const chunks = [];
+                response.on('data', chunk => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+                response.on('end', () => {
+                    const rawBody = Buffer.concat(chunks).toString('utf8');
+                    const contentType = headerValue(response.headers, 'content-type');
+                    let responseBody = rawBody;
+                    try {
+                        if (contentType.includes('application/json'))
+                            responseBody = JSON.parse(rawBody);
+                    }
+                    catch (error) {
+                        const detail = error instanceof Error ? error.message : 'The response body could not be parsed.';
+                        finish(new HttpActionError('HTTP_RESPONSE_PARSE_ERROR', `HTTP Action received status ${response.statusCode ?? 0}, but the response body could not be parsed. ${detail}`));
+                        return;
+                    }
+                    finish(undefined, { status: response.statusCode ?? 0, body: responseBody, headers: normalizeHeaders(response.headers) });
+                });
+                response.on('error', error => finish(new HttpActionError('HTTP_NETWORK_ERROR', `HTTP Action could not read the response from ${url}. ${error.message}`)));
+            });
+            request.on('error', error => {
+                if (timedOut)
+                    finish(new HttpActionError('HTTP_TIMEOUT', `HTTP Action exceeded its ${init.timeoutMs}ms timeout.`));
+                else if (!settled && !init.signal.aborted)
+                    finish(new HttpActionError('HTTP_NETWORK_ERROR', `HTTP Action could not reach ${url}. ${error.message}`));
+            });
+            init.signal.addEventListener('abort', abort, { once: true });
+            if (init.timeoutMs !== undefined) {
+                timeout = setTimeout(() => { timedOut = true; request.destroy(); finish(new HttpActionError('HTTP_TIMEOUT', `HTTP Action exceeded its ${init.timeoutMs}ms timeout.`)); }, init.timeoutMs);
+            }
+            if (body !== undefined)
+                request.write(body);
+            request.end();
+        });
+    }
+}
+function normalizeHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, Array.isArray(value) ? value.join(', ') : value ?? '']));
+}
+function headerValue(headers, name) {
+    const value = headers[name];
+    return Array.isArray(value) ? value.join(', ') : value ?? '';
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@qaick/http-executor",
+  "version": "0.1.0-alpha.1",
+  "description": "Reusable QAick HTTP Action execution with browser and native Node transports.",
+  "keywords": ["qaick", "http", "executor", "automation"],
+  "type": "module",
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public", "tag": "alpha" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./node": { "types": "./dist/node-http-transport.d.ts", "import": "./dist/node-http-transport.js" }
+  },
+  "scripts": { "build": "tsc -p tsconfig.json", "typecheck": "tsc -p tsconfig.json --noEmit", "test": "vitest run", "prepublishOnly": "npm run build" },
+  "peerDependencies": { "@qaick/executor": ">=0.1.0-alpha.1 <0.2.0" },
+  "devDependencies": { "@qaick/executor": "file:../QAICK_Executor", "@types/node": "^24.13.3", "typescript": "~6.0.2", "vitest": "^5.0.1" }
+}