@coscine/api-client 3.25.0 → 3.26.0

package/README.md

@@ -8,6 +8,127 @@ The API Client library for JavaScript clients contains generated API connection
 
 ## 📖 Usage
 
+### Customize Axios (interceptors, headers)
+The library offers two ways to customize Axios behavior:
+1) Reuse the shared instance that powers the default API exports.
+2) Provide your own Axios instance when creating APIs.
+
+Choose the shared instance if you want all default exports (e.g. `AccountApi`) to pick up your interceptors automatically. Use a custom instance if you need isolated behavior, different base config, or multiple clients in the same app.
+
+```ts
+import { apiClientAxios, AccountApi } from '@coscine/api-client';
+
+apiClientAxios.interceptors.request.use((config) => {
+  // add headers/logging/etc
+  return config;
+});
+
+// Default exports use the shared instance, so interceptors apply here.
+AccountApi.someCall();
+```
+
+```ts
+import axios from 'axios';
+import { createApis } from '@coscine/api-client';
+
+const customAxios = axios.create({ withCredentials: true });
+customAxios.interceptors.request.use((config) => config);
+
+// APIs created this way use only your instance.
+const apis = createApis(customAxios);
+apis.AccountApi.someCall();
+```
+
+### Playwright-friendly endpoint matching
+For tests, you can resolve the exact endpoint path behind a generated API method without manual hardcoding.
+
+```ts
+import { apiParamCreators, describeEndpoint, makeRequestMatcher } from '@coscine/api-client';
+
+const endpoint = await describeEndpoint(
+  apiParamCreators.SelfApiAxiosParamCreator().getCurrentUser()
+);
+const isGetCurrentUser = makeRequestMatcher(endpoint);
+
+await page.route('**/*', (route) => {
+  if (isGetCurrentUser(route.request())) {
+    return route.fulfill({ status: 200, json: userFixture });
+  }
+  return route.continue();
+});
+```
+
+#### Example: mock API + waitForResponse helpers
+This pattern builds request/response matchers from `testing.ts` helpers and reuses them for routing and `waitForResponse`.
+
+```ts
+import type { Page, Response, Route } from '@playwright/test';
+import {
+  apiParamCreators,
+  describeEndpoint,
+  makeRequestMatcher
+} from '@coscine/api-client';
+
+type ApiMockData = {
+  projects?: unknown[];
+};
+
+const jsonHandler = (status: number, data: unknown) => (route: Route) =>
+  route.fulfill({ status, json: data });
+
+export async function createResponseMatchers(basePath?: string) {
+  const endpoints = await Promise.all([
+    describeEndpoint(apiParamCreators.ProjectApiAxiosParamCreator().getProjects(), basePath),
+  ]);
+
+  const [projectsMatcher] = endpoints.map(makeRequestMatcher);
+
+  return {
+    isGetProjects: (res: Response) => projectsMatcher(res.request()) && res.status() === 200,
+  };
+}
+
+export async function createMockDefinitions(data: ApiMockData = {}, basePath?: string) {
+  const mocks = [
+    {
+      endpoint: apiParamCreators.ProjectApiAxiosParamCreator().getProjects(),
+      handler: jsonHandler(200, { data: data.projects ?? [] }),
+    },
+  ];
+
+  const endpoints = await Promise.all(
+    mocks.map((m) => describeEndpoint(m.endpoint, basePath))
+  );
+
+  return mocks.map((mock, i) => ({
+    matcher: makeRequestMatcher(endpoints[i]),
+    handler: mock.handler,
+  }));
+}
+
+export async function mockApi(page: Page, data: ApiMockData = {}, basePath?: string) {
+  const [mocks, matchers] = await Promise.all([
+    createMockDefinitions(data, basePath),
+    createResponseMatchers(basePath),
+  ]);
+
+  await page.route('**/api/**', (route) => {
+    for (const mock of mocks) {
+      if (mock.matcher(route.request())) {
+        return mock.handler(route);
+      }
+    }
+    return route.fulfill({ status: 404, json: { message: 'Unhandled' } });
+  });
+
+  return matchers;
+}
+
+// Usage:
+// const { isGetProjects } = await mockApi(page, { projects: [] }, 'https://coscine.test/coscine');
+// await Promise.all([page.waitForResponse(isGetProjects), page.goto('/')]);
+```
+
 ### How to generate a new API Client library version
 * Start the API on the branch with the changes you want to see in the API Client library
 * Open the API Client library with SSH (not in a Container) on a new branch
@@ -27,11 +148,18 @@ The API Client library for JavaScript clients contains generated API connection
 * `yarn build`
 
 ### Testing
-* `yarn test`
+* `yarn test` (recommended with Yarn PnP)
 
 ### Linting
 * `yarn lint:fix`
 
+### VS Code + Yarn PnP
+If you see missing module errors in VS Code (e.g., `Cannot find module 'axios'`), install deps and the Yarn SDKs:
+* `yarn install`
+* `yarn dlx @yarnpkg/sdks vscode`
+
+Then in VS Code: restart the TypeScript server and select the workspace TypeScript version.
+
 ### Links
 Bundles the output of [CodeGen](https://git.rwth-aachen.de/coscine/backend/scripts/codegen).
 
@@ -62,5 +190,5 @@ By following these simple steps, you can get the support you need to use Coscine
 
 ## 📦 Release & Changelog
 
-External users can find the _Releases and Changelog_ inside each project's repository. The repository contains a section for Releases (`Deployments > Releases`), where users can find the latest release changelog and source. Withing the Changelog you can find a list of all the changes made in that particular release and version.  
+External users can find the _Releases and Changelog_ inside each project's repository. The repository contains a section for Releases (`Deployments > Releases`), where users can find the latest release changelog and source. Within the Changelog you can find a list of all the changes made in that particular release and version.  
 By regularly checking for new releases and changes in the Changelog, you can stay up-to-date with the latest improvements and bug fixes by our team and community!