@nkmc/gateway 0.1.0

package/test/onboard/apis-guru.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { discoverFromApisGuru } from "../../src/onboard/apis-guru.js";
+
+const MOCK_CATALOG = {
+  "petstore.com:1.0.0": {
+    preferred: "1.0.0",
+    versions: {
+      "1.0.0": {
+        swaggerUrl: "https://petstore.com/openapi.json",
+        info: { title: "Petstore", description: "A pet store API" },
+      },
+    },
+  },
+  "weather.com:2.0": {
+    preferred: "2.0",
+    versions: {
+      "2.0": {
+        swaggerUrl: "https://weather.com/v2/openapi.json",
+        info: { title: "Weather API", description: "Global weather data" },
+      },
+    },
+  },
+  "nospec.com:1.0": {
+    preferred: "1.0",
+    versions: { "1.0": { info: { title: "No Spec" } } },
+  },
+};
+
+function mockFetch() {
+  return async () =>
+    new Response(JSON.stringify(MOCK_CATALOG), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+}
+
+describe("discoverFromApisGuru", () => {
+  it("should discover APIs from catalog", async () => {
+    const entries = await discoverFromApisGuru({ fetchFn: mockFetch() as any });
+    // nospec.com has no swaggerUrl → skipped
+    expect(entries).toHaveLength(2);
+    expect(entries[0].domain).toBe("petstore.com");
+    expect(entries[0].specUrl).toBe("https://petstore.com/openapi.json");
+    expect(entries[0].tags).toContain("apis-guru");
+  });
+
+  it("should respect limit", async () => {
+    const entries = await discoverFromApisGuru({ limit: 1, fetchFn: mockFetch() as any });
+    expect(entries).toHaveLength(1);
+  });
+
+  it("should filter by keyword", async () => {
+    const entries = await discoverFromApisGuru({ filter: "weather", fetchFn: mockFetch() as any });
+    expect(entries).toHaveLength(1);
+    expect(entries[0].domain).toBe("weather.com");
+  });
+});

package/test/onboard/e2e.test.ts

@@ -0,0 +1,70 @@
+/**
+ * E2E: onboard real APIs from apis.guru, then interact via AgentFs.
+ */
+import { describe, it, expect } from "vitest";
+import { OnboardPipeline } from "../../src/onboard/pipeline.js";
+import { discoverFromApisGuru } from "../../src/onboard/apis-guru.js";
+import { MemoryRegistryStore } from "../../src/registry/memory-store.js";
+import { createRegistryResolver } from "../../src/registry/resolver.js";
+import { AgentFs } from "@nkmc/agent-fs";
+
+describe("Onboard E2E: apis.guru → AgentFs (real network)", () => {
+  it("should discover, onboard, and browse a real public API", async () => {
+    const store = new MemoryRegistryStore();
+
+    // 1. Discover — pick a known small API
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "petstore3.swagger.io",
+      specUrl: "https://petstore3.swagger.io/api/v3/openapi.json",
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.source).toBe("openapi");
+    expect(result.endpoints).toBeGreaterThan(0);
+    expect(result.resources).toBeGreaterThan(0);
+
+    // 2. Browse via AgentFs
+    const { onMiss, listDomains } = createRegistryResolver({ store, wrapVirtualFiles: false });
+    const fs = new AgentFs({ mounts: [], onMiss, listDomains });
+
+    // ls / — should show the registered service
+    const lsRoot = await fs.execute("ls /");
+    expect(lsRoot.ok).toBe(true);
+    expect(lsRoot.data).toContain("petstore3.swagger.io/");
+
+    // ls /domain/ — should show resources from the spec
+    const lsDomain = await fs.execute("ls /petstore3.swagger.io/");
+    expect(lsDomain.ok).toBe(true);
+    const entries = lsDomain.data as string[];
+    expect(entries.some((e) => e.includes("pet"))).toBe(true);
+    expect(entries).toContain("_api/");
+  }, 30_000);
+
+  it("should batch-onboard multiple APIs from apis.guru", async () => {
+    // Discover 3 APIs with keyword filter
+    const entries = await discoverFromApisGuru({ limit: 3 });
+    expect(entries.length).toBeGreaterThan(0);
+
+    const store = new MemoryRegistryStore();
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+      concurrency: 3,
+    });
+
+    const report = await pipeline.onboardMany(entries);
+
+    // At least some should succeed (some specs might be unreachable)
+    expect(report.total).toBe(entries.length);
+    expect(report.ok).toBeGreaterThan(0);
+
+    // Verify store has services
+    const services = await store.list();
+    expect(services.length).toBe(report.ok);
+  }, 60_000);
+});

