@elyracode/http-tools 0.4.6

package/README.md

@@ -0,0 +1,57 @@
+# @elyracode/http-tools
+
+HTTP tools for Elyra -- API testing, live documentation fetching, and OpenAPI spec parsing.
+
+## Install
+
+```
+elyra install npm:@elyracode/http-tools
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `execute_http_request` | Send HTTP requests (GET, POST, PUT, PATCH, DELETE) with headers, body, and auth. Returns status, headers, and body. |
+| `read_url_content` | Fetch a URL and convert HTML to readable text. Perfect for reading live documentation. |
+| `inspect_openapi` | Fetch and parse OpenAPI/Swagger specs. Returns structured endpoint summaries. |
+
+## Commands
+
+- `/http` -- Interactive selector for all HTTP tools
+
+## Usage
+
+### API Testing
+```
+> Test POST localhost:8000/api/login with email and password
+> Send a GET to /api/users with Bearer token authentication
+> Test all CRUD endpoints for the products API
+```
+
+The agent sends the request, reads the response, and if something fails, it can check your logs and fix the code.
+
+### Live Documentation
+```
+> Read the Laravel Reverb docs and show me how to set it up
+> Fetch the latest React 19 changelog
+> What's new in Tailwind CSS 4?
+```
+
+The agent fetches live documentation, so it always has current information -- even for features released after its training cutoff.
+
+### OpenAPI / Swagger
+```
+> Parse this OpenAPI spec and generate a PHP client with Guzzle
+> Show me all user-related endpoints from the GitHub API
+> Build TypeScript types from this Swagger spec
+```
+
+The agent reads the entire API definition and generates integration code based on the actual schema.
+
+## Security
+
+- Requests include a `User-Agent: elyra-http-tools` header
+- 30-second timeout by default (configurable)
+- Large responses are truncated at 50KB (HTTP) or 80KB (URL content)
+- No credentials are stored -- auth headers are passed per-request

package/extensions/index.ts

@@ -0,0 +1,395 @@
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+
+export default function (elyra: ExtensionAPI): void {
+
+	// ── Tool 1: execute_http_request ──
+	// "Intelligent Postman" -- send HTTP requests and analyze responses
+	elyra.registerTool({
+		name: "execute_http_request",
+		label: "Execute HTTP Request",
+		description:
+			"Send an HTTP request to any URL and return the response. " +
+			"Use this to test API endpoints, verify responses, debug issues. " +
+			"Supports GET, POST, PUT, PATCH, DELETE with headers, body, and auth. " +
+			"Returns status code, headers, and body. Useful for testing local APIs (localhost).",
+		parameters: Type.Object({
+			url: Type.String({ description: "The URL to request (e.g., http://localhost:8000/api/users)" }),
+			method: Type.Optional(
+				Type.Union(
+					[Type.Literal("GET"), Type.Literal("POST"), Type.Literal("PUT"), Type.Literal("PATCH"), Type.Literal("DELETE"), Type.Literal("HEAD"), Type.Literal("OPTIONS")],
+					{ description: "HTTP method (default: GET)" },
+				),
+			),
+			headers: Type.Optional(
+				Type.Record(Type.String(), Type.String(), {
+					description: "Request headers (e.g., { \"Authorization\": \"Bearer token\", \"Content-Type\": \"application/json\" })",
+				}),
+			),
+			body: Type.Optional(
+				Type.String({ description: "Request body (JSON string for POST/PUT/PATCH)" }),
+			),
+			timeout: Type.Optional(
+				Type.Number({ description: "Timeout in milliseconds (default: 30000)" }),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			try {
+				const method = params.method ?? "GET";
+				const headers: Record<string, string> = {
+					"User-Agent": "elyra-http-tools",
+					...params.headers,
+				};
+
+				// Auto-set Content-Type for body requests if not specified
+				if (params.body && !headers["Content-Type"] && !headers["content-type"]) {
+					headers["Content-Type"] = "application/json";
+				}
+
+				const response = await fetch(params.url, {
+					method,
+					headers,
+					body: params.body ?? undefined,
+					signal: AbortSignal.timeout(params.timeout ?? 30000),
+				});
+
+				const responseHeaders: Record<string, string> = {};
+				response.headers.forEach((value, key) => {
+					responseHeaders[key] = value;
+				});
+
+				const contentType = response.headers.get("content-type") ?? "";
+				let body: string;
+
+				if (contentType.includes("application/json")) {
+					const json = await response.json();
+					body = JSON.stringify(json, null, 2);
+				} else {
+					body = await response.text();
+				}
+
+				// Truncate large responses
+				const truncated = body.length > 50000
+					? `${body.slice(0, 50000)}\n\n... (truncated, ${body.length} chars total)`
+					: body;
+
+				const lines: string[] = [
+					`${method} ${params.url}`,
+					`Status: ${response.status} ${response.statusText}`,
+					"",
+					"Response Headers:",
+					...Object.entries(responseHeaders).map(([k, v]) => `  ${k}: ${v}`),
+					"",
+					"Body:",
+					truncated,
+				];
+
+				return {
+					content: [{ type: "text", text: lines.join("\n") }],
+					details: {
+						status: response.status,
+						statusText: response.statusText,
+						contentType,
+					},
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `HTTP request failed: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Tool 2: read_url_content ──
+	// Fetch a URL and convert to readable text (strips HTML tags)
+	elyra.registerTool({
+		name: "read_url_content",
+		label: "Read URL Content",
+		description:
+			"Fetch a web page or documentation URL and return its text content. " +
+			"HTML is stripped to readable text. Use this to read live documentation, " +
+			"blog posts, changelogs, or any web content that may be newer than your training data. " +
+			"Especially useful for reading framework docs (Laravel, React, etc.) to get up-to-date information.",
+		parameters: Type.Object({
+			url: Type.String({ description: "The URL to fetch (e.g., https://laravel.com/docs/13.x/reverb)" }),
+			selector: Type.Optional(
+				Type.String({
+					description: "CSS-like content hint: 'main', 'article', 'body'. Used to focus on main content and skip navigation/footer (default: auto-detect)",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			try {
+				const response = await fetch(params.url, {
+					headers: {
+						"User-Agent": "elyra-http-tools (documentation reader)",
+						Accept: "text/html, text/plain, application/json, text/markdown",
+					},
+					signal: AbortSignal.timeout(30000),
+				});
+
+				if (!response.ok) {
+					return {
+						content: [{ type: "text", text: `Failed to fetch ${params.url}: ${response.status} ${response.statusText}` }],
+						details: {},
+					};
+				}
+
+				const contentType = response.headers.get("content-type") ?? "";
+				let text: string;
+
+				if (contentType.includes("application/json")) {
+					const json = await response.json();
+					text = JSON.stringify(json, null, 2);
+				} else {
+					const html = await response.text();
+					if (contentType.includes("text/html")) {
+						text = htmlToText(html, params.selector);
+					} else {
+						text = html;
+					}
+				}
+
+				// Truncate
+				const truncated = text.length > 80000
+					? `${text.slice(0, 80000)}\n\n... (truncated, ${text.length} chars total)`
+					: text;
+
+				return {
+					content: [{ type: "text", text: `# Content from ${params.url}\n\n${truncated}` }],
+					details: { url: params.url, length: text.length },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Failed to read ${params.url}: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Tool 3: inspect_openapi ──
+	// Fetch and parse an OpenAPI/Swagger spec
+	elyra.registerTool({
+		name: "inspect_openapi",
+		label: "Inspect OpenAPI Spec",
+		description:
+			"Fetch an OpenAPI/Swagger specification from a URL and return a structured summary " +
+			"of all endpoints, methods, parameters, request bodies, and response schemas. " +
+			"Use this when the user wants to build an API client, generate SDK code, " +
+			"or understand a third-party API structure.",
+		parameters: Type.Object({
+			url: Type.String({
+				description: "URL to the OpenAPI/Swagger JSON or YAML spec (e.g., https://petstore.swagger.io/v2/swagger.json)",
+			}),
+			filter: Type.Optional(
+				Type.String({
+					description: "Filter endpoints by path prefix (e.g., '/users', '/orders'). Omit for all endpoints.",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			try {
+				const response = await fetch(params.url, {
+					headers: {
+						"User-Agent": "elyra-http-tools",
+						Accept: "application/json, application/yaml, text/yaml",
+					},
+					signal: AbortSignal.timeout(30000),
+				});
+
+				if (!response.ok) {
+					return {
+						content: [{ type: "text", text: `Failed to fetch spec: ${response.status} ${response.statusText}` }],
+						details: {},
+					};
+				}
+
+				const spec = await response.json() as Record<string, unknown>;
+				const info = spec.info as Record<string, unknown> | undefined;
+				const paths = spec.paths as Record<string, Record<string, unknown>> | undefined;
+
+				if (!paths) {
+					return {
+						content: [{ type: "text", text: "Invalid OpenAPI spec: no 'paths' found." }],
+						details: {},
+					};
+				}
+
+				const lines: string[] = [
+					`# OpenAPI: ${(info?.title as string) ?? "Unknown API"}`,
+					`Version: ${(info?.version as string) ?? "unknown"}`,
+					`Description: ${(info?.description as string) ?? "none"}`,
+					`Base URL: ${extractBaseUrl(spec)}`,
+					"",
+				];
+
+				let endpointCount = 0;
+				for (const [path, methods] of Object.entries(paths)) {
+					if (params.filter && !path.startsWith(params.filter)) continue;
+
+					for (const [method, details] of Object.entries(methods)) {
+						if (method.startsWith("x-") || typeof details !== "object" || !details) continue;
+						const op = details as Record<string, unknown>;
+						endpointCount++;
+						const summary = (op.summary as string) ?? "";
+						const operationId = (op.operationId as string) ?? "";
+						lines.push(`## ${method.toUpperCase()} ${path}`);
+						if (summary) lines.push(`Summary: ${summary}`);
+						if (operationId) lines.push(`Operation: ${operationId}`);
+
+						// Parameters
+						const parameters = op.parameters as Array<Record<string, unknown>> | undefined;
+						if (parameters && parameters.length > 0) {
+							lines.push("Parameters:");
+							for (const param of parameters) {
+								const required = param.required ? " (required)" : "";
+								lines.push(`  - ${param.name} [${param.in}]: ${param.description ?? (param.schema as Record<string, unknown>)?.type ?? "unknown"}${required}`);
+							}
+						}
+
+						// Request body
+						const requestBody = op.requestBody as Record<string, unknown> | undefined;
+						if (requestBody) {
+							const content = requestBody.content as Record<string, Record<string, unknown>> | undefined;
+							if (content) {
+								const jsonSchema = content["application/json"]?.schema;
+								if (jsonSchema) {
+									lines.push(`Request Body: ${JSON.stringify(jsonSchema, null, 2).slice(0, 500)}`);
+								}
+							}
+						}
+
+						// Response codes
+						const responses = op.responses as Record<string, Record<string, unknown>> | undefined;
+						if (responses) {
+							const codes = Object.keys(responses).join(", ");
+							lines.push(`Responses: ${codes}`);
+						}
+
+						lines.push("");
+					}
+				}
+
+				lines.unshift(`Endpoints: ${endpointCount}${params.filter ? ` (filtered by ${params.filter})` : ""}`);
+
+				const text = lines.join("\n");
+				const truncated = text.length > 80000
+					? `${text.slice(0, 80000)}\n\n... (truncated)`
+					: text;
+
+				return {
+					content: [{ type: "text", text: truncated }],
+					details: { endpointCount, title: info?.title },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Failed to parse OpenAPI spec: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Command: /http ──
+	elyra.registerCommand("http", {
+		description: "HTTP tools: test APIs, fetch docs, parse OpenAPI specs",
+		handler: async (_args: string, ctx) => {
+			const options = [
+				"Test API -- send an HTTP request to test an endpoint",
+				"Read URL -- fetch web content or documentation",
+				"OpenAPI -- parse a Swagger/OpenAPI spec",
+			];
+
+			const selected = await ctx.ui.select("HTTP Tools", options);
+			if (!selected) return;
+
+			if (selected.startsWith("Test API")) {
+				elyra.sendUserMessage("I want to test an API endpoint. Ask me for the URL, method, and any headers or body to send.");
+			} else if (selected.startsWith("Read URL")) {
+				elyra.sendUserMessage("I want to read content from a URL. Ask me which URL to fetch.");
+			} else if (selected.startsWith("OpenAPI")) {
+				elyra.sendUserMessage("I want to parse an OpenAPI spec. Ask me for the URL to the spec.");
+			}
+		},
+	});
+}
+
+/**
+ * Strip HTML tags and extract readable text content.
+ * Simple but effective for documentation pages.
+ */
+function htmlToText(html: string, selectorHint?: string): string {
+	let content = html;
+
+	// Try to extract main content area
+	if (selectorHint) {
+		const tagMatch = content.match(new RegExp(`<${selectorHint}[^>]*>([\\s\\S]*?)<\\/${selectorHint}>`, "i"));
+		if (tagMatch) content = tagMatch[1];
+	} else {
+		// Auto-detect: prefer <main>, then <article>, then <body>
+		for (const tag of ["main", "article"]) {
+			const match = content.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`, "i"));
+			if (match) {
+				content = match[1];
+				break;
+			}
+		}
+	}
+
+	// Remove script and style blocks
+	content = content.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "");
+	content = content.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "");
+	content = content.replace(/<nav[^>]*>[\s\S]*?<\/nav>/gi, "");
+	content = content.replace(/<footer[^>]*>[\s\S]*?<\/footer>/gi, "");
+	content = content.replace(/<header[^>]*>[\s\S]*?<\/header>/gi, "");
+
+	// Convert common elements to text
+	content = content.replace(/<h[1-6][^>]*>([\s\S]*?)<\/h[1-6]>/gi, "\n## $1\n");
+	content = content.replace(/<p[^>]*>([\s\S]*?)<\/p>/gi, "\n$1\n");
+	content = content.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, "- $1\n");
+	content = content.replace(/<br\s*\/?>/gi, "\n");
+	content = content.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, "\n```\n$1\n```\n");
+	content = content.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, "`$1`");
+	content = content.replace(/<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, "$2 ($1)");
+	content = content.replace(/<strong[^>]*>([\s\S]*?)<\/strong>/gi, "**$1**");
+	content = content.replace(/<em[^>]*>([\s\S]*?)<\/em>/gi, "*$1*");
+
+	// Strip remaining HTML tags
+	content = content.replace(/<[^>]+>/g, "");
+
+	// Clean up HTML entities
+	content = content.replace(/&amp;/g, "&");
+	content = content.replace(/&lt;/g, "<");
+	content = content.replace(/&gt;/g, ">");
+	content = content.replace(/&quot;/g, '"');
+	content = content.replace(/&#39;/g, "'");
+	content = content.replace(/&nbsp;/g, " ");
+
+	// Clean up whitespace
+	content = content.replace(/\n{3,}/g, "\n\n");
+	content = content.trim();
+
+	return content;
+}
+
+function extractBaseUrl(spec: Record<string, unknown>): string {
+	// OpenAPI 3.x
+	const servers = spec.servers as Array<Record<string, unknown>> | undefined;
+	if (servers && servers.length > 0) {
+		return (servers[0].url as string) ?? "";
+	}
+	// Swagger 2.x
+	const host = spec.host as string | undefined;
+	const basePath = spec.basePath as string | undefined;
+	const schemes = spec.schemes as string[] | undefined;
+	if (host) {
+		const scheme = schemes?.[0] ?? "https";
+		return `${scheme}://${host}${basePath ?? ""}`;
+	}
+	return "";
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@elyracode/http-tools",
+  "version": "0.4.6",
+  "description": "Elyra extension for HTTP requests -- API testing, live docs fetching, and OpenAPI parsing",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "http",
+    "api-testing",
+    "openapi",
+    "swagger",
+    "fetch"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/http-tools"
+  },
+  "elyra": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}