Feat/taxonomy publishing

src/common/types.ts

@@ -21,25 +21,25 @@ export type queryParams = {
 
 /**
  * Interface for creating Contentstack plugins
- * 
+ *
  * @example
  * ```typescript
  * import { ContentstackPlugin } from '@contentstack/delivery-sdk';
- * 
+ *
  * class MyPlugin implements ContentstackPlugin {
  *   onRequest(config: any): any {
  *     // Modify request configuration
  *     console.log('Processing request:', config.url);
  *     return { ...config, headers: { ...config.headers, 'X-Custom-Header': 'value' } };
  *   }
- * 
+ *
  *   onResponse(request: any, response: any, data: any): any {
  *     // Process response data
  *     console.log('Processing response:', response.status);
  *     return { ...response, data: { ...data, processed: true } };
  *   }
  * }
- * 
+ *
  * const stack = contentstack.stack({
  *   apiKey: 'your-api-key',
  *   deliveryToken: 'your-delivery-token',
@@ -344,6 +344,8 @@ export interface FindResponse<T, TContentType = unknown> {
   assets?: T[];
   global_fields?: T[];
   count?: number;
+  taxonomies?: T[];
+  terms?: T[];
 }
 
 export interface LivePreviewQuery {
@@ -367,3 +369,31 @@ export type LivePreview = {
   management_token?: string;
   preview_token?: string;
 };
+
+export interface BaseTaxonomy {
+  uid: string;
+  name: string;
+  description?: string;
+  terms_count?: number;
+  created_at: string;
+  updated_at: string;
+  created_by: string;
+  updated_by: string;
+  type: string;
+  ACL: ACL;
+  publish_details?: PublishDetails;
+}
+
+export interface BaseTerm {
+  taxonomy_uid: string;
+  uid: string;
+  name: string;
+  created_by: string;
+  created_at: string;
+  updated_by: string;
+  updated_at: string;
+  children_count?: number;
+  depth?: number;
+  ACL: ACL;
+  publish_details?: PublishDetails;
+}

src/index.ts

@@ -13,6 +13,7 @@ export type { ImageTransform } from './assets';
 export type { AssetQuery } from './query';
 export type { TaxonomyQuery } from './query';
 export type { ContentTypeQuery } from './query';
+export type { Taxonomy } from './taxonomy';
 export { ErrorMessages, ErrorCode } from './common/error-messages';
 
 export default contentstack;

src/query/taxonomy-query.ts

@@ -1,10 +1,31 @@
 import { Query } from "./query";
-import { AxiosInstance } from "@contentstack/core";
+import { AxiosInstance, getData } from "@contentstack/core";
+import { FindResponse } from "../common/types";
 
 export class TaxonomyQuery extends Query {
-    constructor(client: AxiosInstance) {
-        super(client, {}, {}); // will need make changes to Query class so that CT uid is not mandatory
-        this._client = client;
-        this._urlPath = `/taxonomies/entries`;
-    }
+  constructor(client: AxiosInstance) {
+    super(client, {}, {}); // will need make changes to Query class so that CT uid is not mandatory
+    this._client = client;
+    this._urlPath = `/taxonomies/entries`;
+  }
+  /**
+   * @method find
+   * @memberof TaxonomyQuery
+   * @description Fetches a list of all published taxonomies available in the stack.
+   * @returns {Promise<FindResponse<T>>}
+   * @example
+   * import contentstack from '@contentstack/delivery-sdk'
+   *
+   * const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
+   * const taxonomyQuery = stack.taxonomy();
+   * const result = await taxonomyQuery.find();
+   */
+  override async find<T>(): Promise<FindResponse<T>> {
+    this._urlPath = "/taxonomies";
+    const response = await getData(this._client, this._urlPath, {
+      params: this._queryParams,
+    });
+
+    return response as FindResponse<T>;
+  }
 };

src/query/term-query.ts

