@mittwald/api-client-commons 0.0.0-development-860f5d6-20261009 → 0.0.0-development-fd38fc6-20261012

package/dist/esm/core/ApiClientError.test.js

@@ -0,0 +1,53 @@
+import { AxiosError, AxiosHeaders } from "axios";
+import ApiClientError from "./ApiClientError.js";
+const makeResponse = (status = 500) => {
+    const config = {
+        url: "v2/projects",
+        method: "GET",
+        headers: new AxiosHeaders(),
+    };
+    return {
+        status,
+        statusText: "Internal Server Error",
+        data: { message: "boom" },
+        headers: new AxiosHeaders(),
+        config,
+        request: { some: "request" },
+        mediaType: "application/json",
+    };
+};
+describe("constructor", () => {
+    test("is recognizable as ApiClientError and as AxiosError", () => {
+        const error = new ApiClientError("nope");
+        expect(error).toBeInstanceOf(ApiClientError);
+        expect(error).toBeInstanceOf(AxiosError);
+        expect(error).toBeInstanceOf(Error);
+    });
+    test("uses its own name instead of the inherited one", () => {
+        expect(new ApiClientError("nope").name).toBe("ApiClientError");
+    });
+    test("keeps message and code", () => {
+        const error = new ApiClientError("nope", "ERR_NOPE");
+        expect(error.message).toBe("nope");
+        expect(error.code).toBe("ERR_NOPE");
+    });
+});
+describe("fromResponse", () => {
+    test("carries over config, request and response of the failed call", () => {
+        const response = makeResponse();
+        const error = ApiClientError.fromResponse("unexpected status", response);
+        expect(error.message).toBe("unexpected status");
+        expect(error.config).toBe(response.config);
+        expect(error.request).toBe(response.request);
+        expect(error.response).toBe(response);
+    });
+    test("exposes the response status via the response", () => {
+        const error = ApiClientError.fromResponse("unexpected status", makeResponse(404));
+        expect(error.response?.status).toBe(404);
+    });
+    test("produces an instance that is catchable as ApiClientError", () => {
+        expect(() => {
+            throw ApiClientError.fromResponse("unexpected status", makeResponse());
+        }).toThrow(ApiClientError);
+    });
+});

package/dist/esm/core/OpenAPIPath.test.js

@@ -0,0 +1,51 @@
+import OpenAPIPath from "./OpenAPIPath.js";
+describe("buildUrl", () => {
+    test("strips the leading slash so the path stays relative to the baseURL", () => {
+        expect(new OpenAPIPath("/v2/projects").buildUrl()).toBe("v2/projects");
+    });
+    test("keeps a path that has no leading slash untouched", () => {
+        expect(new OpenAPIPath("v2/projects").buildUrl()).toBe("v2/projects");
+    });
+    test("substitutes a single path parameter", () => {
+        const path = new OpenAPIPath("/v2/projects/{projectId}", {
+            projectId: "abc",
+        });
+        expect(path.buildUrl()).toBe("v2/projects/abc");
+    });
+    test("substitutes multiple path parameters", () => {
+        const path = new OpenAPIPath("/v2/projects/{projectId}/apps/{appId}", {
+            projectId: "abc",
+            appId: "def",
+        });
+        expect(path.buildUrl()).toBe("v2/projects/abc/apps/def");
+    });
+    test("stringifies numeric path parameters", () => {
+        const path = new OpenAPIPath("/v2/items/{index}", { index: 42 });
+        expect(path.buildUrl()).toBe("v2/items/42");
+    });
+    test("URL-encodes path parameter values", () => {
+        const path = new OpenAPIPath("/v2/domains/{hostname}", {
+            hostname: "foo bar/baz?x=1",
+        });
+        expect(path.buildUrl()).toBe("v2/domains/foo%20bar%2Fbaz%3Fx%3D1");
+    });
+    test("leaves placeholders in place when no parameters are given", () => {
+        expect(new OpenAPIPath("/v2/projects/{projectId}").buildUrl()).toBe("v2/projects/{projectId}");
+    });
+    test("leaves unrelated placeholders in place", () => {
+        const path = new OpenAPIPath("/v2/projects/{projectId}/apps/{appId}", {
+            projectId: "abc",
+        });
+        expect(path.buildUrl()).toBe("v2/projects/abc/apps/{appId}");
+    });
+    test("only replaces the first occurrence of a repeated placeholder", () => {
+        const path = new OpenAPIPath("/v2/{id}/{id}", { id: "abc" });
+        expect(path.buildUrl()).toBe("v2/abc/{id}");
+    });
+    test("does not mutate the raw path between calls", () => {
+        const path = new OpenAPIPath("/v2/projects/{projectId}", {
+            projectId: "abc",
+        });
+        expect(path.buildUrl()).toBe(path.buildUrl());
+    });
+});

