@nkmc/agent-fs 0.1.0

package/test/http-oauth2.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { HttpBackend } from "../src/backends/http.js";
+
+describe("HttpBackend OAuth2 client_credentials", () => {
+  let server: Server;
+  let port: number;
+  let tokenRequestCount: number;
+
+  beforeAll(async () => {
+    tokenRequestCount = 0;
+
+    await new Promise<void>((resolve) => {
+      server = createServer((req: IncomingMessage, res: ServerResponse) => {
+        res.setHeader("Content-Type", "application/json");
+
+        const chunks: Buffer[] = [];
+        req.on("data", (c: Buffer) => chunks.push(c));
+        req.on("end", () => {
+          const body = chunks.length ? Buffer.concat(chunks).toString() : "";
+
+          // Token endpoint
+          if (req.url === "/oauth/token" && req.method === "POST") {
+            tokenRequestCount++;
+
+            // Verify client credentials in Authorization header
+            const auth = req.headers.authorization;
+            if (!auth?.startsWith("Basic ")) {
+              res.writeHead(401);
+              res.end(JSON.stringify({ error: "invalid_client" }));
+              return;
+            }
+
+            const decoded = Buffer.from(auth.slice(6), "base64").toString();
+            const [clientId, clientSecret] = decoded.split(":");
+            if (clientId !== "my-client" || clientSecret !== "my-secret") {
+              res.writeHead(401);
+              res.end(JSON.stringify({ error: "invalid_client" }));
+              return;
+            }
+
+            // Verify grant_type
+            const params = new URLSearchParams(body);
+            if (params.get("grant_type") !== "client_credentials") {
+              res.writeHead(400);
+              res.end(JSON.stringify({ error: "unsupported_grant_type" }));
+              return;
+            }
+
+            res.writeHead(200);
+            res.end(JSON.stringify({
+              access_token: `token-${tokenRequestCount}`,
+              token_type: "bearer",
+              expires_in: 3600,
+            }));
+            return;
+          }
+
+          // Protected API endpoint
+          if (req.url === "/api/data" && req.method === "GET") {
+            const auth = req.headers.authorization;
+            if (!auth?.startsWith("Bearer token-")) {
+              res.writeHead(401);
+              res.end(JSON.stringify({ error: "unauthorized" }));
+              return;
+            }
+
+            res.writeHead(200);
+            res.end(JSON.stringify({ items: [{ id: "1" }], token_used: auth }));
+            return;
+          }
+
+          res.writeHead(404);
+          res.end("{}");
+        });
+      });
+      server.listen(0, () => {
+        port = (server.address() as any).port;
+        resolve();
+      });
+    });
+  });
+
+  afterAll(() => server?.close());
+
+  it("should automatically fetch OAuth2 token and use it for requests", async () => {
+    tokenRequestCount = 0;
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      auth: {
+        type: "oauth2",
+        tokenUrl: `http://localhost:${port}/oauth/token`,
+        clientId: "my-client",
+        clientSecret: "my-secret",
+      },
+    });
+
+    const result = await backend.read("/api/data") as any;
+    expect(result.items).toEqual([{ id: "1" }]);
+    expect(result.token_used).toBe("Bearer token-1");
+    expect(tokenRequestCount).toBe(1);
+  });
+
+  it("should cache the token across multiple requests", async () => {
+    tokenRequestCount = 0;
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      auth: {
+        type: "oauth2",
+        tokenUrl: `http://localhost:${port}/oauth/token`,
+        clientId: "my-client",
+        clientSecret: "my-secret",
+      },
+    });
+
+    await backend.read("/api/data");
+    await backend.read("/api/data");
+    await backend.read("/api/data");
+
+    // Token should only be fetched once (cached)
+    expect(tokenRequestCount).toBe(1);
+  });
+
+  it("should pass scope if provided", async () => {
+    let tokenBody = "";
+    const mockServer = createServer((req: IncomingMessage, res: ServerResponse) => {
+      res.setHeader("Content-Type", "application/json");
+      const chunks: Buffer[] = [];
+      req.on("data", (c: Buffer) => chunks.push(c));
+      req.on("end", () => {
+        const body = chunks.length ? Buffer.concat(chunks).toString() : "";
+        if (req.url === "/token") {
+          tokenBody = body; // capture only the token request body
+          res.end(JSON.stringify({ access_token: "t", expires_in: 3600 }));
+          return;
+        }
+        res.end(JSON.stringify({ ok: true }));
+      });
+    });
+
+    await new Promise<void>((resolve) => mockServer.listen(0, resolve));
+    const p = (mockServer.address() as any).port;
+
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${p}`,
+      auth: {
+        type: "oauth2",
+        tokenUrl: `http://localhost:${p}/token`,
+        clientId: "c",
+        clientSecret: "s",
+        scope: "read write",
+      },
+    });
+
+    await backend.read("/test");
+    expect(tokenBody).toContain("scope=read+write");
+
+    mockServer.close();
+  });
+
+  it("should fail gracefully on invalid credentials", async () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      auth: {
+        type: "oauth2",
+        tokenUrl: `http://localhost:${port}/oauth/token`,
+        clientId: "wrong",
+        clientSecret: "wrong",
+      },
+    });
+
+    await expect(backend.read("/api/data")).rejects.toThrow("OAuth2 token request failed");
+  });
+});

