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

Documentation for GSB MCP implementations

/**
 * Documentation for the removeMappedItems operation
 */

/**
 * Returns documentation for the removeMappedItems operation
 * @return {string} markdown documentation
 */
export function removeMappedItemsDocs(): string {
  return `
# RemoveMappedItems Operation

## General Description

The \`removeMappedItems\` operation removes mapped items from a parent entity, with options for cascade deletion based on relationship type.

## Detailed Description

This operation allows you to remove the relationship between a parent entity and its mapped items. Depending on the relationship type and cascade settings, this operation may:
1. Simply break the reference between entities (for most relationships)
2. Delete the mapped items completely (if the relationship is marked as cascade or is a ManyToOne relationship)
3. Update the reference properties in both entities to maintain data integrity

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| request | object | Yes | The mapped remove request object containing the mapping details. |
| 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. |

### Request Object Structure

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| entDefName | string | Yes* | Name of the entity definition for the mapped items. Required if entDefId is not provided. |
| entDefId | string | Yes* | ID of the entity definition for the mapped items. Required if entDefName is not provided. |
| entityDef | object | No | Optional entity definition object with id and/or name properties. |
| items | array | Yes | Array of items to unmap from the parent entity. Typically contains IDs or identifying properties of the mapped items. |
| entityId | string | Yes | ID of the parent entity from which the items will be unmapped. |
| propName | string | Yes | Property name in the parent entity that holds the mapped items. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "deletedCount": number  // Number of removed mapped items
}
\`\`\`

### Error Response

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

## Example Usage

### Remove Items from an Order

\`\`\`typescript
const result = await removeMappedItems({
  request: {
    entDefName: "OrderItem",
    entityId: "order-123",
    propName: "items",
    items: [
      { id: "order-item-456" },
      { id: "order-item-789" }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(\`Removed \${result.deletedCount} items from the order\`);
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Remove Users from a Group (Reference Only)

\`\`\`typescript
// This will only break the reference between users and the group,
// not delete the user entities
const result = await removeMappedItems({
  request: {
    entDefName: "User",
    entityId: "group-456",
    propName: "members",
    items: [
      { id: "user-123" },
      { id: "user-456" }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(\`Removed \${result.deletedCount} users from the group\`);
}
\`\`\`

### Remove Child Entities with Cascade Delete

\`\`\`typescript
// This will delete the comment entities completely because
// the relationship is marked as cascade
const result = await removeMappedItems({
  request: {
    entDefName: "Comment",
    entityId: "post-789",
    propName: "comments",
    items: [
      { id: "comment-111" },
      { id: "comment-222" }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(\`Deleted \${result.deletedCount} comments from the post\`);
}
\`\`\`

## Additional Information

- The removeMappedItems operation handles different behaviors based on the relationship type:
  - For standard references (OneToMany, ManyToMany), it typically just breaks the reference
  - For ManyToOne relationships, it may delete the mapped items completely
  - For relationships marked with cascade delete, it will delete the mapped items
- The operation returns the number of affected items (removed mappings or deleted entities).
- When removing items from a relationship:
  - Reference properties in both entities are updated to maintain data integrity
  - If the reference is bidirectional, both sides of the relationship are updated
  - If cascade delete is enabled, dependent entities are also deleted
- For adding mapped items, use the saveMappedItems operation instead.
- Access permissions are enforced based on the provided token.
- The operation is permanent and cannot be undone, so it should be used with caution.
- Be particularly careful when working with relationships that have cascade delete enabled,
  as this will permanently delete the mapped entities.
`;
}

/**
 * Returns a brief summary of the removeMappedItems operation.
 * @return {string} A short description of the function.
 */
export function removeMappedItemsSummary(): string {
  return `
**Purpose**: Removes relationships between entities or deletes related entities.

**When to use**:
- Breaking connections between related entities
- Removing items from collections
- Deleting dependent entities (with cascade)

**Inputs**:
- request: Object with entityId, propName, items to remove {entDefName/entDefId: string, entityId: string, propName: string, items: [...,{id: string}]}
- token (optional)
- tenantCode (optional)

**Returns**: Count of removed mappings/deleted entities.

**Effects**: May permanently delete entities if relationship has cascade delete.
`;
}

export default removeMappedItemsDocs;