package/dist/esm/core/Request.test.js

@@ -1,4 +1,5 @@
 import Request from "./Request.js";
+import { AxiosError } from "axios";
 import { jest } from "@jest/globals";
 const requestFn = jest.fn();
 const mockedAxios = {
@@ -118,3 +119,104 @@ describe("dates in requests", () => {
         expect(config.data).toBe(data);
     });
 });
+describe("axios config", () => {
+    test("resolves path parameters into the url", () => {
+        const request = new Request({ path: "/v2/projects/{projectId}", operationId: "get", method: "GET" }, { projectId: "abc" });
+        expect(request.requestConfig.url).toBe("v2/projects/abc");
+    });
+    test("passes the method through", () => {
+        const request = new Request({
+            path: "/v2/projects",
+            operationId: "create",
+            method: "POST",
+        });
+        expect(request.requestConfig.method).toBe("POST");
+    });
+    test("always accepts every status so error responses are returned", () => {
+        const request = new Request({
+            path: "/",
+            operationId: "test",
+            method: "GET",
+        });
+        const { validateStatus } = request.requestConfig;
+        expect(validateStatus(500)).toBe(true);
+    });
+    test("forwards the request body as data", () => {
+        const request = new Request({ path: "/v2/projects", operationId: "create", method: "POST" }, { data: { description: "test" } });
+        expect(request.requestConfig.data).toEqual({ description: "test" });
+    });
+    test("leaves data undefined when the request object has no body", () => {
+        const request = new Request({ path: "/v2/projects", operationId: "get", method: "GET" }, { queryParameters: { limit: 1 } });
+        expect(request.requestConfig.data).toBeUndefined();
+    });
+    test("stringifies header values", () => {
+        const request = new Request({ path: "/", operationId: "test", method: "GET" }, { headers: { "x-limit": 5, "x-flag": true, "x-name": "foo" } });
+        expect(request.requestConfig.headers).toEqual({
+            "x-limit": "5",
+            "x-flag": "true",
+            "x-name": "foo",
+        });
+    });
+    test("leaves headers undefined when none are given", () => {
+        const request = new Request({
+            path: "/",
+            operationId: "test",
+            method: "GET",
+        });
+        expect(request.requestConfig.headers).toBeUndefined();
+    });
+});
+describe("query parameter edge cases", () => {
+    const op = { path: "/", operationId: "test", method: "GET" };
+    const paramsOf = (queryParameters) => new Request(op, { queryParameters }).requestConfig.params;
+    test("omits undefined values", () => {
+        expect(paramsOf({ foo: "bar", skipped: undefined })?.toString()).toBe("foo=bar");
+    });
+    test("keeps null values as the string 'null'", () => {
+        expect(paramsOf({ foo: null })?.toString()).toBe("foo=null");
+    });
+    test("is undefined when no query parameters are given", () => {
+        expect(new Request(op).requestConfig.params).toBeUndefined();
+    });
+    test("passes an URLSearchParams instance through unchanged", () => {
+        const searchParams = new URLSearchParams({ foo: "bar" });
+        expect(paramsOf(searchParams)).toBe(searchParams);
+    });
+    test("parses a query string", () => {
+        expect(paramsOf("foo=bar&baz=1")?.toString()).toBe("foo=bar&baz=1");
+    });
+    test("rejects a query parameter type it cannot serialize", () => {
+        expect(() => paramsOf(42)).toThrow("Unexpected query parameter type (number)");
+    });
+});
+describe("execute", () => {
+    const op = { path: "/", operationId: "test", method: "GET" };
+    test("resolves with the axios response", async () => {
+        const response = { status: 200, data: { ok: true } };
+        requestFn.mockResolvedValue(response);
+        await expect(new Request(op).execute(mockedAxios)).resolves.toBe(response);
+    });
+    /**
+     * `execute` intends to fall back to `error.response` for HTTP errors, but
+     * `AxiosError.from()` builds a fresh error without the response (see
+     * axios/lib/core/AxiosError.js), so the fallback never triggers. In practice
+     * this is masked by `validateStatus: () => true`, which stops axios from
+     * throwing on HTTP errors at all.
+     */
+    test("rethrows an axios error that carries a response instead of returning it", async () => {
+        const response = { status: 404, data: { message: "nope" } };
+        const httpError = Object.assign(new AxiosError("Not Found"), { response });
+        requestFn.mockRejectedValue(httpError);
+        await expect(new Request(op).execute(mockedAxios)).rejects.toBe(httpError);
+    });
+    test("rethrows an axios error without a response, such as a network error", async () => {
+        const networkError = new AxiosError("Network Error", "ERR_NETWORK");
+        requestFn.mockRejectedValue(networkError);
+        await expect(new Request(op).execute(mockedAxios)).rejects.toBe(networkError);
+    });
+    test("rethrows a non-axios error unchanged", async () => {
+        const failure = new TypeError("boom");
+        requestFn.mockRejectedValue(failure);
+        await expect(new Request(op).execute(mockedAxios)).rejects.toBe(failure);
+    });
+});