@@ -0,0 +1,40 @@
+import { AxiosInstance, getData } from '@contentstack/core';
+import { FindResponse } from '../common/types';
+
+/**
+ * @class TermQuery
+ * @description Represents a query for fetching multiple published terms from a taxonomy. Requires taxonomy_publish feature flag to be enabled.
+ */
+export class TermQuery {
+  private _taxonomyUid: string;
+  private _client: AxiosInstance;
+  private _urlPath: string;
+  _queryParams: { [key: string]: string | number } = {};
+
+  /**
+   * @constructor
+   * @param {AxiosInstance} client - The HTTP client instance
+   * @param {string} taxonomyUid - The taxonomy UID
+   */
+  constructor(client: AxiosInstance, taxonomyUid: string) {
+    this._client = client;
+    this._taxonomyUid = taxonomyUid;
+    this._urlPath = `/taxonomies/${this._taxonomyUid}/terms`;
+  }
+
+  /**
+   * @method find
+   * @memberof TermQuery
+   * @description Fetches a list of all published terms within a specific taxonomy.
+   * @returns {Promise<FindResponse<T>>}
+   * @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().find();
+   */
+  async find<T>(): Promise<FindResponse<T>> {
+    const response = await getData(this._client, this._urlPath, { params: this._queryParams });
+    return response as FindResponse<T>;
+  }
+}

src/stack/stack.ts

@@ -8,6 +8,7 @@ import { synchronization } from '../sync';
 import { TaxonomyQuery } from '../query';
 import { GlobalFieldQuery } from '../query';
 import { GlobalField } from '../global-field';
