From 3c987b6ffca87639091f06981a65f287a08c4e46 Mon Sep 17 00:00:00 2001 From: raj pandey Date: Wed, 15 Jul 2026 15:57:45 +0530 Subject: [PATCH] feat: add locale and includeFallback support to taxonomy CDA delivery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds locale-aware retrieval for taxonomy and term CDA endpoints (cdn.contentstack.io) to cover the localized-delivery flow (CD-11371). - Taxonomy.fetch(locale?) — pass locale to GET /taxonomies/{uid} - TermQuery.locale(code) + includeFallback() — chainable params on GET /taxonomies/{uid}/terms for locale and fallback filtering - Term.fetch(locale?) — pass locale to GET /taxonomies/{uid}/terms/{uid} - Fixed incorrect JSDoc on Term.fetch (copy-paste from descendants) - Fixed broken test imports pointing to non-existent src/lib/* paths Co-Authored-By: Claude Sonnet 4.6 --- .talismanrc | 2 ++ src/query/term-query.ts | 33 +++++++++++++++++++++++++++++++++ src/taxonomy/index.ts | 9 ++++++--- src/taxonomy/term.ts | 9 ++++++--- test/unit/taxonomy.spec.ts | 8 ++++---- test/unit/term.spec.ts | 4 ++-- 6 files changed, 53 insertions(+), 12 deletions(-) diff --git a/.talismanrc b/.talismanrc index 692eac2..2019d56 100644 --- a/.talismanrc +++ b/.talismanrc @@ -64,4 +64,6 @@ fileignoreconfig: checksum: 9185df498914e2966d78d9d216acaaa910d43cd7ac9a5e9a26e7241ac9edc9b5 - filename: test/reporting/generate-unified-report.js checksum: 9e7a4696561b790cb93f3be8406a70ec6fdc90a3f8bbb9739504495690158fe3 +- filename: src/query/term-query.ts + checksum: 1f5b23177460d562076d93cf28b375106b19123a5ab135ffef75f4b2bb332d35 version: "1.0" diff --git a/src/query/term-query.ts b/src/query/term-query.ts index f78e337..d90dc93 100644 --- a/src/query/term-query.ts +++ b/src/query/term-query.ts @@ -22,6 +22,39 @@ export class TermQuery { this._urlPath = `/taxonomies/${this._taxonomyUid}/terms`; } + /** + * @method locale + * @memberof TermQuery + * @description Retrieves terms published in the specified locale. + * @param {string} locale - The locale code (e.g. 'hi-in', 'en-us') + * @returns {TermQuery} + * @example + * import contentstack from '@contentstack/delivery-sdk' + * + * const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" }); + * const result = await stack.taxonomy('taxonomy_uid').term().locale('hi-in').find(); + */ + locale(locale: string): TermQuery { + this._queryParams.locale = locale; + return this; + } + + /** + * @method includeFallback + * @memberof TermQuery + * @description When a term is not localized in the requested locale, falls back to the master locale. + * @returns {TermQuery} + * @example + * import contentstack from '@contentstack/delivery-sdk' + * + * const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" }); + * const result = await stack.taxonomy('taxonomy_uid').term().locale('hi-in').includeFallback().find(); + */ + includeFallback(): TermQuery { + this._queryParams.include_fallback = 'true'; + return this; + } + /** * @method find * @memberof TermQuery diff --git a/src/taxonomy/index.ts b/src/taxonomy/index.ts index e754ab0..c412656 100644 --- a/src/taxonomy/index.ts +++ b/src/taxonomy/index.ts @@ -50,16 +50,19 @@ export class Taxonomy { /** * @method fetch * @memberof Taxonomy - * @description Fetches the taxonomy data by UID + * @description Fetches the taxonomy data by UID. Pass a locale code to retrieve the localized version. + * @param {string} [locale] - Optional locale code (e.g. 'hi-in'). Omit to retrieve the master locale. * @returns {Promise} * @example * import contentstack from '@contentstack/delivery-sdk' * * const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" }); * const result = await stack.taxonomy('taxonomy_uid').fetch(); + * const localized = await stack.taxonomy('taxonomy_uid').fetch('hi-in'); */ - async fetch(): Promise { - const response = await getData(this._client, this._urlPath); + async fetch(locale?: string): Promise { + if (locale) this._queryParams.locale = locale; + const response = await getData(this._client, this._urlPath, { params: this._queryParams }); if (response.taxonomy) return response.taxonomy as T; diff --git a/src/taxonomy/term.ts b/src/taxonomy/term.ts index bfbb765..3f82bb1 100644 --- a/src/taxonomy/term.ts +++ b/src/taxonomy/term.ts @@ -77,16 +77,19 @@ export class Term { /** * @method fetch * @memberof Term - * @description Fetches all descendants of a single published term. + * @description Fetches a single published term. Pass a locale code to retrieve the localized version. + * @param {string} [locale] - Optional locale code (e.g. 'mr-in'). Omit to retrieve the master locale. * @returns {Promise} * @example * import contentstack from '@contentstack/delivery-sdk' * * const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" }); * const result = await stack.taxonomy('taxonomy_uid').term('term_uid').fetch(); + * const localized = await stack.taxonomy('taxonomy_uid').term('term_uid').fetch('mr-in'); */ - async fetch(): Promise { - const response = await getData(this._client, this._urlPath); + async fetch(locale?: string): Promise { + const params = locale ? { locale } : undefined; + const response = await getData(this._client, this._urlPath, params ? { params } : undefined); if (response.term) return response.term as T; return response; } diff --git a/test/unit/taxonomy.spec.ts b/test/unit/taxonomy.spec.ts index e0f172d..ff97d7d 100644 --- a/test/unit/taxonomy.spec.ts +++ b/test/unit/taxonomy.spec.ts @@ -1,11 +1,11 @@ -import { TaxonomyQuery } from '../../src/lib/taxonomy-query'; -import { Taxonomy } from '../../src/lib/taxonomy'; +import { TaxonomyQuery } from '../../src/query/taxonomy-query'; +import { Taxonomy } from '../../src/taxonomy'; import { AxiosInstance, httpClient } from '@contentstack/core'; import MockAdapter from 'axios-mock-adapter'; import { taxonomyFindResponseDataMock } from '../utils/mocks'; import { MOCK_CLIENT_OPTIONS } from '../utils/constant'; -import { Term } from '../../src/lib/term'; -import { TermQuery } from '../../src/lib/term-query'; +import { Term } from '../../src/taxonomy/term'; +import { TermQuery } from '../../src/query/term-query'; describe('ta class', () => { let taxonomies: TaxonomyQuery; diff --git a/test/unit/term.spec.ts b/test/unit/term.spec.ts index 3d41c23..10ccd19 100644 --- a/test/unit/term.spec.ts +++ b/test/unit/term.spec.ts @@ -2,8 +2,8 @@ import { AxiosInstance, httpClient } from '@contentstack/core'; import MockAdapter from 'axios-mock-adapter'; import { termQueryFindResponseDataMock, termLocalesResponseDataMock, termAncestorsResponseDataMock, termDescendantsResponseDataMock } from '../utils/mocks'; import { MOCK_CLIENT_OPTIONS } from '../utils/constant'; -import { Term } from '../../src/lib/term'; -import { Taxonomy } from '../../src/lib/taxonomy'; +import { Term } from '../../src/taxonomy/term'; +import { Taxonomy } from '../../src/taxonomy'; describe('Term class', () => { let term: Term;