package/dist/esm/interceptors/accessToken.test.js

@@ -0,0 +1,59 @@
+import axios from "axios";
+import nock from "nock";
+import ApiClientBase from "../core/ApiClientBase.js";
+import withAccessToken from "./accessToken.js";
+const baseURL = "http://accesstoken.example.com";
+class TestClient extends ApiClientBase {
+    getProjects = this.requestFunctionFactory({
+        path: "/v2/projects",
+        method: "GET",
+        operationId: "getProjects",
+    });
+}
+/** Performs a request and returns the headers the server actually received. */
+const capturedHeaders = async (run) => {
+    const received = [];
+    const scope = nock(baseURL).get("/v2/projects").reply(200, {});
+    scope.on("request", (req) => received.push(req.headers));
+    await run();
+    scope.done();
+    return received[0];
+};
+const createInstance = () => axios.create({ baseURL });
+afterEach(() => {
+    nock.cleanAll();
+});
+test("sets the default x-access-token header", async () => {
+    const instance = withAccessToken(createInstance(), "secret-token");
+    const headers = await capturedHeaders(() => instance.get("/v2/projects"));
+    expect(headers["x-access-token"]).toBe("secret-token");
+});
+test("uses a custom header name when given", async () => {
+    const instance = withAccessToken(createInstance(), "secret-token", "x-my-token");
+    const headers = await capturedHeaders(() => instance.get("/v2/projects"));
+    expect(headers["x-my-token"]).toBe("secret-token");
+    expect(headers["x-access-token"]).toBeUndefined();
+});
+test("does not overwrite a token that the caller set per request", async () => {
+    const instance = withAccessToken(createInstance(), "secret-token");
+    const headers = await capturedHeaders(() => instance.get("/v2/projects", {
+        headers: { "x-access-token": "per-request-token" },
+    }));
+    expect(headers["x-access-token"]).toBe("per-request-token");
+});
+test("sends no token when the token is undefined", async () => {
+    const instance = withAccessToken(createInstance(), undefined);
+    const headers = await capturedHeaders(() => instance.get("/v2/projects"));
+    expect(headers["x-access-token"]).toBeUndefined();
+});
+test("returns the given axios instance unchanged", () => {
+    const instance = createInstance();
+    expect(withAccessToken(instance, "secret-token")).toBe(instance);
+});
+test("configures the axios instance of an ApiClientBase and returns the client", async () => {
+    const client = new TestClient(createInstance());
+    const returned = withAccessToken(client, "secret-token");
+    expect(returned).toBe(client);
+    const headers = await capturedHeaders(() => client.getProjects());
+    expect(headers["x-access-token"]).toBe("secret-token");
+});

