chore: fixes to TSDocs (#14186)

* chore: fixes to TSDocs * update comments for auth provider
2025-12-02 11:57:04 +02:00
parent 9372a17d1f
commit 92769b2b1c
10 changed files with 49 additions and 30 deletions
--- a/packages/core/core-flows/src/order/steps/list-order-change-actions-by-type.ts
+++ b/packages/core/core-flows/src/order/steps/list-order-change-actions-by-type.ts
@@ -5,7 +5,7 @@ import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 /**
 * This step lists order change actions filtered by action type.
 * 
- * @since v2.12.0
+ * @since 2.12.0
 */
 export const listOrderChangeActionsByTypeStep = createStep(
  "list-order-change-actions-by-type",
--- a/packages/core/core-flows/src/order/workflows/compute-adjustments-for-preview.ts
+++ b/packages/core/core-flows/src/order/workflows/compute-adjustments-for-preview.ts
@@ -53,7 +53,7 @@ export const computeAdjustmentsForPreviewWorkflowId =
 * You can use this workflow within your customizations or your own custom workflows, allowing you to compute adjustments
 * in your custom flows.
 *
- * @since v2.12.0
+ * @since 2.12.0
 *
 * @example
 * const { result } = await computeAdjustmentsForPreviewWorkflow(container)
--- a/packages/core/core-flows/src/order/workflows/on-carry-promotions-flag-set.ts
+++ b/packages/core/core-flows/src/order/workflows/on-carry-promotions-flag-set.ts
@@ -44,7 +44,7 @@ export type OnCarryPromotionsFlagSetWorkflowInput = {
 *
 * :::
 * 
- * @since v2.12.0
+ * @since 2.12.0
 *
 * @example
 * const data = validateCarryPromotionsFlagStep({
@@ -150,7 +150,7 @@ export const onCarryPromotionsFlagSetId = "on-carry-promotions-flag-set"
 * You can use this workflow within your customizations or your own custom workflows, allowing you to 
 * set the carry over promotions flag for an order change in your custom flows.
 * 
- * @since v2.12.0
+ * @since 2.12.0
 *
 * @example
 * const { result } = await onCarryPromotionsFlagSet(container)
--- a/packages/core/core-flows/src/order/workflows/update-order-change.ts
+++ b/packages/core/core-flows/src/order/workflows/update-order-change.ts
@@ -19,7 +19,7 @@ export const updateOrderChangeWorkflowId = "update-order-change-workflow"
 * You can use this workflow within your customizations or your own custom workflows, allowing you to wrap custom logic around
 * updating an order change and conditionally handling promotion carry-over.
 * 
- * @since v2.12.0
+ * @since 2.12.0
 *
 * @example
 * const { result } = await updateOrderChangeWorkflow(container)
--- a/packages/core/js-sdk/src/admin/order.ts
+++ b/packages/core/js-sdk/src/admin/order.ts
@@ -639,7 +639,7 @@ export class Order {
   * [Update Order Change](https://docs.medusajs.com/api/admin#order-changes_postorder-changesid)
   * API route.
   * 
-   * @since v2.12.0
+   * @since 2.12.0
   *
   * @param id - The order change's ID.
   * @param body - The update details.
--- a/packages/core/types/src/caching/index.ts
+++ b/packages/core/types/src/caching/index.ts
@@ -13,7 +13,7 @@ type Providers = (string | {
 })[]

 /**
- * @since v2.11.0
+ * @since 2.11.0
 */
 export interface ICachingModuleService extends IModuleService {
  // Static trace methods
@@ -47,7 +47,7 @@ export interface ICachingModuleService extends IModuleService {
   * To retrieve by key:
   * 
   * ```ts
-   * const data = await cacheModuleService.get({
+   * const data = await cachingModuleService.get({
   *   key: "products", // this key would typically be a hash
   * }) as { id: string; title: string; }
   * ```
@@ -55,7 +55,7 @@ export interface ICachingModuleService extends IModuleService {
   * To retrieve by tags:
   * 
   * ```ts
-   * const data = await cacheModuleService.get({
+   * const data = await cachingModuleService.get({
   *   tags: ["Product:list:*"],
   * }) as { id: string; title: string; }[]
   * ```
@@ -63,7 +63,7 @@ export interface ICachingModuleService extends IModuleService {
   * To retrieve by key from specific providers:
   * 
   * ```ts
-   * const data = await cacheModuleService.get({
+   * const data = await cachingModuleService.get({
   *   key: "products", // this key would typically be a hash
   *   providers: ["caching-redis", "caching-memcached"]
   * }) as { id: string; title: string; }
@@ -106,8 +106,8 @@ export interface ICachingModuleService extends IModuleService {
   * 
   * ```ts
   * const data = { id: "prod_123", title: "Product 123" }
-   * const key = await cacheModuleService.computeKey(data)
-   * await cacheModuleService.set({
+   * const key = await cachingModuleService.computeKey(data)
+   * await cachingModuleService.set({
   *   key,
   *   data
   * })
@@ -123,8 +123,8 @@ export interface ICachingModuleService extends IModuleService {
   * 
   * ```ts
   * const data = [{ id: "prod_123", title: "Product 123" }]
-   * const key = await cacheModuleService.computeKey(data)
-   * await cacheModuleService.set({
+   * const key = await cachingModuleService.computeKey(data)
+   * await cachingModuleService.set({
   *   key,
   *   data,
   *   tags: [`Product:${data[0].id}`, "Product:list:*"]
@@ -135,8 +135,8 @@ export interface ICachingModuleService extends IModuleService {
   * 
   * ```ts
   * const data = [{ id: "prod_123", title: "Product 123" }]
-   * const key = await cacheModuleService.computeKey(data)
-   * await cacheModuleService.set({
+   * const key = await cachingModuleService.computeKey(data)
+   * await cachingModuleService.set({
   *   key,
   *   data,
   *   options: { autoInvalidate: false }
@@ -149,8 +149,8 @@ export interface ICachingModuleService extends IModuleService {
   * 
   * ```ts
   * const data = { id: "prod_123", title: "Product 123" }
-   * const key = await cacheModuleService.computeKey(data)
-   * await cacheModuleService.set({
+   * const key = await cachingModuleService.computeKey(data)
+   * await cachingModuleService.set({
   *   key,
   *   data,
   *   providers: [
@@ -224,7 +224,7 @@ export interface ICachingModuleService extends IModuleService {
   * To invalidate cache by key:
   * 
   * ```ts
-   * await cacheModuleService.clear({
+   * await cachingModuleService.clear({
   *  key: "products" // this key would typically be a hash
   * })
   * ```
@@ -234,7 +234,7 @@ export interface ICachingModuleService extends IModuleService {
   * To invalidate cache by tags:
   * 
   * ```ts
-   * await cacheModuleService.clear({
+   * await cachingModuleService.clear({
   *  tags: ["Product:list:*"]
   * })
   * ```
@@ -244,7 +244,7 @@ export interface ICachingModuleService extends IModuleService {
   * To invalidate only the cache data that were set to automatically invalidate:
   * 
   * ```ts
-   * await cacheModuleService.clear({
+   * await cachingModuleService.clear({
   *  tags: ["Product:list:*"],
   *  options: { autoInvalidate: true }
   * })
@@ -263,7 +263,7 @@ export interface ICachingModuleService extends IModuleService {
   * To invalidate cache from specific providers:
   * 
   * ```ts
-   * await cacheModuleService.clear({
+   * await cachingModuleService.clear({
   *  key: "products",
   *  providers: ["caching-redis", "caching-memcached"]
   * })
@@ -311,7 +311,7 @@ export interface ICachingModuleService extends IModuleService {
   * @returns The computed cache key.
   * 
   * @example
-   * const key = await cacheModuleService.computeKey({
+   * const key = await cachingModuleService.computeKey({
   *   id: "prod_123",
   *   title: "Product 123"
   * })
@@ -327,7 +327,7 @@ export interface ICachingModuleService extends IModuleService {
   * @returns An array of computed cache tags.
   * 
   * @example
-   * const tags = await cacheModuleService.computeTags({
+   * const tags = await cachingModuleService.computeTags({
   *   products: [{ id: "prod_123" }, { id: "prod_456" }],
   * }, {
   *   operation: "updated"
--- a/packages/core/utils/src/auth/abstract-auth-provider.ts
+++ b/packages/core/utils/src/auth/abstract-auth-provider.ts
@@ -176,7 +176,6 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   *     // authentication is successful, retrieve the identity
   *     const authIdentity = await authIdentityProviderService.retrieve({
   *       entity_id: data.body.email, // email or some ID
-   *       provider: this.provider
   *     })
   *
   *     return {
@@ -215,6 +214,16 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   *         error: "Incorrect credentials"
   *       }
   *     }
+   * 
+   *     // optional, useful for third-party providers that require a redirect URL
+   *     // to continue the authentication flow
+   *     // const stateKey = crypto.randomBytes(32).toString("hex")
+   *     // const state = {
+   *     //   callback_url: body?.callback_url ?? this.config_.callbackUrl,
+   *     // }
+   *     
+   *     // verify this later in the `validateCallback` method
+   *     // await authIdentityService.setState(stateKey, state)
   *
   *     return {
   *       success: true,
@@ -396,6 +405,16 @@ export abstract class AbstractAuthModuleProvider implements IAuthProvider {
   *     authIdentityProviderService: AuthIdentityProviderService
   *   ): Promise<AuthenticationResponse> {
   *     const isAuthenticated = false
+   * 
+   *     // optional, useful for third-party providers that require a redirect URL
+   *     // to continue the authentication flow
+   *     // const stateKey = data.query?.state as string
+   *     // const state = await authIdentityService.getState(stateKey)
+   *     // if (!state) {
+   *     //   return { success: false, error: "No state provided, or session expired" }
+   *     // }
+   *     // // use callback URL with the third-party service
+   *     // const callbackUrl = state.callback_url
   *     // TODO perform custom logic to authenticate the user
   *     // ...
   *
--- a/packages/medusa/src/api/admin/order-changes/[id]/route.ts
+++ b/packages/medusa/src/api/admin/order-changes/[id]/route.ts
@@ -7,7 +7,7 @@ import {
 import { ContainerRegistrationKeys } from "@medusajs/framework/utils"

 /**
- * @since v2.12.0
+ * @since 2.12.0
 */
 export const POST = async (
  req: AuthenticatedMedusaRequest<
--- a/packages/modules/order/src/models/order-change.ts
+++ b/packages/modules/order/src/models/order-change.ts
@@ -28,7 +28,7 @@ const _OrderChange = model
    canceled_by: model.text().nullable(),
    canceled_at: model.dateTime().nullable(),
    /**
-     * @since v2.12.0
+     * @since 2.12.0
     */
    carry_over_promotions: model.boolean().nullable(),
    order: model.belongsTo<() => typeof Order>(() => Order, {
--- a/packages/modules/promotion/src/models/promotion.ts
+++ b/packages/modules/promotion/src/models/promotion.ts
@@ -10,11 +10,11 @@ const Promotion = model
    is_automatic: model.boolean().default(false),
    is_tax_inclusive: model.boolean().default(false),
    /**
-     * @since v2.12.0
+     * @since 2.12.0
     */
    limit: model.number().nullable(),
    /**
-     * @since v2.12.0
+     * @since 2.12.0
     */
    used: model.number().default(0),
    type: model.enum(PromotionUtils.PromotionType).index("IDX_promotion_type"),
@@ -37,7 +37,7 @@ const Promotion = model
      mappedBy: "promotions",
    }),
    /**
-     * @since v2.12.0
+     * @since 2.12.0
     */
    metadata: model.json().nullable(),
  })