# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- **DataHub API 接口规范文档** (`docs/datahub_sdk/datahub_api_spec.md`) — 说明如何实现 `/api/search`、`/api/execute` 接口以供 DataHub SDK 调用，包含数据模型、认证方式和完整请求示例
- **README 更新** — 新增 DataHub SDK、Hezor2 SDK 使用说明和认证方式文档

## [0.5.0] - 2026-03-10

### Added
- **`app_name` 参数** — `BaseAPIClient`、`DataAPIClient`、`Hezor2APIClient`、`Hezor2SDK` 均支持 `app_name` 参数，通过 `X-APP-NAME` 请求头传递应用标识
- **`MetaInfoDecoder`** — 新增 `meta_info_decoder.py`，提供 MetaInfo JWT 解码工具
- **Hezor2 SDK API 参考文档** (`docs/hezor2_sdk/api_reference.md`, `docs/hezor2_sdk/api_reference_not_py.md`) — Python 和非 Python 客户端的完整 API 文档
- **签名方法文档** (`docs/signature_method.md`) — X-META-INFO JWT 签名流程的独立说明文档

### Changed
- **CredentialMiddleware** — 重构以支持 `app_name` 提取，新增常量定义

## [0.4.3] - 2026-02-09

### Added
- **Knowledge Graph SDK** (`transfer/knowledge_graph_sdk/`) — 全新的知识图谱 SDK，支持向量搜索功能
  - `KnowledgeGraphSDK` — 主异步客户端，支持向量搜索和健康检查
  - `KnowledgeGraphAPIClient` — 底层 HTTP 客户端
  - `KnowledgeGraphEnvConfig` — 环境变量配置类
  - 向量搜索 API 文档 (`api_docs/VECTOR_SEARCH.md`)
  - 完整示例 (`examples/transfer/knowledge_graph_sdk_example.py`)
- **向量搜索数据模型** (`data_model/searching/`) — 新增向量搜索请求/响应模型
  - `VectorSearchRequest`、`VectorSearchResponse`、`VectorSearchResult` 等
  - 支持多集合搜索、过滤条件、分页等
- **健康检查** — `DatahubSDK`、`Hezor2SDK` 新增 `health_check()` 方法

### Fixed
- **KnowledgeGraphAPIClient** — 修正向量搜索和健康检查的 API 端点路径

## [0.4.2] - 2026-01-29

### Added
- **Comprehensive test suite for middlewares module** - 72 unit tests covering all credential middleware functionality
  - `test_credential_middleware.py` - Tests for CredentialMiddleware (API key and MetaInfo JWT extraction/validation)
  - `test_require_api_key.py` - Tests for RequireAPIKey dependency factory with custom realm support
  - `test_require_meta_info.py` - Tests for RequireMetaInfo and GetMetaInfo dependencies
  - `test_require_credentials.py` - Tests for RequireCredentials and GetCredentials dependencies
- **Enhanced credential dependency factories** - All credential dependencies now support custom realm configuration
  - `RequireAPIKey` class - Configurable API key dependency factory with custom realm
  - `RequireMetaInfo` class - Configurable MetaInfo dependency factory with custom realm
  - `RequireCredentials` class - Configurable dual-credential dependency factory with custom realm
  - `GetMetaInfo` class - Optional MetaInfo extraction dependency
  - `GetCredentials` class - Optional credentials extraction dependency

### Changed
- **Modularized middleware dependencies** - Extracted credential dependencies into separate files for better maintainability
  - `require_api_key.py` - RequireAPIKey class and default instance
  - `require_meta_info.py` - RequireMetaInfo, GetMetaInfo classes and default instances
  - `require_credentials.py` - RequireCredentials, GetCredentials classes and default instances
- **Credential dependencies now support custom realm** - All `require_*` and `get_*` dependencies can be instantiated with custom authentication realm for WWW-Authenticate headers

## [0.4.1] - 2026-01-28

### Changed
- Updated agno dependency version to 2.4.5

## [0.4.0] - 2026-01-27

### Added
- **Hezor2SDK** - New SDK for Hezor2 API access with unified interface
- `Hezor2APIClient` - API client inheriting from BaseAPIClient with automatic authentication
- `publish_creation_report()` - Method and convenience function to publish creation reports to Hezor2 webhook
- `Hezor2EnvConfig` - Environment configuration class for Hezor2 SDK settings
- Hezor2 SDK exports creation data models: `CreationGenerateResult`, `CreationWebhookRequest`, `CreationWebhookResponse`

