# MCPcat TypeScript SDK - Code Style & Conventions

## TypeScript Conventions
- **File Extensions**: Use `.ts` for source files, `.js` imports in code
- **Module System**: ESM modules with explicit `.js` extensions in imports
- **Type Exports**: Separate type exports using `export type` syntax
- **Interfaces**: Prefer interfaces over types for object shapes
- **Naming**:
  - Interfaces: PascalCase (e.g., `MCPCatData`, `UserIdentity`)
  - Functions: camelCase (e.g., `publishEvent`, `getSessionInfo`)
  - Constants: UPPER_SNAKE_CASE (e.g., `PROTECTED_FIELDS`)
  - Files: kebab-case or camelCase

## Code Organization
- Keep related functionality in modules under `src/modules/`
- Export public API through `src/index.ts`
- Use barrel exports for module directories
- Maintain clear separation between types and implementation

## Testing
- Test files named `*.test.ts` in `src/tests/`
- Use Vitest's describe/it/expect pattern
- Mock external dependencies when needed
- Test utilities in `src/tests/test-utils/`

## Error Handling
- Use try-catch blocks for error-prone operations
- Log warnings instead of throwing for non-critical failures
- Use the `writeToLog` function for logging (not console.log)
- Provide fallback behavior when tracking fails

## Documentation
- JSDoc comments for public APIs
- Inline comments for complex logic
- README updates for new features

## Async/Await
- Prefer async/await over promises
- Handle async errors properly
- Use Promise.all for parallel operations