chore: add tsdocs for latest changes (#13539)

2025-09-18 18:04:24 +03:00
parent 57897c232e
commit aa7ea4d9a6
8 changed files with 133 additions and 42 deletions
--- a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts
+++ b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart-with-pricing.ts
@@ -75,6 +75,48 @@ export const listShippingOptionsForCartWithPricingWorkflowId =
 * @summary
 *
 * List a cart's shipping options with prices.
+ * 
+ * @property hooks.setShippingOptionsContext - This hook is executed after the cart is retrieved and before the shipping options are queried. You can consume this hook to return any custom context useful for the shipping options retrieval.
+ *
+ * For example, you can consume the hook to add the customer Id to the context:
+ * 
+ * ```ts
+ * import { listShippingOptionsForCartWithPricingWorkflow } from "@medusajs/medusa/core-flows"
+ * import { StepResponse } from "@medusajs/workflows-sdk"
+ * 
+ * listShippingOptionsForCartWithPricingWorkflow.hooks.setShippingOptionsContext(
+ *   async ({ cart }, { container }) => {
+ * 
+ *     if (cart.customer_id) {
+ *       return new StepResponse({
+ *         customer_id: cart.customer_id,
+ *       })
+ *     }
+ * 
+ *     const query = container.resolve("query")
+ * 
+ *     const { data: carts } = await query.graph({
+ *       entity: "cart",
+ *       filters: {
+ *         id: cart.id,
+ *       },
+ *       fields: ["customer_id"],
+ *     })
+ * 
+ *     return new StepResponse({
+ *       customer_id: carts[0].customer_id,
+ *     })
+ *   }
+ * )
+ * ```
+ * 
+ * The `customer_id` property will be added to the context along with other properties such as `is_return` and `enabled_in_store`.
+ * 
+ * :::note
+ *
+ * You should also consume the `setShippingOptionsContext` hook in the {@link listShippingOptionsForCartWorkflow} workflow to ensure that the context is consistent when listing shipping options across workflows.
+ *
+ * :::
 */
 export const listShippingOptionsForCartWithPricingWorkflow = createWorkflow(
  listShippingOptionsForCartWithPricingWorkflowId,
--- a/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts
+++ b/packages/core/core-flows/src/cart/workflows/list-shipping-options-for-cart.ts
@@ -84,6 +84,48 @@ export const listShippingOptionsForCartWorkflowId =
 * Learn more about prices calculation context in the [Prices Calculation](https://docs.medusajs.com/resources/commerce-modules/pricing/price-calculation) documentation.
 *
 * :::
+ * 
+ * @property hooks.setShippingOptionsContext - This hook is executed after the cart is retrieved and before the shipping options are queried. You can consume this hook to return any custom context useful for the shipping options retrieval.
+ *
+ * For example, you can consume the hook to add the customer Id to the context:
+ * 
+ * ```ts
+ * import { listShippingOptionsForCartWithPricingWorkflow } from "@medusajs/medusa/core-flows"
+ * import { StepResponse } from "@medusajs/workflows-sdk"
+ * 
+ * listShippingOptionsForCartWithPricingWorkflow.hooks.setShippingOptionsContext(
+ *   async ({ cart }, { container }) => {
+ * 
+ *     if (cart.customer_id) {
+ *       return new StepResponse({
+ *         customer_id: cart.customer_id,
+ *       })
+ *     }
+ * 
+ *     const query = container.resolve("query")
+ * 
+ *     const { data: carts } = await query.graph({
+ *       entity: "cart",
+ *       filters: {
+ *         id: cart.id,
+ *       },
+ *       fields: ["customer_id"],
+ *     })
+ * 
+ *     return new StepResponse({
+ *       customer_id: carts[0].customer_id,
+ *     })
+ *   }
+ * )
+ * ```
+ * 
+ * The `customer_id` property will be added to the context along with other properties such as `is_return` and `enabled_in_store`.
+ * 
+ * :::note
+ * 
+ * You should also consume the `setShippingOptionsContext` hook in the {@link listShippingOptionsForCartWithPricingWorkflow} workflow to ensure that the context is consistent when listing shipping options across workflows.
+ * 
+ * :::
 */
 export const listShippingOptionsForCartWorkflow = createWorkflow(
  listShippingOptionsForCartWorkflowId,
--- a/packages/core/js-sdk/src/admin/index.ts
+++ b/packages/core/js-sdk/src/admin/index.ts
@@ -229,7 +229,7 @@ export class Admin {
  public plugin: Plugin
  /**
   * @tags views
-   * @ignore
+   * @featureFlag view_configurations
   */
  public views: Views

--- a/packages/core/js-sdk/src/admin/views.ts
+++ b/packages/core/js-sdk/src/admin/views.ts
@@ -6,7 +6,10 @@ import { ClientHeaders } from "../types"
 export class Views {
  constructor(private client: Client) {}

-  // Generic method to get columns for any entity
+  /**
+   * @since 2.10.3
+   * @featureFlag view_configurations
+   */
  async columns(
    entity: string,
    query?: SelectParams,
@@ -19,6 +22,10 @@ export class Views {
    })
  }

+  /**
+   * @since 2.10.3
+   * @featureFlag view_configurations
+   */
  async listConfigurations(
    entity: string,
    query?: HttpTypes.AdminGetViewConfigurationsParams,
@@ -31,6 +38,10 @@ export class Views {
    })
  }

+  /**
+   * @since 2.10.3
+   * @featureFlag view_configurations
+   */
  async createConfiguration(
    entity: string,
    body: HttpTypes.AdminCreateViewConfiguration,
@@ -43,6 +54,10 @@ export class Views {
    })
  }

+  /**
+   * @since 2.10.3
+   * @featureFlag view_configurations
+   */
  async retrieveConfiguration(
    entity: string,
    id: string,
@@ -59,6 +74,10 @@ export class Views {
    )
  }

+  /**
+   * @since 2.10.3
+   * @featureFlag view_configurations
+   */
  async updateConfiguration(
    entity: string,
    id: string,
@@ -75,6 +94,10 @@ export class Views {
    )
  }

+  /**
+   * @since 2.10.3
+   * @featureFlag view_configurations
+   */
  async deleteConfiguration(
    entity: string,
    id: string,
@@ -89,6 +112,10 @@ export class Views {
    )
  }

+  /**
+   * @since 2.10.3
+   * @featureFlag view_configurations
+   */
  async retrieveActiveConfiguration(
    entity: string,
    headers?: ClientHeaders
@@ -106,6 +133,10 @@ export class Views {
    )
  }

+  /**
+   * @since 2.10.3
+   * @featureFlag view_configurations
+   */
  async setActiveConfiguration(
    entity: string,
    body: { view_configuration_id: string | null },
--- a/packages/medusa/src/api/admin/views/[entity]/columns/route.ts
+++ b/packages/medusa/src/api/admin/views/[entity]/columns/route.ts
@@ -10,11 +10,8 @@ import { generateEntityColumns } from "./helpers"
 import { ENTITY_MAPPINGS } from "./entity-mappings"

 /**
- * @ignore
- * 
- * @privateRemarks
- * Remove the `ignore` tag once the feature is ready. Otherwise,
- * it will be generated in the documentation.
+ * @since 2.10.3
+ * @featureFlag view_configurations
 */
 export const GET = async (
  req: AuthenticatedMedusaRequest,
--- a/packages/medusa/src/api/admin/views/[entity]/configurations/[id]/route.ts
+++ b/packages/medusa/src/api/admin/views/[entity]/configurations/[id]/route.ts
@@ -8,11 +8,8 @@ import { MedusaError, Modules } from "@medusajs/framework/utils"
 import { updateViewConfigurationWorkflow } from "@medusajs/core-flows"

 /**
- * @ignore
- * 
- * @privateRemarks
- * Remove the `ignore` tag once the feature is ready. Otherwise,
- * it will be generated in the documentation.
+ * @since 2.10.3
+ * @featureFlag view_configurations
 */
 export const GET = async (
  req: AuthenticatedMedusaRequest<HttpTypes.AdminGetViewConfigurationParams>,
@@ -40,11 +37,8 @@ export const GET = async (
 }

 /**
- * @ignore
- * 
- * @privateRemarks
- * Remove the `ignore` tag once the feature is ready. Otherwise,
- * it will be generated in the documentation.
+ * @since 2.10.3
+ * @featureFlag view_configurations
 */
 export const POST = async (
  req: AuthenticatedMedusaRequest<AdminUpdateViewConfigurationType>,
@@ -78,11 +72,8 @@ export const POST = async (
 }

 /**
- * @ignore
- * 
- * @privateRemarks
- * Remove the `ignore` tag once the feature is ready. Otherwise,
- * it will be generated in the documentation.
+ * @since 2.10.3
+ * @featureFlag view_configurations
 */
 export const DELETE = async (
  req: AuthenticatedMedusaRequest,
--- a/packages/medusa/src/api/admin/views/[entity]/configurations/active/route.ts
+++ b/packages/medusa/src/api/admin/views/[entity]/configurations/active/route.ts
@@ -10,11 +10,8 @@ import { HttpTypes } from "@medusajs/framework/types"
 import { Modules } from "@medusajs/framework/utils"

 /**
- * @ignore
- * 
- * @privateRemarks
- * Remove the `ignore` tag once the feature is ready. Otherwise,
- * it will be generated in the documentation.
+ * @since 2.10.3
+ * @featureFlag view_configurations
 */
 export const GET = async (
  req: AuthenticatedMedusaRequest<AdminGetActiveViewConfigurationParamsType>,
@@ -49,11 +46,8 @@ export const GET = async (
 }

 /**
- * @ignore
- * 
- * @privateRemarks
- * Remove the `ignore` tag once the feature is ready. Otherwise,
- * it will be generated in the documentation.
+ * @since 2.10.3
+ * @featureFlag view_configurations
 */
 export const POST = async (
  req: AuthenticatedMedusaRequest<AdminSetActiveViewConfigurationType>,
--- a/packages/medusa/src/api/admin/views/[entity]/configurations/route.ts
+++ b/packages/medusa/src/api/admin/views/[entity]/configurations/route.ts
@@ -8,11 +8,8 @@ import { MedusaError, Modules } from "@medusajs/framework/utils"
 import { createViewConfigurationWorkflow } from "@medusajs/core-flows"

 /**
- * @ignore
- * 
- * @privateRemarks
- * Remove the `ignore` tag once the feature is ready. Otherwise,
- * it will be generated in the documentation.
+ * @since 2.10.3
+ * @featureFlag view_configurations
 */
 export const GET = async (
  req: AuthenticatedMedusaRequest<HttpTypes.AdminGetViewConfigurationsParams>,
@@ -41,11 +38,8 @@ export const GET = async (
 }

 /**
- * @ignore
- * 
- * @privateRemarks
- * Remove the `ignore` tag once the feature is ready. Otherwise,
- * it will be generated in the documentation.
+ * @since 2.10.3
+ * @featureFlag view_configurations
 */
 export const POST = async (
  req: AuthenticatedMedusaRequest<AdminCreateViewConfigurationType>,