chore(types, utils): TSDoc improvements for providers (medusajs#12498)

* chore(types, utils): TSDoc improvements for providers

* small iteration

Author: shahednasser

packages/core/types/src/file/provider.ts

@@ -140,12 +140,27 @@ export interface IFileProvider {
   getPresignedDownloadUrl(fileData: ProviderGetFileDTO): Promise<string>
 
   /**
-   * This method is used to get a presigned upload URL for a file.
-   * If the file provider does not support direct upload, an exception will be thrown when calling this method.
+   * This method is used to get a presigned upload URL for a file. For some providers,
+   * such as S3, a presigned URL indicates a temporary URL to get upload a file.
+   * 
+   * If your provider doesn’t perform or offer a similar functionality, you don't have to
+   * implement this method. Instead, an error is thrown when the method is called.
    *
    * @param {ProviderGetPresignedUploadUrlDTO} fileData - The details of the file to get a presigned upload URL for.
    * @returns {Promise<ProviderFileResultDTO>} The presigned URL and file key to upload the file to
    *
+   * @example
+   * class MyFileProviderService extends AbstractFileProviderService {
+   *   // ...
+   *   async getPresignedUploadUrl(
+   *     fileData: ProviderGetPresignedUploadUrlDTO
+   *   ): Promise<ProviderFileResultDTO> {
+   *     // TODO logic to get the presigned upload URL
+   *     // for example:
+   *     return this.client.getPresignedUploadUrl(fileData.filename, fileData.mimeType)
+   *   }
+   * }
+   *
    */
   getPresignedUploadUrl?(
     fileData: ProviderGetPresignedUploadUrlDTO

packages/core/types/src/fulfillment/provider.ts

@@ -80,6 +80,7 @@ export interface IFulfillmentProvider {
   /**
    *
    * Return a unique identifier to retrieve the fulfillment plugin provider
+   * @ignore
    */
   getIdentifier(): string
   /**

packages/core/types/src/payment/provider.ts

@@ -339,7 +339,9 @@ export interface GetPaymentStatusOutput extends PaymentProviderOutput {
  */
 export type WebhookActionData = {
   /**
-   * The associated payment session's ID.
+   * The ID of the payment session in Medusa.
+   * Make sure to store this ID in the third-party payment provider
+   * to be able to retrieve the payment session later.
    */
   session_id: string
 
@@ -356,7 +358,7 @@ export type WebhookActionData = {
  */
 export type WebhookActionResult = {
   /**
-   * Normalized events from payment provider to internal payment module events.
+   * The action that was performed so that Medusa can handle it internally.
    */
   action: PaymentActions
 
@@ -392,7 +394,7 @@ export interface IPaymentProvider {
 
   /**
    * This method is used when creating an account holder in Medusa, allowing you to create
-   * the equivalent account in the third-party service. An account holder is useful to
+   * the equivalent account in the third-party payment provider. An account holder is useful to
    * later save payment methods, such as credit cards, for a customer in the
    * third-party payment provider using the {@link savePaymentMethod} method.
    *
@@ -444,7 +446,7 @@ export interface IPaymentProvider {
 
   /**
    * This method is used when updating an account holder in Medusa, allowing you to update
-   * the equivalent account in the third-party service.
+   * the equivalent account in the third-party payment provider.
    *
    * The returned data will be stored in the account holder created in Medusa. For example,
    * the returned `id` property will be stored in the account holder's `external_id` property.
@@ -488,7 +490,7 @@ export interface IPaymentProvider {
 
   /**
    * This method is used when an account holder is deleted in Medusa, allowing you
-   * to also delete the equivalent account holder in the third-party service.
+   * to also delete the equivalent account holder in the third-party payment provider.
    *
    * @param data - Input data including the details of the account holder to delete.
    * @returns The result of deleting the account holder. If an error occurs, throw it.