feat: Adds support for filtering language variants (early access)

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [7.11.0-4](https://github.com/kontent-ai/management-sdk-js/compare/v7.11.0-3...v7.11.0-4) (2025-09-18)
+
+## [7.11.0-3](https://github.com/kontent-ai/management-sdk-js/compare/v7.11.0-2...v7.11.0-3) (2025-09-18)
+
+## [7.11.0-2](https://github.com/kontent-ai/management-sdk-js/compare/v7.11.0-1...v7.11.0-2) (2025-09-11)
+
+## [7.11.0-1](https://github.com/kontent-ai/management-sdk-js/compare/v7.11.0-0...v7.11.0-1) (2025-09-11)
+
+## [7.11.0-0](https://github.com/kontent-ai/management-sdk-js/compare/v7.10.0...v7.11.0-0) (2025-09-11)
+
+
+### Features
+
+* adds support for early access language variant filter method ([d0f404f](https://github.com/kontent-ai/management-sdk-js/commit/d0f404f33b202862ba475e37e75a000b70ad7c5b))
+* updates deps ([bc52064](https://github.com/kontent-ai/management-sdk-js/commit/bc52064c8615c036e49e540a834f14909c1d6876))
+
 ## [7.10.0](https://github.com/kontent-ai/management-sdk-js/compare/v7.9.1...v7.10.0) (2025-08-05)
 
 

README.md

@@ -118,6 +118,39 @@ const client = createManagementClient({
 | `retryStrategy` | undefined                             | Retry strategy configuration. If not set, default strategy is used.                                                                                                 |
 | `httpService`   | HttpService                           | Used to inject implementation of `IHttpService` used to make HTTP request across network. Can also be useful for testing purposes by returning specified responses. |
 
+### Early access
+
+Some SDK queries are available under the `earlyAccess` namespace. These APIs are experimental and may change without a major version bump. Use with caution in production.
+
+- Access early access features via `client.earlyAccess`
+- Endpoints, request/response shapes, and availability may evolve
+
+#### Example: Filter language variants
+
+```typescript
+import { createManagementClient } from '@kontent-ai/management-sdk';
+
+const client = createManagementClient({
+    environmentId: 'xxx',
+    apiKey: 'yyy'
+});
+
+const response = await client
+    .earlyAccess
+    .filterLanguageVariants()
+    .withData({
+        filters: {
+            search_phrase: 'home'
+        },
+        order: {
+            by: 'last_modified',
+            direction: 'desc'
+        },
+        include_content: false
+    })
+    .toPromise();
+```
+
 ### Handling API Management Errors
 
 See the [error section in Management API reference](https://kontent.ai/learn/reference/management-api-v2#section/Guidelines-on-handling-changes) for infofmation about status codes and error messages.

lib/client/imanagement-client.interface.ts

@@ -146,7 +146,8 @@ import {
     GetCustomAppQuery,
     ListCustomAppsQuery,
     ModifyCustomAppQuery,
-    DeleteCustomAppQuery
+    DeleteCustomAppQuery,
+    FilterLanguageVariantsQuery
 } from '../queries';
 import { IMappingService } from '../services';
 import { GetEnvironmentCloningStateQuery } from '../queries/environments';
@@ -155,10 +156,20 @@ import { EnvironmentModels } from '../models/environments/environment.models';
 import { CloneEnvironmentQuery } from '../queries/environments/clone-environment-query';
 import { MarkEnvironmentAsProductionQuery } from '../queries/environments/mark-environment-as-production-query';
 import { ModifyEnvironmentQuery } from '../queries/environments/modify-environment-query';
+import { LanguageVariantModels } from '../models';
+
+export interface IEarlyAccess {
+    filterLanguageVariants(): DataQuery<FilterLanguageVariantsQuery, LanguageVariantModels.IFilterLanguageVariantsData>
+}
 
 export interface IManagementClient<TCancelToken> {
     mappingService: IMappingService;
 
+    /**
+     * Early access queries. Use with caution as these are not yet stable and may change.
+     */
+    earlyAccess: IEarlyAccess;
+
     /**
      * Creates cancel token
      */

lib/client/index.ts

@@ -1,3 +1,3 @@
 export * from './imanagement-client.interface';
 export * from './management-client.class';
-export * from './management-client.factory';
+export * from './management-client.factories';

lib/client/management-client.class.ts

@@ -5,6 +5,7 @@ import {
     CollectionModels,
     CustomAppModels,
     LanguageVariantElementsBuilder,
+    LanguageVariantModels,
     PreviewModels,
     ProjectUserModels,
     SpaceModels,
@@ -150,11 +151,12 @@ import {
     CustomAppsIdentifierQuery,
     GetCustomAppQuery,
     ModifyCustomAppQuery,
-    DeleteCustomAppQuery
+    DeleteCustomAppQuery,
+    FilterLanguageVariantsQuery
 } from '../queries';
 import { sdkInfo } from '../sdk-info.generated';
 import { ManagementQueryService, IMappingService, MappingService } from '../services';
-import { IManagementClient } from './imanagement-client.interface';
+import { IEarlyAccess, IManagementClient } from './imanagement-client.interface';
 import { CancelToken } from 'axios';
 import { GetEnvironmentCloningStateQuery } from '../queries/environments';
 import { DeleteEnvironmentQuery } from '../queries/environments/delete-environment-query';
@@ -164,7 +166,7 @@ import { MarkEnvironmentAsProductionQuery } from '../queries/environments/mark-e
 import { ModifyEnvironmentQuery } from '../queries/environments/modify-environment-query';
 
 export class ManagementClient implements IManagementClient<CancelToken> {
-    private readonly queryService: ManagementQueryService;
+    protected readonly queryService: ManagementQueryService;
     private httpService: IHttpService<CancelToken>;
 
     public readonly mappingService: IMappingService = new MappingService();
@@ -180,6 +182,16 @@ export class ManagementClient implements IManagementClient<CancelToken> {
         this.httpService = httpService;
     }
 
+    earlyAccess: IEarlyAccess = {
+        filterLanguageVariants: () => {
+            return new DataQuery<FilterLanguageVariantsQuery, LanguageVariantModels.IFilterLanguageVariantsData>(
+                this.config,
+                this.queryService,
+                (config, queryService, data) => new FilterLanguageVariantsQuery(config, queryService, data)
+            );
+        }
+    }
+
     createCancelToken(): IHttpCancelRequestToken<CancelToken> {
         return this.httpService.createCancelToken();
     }

lib/client/management-client.factory.ts → lib/client/management-client.factories.ts

@@ -4,3 +4,4 @@ import { IManagementClientConfig } from '../config';
 export function createManagementClient(config: IManagementClientConfig): ManagementClient {
     return new ManagementClient(config);
 }
+

lib/contracts/content-item-contracts.ts

@@ -5,15 +5,12 @@ export namespace ContentItemContracts {
         id: string;
         name: string;
         codename: string;
-        type: {
-            id?: string;
-            codename?: string;
-            external_id?: string;
-        };
+        type: SharedContracts.IIdReferenceContract;
         external_id?: string;
-        last_modified: Date;
+        last_modified: string;
         spaces: SharedContracts.IIdReferenceContract[];
-        collection: SharedContracts.IReferenceObjectContract;
+        collection: SharedContracts.IIdReferenceContract;
+        sitemap_locations?: SharedContracts.IIdReferenceContract[];
     }
 
     export interface IContentItemsListingResponseContract {

lib/contracts/element-contracts.ts

@@ -7,30 +7,31 @@ export namespace ElementContracts {
         codename: string;
     }
 
+    export type ElementValueContract = string | number | SharedContracts.IIdReferenceContract[];
+
     export type IContentTypeElementModeTypeContract = 'single' | 'multiple';
 
     export interface IContentTypeElementContract {
         name: string;
         type: string;
-
         id?: string;
         external_id?: string;
         codename?: string;
         content_group?: SharedContracts.IReferenceObjectContract;
     }
 
     export interface IContentItemElementContract {
-        element: SharedContracts.IReferenceObjectContract;
-        value: string | number | SharedContracts.IReferenceObjectContract[];
+        element: SharedContracts.IIdReferenceContract;
+        value: ElementValueContract;
         components?: IContentItemElementComponent[];
-        searchableValue?: string;
-        display_timezone?: string;
+        searchable_value?: string | null;
+        display_timezone?: string | null;
         mode?: 'autogenerated' | 'custom';
     }
 
     export interface IContentItemElementComponent {
         id: string;
-        type: SharedContracts.IReferenceObjectContract;
+        type: SharedContracts.IIdReferenceContract;
         elements: IContentItemElementContract[];
     }
 }

lib/contracts/language-variant-contracts.ts

@@ -1,18 +1,20 @@
 import { ElementContracts } from './element-contracts';
 import { SharedContracts } from './shared-contracts';
 import { LanguageVariantElements } from '../models';
+import { ContentItemContracts } from './content-item-contracts';
 
 export namespace LanguageVariantContracts {
     export interface ILanguageVariantModelContract {
-        item: SharedContracts.IReferenceObjectContract;
+        item: SharedContracts.IIdReferenceContract;
         elements: ElementContracts.IContentItemElementContract[];
-        language: SharedContracts.IReferenceObjectContract;
+        language: SharedContracts.IIdReferenceContract;
         last_modified: string;
         workflow: ILanguageVariantWorkflowContract;
         schedule: ILanguageVariantSchedule;
         due_date: ILanguageVariantDueDate;
         contributors: SharedContracts.UserReferenceContract[];
-        note?: string;
+        workflow_step: SharedContracts.IIdReferenceContract;
+        note?: string | null;
     }
 
     export interface ILanguageVariantModelsContract {
@@ -25,7 +27,7 @@ export namespace LanguageVariantContracts {
         due_date: ILanguageVariantDueDate;
     }
 
-    export interface IListLanguageVariantsOfItemResponseContract extends ILanguageVariantModelContract {}
+    export interface IListLanguageVariantsOfItemResponseContract extends ILanguageVariantModelContract { }
 
     export interface IUpsertLanguageVariantPostContract {
         elements: LanguageVariantElements.ILanguageVariantElementBase[];
@@ -44,6 +46,16 @@ export namespace LanguageVariantContracts {
         pagination: SharedContracts.IPaginationModelContract;
     }
 
+    export interface IFilterLanguageVariantsResponseContract {
+        data: IFilterLanguageVariantsResponseDataContract[];
+        pagination: SharedContracts.IPaginationModelContract;
+    }
+
+    export interface IFilterLanguageVariantsResponseDataContract {
+        item: ContentItemContracts.IContentItemModelContract,
+        variant: ILanguageVariantModelContract,
+    }
+
     export interface IListLanguageVariantsBySpaceResponseContract {
         variants: ILanguageVariantModelContract[];
         pagination: SharedContracts.IPaginationModelContract;
@@ -70,7 +82,7 @@ export namespace LanguageVariantContracts {
         value: string | null;
     }
 
-    export interface IUpsertLanguageVariantResponseContract extends ILanguageVariantModelContract {}
+    export interface IUpsertLanguageVariantResponseContract extends ILanguageVariantModelContract { }
 
-    export interface IViewLanguageVariantResponseContract extends ILanguageVariantModelContract {}
+    export interface IViewLanguageVariantResponseContract extends ILanguageVariantModelContract { }
 }

lib/contracts/shared-contracts.ts

@@ -14,13 +14,13 @@ export namespace SharedContracts {
 
     export type UserReferenceDataContract =
         | {
-              id: string;
-              email?: never;
-          }
+            id: string;
+            email?: never;
+        }
         | {
-              id?: never;
-              email: string;
-          };
+            id?: never;
+            email: string;
+        };
 
     export interface ICodenameIdReferenceContract {
         id?: string;
@@ -42,5 +42,21 @@ export namespace SharedContracts {
         validation_errors?: IValidationErrorContract[];
     }
 
-    export interface IEmptyResponseContract {}
+    export interface IResponseWorkflowStepsReferenceContract {
+        workflow_identifier: IIdReferenceContract;
+        step_identifier: IIdReferenceContract;
+    }
+
+    export interface IRequestWorkflowStepsReferenceContract {
+        workflow_identifier: IReferenceObjectContract;
+        step_identifiers: IReferenceObjectContract[];
+    }
+
+    export interface ITaxonomyGroupReferenceContract {
+        taxonomy_identifier: IReferenceObjectContract;
+        term_identifiers?: IReferenceObjectContract[];
+        include_uncategorized?: boolean;
+    }
+
+    export interface IEmptyResponseContract { }
 }

lib/mappers/content-items-mapper.ts

@@ -1,5 +1,4 @@
 import { IResponse } from '@kontent-ai/core-sdk';
-
 import { ContentItemContracts } from '../contracts';
 import { ContentItemModels } from '../models';
 import { ContentItemResponses } from '../responses';
@@ -66,8 +65,9 @@ export class ContentItemsMapper extends BaseMapper {
             lastModified: new Date(rawItem.last_modified),
             name: rawItem.name,
             type: rawItem.type,
-            collection: super.mapReference(rawItem.collection),
+            collection: super.mapIdReference(rawItem.collection),
             spaces: rawItem.spaces.map((m) => super.mapIdReference(m)),
+            sitemapLocations: rawItem.sitemap_locations?.map((m) => super.mapIdReference(m)) ?? [],
             _raw: rawItem
         });
     }

lib/mappers/elements-mapper.ts

@@ -28,7 +28,7 @@ export class ElementsMapper extends BaseMapper {
             components: this.mapElementComponents(rawElement.components ?? []),
             display_timezone: rawElement.display_timezone,
             mode: rawElement.mode,
-            searchableValue: rawElement.searchableValue,
+            searchableValue: rawElement.searchable_value,
             _raw: rawElement
         });
     }

lib/mappers/language-variant-mapper.ts

@@ -56,6 +56,20 @@ export class LanguageVariantMapper extends BaseMapper {
         );
     }
 
+    mapFilterLanguageVariantsResponse(
+        response: IResponse<LanguageVariantContracts.IFilterLanguageVariantsResponseContract>
+    ): LanguageVariantResponses.FilterLanguageVariantsResponse {
+        return new LanguageVariantResponses.FilterLanguageVariantsResponse(
+            super.mapResponseDebug(response),
+            response.data,
+            {
+                items: response.data.data,
+                pagination: super.mapPagination(response.data.pagination)
+            }
+        );
+    }
+
+
     mapLanguageVariantsBySpaceResponse(
         response: IResponse<LanguageVariantContracts.IListLanguageVariantsBySpaceResponseContract>
     ): LanguageVariantResponses.ListLanguageVariantsBySpaceResponse {

lib/models/content-items/content-item.models.ts

@@ -6,28 +6,24 @@ export namespace ContentItemModels {
         public id!: string;
         public name!: string;
         public codename!: string;
-        public type!: {
-            id: string;
-        };
+        public type!: SharedModels.IIdRefenceObject;
         public externalId?: string;
         public lastModified!: Date;
-        public collection!: SharedModels.ReferenceObject;
+        public collection!: SharedModels.IIdRefenceObject;
         public spaces: SharedModels.IIdRefenceObject[] = [];
+        public sitemapLocations: SharedModels.IIdRefenceObject[] = [];
         public _raw!: ContentItemContracts.IContentItemModelContract;
 
         constructor(data: {
             id: string;
             name: string;
             codename: string;
-            type: {
-                id?: string;
-                codename?: string;
-                external_id?: string;
-            };
+            type: SharedModels.IIdRefenceObject;
             externalId?: string;
             lastModified: Date;
-            collection: SharedModels.ReferenceObject;
+            collection: SharedModels.IIdRefenceObject;
             spaces: SharedModels.IIdRefenceObject[];
+            sitemapLocations: SharedModels.IIdRefenceObject[];
             _raw: ContentItemContracts.IContentItemModelContract;
         }) {
             Object.assign(this, data);