package/test/http-pagination.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { HttpBackend } from "../src/backends/http.js";
+import { getNestedValue } from "../src/backends/http.js";
+
+describe("getNestedValue", () => {
+  it("should resolve dot-separated paths", () => {
+    expect(getNestedValue({ a: { b: { c: 42 } } }, "a.b.c")).toBe(42);
+  });
+
+  it("should resolve single-level paths", () => {
+    expect(getNestedValue({ cursor: "abc" }, "cursor")).toBe("abc");
+  });
+
+  it("should return undefined for missing paths", () => {
+    expect(getNestedValue({ a: 1 }, "b")).toBeUndefined();
+    expect(getNestedValue(null, "a")).toBeUndefined();
+  });
+});
+
+describe("Cursor pagination", () => {
+  let server: Server;
+  let port: number;
+
+  beforeAll(async () => {
+    await new Promise<void>((resolve) => {
+      server = createServer((req: IncomingMessage, res: ServerResponse) => {
+        res.setHeader("Content-Type", "application/json");
+        const url = new URL(req.url ?? "/", "http://localhost");
+
+        if (url.pathname === "/items") {
+          const cursor = url.searchParams.get("starting_after");
+          if (!cursor) {
+            // Page 1
+            res.end(JSON.stringify({
+              data: [{ id: "a" }, { id: "b" }],
+              has_more: true,
+              next_cursor: "b",
+            }));
+          } else if (cursor === "b") {
+            // Page 2
+            res.end(JSON.stringify({
+              data: [{ id: "c" }, { id: "d" }],
+              has_more: true,
+              next_cursor: "d",
+            }));
+          } else {
+            // Page 3 (last)
+            res.end(JSON.stringify({
+              data: [{ id: "e" }],
+              has_more: false,
+            }));
+          }
+          return;
+        }
+
+        res.writeHead(404);
+        res.end("{}");
+      });
+      server.listen(0, () => {
+        port = (server.address() as any).port;
+        resolve();
+      });
+    });
+  });
+
+  afterAll(() => server?.close());
+
+  it("should follow cursor pagination across multiple pages", async () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      resources: [{ name: "items", apiPath: "/items", listKey: "data" }],
+      pagination: {
+        type: "cursor",
+        cursorParam: "starting_after",
+        cursorPath: "next_cursor",
+        maxPages: 10,
+      },
+    });
+
+    const items = await backend.list("/items/");
+    expect(items).toEqual(["a.json", "b.json", "c.json", "d.json", "e.json"]);
+  });
+
+  it("should respect maxPages limit", async () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      resources: [{ name: "items", apiPath: "/items", listKey: "data" }],
+      pagination: {
+        type: "cursor",
+        cursorParam: "starting_after",
+        cursorPath: "next_cursor",
+        maxPages: 2, // Only fetch 2 pages total
+      },
+    });
+
+    const items = await backend.list("/items/");
+    // Page 1: a,b + Page 2: c,d (maxPages=2 means 1 additional page)
+    expect(items).toEqual(["a.json", "b.json", "c.json", "d.json"]);
+  });
+});
+
+describe("Offset pagination", () => {
+  let server: Server;
+  let port: number;
+
+  beforeAll(async () => {
+    await new Promise<void>((resolve) => {
+      server = createServer((req: IncomingMessage, res: ServerResponse) => {
+        res.setHeader("Content-Type", "application/json");
+        const url = new URL(req.url ?? "/", "http://localhost");
+
+        if (url.pathname === "/records") {
+          const offset = parseInt(url.searchParams.get("offset") ?? "0");
+          const limit = parseInt(url.searchParams.get("limit") ?? "2");
+          const allItems = [{ id: "1" }, { id: "2" }, { id: "3" }, { id: "4" }, { id: "5" }];
+          const page = allItems.slice(offset, offset + limit);
+          res.end(JSON.stringify({ items: page, total: allItems.length }));
+          return;
+        }
+
+        res.writeHead(404);
+        res.end("{}");
+      });
+      server.listen(0, () => {
+        port = (server.address() as any).port;
+        resolve();
+      });
+    });
+  });
+
+  afterAll(() => server?.close());
+
+  it("should follow offset pagination", async () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      resources: [{ name: "records", apiPath: "/records", listKey: "items" }],
+      pagination: {
+        type: "offset",
+        offsetParam: "offset",
+        limitParam: "limit",
+        pageSize: 2,
+        maxPages: 10,
+      },
+    });
+
+    const items = await backend.list("/records/");
+    expect(items).toEqual(["1.json", "2.json", "3.json", "4.json", "5.json"]);
+  });
+});
+
+describe("Page pagination", () => {
+  let server: Server;
+  let port: number;
+
+  beforeAll(async () => {
+    await new Promise<void>((resolve) => {
+      server = createServer((req: IncomingMessage, res: ServerResponse) => {
+        res.setHeader("Content-Type", "application/json");
+        const url = new URL(req.url ?? "/", "http://localhost");
+
+        if (url.pathname === "/entries") {
+          const page = parseInt(url.searchParams.get("page") ?? "1");
+          if (page === 1) {
+            res.end(JSON.stringify({ results: [{ id: "x" }, { id: "y" }] }));
+          } else if (page === 2) {
+            res.end(JSON.stringify({ results: [{ id: "z" }] }));
+          } else {
+            res.end(JSON.stringify({ results: [] }));
+          }
+          return;
+        }
+
+        res.writeHead(404);
+        res.end("{}");
+      });
+      server.listen(0, () => {
+        port = (server.address() as any).port;
+        resolve();
+      });
+    });
+  });
+
+  afterAll(() => server?.close());
+
+  it("should follow page pagination", async () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      resources: [{ name: "entries", apiPath: "/entries", listKey: "results" }],
+      pagination: {
+        type: "page",
+        pageParam: "page",
+        maxPages: 10,
+      },
+    });
+
+    const items = await backend.list("/entries/");
+    expect(items).toEqual(["x.json", "y.json", "z.json"]);
+  });
+});

