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

Documentation for GSB MCP implementations

/**
 * Documentation for the saveMappedItems operation
 */
/**
 * Returns documentation for the saveMappedItems operation
 * @return {string} markdown documentation
 */
export function saveMappedItemsDocs() {
    return `
# SaveMappedItems Operation

## General Description

The \`saveMappedItems\` operation saves or updates mapped items (related entities) for a parent entity.

## Detailed Description

This operation allows you to add or update related entities for a parent entity through a reference property. It's particularly useful for managing many-to-many or one-to-many relationships. The operation can create new related entities, update existing ones, and maintain the relationship between them and the parent entity.

Like the save and saveMulti operations, saveMappedItems supports complex JSON structures with nested objects and arrays. GSB automatically processes the data, performing inserts or updates for all nested entities and managing relationships based on the presence of primary keys.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| request | object | Yes | The mapped save 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 map to the parent entity. Each item can be a complex object with nested entities. |
| entityId | string | Yes | ID of the parent entity to which the items will be mapped. |
| propName | string | Yes | Property name in the parent entity that holds the mapped items. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "ids": [
        "string",  // ID of the first mapped item
        "string",  // ID of the second mapped item
        // Additional IDs in the same order as the input items
    ]
}
\`\`\`

### Error Response

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

## Example Usage

### Add Items to an Order

\`\`\`typescript
const result = await saveMappedItems({
  request: {
    entDefName: "OrderItem",
    entityId: "order-123",
    propName: "items",
    items: [
      {
        productName: "Smartphone",
        quantity: 1,
        unitPrice: 999.99
      },
      {
        productName: "Phone Case",
        quantity: 1,
        unitPrice: 29.99
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Added items with IDs:", result.ids);
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Update Existing Mapped Items

\`\`\`typescript
const result = await saveMappedItems({
  request: {
    entDefName: "OrderItem",
    entityId: "order-123",
    propName: "items",
    items: [
      {
        id: "item-456",  // Existing item - will be updated
        quantity: 2,     // Updating quantity
        unitPrice: 999.99
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Updated item with ID:", result.ids[0]);
}
\`\`\`

### Add Users to a Group

\`\`\`typescript
const result = await saveMappedItems({
  request: {
    entDefName: "User",
    entityId: "group-789",
    propName: "members",
    items: [
      { id: "user-123" },  // Reference to existing user
      { id: "user-456" }   // Reference to existing user
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Added users to group");
}
\`\`\`

### Save Mapped Items with Complex Nested Data

\`\`\`typescript
const result = await saveMappedItems({
  request: {
    entDefName: "OrderItem",
    entityId: "order-123",
    propName: "items",
    items: [
      {
        productName: "Gaming Console",
        quantity: 1,
        unitPrice: 499.99,
        product: {
          id: "product-789", // Existing product - will be referenced
          name: "Next-Gen Console",
          category: "Electronics"
        },
        options: [
          {
            // New option will be created and linked to the order item
            name: "Extended Warranty",
            price: 49.99
          },
          {
            id: "option-456", // Existing option - will be updated
            name: "Premium Controller",
            price: 69.99
          }
        ],
        shippingDetails: {
          // New shipping details will be created and linked
          method: "Express",
          estimatedDelivery: "2023-06-20",
          tracking: {
            // Nested object within shipping details
            carrier: "FastShip",
            number: "FS123456789"
          }
        }
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Added complex order item with ID:", result.ids[0]);
}
\`\`\`

## Additional Information

- The saveMappedItems operation can both create new related entities and update existing ones.
- When an item has an ID, the system will update the existing entity if it exists.
- When an item doesn't have an ID, a new entity will be created.
- The operation maintains the relationship between the parent entity and the mapped items.
- For many-to-many relationships, the operation updates the join table appropriately.
- For one-to-many relationships, the operation updates the foreign key in the child entities.
- For removing mapped items, use the removeMappedItems operation instead.
- Access permissions are enforced based on the provided token.
- The operation returns an array of IDs for all saved mapped items, in the same order as the input items.

### Complex Data Handling

- Each item in the items array can include complex nested objects and arrays.
- GSB automatically processes nested objects and arrays as related entities.
- For each nested entity:
  - If an ID is provided and exists in the database, the entity will be updated.
  - If no ID is provided or the ID doesn't exist, a new entity will be created.
- Relationships between entities are automatically maintained at all levels of nesting.
- One-to-many and many-to-many relationships are handled through arrays of objects.
- One-to-one relationships are handled through nested objects.
- The system intelligently determines whether to perform inserts or updates based on the presence of primary keys.
- All operations are performed in a single transaction, ensuring data consistency across all entities and their related data.
- If any part of the complex save operation fails, the entire transaction is rolled back.
`;
}
/**
 * Returns a brief summary of the saveMappedItems operation.
 * @return {string} A short description of the function.
 */
export function saveMappedItemsSummary() {
    return `
**Purpose**: Adds or updates related entities for a parent entity.

**When to use**:
- Creating/updating items in collections
- Managing one-to-many relationships
- Establishing many-to-many connections

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

**Returns**: IDs of saved items.

**Effects**: Creates/updates related entities, establishes relationships.
`;
}
export default saveMappedItemsDocs;
//# sourceMappingURL=saveMappedItems.js.map