263 lines
10 KiB
TypeScript
263 lines
10 KiB
TypeScript
import { describe, it, expect } from "vitest";
|
|
import { createToolctrlClient, ToolctrlApiError, ToolctrlNetworkError } from "./client.js";
|
|
|
|
function mockFetchSequence(responses: Array<Response | Error>): typeof fetch {
|
|
let index = 0;
|
|
return (async () => {
|
|
const next = responses[index++];
|
|
if (next === undefined) {
|
|
throw new Error("mock fetch exhausted");
|
|
}
|
|
if (next instanceof Error) throw next;
|
|
return next;
|
|
}) as unknown as typeof fetch;
|
|
}
|
|
|
|
function jsonResponse(status: number, body: unknown, headers: Record<string, string> = {}): Response {
|
|
return new Response(JSON.stringify(body), {
|
|
status,
|
|
headers: { "content-type": "application/json", ...headers },
|
|
});
|
|
}
|
|
|
|
describe("createToolctrlClient", () => {
|
|
it("rejects when baseUrl is missing", () => {
|
|
expect(() => createToolctrlClient({ baseUrl: "" } as never)).toThrow(/baseUrl/);
|
|
});
|
|
|
|
it("strips trailing slashes from the base url", () => {
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com///",
|
|
fetch: mockFetchSequence([jsonResponse(200, { ok: true })]),
|
|
});
|
|
expect(client.baseUrl).toBe("https://api.example.com");
|
|
});
|
|
|
|
it("sends Authorization bearer when bearerToken is set", async () => {
|
|
const captured: { headers: Headers | null } = { headers: null };
|
|
const stub: typeof fetch = (async (_url: unknown, init: RequestInit) => {
|
|
captured.headers = init.headers as Headers;
|
|
return jsonResponse(200, { hello: "world" });
|
|
}) as unknown as typeof fetch;
|
|
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
auth: { bearerToken: "secret-token" },
|
|
fetch: stub,
|
|
});
|
|
const result = await client.request<{ hello: string }>({ method: "GET", path: "/v1/me" });
|
|
expect(result.hello).toBe("world");
|
|
expect(captured.headers!.get("authorization")).toBe("Bearer secret-token");
|
|
});
|
|
|
|
it("sends X-API-Key when apiKey is set", async () => {
|
|
const captured: { headers: Headers | null } = { headers: null };
|
|
const stub: typeof fetch = (async (_url: unknown, init: RequestInit) => {
|
|
captured.headers = init.headers as Headers;
|
|
return jsonResponse(200, {});
|
|
}) as unknown as typeof fetch;
|
|
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
auth: { apiKey: "ak_test_123" },
|
|
fetch: stub,
|
|
});
|
|
await client.request({ method: "GET", path: "/v1/ping" });
|
|
expect(captured.headers!.get("x-api-key")).toBe("ak_test_123");
|
|
});
|
|
|
|
it("auto-generates Idempotency-Key on POST", async () => {
|
|
const captured: { headers: Headers | null } = { headers: null };
|
|
const stub: typeof fetch = (async (_url: unknown, init: RequestInit) => {
|
|
captured.headers = init.headers as Headers;
|
|
return jsonResponse(201, {});
|
|
}) as unknown as typeof fetch;
|
|
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
fetch: stub,
|
|
});
|
|
await client.request({ method: "POST", path: "/v1/items", body: { foo: 1 } });
|
|
expect(captured.headers!.get("idempotency-key")).toMatch(/^[0-9a-f-]{36}$/i);
|
|
});
|
|
|
|
it("does not auto-generate Idempotency-Key on GET", async () => {
|
|
const captured: { headers: Headers | null } = { headers: null };
|
|
const stub: typeof fetch = (async (_url: unknown, init: RequestInit) => {
|
|
captured.headers = init.headers as Headers;
|
|
return jsonResponse(200, {});
|
|
}) as unknown as typeof fetch;
|
|
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
fetch: stub,
|
|
});
|
|
await client.request({ method: "GET", path: "/v1/items" });
|
|
expect(captured.headers!.get("idempotency-key")).toBeNull();
|
|
});
|
|
|
|
it("respects autoGenerate=false", async () => {
|
|
const captured: { headers: Headers | null } = { headers: null };
|
|
const stub: typeof fetch = (async (_url: unknown, init: RequestInit) => {
|
|
captured.headers = init.headers as Headers;
|
|
return jsonResponse(201, {});
|
|
}) as unknown as typeof fetch;
|
|
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
idempotency: { autoGenerate: false },
|
|
fetch: stub,
|
|
});
|
|
await client.request({ method: "POST", path: "/v1/items", body: { foo: 1 } });
|
|
expect(captured.headers!.get("idempotency-key")).toBeNull();
|
|
});
|
|
|
|
it("honors caller-provided Idempotency-Key", async () => {
|
|
const captured: { headers: Headers | null } = { headers: null };
|
|
const stub: typeof fetch = (async (_url: unknown, init: RequestInit) => {
|
|
captured.headers = init.headers as Headers;
|
|
return jsonResponse(201, {});
|
|
}) as unknown as typeof fetch;
|
|
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
fetch: stub,
|
|
});
|
|
await client.request({ method: "POST", path: "/v1/items", body: {}, idempotencyKey: "caller-key" });
|
|
expect(captured.headers!.get("idempotency-key")).toBe("caller-key");
|
|
});
|
|
|
|
it("forwards X-Tenant-ID and Sentry trace headers", async () => {
|
|
const captured: { headers: Headers | null } = { headers: null };
|
|
const stub: typeof fetch = (async (_url: unknown, init: RequestInit) => {
|
|
captured.headers = init.headers as Headers;
|
|
return jsonResponse(200, {});
|
|
}) as unknown as typeof fetch;
|
|
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
tenantId: "ten_abc",
|
|
sentry: { trace: "abc-1", baggage: "k=v" },
|
|
fetch: stub,
|
|
});
|
|
await client.request({ method: "GET", path: "/v1/ping" });
|
|
expect(captured.headers!.get("x-tenant-id")).toBe("ten_abc");
|
|
expect(captured.headers!.get("sentry-trace")).toBe("abc-1");
|
|
expect(captured.headers!.get("baggage")).toBe("k=v");
|
|
});
|
|
|
|
it("retries on 5xx then succeeds", async () => {
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
retry: { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 5 },
|
|
fetch: mockFetchSequence([jsonResponse(503, { error: "down" }), jsonResponse(200, { ok: true })]),
|
|
});
|
|
const result = await client.request<{ ok: boolean }>({ method: "GET", path: "/v1/ping" });
|
|
expect(result.ok).toBe(true);
|
|
});
|
|
|
|
it("retries on 429 honoring Retry-After", async () => {
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
retry: { maxAttempts: 3, baseDelayMs: 1000, maxDelayMs: 10_000 },
|
|
fetch: mockFetchSequence([
|
|
jsonResponse(429, { error: "rate" }, { "retry-after": "0" }),
|
|
jsonResponse(200, { ok: true }),
|
|
]),
|
|
});
|
|
const t0 = Date.now();
|
|
const result = await client.request<{ ok: boolean }>({ method: "GET", path: "/v1/ping" });
|
|
expect(result.ok).toBe(true);
|
|
// retry-after=0 should not have produced exponential backoff (which would be >=1000ms)
|
|
expect(Date.now() - t0).toBeLessThan(1000);
|
|
});
|
|
|
|
it("throws ToolctrlApiError on non-retryable 4xx", async () => {
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
retry: { maxAttempts: 3, baseDelayMs: 1 },
|
|
fetch: mockFetchSequence([
|
|
jsonResponse(404, { error: { code: "not_found", message: "missing", requestId: "req_1" } }, { "x-request-id": "req_1" }),
|
|
]),
|
|
});
|
|
await expect(client.request({ method: "GET", path: "/v1/missing" })).rejects.toMatchObject({
|
|
name: "ToolctrlApiError",
|
|
status: 404,
|
|
requestId: "req_1",
|
|
});
|
|
});
|
|
|
|
it("throws ToolctrlNetworkError after exhausting retries", async () => {
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
retry: { maxAttempts: 2, baseDelayMs: 1, maxDelayMs: 5 },
|
|
fetch: mockFetchSequence([new Error("ECONNRESET"), new Error("ECONNRESET")]),
|
|
});
|
|
await expect(client.request({ method: "GET", path: "/v1/ping" })).rejects.toBeInstanceOf(ToolctrlNetworkError);
|
|
});
|
|
|
|
it("paginate auto-follows nextCursor and stops on null", async () => {
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
fetch: mockFetchSequence([
|
|
jsonResponse(200, { data: [{ id: 1 }, { id: 2 }], nextCursor: "c1" }),
|
|
jsonResponse(200, { data: [{ id: 3 }], nextCursor: null }),
|
|
]),
|
|
});
|
|
const items: Array<{ id: number }> = [];
|
|
for await (const item of client.paginate<{ id: number }>("/v1/items")) {
|
|
items.push(item);
|
|
}
|
|
expect(items.map((i) => i.id)).toEqual([1, 2, 3]);
|
|
});
|
|
|
|
it("paginate handles nextPage offset pagination", async () => {
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
fetch: mockFetchSequence([
|
|
jsonResponse(200, { data: [{ id: "a" }], nextPage: 2 }),
|
|
jsonResponse(200, { data: [{ id: "b" }] }),
|
|
]),
|
|
});
|
|
const items: Array<{ id: string }> = [];
|
|
for await (const item of client.paginate<{ id: string }>("/v1/items", { maxPages: 5 })) {
|
|
items.push(item);
|
|
}
|
|
expect(items.map((i) => i.id)).toEqual(["a", "b"]);
|
|
});
|
|
|
|
it("getter mode resolves bearer token freshly", async () => {
|
|
let calls = 0;
|
|
const captured: Array<string | null> = [];
|
|
const stub: typeof fetch = (async (_url: unknown, init: RequestInit) => {
|
|
captured.push((init.headers as Headers).get("authorization"));
|
|
return jsonResponse(200, {});
|
|
}) as unknown as typeof fetch;
|
|
|
|
const client = createToolctrlClient({
|
|
baseUrl: "https://api.example.com",
|
|
auth: {
|
|
getToken: async () => `jwt-${++calls}`,
|
|
},
|
|
fetch: stub,
|
|
});
|
|
await client.request({ method: "GET", path: "/v1/a" });
|
|
await client.request({ method: "GET", path: "/v1/b" });
|
|
expect(captured).toEqual(["Bearer jwt-1", "Bearer jwt-2"]);
|
|
});
|
|
});
|
|
|
|
describe("error types", () => {
|
|
it("ToolctrlApiError carries status, body, and requestId", () => {
|
|
const err = new ToolctrlApiError(403, "Forbidden", { error: { code: "forbidden" } }, "req_x");
|
|
expect(err.name).toBe("ToolctrlApiError");
|
|
expect(err.status).toBe(403);
|
|
expect(err.requestId).toBe("req_x");
|
|
});
|
|
it("ToolctrlNetworkError preserves cause", () => {
|
|
const cause = new Error("ECONNRESET");
|
|
const err = new ToolctrlNetworkError("net", cause);
|
|
expect(err.cause).toBe(cause);
|
|
});
|
|
});
|