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

Documentation for GSB MCP implementations

/**
 * Documentation for the delete operation
 */

/**
 * Returns documentation for the delete operation
 * @return {string} markdown documentation
 */
export function deleteDocs(): string {
  return `
# Delete Operation

## General Description

The \`delete\` operation removes entities from the database based on specified criteria.

## Detailed Description

This operation allows you to delete one or more entities that match specific criteria. It can delete a single entity by ID or multiple entities that match certain conditions. The operation is permanent and cannot be undone, so it should be used with caution.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| request | object | Yes | The delete request object specifying what to delete. |
| 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. Required if entDefId is not provided. |
| entDefId | string | Yes* | ID of the entity definition. Required if entDefName is not provided. |
| entityDef | object | No | Optional entity definition object with id and/or name properties. |
| entityId | string | Yes | ID of the entity to delete. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "deletedCount": number  // Number of deleted entities
}
\`\`\`

### Error Response

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

## Example Usage

### Delete a Single Entity by ID

\`\`\`typescript
const result = await delete({
  request: {
    entDefName: "Customer",
    entityId: "customer-id-to-delete"
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log(\`Deleted \${result.deletedCount} customer(s)\`);
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Delete Using Entity Definition ID

\`\`\`typescript
const result = await delete({
  request: {
    entDefId: "customer-def-id",
    entityId: "customer-id-to-delete"
  },
  token: "your-auth-token"
});

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

### Delete with Entity Definition Object

\`\`\`typescript
const result = await delete({
  request: {
    entityDef: {
      name: "Order"
    },
    entityId: "order-id-to-delete"
  },
  token: "your-auth-token"
});
\`\`\`

## Additional Information

- The delete operation is permanent and cannot be undone. Use it with caution.
- When deleting by ID, exactly one entity will be deleted if it exists.
- The operation returns the number of affected rows (deleted entities).
- Access permissions are enforced based on the provided token.
- For complex delete operations based on query parameters, use the deleteQuery operation instead.
- Depending on the entity definition, deleting an entity may cascade to related entities or be prevented by referential integrity constraints.
- For soft delete functionality (marking entities as deleted without physically removing them), consider using a status field and the save operation instead.
`;
}

/**
 * Returns a brief summary of the delete operation.
 * @return {string} A short description of the function.
 */
export function deleteSummary(): string {
  return `
**Purpose**: Removes a single entity from the database by its ID.

**When to use**:
- Deleting specific records
- Removing data permanently
- Targeted data cleanup

**Inputs**:
- request: Object with entityId and entity definition info {entDefName/entDefId: string, entityId: string}
- token (optional)
- tenantCode (optional)

**Returns**: Count of deleted entities (typically 1).

**Effects**: PERMANENT DATA REMOVAL - Cannot be undone.
`;
}

export default deleteDocs;