### Changed
- Hezor2SDK follows the same modular architecture as DataHub SDK with separated function files for better maintainability

## [0.3.0] - 2026-01-26

### Added
- Anonymous key fallback for DataAPIClient when `private_key_path` is not provided
- `private_key_pem` parameter to `MetaInfo.to_request_header()` for direct PEM content support
- `CredentialMiddleware` - FastAPI middleware for extracting and validating API key and MetaInfo JWT credentials
- Credential extraction helper functions: `require_api_key()`, `require_meta_info()`, `require_credentials()`, `get_meta_info()`, `get_credentials()`
- `credential_middleware_example.py` - Server example demonstrating credential middleware usage
- `base_sdk_example.py` - Client example demonstrating BaseAPIClient usage with custom client class inheritance

### Changed
- DataAPIClient now automatically uses anonymous private key with warning when `meta_info` is provided but `private_key_path` is None
- MetaInfo.to_request_header() now accepts either `private_key_path` (file) or `private_key_pem` (content)
- **BaseAPIClient**: Changed all HTTP method parameters from `url` to `path` for better clarity (methods now expect paths like "/api/users" instead of full URLs)
- **BaseAPIClient**: Now properly configures `httpx.AsyncClient` with `base_url` parameter
- **DataAPIClient**: Updated to use path-based requests instead of manually concatenating full URLs
- **MetaInfo**: Changed model config from `extra="forbid"` to `extra="ignore"` to allow JWT standard fields (exp, iat, etc.)

### Fixed
- DataAPIClient no longer raises ValueError when using MetaInfo without explicit private key path
- BaseAPIClient now correctly constructs request URLs using the configured base_url
- MetaInfo JWT decoding no longer fails due to standard JWT fields being rejected

### Breaking Changes
- **BaseAPIClient**: All HTTP methods (get, post, put, patch, delete) now use `path` parameter instead of `url`. Update your code to pass paths (e.g., "/api/users") instead of full URLs (e.g., "http://api.example.com/api/users")

## [0.2.0] - 2026-01-25

### Added
- Data models for creations (CreationModel, ChapterModel, SectionModel)
- Creation metadata models (CreationMeta, Author, Contributor)
- Result models for generation (SectionGenerateResult, ChapterGenerateResult)
- Security utilities (JWT, signature)
- DataHub SDK for data transfer operations
- Cache manager utilities
- Short snowflake ID utilities
- Agentic utilities with dependencies management

### Changed
- Updated Python requirement to >= 3.11
- Migrated to Pydantic 2.0+
- Modernized type hints from `Optional[T]` to `T | None` (PEP 604 syntax)

### Breaking Changes
- **Python 3.11+ required**: Dropped support for Python < 3.11. Projects using older Python versions must upgrade.
- **Pydantic 2.0+ migration**: Upgraded from Pydantic 1.x to 2.0+. This may require code changes if you're using Pydantic models from this library:
  - Model configuration uses `model_config` instead of `Config` class
  - Validation behavior may differ in some edge cases
  - See [Pydantic Migration Guide](https://docs.pydantic.dev/latest/migration/) for details

## [0.1.0] - Initial Release

### Added
- Initial project structure
- Basic utilities and data models
- MIT License

[0.5.0]: https://github.com/ericapaeus/hezor_common/releases/tag/v0.5.0
[0.4.3]: https://github.com/ericapaeus/hezor_common/releases/tag/v0.4.3
[0.4.2]: https://github.com/ericapaeus/hezor_common/releases/tag/v0.4.2
[0.4.1]: https://github.com/ericapaeus/hezor_common/releases/tag/v0.4.1
[0.4.0]: https://github.com/ericapaeus/hezor_common/releases/tag/v0.4.0
[0.3.0]: https://github.com/ericapaeus/hezor_common/releases/tag/v0.3.0
[0.2.0]: https://github.com/ericapaeus/hezor_common/releases/tag/v0.2.0
[0.1.0]: https://github.com/ericapaeus/hezor_common/releases/tag/v0.1.0
