refactor integration config

.changeset/afraid-rings-wave.md

@@ -0,0 +1,7 @@
+---
+'@o2s/configs.integrations': minor
+'@o2s/api-harmonization': minor
+'@o2s/framework': minor
+---
+
+Refactored integration configuration by consolidating 18 individual model files into a single typed config with a createIntegrationConfig helper that validates domain bindings at runtime.

apps/api-harmonization/src/app.config.ts

@@ -1,45 +1,7 @@
-import {
-    Articles,
-    Auth,
-    BillingAccounts,
-    CMS,
-    Cache,
-    Carts,
-    Checkout,
-    Customers,
-    Invoices,
-    Notifications,
-    Orders,
-    Organizations,
-    Payments,
-    Products,
-    Resources,
-    Search,
-    Tickets,
-    Users,
-} from '@o2s/configs.integrations';
+import { integrations } from '@o2s/configs.integrations';
 
 import { ApiConfig } from '@o2s/framework/modules';
 
 export const AppConfig: ApiConfig = {
-    integrations: {
-        users: Users.UsersIntegrationConfig,
-        organizations: Organizations.OrganizationsIntegrationConfig,
-        tickets: Tickets.TicketsIntegrationConfig,
-        notifications: Notifications.NotificationsIntegrationConfig,
-        articles: Articles.ArticlesIntegrationConfig,
-        resources: Resources.ResourcesIntegrationConfig,
-        invoices: Invoices.InvoicesIntegrationConfig,
-        cms: CMS.CmsIntegrationConfig,
-        cache: Cache.CacheIntegrationConfig,
-        billingAccounts: BillingAccounts.BillingAccountsIntegrationConfig,
-        search: Search.SearchIntegrationConfig,
-        products: Products.ProductsIntegrationConfig,
-        orders: Orders.OrdersIntegrationConfig,
-        carts: Carts.CartsIntegrationConfig,
-        customers: Customers.CustomersIntegrationConfig,
-        payments: Payments.PaymentsIntegrationConfig,
-        checkout: Checkout.CheckoutIntegrationConfig,
-        auth: Auth.AuthIntegrationConfig,
-    },
+    integrations,
 };

apps/docs/docs/guides/create-new-block/integrations.md

