chore(workflows-sdk): add TSDocs related to create-hook (#8380)

packages/core/workflows-sdk/src/helper/type.ts

@@ -44,9 +44,21 @@ export type FlowCancelOptions = {
   container?: LoadedModule[] | MedusaContainer
 }
 
+/**
+ * The details of a workflow's execution.
+ */
 export type WorkflowResult<TResult = unknown> = {
+  /**
+   * Any errors that occured in the workflow.
+   */
   errors: TransactionStepError[]
+  /**
+   * The transaction details of the workflow's execution.
+   */
   transaction: DistributedTransaction
+  /**
+   * The result returned by the workflow.
+   */
   result: TResult
 }
 

packages/core/workflows-sdk/src/utils/composer/create-hook.ts

@@ -19,11 +19,39 @@ export type Hook<Name extends string, Input> = {
 }
 
 /**
- * Define a workflow hook to be executed within steps. The created hook
+ * Expose a hook in your workflow where you can inject custom functionality as a step function. 
- * is exposed publicly for the workflow consumers to inject and run
- * custom logic.
  * 
- * Hooks behaves like steps
+ * A handler hook can later be registered to consume the hook and perform custom functionality.
+ * 
+ * Learn more in [this documentation](https://docs.medusajs.com/v2/advanced-development/workflows/add-workflow-hook).
+ * 
+ * @param name - The hook's name. This is used when the hook handler is registered to consume the workflow.
+ * @param input - The input to pass to the hook handler.
+ * @returns A workflow hook.
+ *
+ * @example
+ * import {
+ *   createStep,
+ *   createHook,
+ *   createWorkflow,
+ *   WorkflowResponse,
+ * } from "@medusajs/workflows-sdk"
+ * import { createProductStep } from "./steps/create-product"
+ * 
+ * export const myWorkflow = createWorkflow(
+ *   "my-workflow", 
+ *   function (input) {
+ *     const product = createProductStep(input)
+ *     const productCreatedHook = createHook(
+ *       "productCreated", 
+ *       { productId: product.id }
+ *     )
+ * 
+ *     return new WorkflowResponse(product, {
+ *       hooks: [productCreatedHook],
+ *     })
+ *   }
+ * )
  */
 export function createHook<Name extends string, TInvokeInput>(
   name: Name,

packages/core/workflows-sdk/src/utils/composer/type.ts

@@ -216,11 +216,28 @@ export type ReturnWorkflow<TData, TResult, THooks extends any[]> = {
   > &
     ExportedWorkflow<TData, TResult, TDataOverride, TResultOverride>
 } & {
+  /**
+   * This method executes the workflow as a step. Useful when running a workflow within another.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/v2/advanced-development/workflows/execute-another-workflow).
+   * 
+   * @param param0 - The options to execute the workflow.
+   * @returns The workflow's result
+   */
   runAsStep: ({
     input,
   }: {
+    /**
+     * The workflow's input.
+     */
     input: TData | WorkflowData<TData>
   }) => ReturnType<StepFunction<TData, TResult>>
+  /**
+   * This method executes a workflow.
+   * 
+   * @param args - The options to execute the workflow.
+   * @returns Details of the workflow's execution, including its result.
+   */
   run: <TDataOverride = undefined, TResultOverride = undefined>(
     ...args: Parameters<
       ExportedWorkflow<TData, TResult, TDataOverride, TResultOverride>["run"]
@@ -228,8 +245,19 @@ export type ReturnWorkflow<TData, TResult, THooks extends any[]> = {
   ) => ReturnType<
     ExportedWorkflow<TData, TResult, TDataOverride, TResultOverride>["run"]
   >
+  /**
+   * This method retrieves the workflow's name.
+   */
   getName: () => string
+  /**
+   * This method sets the workflow's configurations.
+   */
   config: (config: TransactionModelOptions) => void
+  /**
+   * The workflow's exposed hooks, used to register a handler to consume the hook.
+   * 
+   * Learn more in [this documentation](https://docs.medusajs.com/v2/advanced-development/workflows/add-workflow-hook#how-to-consume-a-hook).
+   */
   hooks: ConvertHooksToFunctions<THooks>
 }