package/dist/esm/interceptors/consistencyHandling.test.js

@@ -0,0 +1,131 @@
+import axios from "axios";
+import nock from "nock";
+import ApiClientBase from "../core/ApiClientBase.js";
+import { withEventConsistencyHandling } from "./consistencyHandling.js";
+const baseURL = "http://consistency.example.com";
+class TestClient extends ApiClientBase {
+    createProject = this.requestFunctionFactory({
+        path: "/v2/projects",
+        method: "POST",
+        operationId: "createProject",
+    });
+    getProjects = this.requestFunctionFactory({
+        path: "/v2/projects",
+        method: "GET",
+        operationId: "getProjects",
+    });
+}
+let received = [];
+/** Registers an interceptor and records the headers each call sends. */
+const record = (scope) => {
+    scope.on("request", (req) => received.push(req.headers));
+    return scope;
+};
+const ifEventReached = (index) => received[index]?.["if-event-reached"];
+const createInstance = () => withEventConsistencyHandling(axios.create({ baseURL }));
+beforeEach(() => {
+    received = [];
+});
+afterEach(() => {
+    nock.cleanAll();
+});
+test("sends no if-event-reached header before any mutation happened", async () => {
+    record(nock(baseURL).get("/v2/projects").reply(200, {}));
+    await createInstance().get("/v2/projects");
+    expect(ifEventReached(0)).toBeUndefined();
+});
+test("replays the etag of a mutation on the next read request", async () => {
+    record(nock(baseURL)
+        .post("/v2/projects")
+        .reply(201, {}, { etag: "event-1" })
+        .get("/v2/projects")
+        .reply(200, {}));
+    const instance = createInstance();
+    await instance.post("/v2/projects", {});
+    await instance.get("/v2/projects");
+    expect(ifEventReached(0)).toBeUndefined();
+    expect(ifEventReached(1)).toBe("event-1");
+});
+test("keeps replaying the most recent etag", async () => {
+    record(nock(baseURL)
+        .post("/v2/projects")
+        .reply(201, {}, { etag: "event-1" })
+        .patch("/v2/projects")
+        .reply(200, {}, { etag: "event-2" })
+        .get("/v2/projects")
+        .reply(200, {}));
+    const instance = createInstance();
+    await instance.post("/v2/projects", {});
+    await instance.patch("/v2/projects", {});
+    await instance.get("/v2/projects");
+    expect(ifEventReached(2)).toBe("event-2");
+});
+test("does not send if-event-reached on mutating requests", async () => {
+    record(nock(baseURL)
+        .post("/v2/projects")
+        .reply(201, {}, { etag: "event-1" })
+        .delete("/v2/projects")
+        .reply(204));
+    const instance = createInstance();
+    await instance.post("/v2/projects", {});
+    await instance.delete("/v2/projects");
+    expect(ifEventReached(1)).toBeUndefined();
+});
+test("does not overwrite an if-event-reached header set by the caller", async () => {
+    record(nock(baseURL)
+        .post("/v2/projects")
+        .reply(201, {}, { etag: "event-1" })
+        .get("/v2/projects")
+        .reply(200, {}));
+    const instance = createInstance();
+    await instance.post("/v2/projects", {});
+    await instance.get("/v2/projects", {
+        headers: { "if-event-reached": "caller-event" },
+    });
+    expect(ifEventReached(1)).toBe("caller-event");
+});
+test("ignores the etag of a non-mutating response", async () => {
+    record(nock(baseURL)
+        .get("/v2/projects")
+        .reply(200, {}, { etag: "event-1" })
+        .get("/v2/projects")
+        .reply(200, {}));
+    const instance = createInstance();
+    await instance.get("/v2/projects");
+    await instance.get("/v2/projects");
+    expect(ifEventReached(1)).toBeUndefined();
+});
+test("ignores a mutating response without an etag", async () => {
+    record(nock(baseURL)
+        .post("/v2/projects")
+        .reply(201, {})
+        .get("/v2/projects")
+        .reply(200, {}));
+    const instance = createInstance();
+    await instance.post("/v2/projects", {});
+    await instance.get("/v2/projects");
+    expect(ifEventReached(1)).toBeUndefined();
+});
+test("tracks event ids per axios instance", async () => {
+    record(nock(baseURL)
+        .post("/v2/projects")
+        .reply(201, {}, { etag: "event-1" })
+        .get("/v2/projects")
+        .reply(200, {}));
+    await createInstance().post("/v2/projects", {});
+    await createInstance().get("/v2/projects");
+    expect(ifEventReached(1)).toBeUndefined();
+});
+test("configures the axios instance of an ApiClientBase and returns the client", async () => {
+    record(nock(baseURL)
+        .post("/v2/projects")
+        .reply(201, {}, { etag: "event-1" })
+        .get("/v2/projects")
+        .reply(200, {}));
+    const client = new TestClient(axios.create({ baseURL }));
+    const returned = withEventConsistencyHandling(client);
+    expect(returned).toBe(client);
+    await client.createProject();
+    await client.getProjects();
+    expect(ifEventReached(1)).toBe("event-1");
+});