@@ -243,20 +243,31 @@ getPage(options: CMS.Request.GetCmsPageParams) {
 Finally, the last thing is to switch the CMS integration in the API Harmonization server. Firstly, let's install it:
 
 ```shell
-npm install @o2s/integrations.custom-cms --workspace=@o2s/api-harmonization
+npm install @o2s/integrations.custom-cms --workspace=@o2s/configs.integrations
 ```
 
-Now we can replace the package within the `apps/api-harmonization/src/models/cms.ts` file:
+Now open `packages/configs/integrations/src/config.ts` and:
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.mocked/integration';
-```
+1. Add the new integration import:
 
-with
+    ```typescript
+    import * as CustomCms from '@o2s/integrations.custom-cms/integration';
+    ```
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.custom-cms/integration';
-```
+2. Update the `cms` domain assignment in the `createIntegrationConfig` call:
+
+    ```typescript
+    const result = createIntegrationConfig({
+        cms: CustomCms,
+        // ... other domains remain unchanged
+    });
+    ```
+
+3. Update the matching `export import` type alias:
+
+    ```typescript
+    export import CMS = CustomCms.Integration.CMS;
+    ```
 
 ### Testing the API
 

apps/docs/docs/guides/integrations/switching-integrations.md

@@ -14,26 +14,37 @@ Thanks to the normalized data model, replacing an integration is completely tran
 
 ## Integration config
 
-Inside the `packages/configs/integrations/src/models` there are a number of files that represent all the framework modules of the `@o2s/framework` package. Inside each of them are local exports that define which integration is used for that module.
+All integration assignments are defined in a single file: `packages/configs/integrations/src/config.ts`. This file uses the `createIntegrationConfig` helper from `@o2s/framework/config` to map each framework domain to an integration module, with runtime validation that each integration provides the domain it's assigned to.
 
-For example, the `packages/configs/integrations/src/models/cms.ts` file that is pre-configured with a [mocked integration](../../integrations/mocked/mocked.md) looks like this:
+The default configuration, pre-configured with a [mocked integration](../../integrations/mocked/mocked.md), looks like this:
 
-```typescript title="integration config for the cms module"
-import { Config, Integration } from '@o2s/integrations.mocked/integration';
+```typescript title="packages/configs/integrations/src/config.ts"
+import * as Mocked from '@o2s/integrations.mocked/integration';
 
-import { ApiConfig } from '@o2s/framework/modules';
+import { createIntegrationConfig } from '@o2s/framework/config';
+import type { ApiConfig } from '@o2s/framework/modules';
 
-export const CmsIntegrationConfig: ApiConfig['integrations']['cms'] = Config.cms!;
+const result = createIntegrationConfig({
+    cms: Mocked,
+    tickets: Mocked,
+    articles: Mocked,
+    notifications: Mocked,
+    // ... all other domains
+});
 
-export import Service = Integration.CMS.Service;
-export import Request = Integration.CMS.Request;
-export import Model = Integration.CMS.Model;
+export const integrations: ApiConfig['integrations'] = result.integrations;
+
+// Type exports for consumers
+export import CMS = Mocked.Integration.CMS;
+export import Tickets = Mocked.Integration.Tickets;
+export import Articles = Mocked.Integration.Articles;
+// ... all other domains
 ```
 
-These files export four things:
+This file exports two things:
 
-1. Integration config, that is then propagated to the framework modules to let them know what implementation to actually use. This is done via the `apps/api-harmonization/app.config.ts` file that does not have to be modified at all when switching integrations.
-2. A service, that is used in other blocks and modules:
+1. Integration config (`integrations`), that is propagated to the framework modules via `apps/api-harmonization/app.config.ts`. This file does not need to be modified when switching integrations.
+2. Type namespaces (Services, Requests, Models) used in blocks and modules:
 
     ```typescript title="usage of services within page.service.ts"
     import { Articles, Auth, CMS } from '@o2s/configs.integrations';
@@ -67,22 +78,35 @@ These files export four things:
 
 In order to switch an integration for a given framework module (like a CMS) all that is required is to:
 
-1. Install a new integration as a dependency of the `api-harmonization` app:
+1. Install a new integration as a dependency of the `@o2s/configs.integrations` package:
 
     ```shell
     npm install @o2s/integrations.strapi-cms --workspace=@o2s/configs.integrations
     ```
 
-2. Replace the previous import with the newly installed package in ``packages/configs/integrations/src/models/cms.ts` (or any other module):
+2. Open `packages/configs/integrations/src/config.ts` and:
+
+    a. Import the new integration module:
+
+    ```typescript
+    import * as Strapi from '@o2s/integrations.strapi-cms/integration';
+    ```
+
+    b. Change the domain assignment from `Mocked` to the new integration:
 
     ```typescript
-    import { Config, Integration } from '@o2s/integrations.mocked/integration';
+    const result = createIntegrationConfig({
+        cms: Strapi,     // changed from Mocked
+        articles: Strapi, // changed from Mocked
+        // ... other domains remain unchanged
+    });
     ```
 
-    into
+    c. Update the matching `export import` type aliases:
 
     ```typescript
-    import { Config, Integration } from '@o2s/integrations.strapi-cms/integration';
+    export import CMS = Strapi.Integration.CMS;
+    export import Articles = Strapi.Integration.Articles;
     ```
 
 Once that is done, the application will start using the new integration.

apps/docs/docs/integrations/articles/zendesk/how-to-setup.md

@@ -22,39 +22,36 @@ This command installs the integration package in the configs workspace, ensuring
 
 After installing the package, you need to configure the integration in the `@o2s/configs.integrations` package. This tells the framework to use Zendesk instead of the default mocked integration.
 
-### Step 1: Update the articles integration config
+### Step 1: Update the integration config
 
-Open the file `packages/configs/integrations/src/models/articles.ts` and replace the import:
+All integration assignments are configured in a single file: `packages/configs/integrations/src/config.ts`.
 
-**Before (using mocked integration):**
+Open this file and make the following changes:
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.mocked/integration';
-```
-
-**After (using Zendesk integration):**
-
-```typescript
-import { Config, Integration } from '@o2s/integrations.zendesk/integration';
-```
+1. **Add the Zendesk import:**
 
-The complete file should look like this:
+    ```typescript
+    import * as Zendesk from '@o2s/integrations.zendesk/integration';
+    ```
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.zendesk/integration';
+2. **Update the `articles` domain assignment** in the `createIntegrationConfig` call:
 
-import { ApiConfig } from '@o2s/framework/modules';
+    ```typescript
+    const result = createIntegrationConfig({
+        articles: Zendesk,
+        // ... other domains remain unchanged
+    });
+    ```
 
-export const ArticlesIntegrationConfig: ApiConfig['integrations']['articles'] = Config.articles!;
+3. **Update the matching `export import` type alias:**
 
-export import Service = Integration.Articles.Service;
-export import Request = Integration.Articles.Request;
-export import Model = Integration.Articles.Model;
-```
+    ```typescript
+    export import Articles = Zendesk.Integration.Articles;
+    ```
 
 ### Step 2: Verify AppConfig
 
-The `AppConfig` in `apps/api-harmonization/src/app.config.ts` should already reference `Articles.ArticlesIntegrationConfig`. You don't need to modify this file - it automatically uses the configuration from `@o2s/configs.integrations`.
+The `AppConfig` in `apps/api-harmonization/src/app.config.ts` already imports from `@o2s/configs.integrations`. You don't need to modify this file.
 
 ## Set environment variables
 

apps/docs/docs/integrations/cache/redis/how-to-setup.md

@@ -26,37 +26,36 @@ Consider managed services: [Redis Cloud](https://redis.com/cloud), [AWS ElastiCa
 
 After installing the package, you need to configure the integration in the `@o2s/configs.integrations` package. This tells the framework to use Redis Cache instead of the default mocked integration.
 
-### Step 1: Update the cache integration config
+### Step 1: Update the integration config
 
-Open the file `packages/configs/integrations/src/models/cache.ts` and replace the import:
+All integration assignments are configured in a single file: `packages/configs/integrations/src/config.ts`.
 
-**Before (using mocked integration):**
+Open this file and make the following changes:
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.mocked/integration';
-```
-
-**After (using Redis Cache integration):**
+1. **Add the Redis import:**
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.redis/integration';
-```
+    ```typescript
+    import * as Redis from '@o2s/integrations.redis/integration';
+    ```
 
-The complete file should look like this:
+2. **Update the `cache` domain assignment** in the `createIntegrationConfig` call:
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.redis/integration';
+    ```typescript
+    const result = createIntegrationConfig({
+        cache: Redis,
+        // ... other domains remain unchanged
+    });
+    ```
 
-import { ApiConfig } from '@o2s/framework/modules';
+3. **Update the matching `export import` type alias:**
 
-export const CacheIntegrationConfig: ApiConfig['integrations']['cache'] = Config.cache!;
-
-export import Service = Integration.Cache.Service;
-```
+    ```typescript
+    export import Cache = Redis.Integration.Cache;
+    ```
 
 ### Step 2: Verify AppConfig
 
-The `AppConfig` in `apps/api-harmonization/src/app.config.ts` should already reference `Cache.CacheIntegrationConfig`. You don't need to modify this file - it automatically uses the configuration from `@o2s/configs.integrations`.
+The `AppConfig` in `apps/api-harmonization/src/app.config.ts` already imports from `@o2s/configs.integrations`. You don't need to modify this file.
 
 ## Configure environment variables
 

apps/docs/docs/integrations/cms/contentful/how-to-setup.md

@@ -22,55 +22,38 @@ This command installs the integration package in the integrations config workspa
 
 After installing the package, you need to configure the integration in the `@o2s/configs.integrations` package. This tells the framework to use Contentful CMS instead of the default mocked integration.
 
-### Step 1: Update the CMS integration config
+### Step 1: Update the integration config
 
-Open the file `packages/configs/integrations/src/models/cms.ts` and replace the import:
+All integration assignments are configured in a single file: `packages/configs/integrations/src/config.ts`.
 
-**Before (using mocked integration):**
+Open this file and make the following changes:
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.mocked/integration';
-```
-
-**After (using Contentful CMS integration):**
-
-```typescript
-import { Config, Integration } from '@o2s/integrations.contentful-cms/integration';
-```
-
-The complete file should look like this:
-
-```typescript
-import { Config, Integration } from '@o2s/integrations.contentful-cms/integration';
+1. **Add the Contentful CMS import:**
 
-import { ApiConfig } from '@o2s/framework/modules';
+    ```typescript
+    import * as Contentful from '@o2s/integrations.contentful-cms/integration';
+    ```
 
-export const CmsIntegrationConfig: ApiConfig['integrations']['cms'] = Config.cms!;
+2. **Update domain assignments** in the `createIntegrationConfig` call — change `cms` (and optionally `articles`) from `Mocked` to `Contentful`:
 
-export import Service = Integration.CMS.Service;
-export import Request = Integration.CMS.Request;
-export import Model = Integration.CMS.Model;
-```
-
-### Step 2: Update the Articles integration config (if using articles)
-
-If you plan to use articles functionality, you also need to update `packages/configs/integrations/src/models/articles.ts`:
+    ```typescript
+    const result = createIntegrationConfig({
+        cms: Contentful,
+        articles: Contentful,  // if using articles functionality
+        // ... other domains remain unchanged
+    });
+    ```
 
-```typescript
-import { Config, Integration } from '@o2s/integrations.contentful-cms/integration';
+3. **Update the matching `export import` type aliases:**
 
-import { ApiConfig } from '@o2s/framework/modules';
-
-export const ArticlesIntegrationConfig: ApiConfig['integrations']['articles'] = Config.articles!;
-
-export import Service = Integration.Articles.Service;
-export import Request = Integration.Articles.Request;
-export import Model = Integration.Articles.Model;
-```
+    ```typescript
+    export import CMS = Contentful.Integration.CMS;
+    export import Articles = Contentful.Integration.Articles;  // if using articles
+    ```
 
-### Step 3: Verify AppConfig
+### Step 2: Verify AppConfig
 
-The `AppConfig` in `apps/api-harmonization/src/app.config.ts` should already reference the integration configs. You don't need to modify this file - it automatically uses the configuration from `@o2s/configs.integrations`.
+The `AppConfig` in `apps/api-harmonization/src/app.config.ts` already imports from `@o2s/configs.integrations`. You don't need to modify this file.
 
 ## Set env variables