docs: update documentation for v0.21.0 refactoring

- Add CHANGELOG entry for v0.21.0 with breaking changes
- Update README with correct method names
- Update CLAUDE.md with mixins architecture and patterns
- Fix outdated examples in guide docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: franccesco

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-01-09
+
+### Changed
+
+- **BREAKING**: `HeadlineListItem` model removed and merged into `HeadlineDetails` (now a type alias for backward compatibility)
+- Refactored internal operations structure to use mixins for better code organization
+- Improved bulk operations with generic validation and processing helpers in base classes
+- Standardized error handling across all operations to consistently use `raise_for_status()`
+
+### Added
+
+- New `mixins/` folder with transform mixins for each operation type (goals, meetings, issues, headlines, todos, users)
+- Generic bulk operation helpers in `AbstractOperations` base class (`_validate_bulk_item`, `_process_bulk_sync`)
+- Generic async bulk processing in `AsyncBaseOperations` with configurable semaphore for concurrency control
+- Reusable `OptionalDatetime` and `OptionalFloat` annotated types using Pydantic's `BeforeValidator`
+
+### Fixed
+
+- Removed duplicate datetime and float validators across models (Todo, Issue, Goal)
+- Removed redundant `__init__` methods from async operations
+
 ## [0.20.1] - 2025-12-10
 
 ### Fixed
@@ -231,7 +252,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configuration management with multiple API key sources
 - httpx-based HTTP client with bearer token authentication
 
-[Unreleased]: https://github.com/franccesco/bloomy-python/compare/v0.20.1...HEAD
+[Unreleased]: https://github.com/franccesco/bloomy-python/compare/v0.21.0...HEAD
+[0.21.0]: https://github.com/franccesco/bloomy-python/compare/v0.20.1...v0.21.0
 [0.20.1]: https://github.com/franccesco/bloomy-python/compare/v0.20.0...v0.20.1
 [0.20.0]: https://github.com/franccesco/bloomy-python/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/franccesco/bloomy-python/compare/v0.18.0...v0.19.0

CLAUDE.md

@@ -80,12 +80,17 @@ The Bloomy Python SDK is organized as a client-based architecture where all API
    - Sync operations in `src/bloomy/operations/` inherit from `BaseOperations`
    - Async operations in `src/bloomy/operations/async_/` inherit from `AsyncBaseOperations`
    - Both inherit from `AbstractOperations` which provides shared logic
+   - Response transformation is handled by mixins in `src/bloomy/operations/mixins/` (e.g., `UserOperationsMixin`, `MeetingOperationsMixin`)
+   - Mixins use `_transform` suffix naming convention (e.g., `goals_transform.py`, `users_transform.py`)
+   - Generic bulk operations logic is provided in base classes (`_validate_bulk_item`, `_process_bulk_sync`, `_process_bulk_async`)
    - Operations are accessed via client attributes: `client.user`, `client.meeting`, etc.
 
 4. **Models (`src/bloomy/models.py`)**:
    - Pydantic models for type-safe API responses
    - All models inherit from `BloomyBaseModel` with common config
    - Field aliases map PascalCase API responses to snake_case Python attributes
+   - Reusable annotated types: `OptionalDatetime` and `OptionalFloat` using Pydantic's `BeforeValidator`
+   - Some models are type aliases for backward compatibility (e.g., `HeadlineListItem = HeadlineDetails`)
 
 5. **API Endpoints**:
    - Base URL: `https://app.bloomgrowth.com/api/v1`
@@ -101,7 +106,7 @@ The Bloomy Python SDK is organized as a client-based architecture where all API
 3. **Error Handling**:
    - Custom exception hierarchy rooted at `BloomyError`
    - `APIError` includes status code
-   - HTTP errors are raised via `response.raise_for_status()`
+   - All operations consistently use `response.raise_for_status()` for error handling
 
 4. **Type Annotations**: Uses Python 3.12+ union syntax (`|`) and Pydantic models for structured return types.
 

README.md

@@ -5,7 +5,7 @@
 
 A Python SDK for interacting with the Bloom Growth API, providing easy access to users, meetings, todos, goals, scorecards, issues, and headlines.
 
-✨ **New in v0.13.0**: Full async/await support with `AsyncClient` for better performance in async applications!
+✨ **New in v0.21.0**: Improved internal architecture with reusable mixins and enhanced bulk operation performance!
 
 ## Installation
 
@@ -59,13 +59,13 @@ asyncio.run(main())
 user = client.user.details()
 
 # Get user with direct reports and positions
-user = client.user.details(user_id=123, all=True)
+user = client.user.details(user_id=123, include_all=True)
 
 # Search users
 results = client.user.search("john")
 
-# Get all users
-users = client.user.all()
+# List all users
+users = client.user.list()
 ```
 
 ### Meetings

docs/guide/async.md

@@ -226,12 +226,12 @@ async def bulk_create_todos(client: AsyncClient, todos_data: list[dict]):
 async def sync_user_data(client: AsyncClient):
     """Sync all user data efficiently."""
     # Get all users
-    all_users = await client.user.all()
-    
+    all_users = await client.user.list()
+
     # Process users in batches to avoid overwhelming the API
     batch_size = 10
     user_details = []
-    
+
     for i in range(0, len(all_users), batch_size):
         batch = all_users[i:i + batch_size]
         batch_tasks = [
@@ -240,7 +240,7 @@ async def sync_user_data(client: AsyncClient):
         ]
         batch_results = await asyncio.gather(*batch_tasks)
         user_details.extend(batch_results)
-    
+
     return user_details
 ```
 

docs/guide/authentication.md

@@ -260,8 +260,8 @@ client_account1 = Client(api_key="api-key-for-account-1")
 client_account2 = Client(api_key="api-key-for-account-2")
 
 # Use different clients for different operations
-users_account1 = client_account1.user.all()
-users_account2 = client_account2.user.all()
+users_account1 = client_account1.user.list()
+users_account2 = client_account2.user.list()
 ```
 
 ## Next Steps

docs/guide/bulk-operations.md

@@ -23,6 +23,9 @@ Each bulk operation returns a `BulkCreateResult` containing:
 !!! note "Best-Effort Processing"
     Bulk operations are not transactional. If one item fails, the operation continues with the remaining items. Always check both successful and failed results.
 
+!!! tip "Enhanced in v0.21.0"
+    Bulk operations now use generic validation and processing helpers in the base classes, providing consistent error handling and performance across all resource types.
+
 ## BulkCreateResult Structure
 
 ```python