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

Documentation for GSB MCP implementations

/**
 * Documentation for the save operation
 */
/**
 * Returns documentation for the save operation
 * @return {string} markdown documentation
 */
export function saveDocs() {
    return `
# Save Operation

## General Description

The \`save\` operation creates a new entity or updates an existing one in the database.

## Detailed Description

This operation handles both creating new entities and updating existing ones. When saving an entity without an ID, a new entity is created, and an ID is automatically generated. When saving an entity with an existing ID, the entity is updated. The operation validates the entity against its definition before saving, ensuring data integrity.

The save operation supports complex JSON structures with nested objects and arrays, automatically handling relationships between entities. GSB will intelligently process the data, performing inserts or updates for all nested entities and managing relationships automatically based on the presence of primary keys.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| request | object | Yes | The request object containing the entity definition and entity to save. |
| request.entityDef | object | Yes | The entity definition object with id and/or name properties. |
| request.entity | object | Yes | The entity object to save, which can include nested objects and arrays for related entities. |
| request.entityDef.name | string | Yes* | Name of the entity definition. Required if entDefId is not provided. |
| request.entityDef.id | string | Yes* | ID of the entity definition. Required if entDefName is not provided. |
| request.entity | object | Yes | The entity object to save, which can include nested objects and arrays for related entities. |
| 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,
    "id": "string",  // ID of the created or updated entity
    "isUpdate": boolean  // Whether this was an update (true) or create (false) operation
}
\`\`\`

### Error Response

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

## Example Usage

### Creating a New Entity

\`\`\`typescript
const result = await save({
  entDefName: "Customer",
  entity: {
    firstName: "John",
    lastName: "Doe",
    email: "john@example.com",
    status: "active"
  }
});

if (result.success) {
  console.log("New customer created with ID:", result.id);
  console.log("Is update?", result.isUpdate); // false
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Updating an Existing Entity

\`\`\`typescript
const result = await save({
  entDefName: "Customer",
  entity: {
    id: "existing-customer-id",
    firstName: "John",
    lastName: "Doe",
    email: "john.updated@example.com",
    status: "inactive"
  }
});

if (result.success) {
  console.log("Customer updated successfully with ID:", result.id);
  console.log("Is update?", result.isUpdate); // true
} else {
  console.error("Error:", result.error);
}
\`\`\`

### Saving Complex Nested Data

\`\`\`typescript
const result = await save({
  entDefName: "Order",
  entity: {
    orderNumber: "ORD-12345",
    orderDate: "2023-06-15",
    status: "pending",
    customer: {
      id: "existing-customer-id",  // Existing customer - will be updated
      firstName: "John",
      lastName: "Doe",
      email: "john@example.com"
    },
    items: [
      {
        id: "existing-item-id",  // Existing item - will be updated
        productName: "Smartphone",
        quantity: 1,
        unitPrice: 999.99
      },
      {
        // No ID - new item will be created
        productName: "Phone Case",
        quantity: 2,
        unitPrice: 29.99
      }
    ],
    shippingAddress: {
      // New address will be created and linked to the order
      street: "123 Main St",
      city: "Anytown",
      state: "CA",
      zipCode: "12345"
    },
    paymentDetails: {
      id: "payment-123",  // Existing payment - will be updated
      method: "credit_card",
      amount: 1059.97
    }
  }
});

if (result.success) {
  console.log("Order saved with ID:", result.id);
}
\`\`\`

### Using Entity Definition ID

\`\`\`typescript
const result = await save({
  entDefId: "customer-def-id",
  entity: {
    firstName: "Jane",
    lastName: "Smith",
    email: "jane@example.com",
    status: "active"
  }
});

if (result.success) {
  console.log("Entity saved with ID:", result.id);
}
\`\`\`

### Using Entity Definition Object

\`\`\`typescript
const result = await save({
  entityDef: {
    name: "Product"
  },
  entity: {
    name: "Smartphone",
    description: "Latest model smartphone",
    price: 999.99,
    inStock: true
  }
});
\`\`\`

## Additional Information

- When creating a new entity, the system automatically generates an ID and sets system fields like createDate and createdBy.
- When updating an entity, the system automatically updates the lastUpdateDate and lastUpdatedBy fields.
- Required fields as defined in the entity definition must be provided.
- Validation rules defined in the entity definition are enforced during saving.
- For saving multiple entities at once, use the saveMulti operation instead.
- The operation returns both the ID of the saved entity and a boolean indicating whether it was an update operation.
- If the entity has unique constraints, the operation will fail if the constraints are violated.
- Access permissions are enforced based on the provided token.
- References to other entities can be included in the entity object using their IDs.
- For saving mapped items in a many-to-many relationship, use the saveMappedItems operation instead.

### Complex Data Handling

- 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.
- 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.
- If any part of the complex save operation fails, the entire transaction is rolled back.
`;
}
/**
 * Returns a brief summary of the save operation.
 * @return {string} A short description of the function.
 */
export function saveSummary() {
    return `
**Purpose**: Creates new entities or updates existing ones.

**When to use**:
- Creating new entities
- Updating existing entities
- Saving complex nested data structures

**Inputs**:
- request: { entityDef:{ name: string, id: string }, entity: object }//provide etiher name or id of the entity definition
- token (optional)
- tenantCode (optional)

**Returns**: ID of saved entity and update status.

**Effects**: Creates or modifies database records, handles nested relationships.
`;
}
export default saveDocs;
//# sourceMappingURL=save.js.map