/**
 * Documentation for the updateEntityDef operation
 */

/**
 * Returns documentation for the updateEntityDef operation
 * @return {string} markdown documentation
 */
export function updateEntityDefDocs(): string {
  return `
# UpdateEntityDef Operation

## General Description

The \`updateEntityDef\` operation modifies an existing entity definition with updated schema information.

## Detailed Description

This operation allows you to update the metadata and structure of an existing entity definition. You can modify attributes like the title, description, permissions, and other aspects of the entity definition. Some structural changes may be limited to preserve data integrity, and adding or removing properties should be done using the dedicated addProperty and removeProperty operations.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| entityDef | object | Yes | The entity definition object with updated information. Must include the ID of the existing entity definition. |
| token | string | No | Authentication token for your request. If not provided, the system will use the default API key from environment variables. |
| tenantCode | string | No | Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables. |

### EntityDef Object Structure

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| id | string | Yes | The ID of the existing entity definition to update. |
| name | string | No | The name of the entity definition (usually cannot be changed after creation). |
| title | string | No | Display title for the entity definition. |
| description | string | No | Description of the entity definition. |
| dbTableName | string | No | Database table name (usually cannot be changed after creation). |
| publicAccess | boolean | No | Whether entity is publicly accessible. |
| activityLogLevel | number | No | Level of activity logging (0=None, 1=Changes, 2=All). |
| isActive | boolean | No | Whether the entity definition is active. |
| permissions | array | No | Array of permission objects controlling access to the entity. |
| propertyPermissions | array | No | Base permissions applied to all properties unless overridden. If set, these permissions are applied to all properties that don't have their own permissions defined. |
| workflowTriggers | array | No | Array of workflow trigger objects for the entity. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "entityDef": // updated entity definition object including id and properties with id
}
\`\`\`

### Error Response

\`\`\`json
{
    "success": false,
    "error": "Error message describing what went wrong"
}
\`\`\`

## Example Usage

### Update Basic Entity Information with Permissions

\`\`\`typescript
const result = await updateEntityDef({
  entityDef: {
    id: "product-def-123",
    title: "Product Catalog Item",
    description: "Updated description for product catalog items",
    publicAccess: false,
    permissions: [
      {id: "product-team-write-permission-id"},
      {id: "all-users-read-permission-id"}
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Entity definition updated successfully");
  console.log("Updated title:", result.data.title);
  console.log("Updated description:", result.data.description);
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Update Entity Activity Logging and Workflow Triggers

\`\`\`typescript
const result = await updateEntityDef({
  entityDef: {
    id: "order-def-456",
    activityLogLevel: 2, // Full logging
    title: "Customer Order Record",
    workflowTriggers: [
      {
        id: "notify-on-status-change"
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Entity definition updated with new logging level and workflow triggers");
}
\`\`\`


### Update Entity Property Permissions with Mixed Access

\`\`\`typescript
const result = await updateEntityDef({
  entityDef: {
    id: "employee-def-456",
    propertyPermissions: [
      {id: "hr-team-permission-id"} // HR team can access all properties by default
    ],
    properties: [
      {
        name: "name",
        permissions: [
          {id: "all-users-read-permission-id"} // Everyone can read names
        ]
      },
      {
        name: "salary",
        permissions: [
          {id: "finance-team-permission-id"}, // Only finance team can access salary
          {id: "self-read-permission-id"} // Employees can see their own salary
        ]
      }
      // All other properties will use propertyPermissions (HR team only)
    ]
  },
  token: "your-auth-token"
});
\`\`\`

## Additional Information

### Immutable Properties
Some properties may be immutable after creation, particularly:
- The name of the entity definition
- The database table name
- Core structural elements
- Primary key configurations
- Certain reference property settings

### Property Management
- For adding new properties to an entity definition, use the addProperty operation
- For removing properties from an entity definition, use the removeProperty operation
- For updating existing properties, use the updateProperty operation
- Property-level permissions can only be modified through the updateProperty operation

### Permissions
- Entity-level permissions control overall access to the entity
- Property-level permissions can be set in two ways:
  1. Using \`propertyPermissions\` at the entity level to set base permissions for all properties
  2. Using \`permissions\` on individual properties to override the base permissions
- If you update \`propertyPermissions\`:
  - The new permissions apply to all properties that don't have their own \`permissions\` defined
  - Properties with their own \`permissions\` remain unaffected

### System Behavior
- Setting an entity definition as inactive (isActive: false) prevents new entities from being created but preserves existing data
- Changes to activity logging levels take effect immediately for new operations
- Updates to workflow triggers are applied to all subsequent events
- Access permissions are enforced based on the provided token

### Best Practices
- Be cautious when updating entity definitions in production environments
- Test changes in a development environment first
- Consider the impact on existing data and integrations
- Document significant changes for other developers
- Coordinate updates with related entity definitions if necessary

### Related Operations
- For creating new entity definitions, use the createEntityDef operation
- For retrieving entity definitions, use the getEntityDef operation
- For creating or updating multiple related entities at once, use the createOrUpdateSchema operation
`;
}

/**
 * Returns a brief summary of the updateEntityDef operation.
 * @return {string} A short description of the function.
 */
export function updateEntityDefSummary(): string {
  return `
**Purpose**: Modifies existing entity definition metadata and configuration.

**When to use**:
- Updating entity titles/descriptions
- Changing permission settings
- Configuring workflow triggers
- Adjusting entity behavior

**Inputs**:
- entityDef: Object with id and attributes to update
- token (optional)
- tenantCode (optional)

**Returns**: Updated entity definition.

**Note**: For property changes, use dedicated property operations.
`;
}

export default updateEntityDefDocs;