/**
 * Documentation for the updateProperty operation
 */

/**
 * Returns documentation for the updateProperty operation
 * @return {string} markdown documentation
 */
export function updatePropertyDocs(): string {
  return `
# UpdateProperty Operation

## General Description

The \`updateProperty\` operation modifies an existing property in an entity definition.

## Detailed Description

This operation allows you to update the attributes and settings of an existing property in an entity definition. You can modify aspects such as the title, description, validation rules, permissions, and other metadata. Some structural changes may be limited to preserve data integrity, and certain core attributes like the property name or data type may have restrictions on modifications.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| property | object | Yes | The property definition object with updated information. It MUST include either the \`id\` of the property, the \`name\` of the property, or the \`ownerEntityDefId\` to identify which property to update. Other attributes to be updated should be included. |
| entityDef | object | No | Optional. The entity definition object to modify. Should contain either the \`id\` or \`name\` of the entity definition. Not required if property.id or property.ownerEntityDefId is provided. |
| 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. |

### Property Object Structure

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| id | string | No | ID of the property to update. If provided, entityDef is not required. |
| ownerEntityDefId | string | No | ID of the entity definition that owns this property. If provided, entityDef is not required. |
| name | string | No | Name of the property (cannot be changed after creation). |
| title | string | No | Human-readable title for the property. |
| description | string | No | Description of the property. |
| definition_id | string | No | Reference to the property definition (data type). |
| isRequired | boolean | No | Whether the property is required. |
| isSearchable | boolean | No | Whether the property should be searchable. |
| isUnique | boolean | No | Whether the property value must be unique across all entities. |
| maxLength | number | No | Maximum length for string properties. |
| defaultValue | any | No | Default value for the property if not specified when creating an entity. |
| regex | string | No | Validation regex pattern. |
| refEntDef_id | string | No | Referenced entity definition ID (for reference properties). |
| refEntPropName | string | No | Property name in referenced entity (for reference properties). |
| refType | number | No | Reference type (OneToOne, OneToMany, etc.). |
| isEncrypted | boolean | No | Whether the property value should be encrypted. |
| isMultiLingual | boolean | No | Whether the property supports multiple languages. |
| fullTextIndex | boolean | No | Whether to create a vector index for full text search (for RichText properties). |
| cascadeReference | boolean | No | Whether to cascade delete and include in copy operations (for reference properties). |
| permissions | array | No | Array of permission objects controlling access to the property. |
| formModes | number | No | Form modes where property is visible. |
| listScreens | number | No | List screens where property is visible. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "data": {
        // The updated entity definition with the modified property
        "id": "string",
        "name": "string",
        "properties": [
            // All properties including the updated one
        ]
    }
}
\`\`\`

### Error Response

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

## Example Usage

### Update Property Title and Description

\`\`\`typescript
const result = await updateProperty({
  property: {
    name: "phoneNumber", // Name of the property to update
    title: "Contact Phone",
    description: "Primary contact phone number for the customer",
    permissions: [
      {id: "sales-team-write-permission-id"},
      {id: "all-users-read-permission-id"}
    ]
  },
  entityDef: { id: "customer-def-123" }, // or { name: "Customer" }
  token: "your-auth-token"
});

if (result.success) {
  console.log("Property updated successfully");
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Update Property Validation Rules and Security
Using property.id to identify the property:

\`\`\`typescript
const result = await updateProperty({
  property: {
    id: "property-id",
    name: "price",
    regex: "^[0-9]+(\\.[0-9]{1,2})?$",
    maxLength: 10,
    isEncrypted: true,
    permissions: [{id: "finance-team-permission-id"}]
  },
  token: "your-auth-token"
});
\`\`\`

### Update Property with Advanced Features
Using ownerEntityDefId to specify the owner:

\`\`\`typescript
const result = await updateProperty({
  property: {
    name: "customerReference",
    title: "Customer Reference Number",
    isRequired: true,
    isSearchable: true,
    isMultiLingual: true,
    description: "Unique reference number provided by the customer",
    ownerEntityDefId: "order-def-789"
  },
  token: "your-auth-token"
});
\`\`\`

### Update Reference Property Settings

\`\`\`typescript
const result = await updateProperty({
  property: {
    name: "assignedTo",
    refEntDef_id: "user-def-id",
    refEntPropName: "assignedTasks",
    refType: 3, // ManyToOne
    cascadeReference: true, // Enable cascade delete
    permissions: [
      {id: "task-managers-permission-id"},
      {id: "assigned-user-permission-id"}
    ]
  },
  entityDef: { name: "Task" },
  token: "your-auth-token"
});
\`\`\`

### Update Multiple Properties
You can use saveMappedItems to update multiple properties at once. Please refer to the saveMappedItems documentation for more information.
Required parameters:
- entityId: The ID of the entity definition
- entityDef: "GsbEntityDef"
- propName: "properties"
- items: Array of property objects to update

## Additional Information

### Property Identification
- Properties can be identified using:
  - property.id: Direct property ID
  - property.name + entityDef: Property name within an entity
  - property.name + property.ownerEntityDefId: Property name with owner entity ID

### Immutable Attributes
Some property attributes cannot be changed after creation:
- Property name
- Core data type (definition_id)
- Primary key status
- Certain reference property configurations

### Permissions
- If you update permissions, the new permissions array completely replaces existing permissions
- If you don't include permissions in the update, existing permissions remain unchanged
- Permissions can be defined in the Admin UI or via API using the "GsbPermission" entity definition
- Don't pass permission IDs that don't exist in the system; instead, pass a fully defined GsbPermission object

### Caching and Availability
- Upon updating a property, the system initiates a cache update process across all redundant servers
- The cache update process is asynchronous and may take up to 5 seconds to complete
- During this time, the updated property configuration may not be immediately available
- It's important to wait for the cache update process to complete before making additional changes

### Data Integrity
When updating a property:
- Making a property required may affect existing entities that don't have a value
- Making a property unique will validate that all existing values are unique
- Adding or modifying validation rules will not automatically validate existing data
- Changing the default value only affects new entities created after the change
- Enabling encryption will not automatically encrypt existing values

### System Behavior
- Changes to searchability may trigger index updates
- Modifying reference properties may affect related entities
- Enabling full text search will create necessary database indexes
- Permission changes take effect immediately for new operations

### Best Practices
- Test changes in a development environment first
- Consider the impact on existing data and queries
- Document significant changes for other developers
- Coordinate updates with related entity definitions
- Use batch updates when modifying multiple properties

### Related Operations
- For adding new properties, use the addProperty operation
- For removing properties, use the removeProperty operation
- For updating multiple properties, use the saveMappedItems operation
- For complete entity updates, use the updateEntityDef operation
`;
}

/**
 * Returns a brief summary of the updateProperty operation.
 * @return {string} A short description of the function.
 */
export function updatePropertySummary(): string {
  return `
**Purpose**: Modifies an existing property within an entity definition.

**When to use**:
- Changing property titles/descriptions
- Updating validation rules
- Modifying security settings
- Adjusting relationship configurations

**Inputs**:
- property: Object with id/name and attributes to update
- entityDef (optional): Object identifying entity definition
- token (optional)
- tenantCode (optional)

**Returns**: Updated entity definition with modified property.

**Note**: Some core attributes (name, data type) cannot be changed.
`;
}

export default updatePropertyDocs;