/**
 * Documentation for the runWfFunction operation
 */

/**
 * Returns documentation for the runWfFunction operation
 * @return {string} markdown documentation
 */
export function runWfFunctionDocs(): string {
  return `
# RunWfFunction Operation

## General Description

The \`runWfFunction\` operation executes a specific workflow function directly without needing to start or run a complete workflow.

## Detailed Description

The \`runWfFunction\` operation allows you to execute a specific GSB serverless function by its ID or name. This is useful for:
- Executing utility functions from other functions
- Testing function behavior in isolation
- Building modular function architectures where complex operations are broken into smaller, reusable functions
- Implementing function-to-function communication patterns

When calling a function using \`runWfFunction\`, you can pass:
- An entity context
- Custom parameters via the \`prms\` object
- Other execution context information

## Input Parameters

The \`runWfFunction\` operation accepts a request object with the following structure:

\`\`\`javascript
{
  "function": {
    // Either use ID
    "id": "function-uuid-here",
    // OR use name (one of these is required)
    "name": "Function Name Here"
  },
  "instance": {
    // The entity to pass to the function (optional)
    "entity": {
      // Entity data
    },
    // Additional parameters to pass (optional)
    "prms": {
      "param1": "value1",
      "param2": "value2"
    }
  }
}
\`\`\`

## Response

The response from \`runWfFunction\` contains:

1. A \`response\` field with whatever was set in the called function using:
   - \`_instance.response = {...}\`
   - \`_runtime.success("Message", responseData)\`
   - \`_runtime.end(statusCode, message, data)\`

2. Status information and execution results from the function

Example response structure:
\`\`\`javascript
{
  "response": {
    // Whatever was set by the function
    "success": true,
    "data": { "id": "123", "status": "completed" }
  },
  "status": 200,
  "message": "Operation completed successfully"
}
\`\`\`

## Example Usage

### Example 1: Basic Function Call

\`\`\`javascript
// Define the function request
let functionRequest = {
  function: {
    name: "Calculate Order Total"
  },
  instance: {
    entity: myOrder,
    prms: {
      applyDiscounts: true
    }
  }
};

// Call the function
let entityService = new GsbEntityService(_runtime);
let result = await entityService.runWfFunction(functionRequest);

// Access the response
if (result.response && result.response.success) {
  let calculatedTotal = result.response.totalPrice;
  // Continue processing...
}
\`\`\`

### Example 2: Function Chain

\`\`\`javascript
async function processOrder() {
  try {
    // Step 1: Validate order
    let validateResult = await entityService.runWfFunction({
      function: { name: "Validate Order" },
      instance: { entity: _instance.entity }
    });
    
    if (!validateResult.response.isValid) {
      _runtime.error(validateResult.response.validationErrors.join(", "));
      return;
    }
    
    // Step 2: Calculate totals
    let totalsResult = await entityService.runWfFunction({
      function: { name: "Calculate Order Totals" },
      instance: { entity: _instance.entity }
    });
    
    // Step 3: Process payment
    let paymentResult = await entityService.runWfFunction({
      function: { name: "Process Payment" },
      instance: { 
        entity: _instance.entity,
        prms: { calculatedTotals: totalsResult.response.totals }
      }
    });
    
    _runtime.success("Order processed successfully", paymentResult.response);
  } catch (error) {
    _runtime.error(error);
  }
}
\`\`\`

## Additional Information

### Best Practices

1. **Error Handling**: Always implement proper error handling when calling functions:
   \`\`\`javascript
   try {
     let result = await entityService.runWfFunction(request);
     if (!result.response || result.response.error) {
       throw new Error(result.response?.errorMessage || "Function execution failed");
     }
   } catch (error) {
     // Handle error
   }
   \`\`\`

2. **Data Passing**: Be consistent in how you structure function responses to make function chains more maintainable.

3. **Function Isolation**: Design functions to be self-contained units that can be tested and executed independently.

4. **Performance**: Be mindful of function call overhead in high-volume scenarios. Consider consolidating multiple small function calls if performance becomes an issue.

### Security Considerations

Functions called via \`runWfFunction\` execute with the permissions of the calling context. Ensure that sensitive operations have appropriate authorization checks within the called function itself.
`;
}

/**
 * Returns a brief summary of the runWfFunction operation.
 * @return {string} A short description of the function.
 */
export function runWfFunctionSummary(): string {
  return `
**Purpose**: Executes a specific workflow function directly by name or ID.

**When to use**:
- Need targeted function execution without running a complete workflow
- Building modular function architectures with reusable components
- Implementing function-to-function communication patterns
- Testing workflow components in isolation

**Key features**:
- Pass entity context and custom parameters
- Receive structured response data
- Chain multiple function calls together
- Execute functions synchronously or as part of larger processes
`;
}

export default runWfFunctionDocs;