@gsb-core/mcp-docs/src/docs/removeProperty.ts

Documentation for GSB MCP implementations

/**
 * Documentation for the removeProperty operation
 */

/**
 * Returns documentation for the removeProperty operation
 * @return {string} markdown documentation
 */
export function removePropertyDocs(): string {
  return `
# RemoveProperty Operation

## General Description

The \`removeProperty\` operation removes a property (column) from an existing entity definition.

## Detailed Description

This operation allows you to remove a property from an existing entity definition. Removing a property modifies the entity definition schema and alters the underlying database structure. This operation is permanent and will result in the loss of all data stored in that property across all entities of this type, so it should be used with caution.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| property | object | Yes | The property object to remove. Must contain the \`name\` of the property. Optionally, it can contain the \`id\` of the property. |
| entityDef | object | No | Optional. The entity definition object to modify. Should contain either the \`id\` or \`name\` of the 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. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "data": {
        // The updated entity definition without the removed property
        "id": "string",
        "name": "string",
        "properties": [
            // Remaining properties
        ]
    }
}
\`\`\`

### Error Response

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

## Example Usage

### Remove a Simple Property

\`\`\`typescript
const result = await removeProperty({
  property: { name: "faxNumber" },
  entityDef: { id: "customer-def-123" }, // or { name: "Customer" }
  token: "your-auth-token"
});

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

### Remove a Property with Error Handling
we can just provide property id to remove the property
\`\`\`typescript
try {
  const result = await removeProperty({
    property: { id: "property-id" },
    token: "your-auth-token"
  });

  if (result.success) {
    console.log("Legacy code property removed successfully");
  } else {
    console.error("Error removing property:", result.error);
  }
} catch (error) {
  console.error("Exception occurred:", error);
}
\`\`\`

### Remove Multiple Properties Sequentially
you can user removeMappedItems to remove multiple properties all at once, pls refer to the removeMappedItems docs for more information
you ill need to provide the entityId: the id of entity definition and entityDef as "GsbEntityDef" and propName as "properties" and items as property array with ids like {id: "property-id"}


## Additional Information

- The removeProperty operation permanently removes a property from the entity definition.
- All data stored in the removed property will be lost across all entities of this type.
- This operation cannot be undone, so use it with caution.
- Some system properties may be protected and cannot be removed.
- Properties that are part of relationships or referenced by other entity definitions may require additional steps to remove.
- Required properties that are in use by existing entities may need special handling.
- For adding new properties, use the addProperty operation.
- For updating existing properties, use the updateProperty operation.
- Access permissions are enforced based on the provided token.
- In production environments, it's recommended to:
  1. Back up your data before removing properties
  2. Consider the impact on existing integrations and code
  3. If possible, deprecate properties before removing them
  4. Communicate changes to users and other stakeholders
`;
}

/**
 * Returns a brief summary of the removeProperty operation.
 * @return {string} A short description of the function.
 */
export function removePropertySummary(): string {
  return `
**Purpose**: Permanently removes a property from an entity definition.

**When to use**:
- Eliminating unused properties
- Restructuring entity schemas

**Inputs**:
- property: Object with name or id of property to remove
- entityDef (optional): Object identifying entity definition

**Returns**: Updated entity definition without the removed property.

**Effects**: PERMANENT DATA LOSS - All data in this property will be deleted across all entities.
`;
}

export default removePropertyDocs;