@opengeni/capabilities 0.1.1

package/src/http.ts

@@ -0,0 +1,131 @@
+import { pinnedFetch, readResponseBodyBounded, type FetchLike } from "@opengeni/network";
+
+import type { IntegrationTransport, PinnedIntegrationTransportOptions } from "./types";
+import { IntegrationInvocationError } from "./types";
+
+export const DEFAULT_INTEGRATION_TIMEOUT_MS = 30_000;
+export const DEFAULT_INTEGRATION_RESPONSE_BYTES = 4 * 1024 * 1024;
+export const MAX_INTEGRATION_SPEC_BYTES = 8 * 1024 * 1024;
+export const MAX_INTEGRATION_TOOLS = 2_000;
+
+export async function fetchIntegrationSourceDocument(
+  transport: IntegrationTransport,
+  sourceUrl: string,
+  maxBytes = MAX_INTEGRATION_SPEC_BYTES,
+): Promise<Uint8Array> {
+  const url = new URL(sourceUrl);
+  const response = await fetchWithDeadline(
+    transport,
+    url,
+    {
+      method: "GET",
+      headers: { accept: "application/json, application/yaml, text/yaml, */*;q=0.5" },
+    },
+    DEFAULT_INTEGRATION_TIMEOUT_MS,
+  );
+  if (response.status >= 300 && response.status < 400) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new IntegrationInvocationError(
+      "source_redirect_rejected",
+      "Integration source attempted to redirect",
+      "failed",
+      false,
+      response.status,
+    );
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined);
+    throw new IntegrationInvocationError(
+      "source_fetch_rejected",
+      "Integration source could not be read",
+      "failed",
+      response.status >= 500,
+      response.status,
+    );
+  }
+  return await readResponseBodyBounded(response, maxBytes, "Integration source");
+}
+
+export function createPinnedIntegrationTransport(
+  options: PinnedIntegrationTransportOptions,
+): IntegrationTransport {
+  return {
+    fetch: (input, init) =>
+      pinnedFetch(input, init, options.network, {
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        label: "Integration request",
+        requireHttpsOutsideLocalTest: true,
+      }),
+  };
+}
+
+export function directIntegrationTransport(fetchImpl: FetchLike): IntegrationTransport {
+  return { fetch: fetchImpl };
+}
+
+export async function fetchWithDeadline(
+  transport: IntegrationTransport,
+  url: URL,
+  init: RequestInit,
+  timeoutMs = DEFAULT_INTEGRATION_TIMEOUT_MS,
+): Promise<Response> {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000) {
+    throw new RangeError("integration timeout must be between 1 and 120000 milliseconds");
+  }
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(init.signal?.reason);
+  if (init.signal?.aborted) onAbort();
+  else init.signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(
+    () => controller.abort(new Error("integration request timed out")),
+    timeoutMs,
+  );
+  try {
+    return await transport.fetch(url, {
+      ...init,
+      signal: controller.signal,
+      redirect: "manual",
+    });
+  } catch {
+    const timedOut = controller.signal.aborted && !init.signal?.aborted;
+    throw new IntegrationInvocationError(
+      timedOut ? "request_timeout" : "request_failed",
+      timedOut ? "Integration request timed out" : "Integration request failed",
+      requestCouldHaveStarted(init.method) ? "unknown" : "not_started",
+      !requestCouldHaveStarted(init.method),
+    );
+  } finally {
+    clearTimeout(timer);
+    init.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+function requestCouldHaveStarted(method: string | undefined): boolean {
+  const normalized = (method ?? "GET").toUpperCase();
+  return normalized !== "GET" && normalized !== "HEAD" && normalized !== "OPTIONS";
+}
+
+export async function readIntegrationResponse(
+  response: Response,
+  maxBytes = DEFAULT_INTEGRATION_RESPONSE_BYTES,
+): Promise<{ data: unknown; contentType: string; bytes: number }> {
+  const body = await readResponseBodyBounded(response, maxBytes, "Integration response");
+  const contentType =
+    response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+  if (body.byteLength === 0) return { data: null, contentType, bytes: 0 };
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(body);
+  if (contentType === "application/json" || contentType.endsWith("+json")) {
+    try {
+      return { data: JSON.parse(text), contentType, bytes: body.byteLength };
+    } catch {
+      throw new IntegrationInvocationError(
+        "response_json_invalid",
+        "Integration returned invalid JSON",
+        "failed",
+        false,
+        response.status,
+      );
+    }
+  }
+  return { data: text, contentType, bytes: body.byteLength };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./auth";
+export * from "./graphql";
+export * from "./http";
+export * from "./mcp-manifest";
+export * from "./openapi";
+export * from "./providers";
+export * from "./revision";
+export * from "./types";

package/src/mcp-manifest.ts

@@ -0,0 +1,90 @@
+import { stableToolId } from "./revision";
+
+export interface McpToolManifestEntry {
+  readonly toolId: string;
+  readonly toolName: string;
+  readonly description: string | null;
+  readonly inputSchema?: unknown;
+  readonly outputSchema?: unknown;
+  readonly annotations?: Readonly<Record<string, unknown>>;
+}
+
+export interface McpToolManifest {
+  readonly server: {
+    readonly name: string | null;
+    readonly version: string | null;
+    readonly instructions: string | null;
+  } | null;
+  readonly tools: readonly McpToolManifestEntry[];
+}
+
+export function extractMcpToolManifest(
+  listToolsResult: unknown,
+  metadata: {
+    readonly serverInfo?: unknown;
+    readonly instructions?: string;
+  } = {},
+): McpToolManifest {
+  const listed =
+    listToolsResult &&
+    typeof listToolsResult === "object" &&
+    Array.isArray((listToolsResult as { tools?: unknown }).tools)
+      ? (listToolsResult as { tools: unknown[] }).tools
+      : [];
+  const seen = new Map<string, number>();
+  const tools = listed.flatMap((value): McpToolManifestEntry[] => {
+    if (!value || typeof value !== "object") return [];
+    const tool = value as Record<string, unknown>;
+    if (typeof tool.name !== "string" || !tool.name.trim()) return [];
+    const toolName = tool.name.trim();
+    return [
+      {
+        toolId: stableToolId(toolName, seen),
+        toolName,
+        description: typeof tool.description === "string" ? tool.description : null,
+        ...(tool.inputSchema !== undefined
+          ? { inputSchema: tool.inputSchema }
+          : tool.parameters !== undefined
+            ? { inputSchema: tool.parameters }
+            : {}),
+        ...(tool.outputSchema !== undefined ? { outputSchema: tool.outputSchema } : {}),
+        ...(tool.annotations && typeof tool.annotations === "object"
+          ? { annotations: tool.annotations as Readonly<Record<string, unknown>> }
+          : {}),
+      },
+    ];
+  });
+  const info =
+    metadata.serverInfo && typeof metadata.serverInfo === "object"
+      ? (metadata.serverInfo as Record<string, unknown>)
+      : null;
+  return {
+    server: info
+      ? {
+          name: typeof info.name === "string" ? info.name : null,
+          version: typeof info.version === "string" ? info.version : null,
+          instructions: metadata.instructions ?? null,
+        }
+      : null,
+    tools,
+  };
+}
+
+export function deriveMcpNamespace(input: {
+  readonly name?: string | null;
+  readonly endpoint?: string | null;
+  readonly command?: string | null;
+}): string {
+  const candidate =
+    input.name?.trim() || hostname(input.endpoint) || basename(input.command) || "mcp";
+  return stableToolId(candidate);
+}
+
+function hostname(value: string | null | undefined): string {
+  if (!value || !URL.canParse(value)) return "";
+  return new URL(value).hostname;
+}
+
+function basename(value: string | null | undefined): string {
+  return value?.trim().split(/[\\/]/).pop() ?? "";
+}