package/test/http-param-styles.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { HttpBackend } from "../src/backends/http.js";
+
+describe("HttpBackend {param} path parameter support", () => {
+  let server: Server;
+  let port: number;
+
+  beforeAll(async () => {
+    await new Promise<void>((resolve) => {
+      server = createServer((req: IncomingMessage, res: ServerResponse) => {
+        res.setHeader("Content-Type", "application/json");
+
+        // /accounts/acc123/records → list
+        const listMatch = req.url?.match(/^\/accounts\/(\w+)\/records$/);
+        if (listMatch && req.method === "GET") {
+          res.end(JSON.stringify([
+            { id: "r1", account: listMatch[1] },
+            { id: "r2", account: listMatch[1] },
+          ]));
+          return;
+        }
+
+        // /accounts/acc123/records/r1 → single item
+        const getMatch = req.url?.match(/^\/accounts\/(\w+)\/records\/(\w+)$/);
+        if (getMatch && req.method === "GET") {
+          res.end(JSON.stringify({ id: getMatch[2], account: getMatch[1], data: "test" }));
+          return;
+        }
+
+        res.writeHead(404);
+        res.end("{}");
+      });
+      server.listen(0, () => {
+        port = (server.address() as any).port;
+        resolve();
+      });
+    });
+  });
+
+  afterAll(() => server?.close());
+
+  it("should resolve {accountId} style params in apiPath", async () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      params: { accountId: "acc123" },
+      resources: [{
+        name: "records",
+        apiPath: "/accounts/{accountId}/records",
+      }],
+    });
+
+    const items = await backend.list("/records/");
+    expect(items).toEqual(["r1.json", "r2.json"]);
+  });
+
+  it("should resolve :accountId style params (existing behavior)", async () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      params: { accountId: "acc123" },
+      resources: [{
+        name: "records",
+        apiPath: "/accounts/:accountId/records",
+      }],
+    });
+
+    const items = await backend.list("/records/");
+    expect(items).toEqual(["r1.json", "r2.json"]);
+  });
+
+  it("should resolve {param} in cat path", async () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      params: { accountId: "acc123" },
+      resources: [{
+        name: "records",
+        apiPath: "/accounts/{accountId}/records",
+      }],
+    });
+
+    const result = await backend.read("/records/r1.json") as Record<string, unknown>;
+    expect(result.id).toBe("r1");
+    expect(result.account).toBe("acc123");
+  });
+
+  it("should throw for missing {param}", () => {
+    const backend = new HttpBackend({
+      baseUrl: `http://localhost:${port}`,
+      params: {}, // no accountId
+      resources: [{
+        name: "records",
+        apiPath: "/accounts/{accountId}/records",
+      }],
+    });
+
+    expect(() => backend.list("/records/")).rejects.toThrow("Missing param: accountId");
+  });
+});