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

Documentation for GSB MCP implementations

/**
 * Overview documentation for the GSB Entity Service API
 */
/**
 * Returns the overview documentation for the GSB Entity Service API
 * @return {string} markdown documentation
 */
export function overviewDocs() {
    return `
# GSB Entity Service API

## Introduction

The GSB Entity Service API provides a comprehensive set of operations for managing entity data and definitions within the GSB platform. It allows you to create, read, update, and delete entity data, as well as define and modify entity schemas.

## Key Concepts

### Entities

Entities represent business objects in your application domain. Each entity has:
- A unique identifier
- A set of properties (fields)
- Optional relationships with other entities
- Metadata describing its structure and behavior

### Entity Definitions

Entity definitions (schemas) define the structure of entities:
- Property definitions (name, type, constraints)
- Relationships with other entity types
- Indexes for optimizing queries
- Validation rules
- Display and UI metadata

### Properties

Properties are the individual fields that make up an entity:
- Simple types (string, number, boolean, date)
- Complex types (objects, arrays)
- References to other entities
- Computed properties

## Authentication

The API uses token-based authentication. Most operations require a valid authentication token, which should be included in the request parameters. The token determines the permissions and access level for the operations.

## Common Parameters

Most operations accept these common parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| token | string | Authentication token for your request. If not provided, the system will use the default API key from environment variables. |
| tenantCode | string | 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 Format

All API operations return responses in a consistent format:

### Success Response

\`\`\`json
{
    "success": true,
    "data": {
        // Operation-specific response data
    }
}
\`\`\`

### Error Response

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

## Operation Categories

### Entity Data Operations

Operations for working with entity data:
- \`getById\`: Retrieve an entity by its ID
- \`getCopy\`: Get a copy of an entity with a new ID
- \`query\`: Query entities based on filters
- \`queryMapped\`: Query entities with mapped results
- \`save\`: Create or update an entity
- \`saveMulti\`: Create or update multiple entities
- \`delete\`: Delete an entity by ID
- \`deleteQuery\`: Delete entities matching a query

### Entity Relationship Operations

Operations for managing relationships between entities:
- \`saveMappedItems\`: Save relationships between entities
- \`removeMappedItems\`: Remove relationships between entities

### Entity Definition Operations

Operations for managing entity definitions (schemas):
- \`getEntityDef\`: Get an entity definition by ID
- \`getDefinition\`: Get an entity definition by name
- \`queryEntityDefs\`: Query entity definitions
- \`createEntityDef\`: Create a new entity definition
- \`updateEntityDef\`: Update an existing entity definition
- \`getCommonPropertyDefs\`: Get common property definitions

### Property Operations

Operations for managing entity properties:
- \`addProperty\`: Add a property to an entity definition
- \`updateProperty\`: Update a property in an entity definition
- \`removeProperty\`: Remove a property from an entity definition

### Workflow Operations

Operations for executing workflows:
- \`runWorkflow\`: Execute a workflow
- \`startWorkflow\`: Start a workflow
- \`runWfFunction\`: Run a workflow function
- \`iterateTask\`: Iterate through a workflow task

### Documentation Operations

Operations for retrieving API documentation:
- \`getDocs\`: Get comprehensive API documentation
- \`getApiDocs\`: Get general API information

## Best Practices

1. **Error Handling**: Always check the \`success\` field in responses and handle errors appropriately.

2. **Pagination**: When querying large datasets, use pagination parameters to limit the result size.

3. **Validation**: Validate entity data against entity definitions before saving to avoid errors.

4. **Transactions**: For operations that modify multiple entities, consider using batch operations like \`saveMulti\` to ensure atomicity.

5. **Security**: Always use the principle of least privilege when assigning permissions to tokens.

6. **Performance**: Use appropriate indexes in entity definitions to optimize query performance.

7. **Caching**: Consider caching frequently accessed entity definitions and reference data.

## Getting Started

To get started with the GSB Entity Service API:

1. Obtain an authentication token with appropriate permissions.

2. Explore the available entity definitions using \`queryEntityDefs\`.

3. Retrieve detailed documentation for specific operations using \`getDocs\`.

4. Start with simple operations like \`getById\` and \`query\` to retrieve data.

5. Progress to more complex operations as you become familiar with the API.

## Additional Resources

- For detailed documentation on each operation, use the \`getDocs\` operation.
- For information about the API version and general metadata, use the \`getApiDocs\` operation.
`;
}
/**
 * Returns a brief summary of the GSB Entity Service API overview.
 * @return {string} A short description of the API.
 */
export function overviewSummary() {
    return `
**Purpose**: Comprehensive platform for managing entity data and definitions.

**Key Components**:
- Entity Management: CRUD operations (getById, save, query, delete)
- Schema Definition: Define entity structures (createEntityDef, updateEntityDef)
- Relationship Handling: Manage entity connections (saveMappedItems)
- Workflow Support: Execute business processes (runWorkflow, startWorkflow)

**Authentication**: Token-based with tenant code support for multi-tenancy.

**Response Format**: Consistent structure with success flag and data/error fields.
`;
}
export default overviewDocs;
//# sourceMappingURL=overview.js.map