From 0f802a977a666b977a160cd28383e57957897ead Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Fri, 9 May 2025 14:34:45 +0300
Subject: [PATCH] chore(js-sdk, types): update TSDocs related to tax provider
 changes (#12428)

---
 .../core/js-sdk/src/admin/tax-provider.ts     | 30 ++++++++++++
 packages/core/js-sdk/src/admin/tax-region.ts  |  2 +
 packages/core/types/src/tax/provider.ts       |  4 +-
 packages/core/types/src/tax/service.ts        | 48 ++++++++++++++++++-
 4 files changed, 81 insertions(+), 3 deletions(-)

diff --git a/packages/core/js-sdk/src/admin/tax-provider.ts b/packages/core/js-sdk/src/admin/tax-provider.ts
index 5a989f78cf..f0d3848ec0 100644
--- a/packages/core/js-sdk/src/admin/tax-provider.ts
+++ b/packages/core/js-sdk/src/admin/tax-provider.ts
@@ -20,6 +20,8 @@ export class TaxProvider {
    * This method retrieves a list of tax providers. It sends a request to the
    * [List Tax Providers](https://docs.medusajs.com/api/admin#tax-providers_gettaxproviders)
    * API route.
+   * 
+   * @version 2.8.0
    *
    * @param query - Filters and pagination configurations.
    * @param headers - Headers to pass in the request.
@@ -34,6 +36,34 @@ export class TaxProvider {
    *   console.log(tax_providers)
    * })
    * ```
+   *
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   *
+   * For example, to retrieve only 10 items and skip 10 items:
+   *
+   * ```ts
+   * sdk.admin.taxProvider.list({
+   *   limit: 10,
+   *   offset: 10,
+   * })
+   * .then(({ tax_providers, count, limit, offset }) => {
+   *   console.log(tax_providers)
+   * })
+   * ```
+   *
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each products:
+   *
+   * ```ts
+   * sdk.admin.taxProvider.list({
+   *   fields: "id,*regions"
+   * })
+   * .then(({ tax_providers, count, limit, offset }) => {
+   *   console.log(tax_providers)
+   * })
+   * ```
+   *
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
    */
   async list(
     query?: HttpTypes.AdminGetTaxProvidersParams,
diff --git a/packages/core/js-sdk/src/admin/tax-region.ts b/packages/core/js-sdk/src/admin/tax-region.ts
index 6b2f65f983..694fb22447 100644
--- a/packages/core/js-sdk/src/admin/tax-region.ts
+++ b/packages/core/js-sdk/src/admin/tax-region.ts
@@ -66,6 +66,8 @@ export class TaxRegion {
    * This method updates a tax region. It sends a request to the
    * [Update Tax Region](https://docs.medusajs.com/api/admin#tax-regions_posttaxregionsid)
    * API route.
+   * 
+   * @version 2.8.0
    *
    * @param id - The ID of the tax region to update.
    * @param body - The details of the tax region to update.
diff --git a/packages/core/types/src/tax/provider.ts b/packages/core/types/src/tax/provider.ts
index 37f983ed85..e20c65741a 100644
--- a/packages/core/types/src/tax/provider.ts
+++ b/packages/core/types/src/tax/provider.ts
@@ -42,7 +42,9 @@ export type ItemTaxCalculationLine = {
  * 
  * ### Identifier Property
  *
- * The `identifier` property in a tax provider is used when the tax provider is loaded by the Tax Module and added to the database. A tax provider is represented in the database by the `TaxProvider` data model.
+ * Each tax provider has a unique identifier defined in its class. The provider's ID
+ * will be stored as `tp_{identifier}_{id}`, where `{id}` is the provider's `id`
+ * property in the `medusa-config.ts`.
  *
  * For example:
  *
diff --git a/packages/core/types/src/tax/service.ts b/packages/core/types/src/tax/service.ts
index b8669fb152..ca67a49a6f 100644
--- a/packages/core/types/src/tax/service.ts
+++ b/packages/core/types/src/tax/service.ts
@@ -584,14 +584,58 @@ export interface ITaxModuleService extends IModuleService {
 
   /**
    * This method retrieves a paginated list of tax providers based on optional filters and configuration.
+   * 
+   * @version 2.8.0
    *
    * @param {FilterableTaxProviderProps} filters - The filters to apply on the retrieved tax providers.
-   * @param {FindConfig<TaxProviderDTO>} config - The configurations determining how the tax provider is retrieved.
+   * @param {FindConfig<TaxProviderDTO>} config - The configurations determining how the tax provider is retrieved. Its properties, such as `select` or `relations`, accept the
+   * attributes or relations associated with a tax provider.
    * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module.
    * @returns {Promise<TaxProviderDTO[]>} The list of tax providers.
    *
    * @example
-   * const taxProviders = await taxModuleService.listTaxProviders()
+   * To retrieve a list of tax providers using their associated tax rate's ID:
+   *
+   * ```ts
+   * const taxProviders = await taxModuleService.listTaxProviders({
+   *   id: ["tp_custom_custom"],
+   * })
+   * ```
+   *
+   * To specify relations that should be retrieved within the tax provider:
+   * 
+   * :::note
+   * 
+   * You can only retrieve data models defined in the same module. To retrieve linked data models
+   * from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.
+   * 
+   * :::
+   *
+   * ```ts
+   * const taxProviders = await taxModuleService.listTaxProviders(
+   *   {
+   *     id: ["tp_custom_custom"],
+   *   },
+   *   {
+   *     relations: ["regions"],
+   *   }
+   * )
+   * ```
+   *
+   * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:
+   *
+   * ```ts
+   * const taxProviders = await taxModuleService.listTaxProviders(
+   *   {
+   *     id: ["tp_custom_custom"],
+   *   },
+   *   {
+   *     relations: ["regions"],
+   *     take: 20,
+   *     skip: 2,
+   *   }
+   * )
+   * ```
    */
 
   listTaxProviders(