@gsb-core/mcp-docs/dist/docs/getCopy.js

Documentation for GSB MCP implementations

/**
 * Documentation for the getCopy operation
 */
/**
 * Returns documentation for the getCopy operation
 * @return {string} markdown documentation
 */
export function getCopyDocs() {
    return `
# GetCopy Operation

## General Description

The \`getCopy\` operation retrieves a copy of an entity with its related entities based on cascade reference rules.

## Detailed Description

This operation creates a deep copy of an entity, including all its properties and related entities based on cascade reference rules defined in the entity properties. Unlike the standard getById operation, getCopy follows reference relationships and includes related entities in a multilevel JSON structure. This is particularly useful when you need to copy an entity along with its related entities or when you need to retrieve a complete object graph for display or processing.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| request | object | Yes | Object containing the entity identifier. It should have \`definitionType\` (string, name of the entity definition) and \`id\` (string, ID of the entity to copy). |
| 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,
    "entity": {
        "id": "string",
        "title": "string",
        "createDate": "string",
        "lastUpdateDate": "string",
        // All other properties of the entity
        // Related entities as nested objects based on cascade references
        "relatedEntity1": {
            "id": "string",
            "title": "string",
            // Properties of the related entity
            // Potentially more nested related entities
        },
        "relatedEntities": [
            {
                "id": "string",
                "title": "string",
                // Properties of each related entity in the collection
            }
        ]
    }
}
\`\`\`

### Error Response

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

## Example Usage

### Get a Copy of an Entity with Related Entities

\`\`\`typescript
const result = await getCopy({
  request: {
    definitionType: "Order",
    id: "order-id-123"
  },
  token: "your-auth-token"
});

if (result.success) {
  const order = result.entity;
  console.log("Order:", order.title);
  
  // Access related customer entity (assuming a cascade reference)
  if (order.customer) {
    console.log("Customer:", order.customer.name);
  }
  
  // Access related order items (assuming a cascade reference)
  if (order.orderItems && Array.isArray(order.orderItems)) {
    console.log("Order Items:", order.orderItems.length);
    order.orderItems.forEach(item => {
      console.log(\`- \${item.title}: \${item.quantity} x \${item.unitPrice}\`);
      
      // Access product information if cascaded
      if (item.product) {
        console.log(\`  Product: \${item.product.title}\`);
      }
    });
  }
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Copy an Entity for Duplication

\`\`\`typescript
// First, get a copy of the entity with related entities
const copyResult = await getCopy({
  request: {
    definitionType: "Product",
    id: "product-id-456"
  },
  token: "your-auth-token"
});

if (copyResult.success) {
  const productCopy = copyResult.entity;
  
  // Modify the copy as needed
  delete productCopy.id; // Remove ID to create a new entity
  productCopy.title = \`Copy of \${productCopy.title}\`;
  
  // Save the modified copy as a new entity
  const saveResult = await save({
    entDefName: "Product",
    entity: productCopy,
    token: "your-auth-token"
  });
  
  if (saveResult.success) {
    console.log("Created copy with ID:", saveResult.id);
  }
}
\`\`\`

## Additional Information

- The getCopy operation follows cascade reference rules defined in the entity properties.
- Cascade references are determined by the property's refType and additional cascade settings.
- All the data is returned with newly generated ids or no id set, except for the references where copyAction is set to reference.
- The title field is return as title + " Copy"
- You can use the save operation to save the copy.
- copyAction filed in property definition determines what happens with the related entities.(include, exclude, reference)
- The operation returns a multilevel JSON object with nested related entities, not just a flat entity.
- This operation is particularly useful for:
  - Creating duplicates of complex entities with related data
  - Retrieving a complete object graph for display or processing
  - Implementing copy functionality in user interfaces
- Unlike the standard getById operation, getCopy includes related entities directly in the response.
- The depth of cascading is determined by the entity definition's reference properties.
- For references marked as cascade, the related entities are included in the result.
- For references not marked as cascade, only the reference ID is included.
- Access permissions are enforced for both the main entity and all related entities.
- Performance may be impacted for entities with many cascade references or deep object graphs.
`;
}
/**
 * Returns a brief summary of the getCopy operation.
 * @return {string} A short description of the function.
 */
export function getCopySummary() {
    return `
**Purpose**: Retrieves a deep copy of an entity with its related entities.

**When to use**:
- Creating duplicates of complex entities
- Getting complete object graphs
- Copying entities with relationships
- Preparing data for duplication

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

**Returns**: Entity with nested related entities based on cascade rules.
`;
}
export default getCopyDocs;
//# sourceMappingURL=getCopy.js.map