package/dist/esm/testing/expectStatus.test.js

@@ -0,0 +1,26 @@
+import { AxiosHeaders } from "axios";
+import expectStatus from "./expectStatus.js";
+const makeResponse = (status) => ({
+    status,
+    statusText: "",
+    data: {},
+    headers: new AxiosHeaders(),
+    config: { headers: new AxiosHeaders() },
+    request: { some: "request" },
+    mediaType: "application/json",
+});
+test("passes for a matching status", () => {
+    expect(() => expectStatus(makeResponse(200), 200)).not.toThrow();
+});
+test("fails the surrounding expectation for a mismatching status", () => {
+    expect(() => expectStatus(makeResponse(404), 200)).toThrow();
+});
+test("reports the mismatch as a jest assertion, not an ApiClientError", () => {
+    expect(() => expectStatus(makeResponse(404), 200)).toThrow(expect.objectContaining({ matcherResult: expect.anything() }));
+});
+test("narrows the response type to the asserted status", () => {
+    const response = makeResponse(204);
+    expectStatus(response, 204);
+    const status = response.status;
+    expect(status).toBe(204);
+});

package/dist/esm/types/assertStatus.test.js

@@ -0,0 +1,46 @@
+import { AxiosHeaders } from "axios";
+import ApiClientError from "../core/ApiClientError.js";
+import assertStatus from "./assertStatus.js";
+import assertOneOfStatus from "./assertOneOfStatus.js";
+const makeResponse = (status) => ({
+    status,
+    statusText: "",
+    data: {},
+    headers: new AxiosHeaders(),
+    config: { headers: new AxiosHeaders() },
+    request: { some: "request" },
+    mediaType: "application/json",
+});
+describe("assertStatus", () => {
+    test("passes for a matching status", () => {
+        expect(() => assertStatus(makeResponse(200), 200)).not.toThrow();
+    });
+    test("throws an ApiClientError for a mismatching status", () => {
+        expect(() => assertStatus(makeResponse(404), 200)).toThrow(ApiClientError);
+    });
+    test("names both the expected and the received status", () => {
+        expect(() => assertStatus(makeResponse(404), 200)).toThrow("Unexpected response status (expected 200, got: 404)");
+    });
+});
+describe("assertOneOfStatus", () => {
+    test("passes when the status is one of the expected ones", () => {
+        expect(() => assertOneOfStatus(makeResponse(204), [200, 204])).not.toThrow();
+    });
+    test("throws when the status is not among the expected ones", () => {
+        expect(() => assertOneOfStatus(makeResponse(500), [200, 204])).toThrow("Unexpected response status (expected 200,204, got: 500)");
+    });
+    test("throws for an empty list of expected statuses", () => {
+        expect(() => assertOneOfStatus(makeResponse(200), [])).toThrow(ApiClientError);
+    });
+    test("attaches the response to the error but drops the request", () => {
+        let error;
+        try {
+            assertOneOfStatus(makeResponse(500), [200]);
+        }
+        catch (e) {
+            error = e;
+        }
+        expect(error?.response?.status).toBe(500);
+        expect(error?.request).toBeUndefined();
+    });
+});