+import { Taxonomy } from '../taxonomy';
 
 export class Stack {
   readonly config: StackConfig;
@@ -78,7 +79,11 @@ export class Stack {
 
    * const taxonomy = stack.taxonomy() // For taxonomy query object
    */
-  taxonomy(): TaxonomyQuery {
+  taxonomy(): TaxonomyQuery;
+  taxonomy(uid: string): Taxonomy;
+  taxonomy(uid?: string): Taxonomy | TaxonomyQuery {
+    if (uid) return new Taxonomy(this._client, uid);
+
     return new TaxonomyQuery(this._client);
   }
 

src/taxonomy/index.ts

@@ -0,0 +1,68 @@
+import { AxiosInstance, getData } from '@contentstack/core';
+import { TermQuery } from '../query/term-query';
+import { Term } from './term';
+
+/**
+ * @class Taxonomy
+ * @description Represents a published taxonomy with methods to fetch taxonomy data and manage terms. Requires taxonomy_publish feature flag to be enabled.
+ */
+export class Taxonomy {
+  private _client: AxiosInstance;
+  private _taxonomyUid: string;
+  private _urlPath: string;
+
+  _queryParams: { [key: string]: string | number } = {};
+
+  /**
+   * @constructor
+   * @param {AxiosInstance} client - The HTTP client instance
+   * @param {string} taxonomyUid - The taxonomy UID
+   */
+  constructor(client: AxiosInstance, taxonomyUid: string) {
+    this._client = client;
+    this._taxonomyUid = taxonomyUid;
+    this._urlPath = `/taxonomies/${this._taxonomyUid}`;
+  }
+
+  /**
+   * @method term
+   * @memberof Taxonomy
+   * @description Gets a specific term or creates a term query
+   * @param {string} [uid] - Optional term UID. If provided, returns a Term instance. If not provided, returns a TermQuery instance.
+   * @returns {Term | TermQuery}
+   * @example
+   * import contentstack from '@contentstack/delivery-sdk'
+   *
+   * const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
+   * // Get a specific term
+   * const term = stack.taxonomy('taxonomy_uid').term('term_uid');
+   * // Get all terms
+   * const termQuery = stack.taxonomy('taxonomy_uid').term();
+   */
+  term(uid: string): Term;
+  term(): TermQuery;
+  term(uid?: string): Term | TermQuery {
+    if (uid) return new Term(this._client, this._taxonomyUid, uid);
+
+    return new TermQuery(this._client, this._taxonomyUid);
+  }
+
+  /**
+   * @method fetch
+   * @memberof Taxonomy
+   * @description Fetches the taxonomy data by UID
+   * @returns {Promise<T>}
+   * @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();
+   */
+  async fetch<T>(): Promise<T> {
+    const response = await getData(this._client, this._urlPath);
+
+    if (response.taxonomy) return response.taxonomy as T;
+
+    return response;
+  }
+}

src/taxonomy/term.ts

@@ -0,0 +1,93 @@
+import { AxiosInstance, getData } from "@contentstack/core";
+
+/**
+ * @class Term
+ * @description Represents a published taxonomy term with methods to fetch term data, locales, ancestors, and descendants. Requires taxonomy_publish feature flag to be enabled.
+ */
+export class Term {
+  protected _client: AxiosInstance;
+  private _taxonomyUid: string;
+  private _termUid: string;
+  private _urlPath: string;
+
+  /**
+   * @constructor
+   * @param {AxiosInstance} client - The HTTP client instance
+   * @param {string} taxonomyUid - The taxonomy UID
+   * @param {string} termUid - The term UID
+   */
+  constructor(client: AxiosInstance, taxonomyUid: string, termUid: string) {
+    this._client = client;
+    this._taxonomyUid = taxonomyUid;
+    this._termUid = termUid;
+    this._urlPath = `/taxonomies/${this._taxonomyUid}/terms/${this._termUid}`;
+  }
+
+  /**
+   * @method locales
+   * @memberof Term
+   * @description Fetches all published, localized versions of a single term.
+   * @returns {Promise<T>}
+   * @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').locales();
+   */
+  async locales<T>(): Promise<T> {
+    const response = await getData(this._client, `${this._urlPath}/locales`); 
+    if (response.locales) return response.locales as T;
+    return response;
+  }
+
+  /**
+   * @method ancestors
+   * @memberof Term
+   * @description Fetches all ancestors of a single published term, up to the root.
+   * @returns {Promise<T>}
+   * @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').ancestors();
+   */
+  async ancestors<T>(): Promise<T> {
+    const response = await getData(this._client, `${this._urlPath}/ancestors`);
+    if (response.ancestors) return response.ancestors as T;
+    return response;
+  }
+
+  /**
+   * @method descendants
+   * @memberof Term
+   * @description Fetches all descendants of a single published term.
+   * @returns {Promise<T>}
+   * @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').descendants();
+   */
+  async descendants<T>(): Promise<T> {
+    const response = await getData(this._client, `${this._urlPath}/descendants`);
+    if (response.descendants) return response.descendants as T;
+    return response;
+  }
+
+  /**
+   * @method fetch
+   * @memberof Term
+   * @description Fetches all descendants of a single published term.
+   * @returns {Promise<T>}
+   * @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();
+   */
+  async fetch<T>(): Promise<T> {
+    const response = await getData(this._client, this._urlPath);
+    if (response.term) return response.term as T;
+    return response;
+  }
+}

test/api/taxonomy.spec.ts

@@ -0,0 +1,33 @@
+/* eslint-disable no-console */
+/* eslint-disable promise/always-return */
+import { stackInstance } from '../utils/stack-instance';
+import { TTaxonomies, TTaxonomy } from './types';
+import dotenv from 'dotenv';
+import { TaxonomyQuery } from '../../src/lib/taxonomy-query';
+import { Taxonomy } from '../../src/lib/taxonomy';
+
+dotenv.config()
+
+const stack = stackInstance();
+describe('ContentType API test cases', () => {
+  it('should give taxonomies when taxonomies method is called', async () => {
+    const result = await makeTaxonomies().find<TTaxonomies>();
+    expect(result).toBeDefined();
+  });
+
+  it('should give a single taxonomy when taxonomy method is called with taxonomyUid', async () => {
+    const result = await makeTaxonomy('taxonomy_testing').fetch<TTaxonomy>();
+    expect(result).toBeDefined();
+  });
+});
+
+function makeTaxonomies(): TaxonomyQuery {
+  const taxonomies = stack.taxonomy();
+
+  return taxonomies;
+}
+
+function makeTaxonomy(taxonomyUid: string): Taxonomy {
+    const taxonomy = stack.taxonomy(taxonomyUid);
+    return taxonomy;
+}