fix: return ApiClient from getApiClient helper

.changeset/slow-jokes-kneel.md

@@ -0,0 +1,12 @@
+---
+"@vue-storefront/middleware": patch
+---
+
+`getApiClient` helper returns now ApiClient interface
+
+Usage:
+
+```typescript
+const sapcc = context.getApiClient<Api, Config, Client>("sapcc");
+// typeof sapcc === ApiClient<Api, Config, Client>
+```

docs/content/3.middleware/2.guides/4.orchestration.md

@@ -207,3 +207,53 @@ export const integrations = {
   },
 };
 ```
+
+## TypeScript Support
+
+`getApiClient` helper returns the `ApiClient` interface, which is a generic type. It takes three type arguments:
+
+- `Api` - the type of the API object returned by the integration,
+- `Config` - the type of the configuration object passed to the integration,
+- `Client` - the type of the HTTP client object returned by the integration.
+
+Usually, an integration exports those types. For example, the `sapcc` integration exports the following types:
+
+```typescript
+import {
+  Endpoints,
+  MiddlewareConfig,
+  AxiosInstance,
+} from "@vsf-enterprise/sapcc-api";
+```
+
+### Endpoints and the `context` object
+
+Each method of the integration api client contains the `context` object as the first argument. However, the `context` is not something that is passed by the developer to the method during the call. This is because the `context` is passed automatically by the `@vue-storefront/middleware` package logic. Because of this, the `context` object should be excluded from the `Api` interface passed to the `ApiClient` type.
+
+To achieve that, the `@vue-storefront/middleware` export the interface `ContextualizedApi`, which basically removes the context from the API.
+
+### Example
+
+Let's take a look at the `sapcc` integration. The `sapcc` integration exports the following types:
+
+```typescript
+import {
+  Endpoints,
+  MiddlewareConfig,
+  AxiosInstance,
+} from "@vsf-enterprise/sapcc-api";
+import { ContextualizedApi } from "@vue-storefront/middleware";
+
+// ...
+
+const sapcc = context.getApiClient<
+  ContextualizedApi<Endpoints>,
+  MiddlewareConfig,
+  AxiosInstance
+>("sapcc");
+
+// sapcc.api now is aware of the SAPCC methods that are not expecting the `context` object
+// sapcc.config is now aware of the SAPCC configuration object
+// sapcc.client is now aware of the SAPCC HTTP client object
+```
+

packages/middleware/src/types/common.ts

@@ -7,7 +7,7 @@ import {
   CustomQueryFunction,
   TObject,
 } from "./base";
-import { ApiClientConfig, ApiClientFactory } from "./server";
+import { ApiClient, ApiClientConfig, ApiClientFactory } from "./server";
 
 export type ApiMethods = Record<string, ApiClientMethod>;
 export type ApiMethodsFactory<
@@ -117,7 +117,9 @@ export interface MiddlewareContext<API extends ApiMethods = any> {
   extensions: ApiClientExtension<API>[];
   customQueries: Record<string, CustomQueryFunction>;
   integrations: IntegrationsLoaded;
-  getApiClient: (integrationName: string) => any;
+  getApiClient: <Api = any, Config = any, Client = any>(
+    integrationName: string
+  ) => ApiClient<Api, Config, Client>;
 }
 
 export type ExtendQuery = <T extends ContextQuery<string>, Key extends keyof T>(