package/dist/esm/types/extractTotalCountHeader.test.js

@@ -0,0 +1,38 @@
+import { AxiosHeaders } from "axios";
+import ApiClientError from "../core/ApiClientError.js";
+import { extractTotalCountHeader } from "./extractTotalCountHeader.js";
+const makeResponse = (headers, status = 200) => ({
+    status,
+    statusText: "",
+    data: {},
+    headers,
+    config: { headers: new AxiosHeaders() },
+    request: { some: "request" },
+    mediaType: "application/json",
+});
+const withTotalCount = (value) => new AxiosHeaders({ "x-pagination-totalcount": value });
+test("returns the total count as a number", () => {
+    expect(extractTotalCountHeader(makeResponse(withTotalCount("42")))).toBe(42);
+});
+test("reads the header case-insensitively", () => {
+    const headers = new AxiosHeaders({ "X-Pagination-TotalCount": "7" });
+    expect(extractTotalCountHeader(makeResponse(headers))).toBe(7);
+});
+test("returns zero for an empty result set", () => {
+    expect(extractTotalCountHeader(makeResponse(withTotalCount("0")))).toBe(0);
+});
+test("rejects a non-200 response before looking at the headers", () => {
+    expect(() => extractTotalCountHeader(makeResponse(withTotalCount("42"), 404))).toThrow("Unexpected response status (expected 200, got: 404)");
+});
+test("rejects plain-object headers that axios did not normalize", () => {
+    expect(() => extractTotalCountHeader(makeResponse({ "x-pagination-totalcount": "42" }))).toThrow("Expected headers to be of type AxiosHeaders");
+});
+test("rejects a missing header", () => {
+    expect(() => extractTotalCountHeader(makeResponse(new AxiosHeaders()))).toThrow("value is not of type string (is undefined instead)");
+});
+test("rejects a non-numeric header value", () => {
+    expect(() => extractTotalCountHeader(makeResponse(withTotalCount("not-a-number")))).toThrow("value is not a valid number");
+});
+test("throws an ApiClientError, not a plain Error", () => {
+    expect(() => extractTotalCountHeader(makeResponse(withTotalCount("not-a-number")))).toThrow(ApiClientError);
+});

package/dist/types/core/ApiClientError.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/core/OpenAPIPath.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/interceptors/accessToken.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/interceptors/consistencyHandling.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/testing/expectStatus.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/types/assertStatus.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/types/extractTotalCountHeader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/api-client-commons",
-  "version": "0.0.0-development-860f5d6-20261009",
+  "version": "0.0.0-development-fd38fc6-20261012",
   "author": "Mittwald CM Service GmbH & Co. KG <opensource@mittwald.de>",
   "type": "module",
   "description": "Common types and utilities for mittwald API clients",
@@ -37,7 +37,8 @@
     "build:clean": "run rimraf dist",
     "format": "run prettier --write '**/*.{ts,tsx,yaml,yml,json,md,mdx,js}'",
     "lint": "run eslint .",
-    "test": "node --experimental-vm-modules $(yarn bin jest)"
+    "test": "node --experimental-vm-modules $(yarn bin jest)",
+    "test:coverage": "run test --coverage"
   },
   "dependencies": {
     "@types/parse-path": "^7.0.3",
@@ -79,5 +80,5 @@
       "optional": true
     }
   },
-  "gitHead": "f97d7936d6b673d95cc2574c929c71a29b7db732"
+  "gitHead": "b4a8cf280ff804dee2c67e6c5919020cd0067c59"
 }