package/test/onboard/pipeline.test.ts

@@ -0,0 +1,318 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { OnboardPipeline } from "../../src/onboard/pipeline.js";
+import { MemoryRegistryStore } from "../../src/registry/memory-store.js";
+import { MemoryCredentialVault } from "../../src/credential/memory-vault.js";
+import type { ManifestEntry } from "../../src/onboard/types.js";
+
+const PETSTORE_SPEC = {
+  openapi: "3.0.0",
+  info: { title: "Petstore", description: "A pet store", version: "1.0.0" },
+  paths: {
+    "/pets": { get: { summary: "List pets" }, post: { summary: "Create pet" } },
+    "/pets/{petId}": { get: { summary: "Get pet" } },
+  },
+};
+
+function mockFetch(overrides?: Record<string, { status: number; body: any; contentType?: string }>) {
+  return async (url: string) => {
+    for (const [pattern, resp] of Object.entries(overrides ?? {})) {
+      if (url.includes(pattern)) {
+        const ct = resp.contentType ?? "application/json";
+        const body = ct.includes("json") ? JSON.stringify(resp.body) : resp.body;
+        return new Response(body, {
+          status: resp.status,
+          headers: { "Content-Type": ct },
+        });
+      }
+    }
+    return new Response(JSON.stringify(PETSTORE_SPEC), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+}
+
+describe("OnboardPipeline", () => {
+  let store: MemoryRegistryStore;
+  let vault: MemoryCredentialVault;
+
+  beforeEach(() => {
+    store = new MemoryRegistryStore();
+    vault = new MemoryCredentialVault();
+  });
+
+  it("should onboard a service from OpenAPI spec URL", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      vault,
+      smokeTest: false,
+      fetchFn: mockFetch() as any,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "petstore.com",
+      specUrl: "https://petstore.com/openapi.json",
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.source).toBe("openapi");
+    expect(result.endpoints).toBe(3);
+    expect(result.resources).toBeGreaterThan(0);
+
+    // Verify service is registered
+    const record = await store.get("petstore.com");
+    expect(record).not.toBeNull();
+    expect(record!.name).toBe("Petstore");
+  });
+
+  it("should onboard a service from inline skill.md", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+      fetchFn: mockFetch() as any,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "acme.com",
+      skillMd: `---
+name: "Acme"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Acme
+
+A service.
+
+## API
+
+### Get data
+
+\`GET /api/data\` — public
+`,
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.source).toBe("skillmd");
+    expect(result.endpoints).toBe(1);
+  });
+
+  it("should store pool credentials from manifest", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      vault,
+      smokeTest: false,
+      fetchFn: mockFetch() as any,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "petstore.com",
+      specUrl: "https://petstore.com/openapi.json",
+      auth: { type: "bearer", token: "secret-123" },
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.hasCredentials).toBe(true);
+
+    // Verify credential is stored
+    const cred = await vault.get("petstore.com");
+    expect(cred).not.toBeNull();
+    expect(cred!.auth).toEqual({ type: "bearer", token: "secret-123" });
+  });
+
+  it("should resolve ${ENV_VAR} in auth", async () => {
+    process.env._TEST_TOKEN = "resolved-secret";
+    const pipeline = new OnboardPipeline({
+      store,
+      vault,
+      smokeTest: false,
+      fetchFn: mockFetch() as any,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "petstore.com",
+      specUrl: "https://petstore.com/openapi.json",
+      auth: { type: "bearer", token: "${_TEST_TOKEN}" },
+    });
+
+    expect(result.status).toBe("ok");
+    const cred = await vault.get("petstore.com");
+    expect(cred!.auth).toEqual({ type: "bearer", token: "resolved-secret" });
+    delete process.env._TEST_TOKEN;
+  });
+
+  it("should skip disabled entries", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+      fetchFn: mockFetch() as any,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "skip.com",
+      specUrl: "https://skip.com/openapi.json",
+      disabled: true,
+    });
+
+    expect(result.status).toBe("skipped");
+  });
+
+  it("should report failure on bad spec URL", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+      fetchFn: mockFetch({
+        "bad.com": { status: 404, body: "not found" },
+      }) as any,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "bad.com",
+      specUrl: "https://bad.com/openapi.json",
+    });
+
+    expect(result.status).toBe("failed");
+    expect(result.error).toContain("404");
+  });
+
+  it("should skip entries with no source", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+      fetchFn: mockFetch() as any,
+    });
+
+    const result = await pipeline.onboardOne({ domain: "empty.com" });
+    expect(result.status).toBe("skipped");
+  });
+
+  it("should run smoke test on registered service", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      vault,
+      smokeTest: true,
+      fetchFn: mockFetch() as any,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "petstore.com",
+      specUrl: "https://petstore.com/openapi.json",
+    });
+
+    expect(result.status).toBe("ok");
+    // Smoke test ls should work (returns local resources)
+    expect(result.smokeTest?.ls).toBe(true);
+  });
+
+  it("should process batch with concurrency", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+      concurrency: 2,
+      fetchFn: mockFetch() as any,
+    });
+
+    const entries: ManifestEntry[] = [
+      { domain: "api1.com", specUrl: "https://api1.com/spec.json" },
+      { domain: "api2.com", specUrl: "https://api2.com/spec.json" },
+      { domain: "api3.com", specUrl: "https://api3.com/spec.json" },
+      { domain: "skip.com", disabled: true },
+    ];
+
+    const report = await pipeline.onboardMany(entries);
+
+    expect(report.total).toBe(4);
+    expect(report.ok).toBe(3);
+    expect(report.skipped).toBe(1);
+    expect(report.failed).toBe(0);
+    expect(report.durationMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it("should onboard a service from RPC definition", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+    });
+
+    const result = await pipeline.onboardOne({
+      domain: "rpc.example.com",
+      rpcDef: {
+        url: "https://rpc.example.com/eth",
+        convention: "evm",
+        methods: [
+          { rpcMethod: "eth_blockNumber", description: "Latest block", resource: "blocks", fsOp: "list" },
+          { rpcMethod: "eth_getBlockByNumber", description: "Get block", resource: "blocks", fsOp: "read" },
+          { rpcMethod: "eth_getBalance", description: "Get balance", resource: "balances", fsOp: "read" },
+          { rpcMethod: "eth_chainId", description: "Chain ID" },
+        ],
+      },
+    });
+
+    expect(result.status).toBe("ok");
+    expect(result.source).toBe("jsonrpc");
+    expect(result.endpoints).toBe(4);
+    expect(result.resources).toBeGreaterThan(0);
+
+    // Verify service is registered with RPC source metadata
+    const record = await store.get("rpc.example.com");
+    expect(record).not.toBeNull();
+    expect(record!.source?.type).toBe("jsonrpc");
+    expect(record!.source?.rpc?.convention).toBe("evm");
+    expect(record!.source?.rpc?.rpcUrl).toBe("https://rpc.example.com/eth");
+
+    // Verify resources are compiled
+    const blocks = record!.source?.rpc?.resources.find((r) => r.name === "blocks");
+    expect(blocks).toBeDefined();
+    expect(blocks!.methods).toEqual({
+      list: "eth_blockNumber",
+      read: "eth_getBlockByNumber",
+    });
+  });
+
+  it("should include RPC services in batch onboard", async () => {
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+      fetchFn: mockFetch() as any,
+    });
+
+    const entries: ManifestEntry[] = [
+      { domain: "api.example.com", specUrl: "https://api.example.com/spec.json" },
+      {
+        domain: "rpc.example.com",
+        rpcDef: {
+          url: "https://rpc.example.com",
+          convention: "evm",
+          methods: [
+            { rpcMethod: "eth_blockNumber", description: "Latest block", resource: "blocks", fsOp: "list" },
+          ],
+        },
+      },
+    ];
+
+    const report = await pipeline.onboardMany(entries);
+    expect(report.ok).toBe(2);
+    expect(report.results[0].source).toBe("openapi");
+    expect(report.results[1].source).toBe("jsonrpc");
+  });
+
+  it("should call onProgress callback", async () => {
+    const progress: { domain: string; index: number }[] = [];
+    const pipeline = new OnboardPipeline({
+      store,
+      smokeTest: false,
+      fetchFn: mockFetch() as any,
+      onProgress: (result, index) => {
+        progress.push({ domain: result.domain, index });
+      },
+    });
+
+    await pipeline.onboardMany([
+      { domain: "a.com", specUrl: "https://a.com/spec.json" },
+      { domain: "b.com", specUrl: "https://b.com/spec.json" },
+    ]);
+
+    expect(progress).toHaveLength(2);
+  });
+});