mirror of https://github.com/buster-so/buster.git
124 lines
3.7 KiB
Plaintext
124 lines
3.7 KiB
Plaintext
---
|
|
description: Rules for how the buster_socket api directory shoudl function
|
|
globs: src/api/buster_socket/**/*
|
|
---
|
|
# API Structure Rules
|
|
|
|
## Directory Structure
|
|
Each API namespace should follow this specific structure:
|
|
|
|
```
|
|
src/api/{namespace}/
|
|
├── {namespace}Requests.ts # Contains all request interfaces and types
|
|
├── {namespace}Responses.ts # Contains all response interfaces and types
|
|
└── index.ts # Exports all public interfaces and functions
|
|
```
|
|
|
|
## File Requirements
|
|
|
|
### {namespace}Requests.ts
|
|
- Must contain all request interfaces and types for the namespace
|
|
- Each request interface should be prefixed with the namespace
|
|
- Example: `interface UserCreateRequest { ... }`
|
|
- Must include proper TypeScript types and documentation
|
|
|
|
### {namespace}Responses.ts
|
|
- Must contain all response interfaces and types for the namespace
|
|
- Each response interface should be prefixed with the namespace
|
|
- Example: `interface UserCreateResponse { ... }`
|
|
- Must include proper TypeScript types and documentation
|
|
|
|
### index.ts
|
|
- Must export all public interfaces, types, and functions
|
|
- Should re-export from both requests and responses files
|
|
- Should contain any namespace-specific utility functions
|
|
- Must use named exports (no default exports)
|
|
|
|
## Naming Conventions
|
|
- All file names must use PascalCase for namespace names
|
|
- All interface names must be prefixed with the namespace
|
|
- All type names must be prefixed with the namespace
|
|
- Use descriptive names that clearly indicate purpose
|
|
|
|
## Documentation Requirements
|
|
- Each interface must have JSDoc comments explaining its purpose
|
|
- Each property in interfaces must be documented
|
|
- Include examples where appropriate
|
|
- Document any validation requirements or constraints
|
|
|
|
## Type Safety
|
|
- Avoid using `any` type. We should NEVER use any types.
|
|
- Use strict TypeScript configurations
|
|
- Define proper type guards when necessary
|
|
- Use generics appropriately for reusable types
|
|
|
|
## Example Structure
|
|
```typescript
|
|
// {namespace}Requests.ts
|
|
export interface {Namespace}CreateRequest {
|
|
// properties
|
|
}
|
|
|
|
// {namespace}Responses.ts
|
|
export interface {Namespace}CreateResponse {
|
|
// properties
|
|
}
|
|
|
|
// index.ts
|
|
export * from './{namespace}Requests';
|
|
export * from './{namespace}Responses';
|
|
```
|
|
|
|
## Socket Request Type Pattern
|
|
All socket request types should follow this specific pattern:
|
|
|
|
```typescript
|
|
/**
|
|
* Request type for [purpose of the request].
|
|
* @interface [RequestName]EmitPayload
|
|
* @extends BusterSocketRequestBase
|
|
*/
|
|
export type [RequestName]EmitPayload = BusterSocketRequestBase<
|
|
'[endpoint/path]',
|
|
{
|
|
/** Description of property */
|
|
propertyName: PropertyType;
|
|
}
|
|
>;
|
|
```
|
|
|
|
Each request type must:
|
|
- Use TSDoc format documentation
|
|
- Extend BusterSocketRequestBase with appropriate generic parameters
|
|
- Include a string literal endpoint path as first generic parameter
|
|
- Include a payload interface as second generic parameter
|
|
- Document each property with JSDoc comments
|
|
|
|
Example:
|
|
```typescript
|
|
/**
|
|
* Request type for retrieving a paginated list of chats.
|
|
* @interface ChatListEmitPayload
|
|
* @extends BusterSocketRequestBase
|
|
*/
|
|
export type ChatListEmitPayload = BusterSocketRequestBase<
|
|
'/chats/list',
|
|
{
|
|
/** Pagination token indicating the page number */
|
|
page_token: number;
|
|
/** Number of chat items to return per page */
|
|
page_size: number;
|
|
/** When true, shows all organization chats (admin only). When false, shows only user's chats */
|
|
admin_view: boolean;
|
|
}
|
|
>;
|
|
```
|
|
|
|
## Additional Guidelines
|
|
1. Keep files focused and single-responsibility
|
|
2. Use TypeScript's strict mode
|
|
3. Implement proper error handling types
|
|
4. Follow consistent formatting
|
|
5. Include proper type exports
|
|
6. Maintain backward compatibility
|
|
7. Use enums for fixed sets of values |