Adiciona README.md e CHANGELOG.md completo para lançamento beta

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
+
+O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
+e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
+
+## [Unreleased]
+
+## [0.1.0-beta] - 2026-01-23
+
+### Added
+
+- Sistema de autenticação com suporte a múltiplas versões da API (`legacy` e `data_sources`)
+- Client HTTP para endpoints `pages`, `databases` e `blocks`
+- Sistema ORM declarativo com `NotionDatabase` para mapeamento de schemas
+- Registry global de databases com `DatabaseRegistry`
+- Container pattern para organização de databases (`DatabasesContainer`)
+- Repositories para `pages` e `databases` com fluent interface
+- Query builders (`QueryFilter` e `QuerySort`)
+- Property extractors e parsers automáticos
+- Schemas Pydantic para todas as respostas da API
+- Suporte a Generic Types para autocomplete perfeito
+- Computed fields e validators customizados
+- Configuração global de timezone via `ORMConfig`
+- Singleton pattern para Client configurável
+- Transformers customizáveis para processamento de propriedades
+
+### Notes
+
+- Primeira release beta do projeto
+- Documentação completa em desenvolvimento
+- Alguns tipos de propriedades ainda não suportados
+
+[0.1.0-beta]: [https://github.com/riguettodev/sdk-notion/releases/tag/v0.1.0-beta](https://github.com/riguettodev/sdk-notion/releases/tag/v0.1.0-beta)

README.md

@@ -1,5 +1,374 @@
 # Notion SDK
 
-**SDK para Integração com Notion API** com base forte em *pydantic*, *asyncio*, e programação orientada a objetos.
+> **Beta Release** 🎉\
+> Desenvolvido por [Eduardo Riguetto](https://riguetto.dev)
 
-Pensado para o uso como *ORMs*. Permitindo personalização total do usuário ao configurar suas Databases do Notion, com recursos como mapeamentos, transformadores, validadores, calculos e mais.
+## 🎯 Visão Geral
+
+SDK Python moderno e type-safe para a API Notion, com foco em Developer Experience (DX) e autocomplete perfeito.
+
+---
+
+## ✨ Principais Features
+
+### 🔐 Autenticação Simplificada
+
+- Configuração centralizada via `Notion()` com suporte a múltiplas versões da API
+- Suporte para versões `legacy` (2022-06-28), `data_sources` (2025-09-03), ou personalizada
+- Headers gerenciados automaticamente via singleton pattern
+
+### 🗄️ ORM Declarativo
+
+- **Sistema de Mapeamento Declarativo**: Defina schemas uma única vez com `NotionDatabase`
+- **Type Hints Perfeitos**: Autocomplete completo em IDEs (VSCode, PyCharm)
+- **Transformers Customizáveis**: Processe propriedades do Notion conforme necessário
+- **Validators Integrados**: Validação automática com Pydantic
+- **Computed Fields**: Campos calculados automaticamente a partir de outros campos
+- **Registry Global**: Acesso centralizado a todas as databases via `DatabaseRegistry`
+- **Container Pattern**: Organize suas databases com `DatabasesContainer`
+
+### 📦 Repositories
+
+**Pages:**
+
+- `CreatePage` - Criação de páginas com fluent interface
+- `GetPage` - Busca de páginas com mapeamento automático de schemas
+- `GetPageProperty` - Acesso direto a propriedades específicas
+
+**Databases:**
+
+- `CreateDatabasePage` - Criação de páginas em databases com type safety
+- `SearchPage` - Queries avançadas com filtros e ordenação
+- `SearchPageProperty` - Busca de propriedades específicas em databases
+
+### 🎨 Fluent Interface
+
+```python
+await notion.orm.repo.pages.CreatePage()\
+    .set_parent("database_id", "db_id")\
+    .set_title("Name", "My Page")\
+    .set_property.start_date("Date", datetime.now())\
+    .set_property.number("Count", 42)\
+    .call()
+```
+
+### 🔧 Features Avançadas
+
+- **Generic Types**: Tipagem forte com Generic/TypeVars para autocomplete perfeito
+- **Property System**: Sistema completo de setters para todos os tipos de propriedades
+- **Query Builders**: Construtores fluentes para filtros (`QueryFilter`) e ordenação (`QuerySort`)
+- **Property Extractors**: Extração automática de propriedades da API Notion
+- **Property Parsers**: Parse inteligente de respostas com suporte a tipos complexos
+- **Property Accessors**: Acesso tipado a propriedades de páginas
+- **Configuração Global**: Timezone e outras configs definidas via `ORMConfig`
+- **Singleton Pattern**: Client configurado globalmente, sem duplicação
+
+---
+
+## 🚀 Quick Start
+
+```python
+from notion import Notion
+from my_databases import MyContainer
+
+# Configuração
+notion: Notion[MyContainer] = Notion(
+    api_token="secret_...",
+    api_version="data_sources",
+    orm_container=MyContainer,
+    timezone="America/Sao_Paulo"
+)
+
+# Uso com autocomplete perfeito
+con = notion.orm.repo.databases.container.tasks.SearchPage
+result = await con\
+    .set_filter(
+        con.filter.checkbox("Done", "equals", False)
+    )\
+    .call()
+
+# Acesso type-safe
+for page in result.results:
+    print(page.properties.myproperty)  # ← Autocomplete funciona!
+```
+
+---
+
+### 📦 Configurando seu ORM
+
+#### 1. Defina seus Schemas
+
+Crie schemas para suas databases do Notion usando `NotionDatabase`:
+
+```python
+# my_databases/tasks.py
+
+from notion.types.orm.databases import NotionDatabase
+from pydantic import ConfigDict
+from typing import Optional, List
+from datetime import date, datetime
+from decimal import Decimal
+
+class TasksDb(NotionDatabase):
+    
+    model_config = ConfigDict(title="Notion_Databases_TasksDb")
+    
+    # Defina os campos do schema
+    title: Optional[str]
+    status: Optional[str]
+    priority: Optional[str]
+    tags: Optional[List[str]]
+    due_date: Optional[date]
+    assignee: Optional[str]
+    completed: bool = False
+    progress: Optional[int]
+    estimated_hours: Optional[Decimal]
+    actual_hours: Optional[Decimal]
+    
+    # Campos computed (não vêm do Notion, são calculados)
+    is_overdue: Optional[bool] = None
+    total_cost: Optional[Decimal] = None
+    
+    class NotionConfig:
+        # ID da sua database no Notion
+        database_id = "abc123def456"
+        
+        # Mapeie campos Python → Campos Notion
+        mappings = {
+            "title": "Title",
+            "status": "Status",
+            "priority": "Priority",
+            "tags": "Tags",
+            "due_date": "Due Date",
+            "assignee": "Assignee",
+            "completed": "Completed",
+            "progress": "Progress",
+            "estimated_hours": "Estimated Hours",
+            "actual_hours": "Actual Hours"
+        }
+        
+        # Transformers para processar valores
+        transformers = {
+            "status": lambda x: x["name"] if x else None,
+            "priority": lambda x: x["name"] if x else None,
+            "tags": lambda x: [t["name"] for t in x] if x else [],
+            "assignee": lambda x: x[0] if x else None,
+            "due_date": lambda x: x["start"] if x else None,
+            "estimated_hours": lambda x: Decimal(str(x)) if x else None,
+            "actual_hours": lambda x: Decimal(str(x)) if x else None
+        }
+        
+        # Validators para garantir integridade dos dados
+        validators = {
+            "progress": lambda v: max(0, min(100, v)) if v else 0,  # Entre 0-100
+            "estimated_hours": lambda v: v if v and v >= 0 else Decimal(0)  # Não negativo
+        }
+        
+        # Computed fields calculados automaticamente
+        computed = {
+            "is_overdue": lambda obj: (
+                obj.due_date < date.today() and not obj.completed
+                if obj.due_date else False
+            ),
+            "total_cost": lambda obj: (
+                obj.actual_hours * Decimal("50.00")  # $50/hora
+                if obj.actual_hours else None
+            )
+        }
+```
+
+#### 2. Crie seu Container
+
+Organize todas as suas databases em um container:
+
+```python
+# my_databases/__init__.py
+
+from notion.types.orm.databases import Container, Registry, Client
+from .tasks import TasksDb
+from .projects import ProjectsDb  # Outras databases...
+
+class MyDatabasesContainer(Container):
+    """Container customizado com suas databases"""
+    
+    def __init__(self):
+        # Registre todas as databases
+        Registry.register(TasksDb)
+        Registry.register(ProjectsDb)
+        
+        # Configure acesso tipado
+        self.tasks: Client[TasksDb] = Client(TasksDb.id())
+        self.projects: Client[ProjectsDb] = Client(ProjectsDb.id())
+
+# Singleton para uso direto
+databases = MyDatabasesContainer()
+
+__all__ = ["MyDatabasesContainer", "databases"]
+```
+
+#### 3. Configure a Integração
+
+No seu `main.py` ou arquivo de inicialização:
+
+```python
+from notion import Notion
+from my_databases import MyDatabasesContainer
+
+# Configure com seu container
+notion = Notion(
+    api_token="secret_...",
+    api_version="data_sources",
+    orm_container=MyDatabasesContainer,
+    timezone="America/Sao_Paulo"
+)
+
+# Agora você tem autocomplete perfeito!
+con = notion.orm.repo.databases.container.tasks.SearchPage
+tasks = await con\
+    .set_filter(
+        con.checkbox("Completed", "equals", False)
+    )\
+    .call()
+
+# Acesso type-safe aos dados
+for task in tasks.results:
+    print(f"📋 {task.properties.title}")
+    print(f"Status: {task.properties.status}")
+    print(f"Due: {task.properties.due_date}")
+```
+
+---
+
+## 📚 Client API
+
+### Pages
+
+- `get(page_id)` - Buscar página por ID
+- `get_property(page_id, property_id)` - Buscar propriedade específica
+- `update_properties(page_id, properties)` - Atualizar propriedades de uma página
+- `create(parent, properties)` - Criar nova página
+
+### Databases
+
+- `get(database_id)` - Buscar informações de uma database
+- `query(database_id, filter, sorts)` - Query com filtros e ordenação
+- `query_property(database_id, property_id)` - Query propriedade específica
+- `update(database_id, properties)` - Atualizar schema de database
+
+### Blocks
+
+- `get_children(block_id)` - Buscar blocos filhos de um bloco/página
+
+---
+
+## 📖 Schemas Disponíveis
+
+**Responses:**
+
+- `pages.Page`, `pages.Parent` - Estruturas de páginas
+- `databases.Query` - Resultados de queries
+- `users.User`, `users.Person`, `users.Bot` - Informações de usuários
+- `errors.Error` - Erros da API
+- `pages.properties.RichText` - Propriedade rich text
+
+**ORM:**
+
+- `NotionDatabase` - Classe base para schemas customizados
+- `DatabasesContainer` - Container para organização de databases
+- `SearchPageProperty` - Schema para propriedades de busca
+- `properties.RichText` - Rich text para ORM
+
+**DTO:**
+
+- Data Transfer Objects para comunicação interna
+
+---
+
+## 🏗️ Arquitetura
+
+```
+notion/
+├── auth/               # Sistema de autenticação
+├── client/             # HTTP clients por endpoint
+│   ├── blocks.py       # Blocks API
+│   ├── databases.py    # Databases API
+│   └── pages.py        # Pages API
+├── orm/
+│   ├── accessors/      # Acesso tipado a propriedades
+│   ├── common/         # QueryFilter, QuerySort, SetProperty
+│   ├── config/         # Configurações globais do ORM
+│   ├── extractors/     # Extração de propriedades da API
+│   ├── mapping/        # Sistema declarativo (NotionDatabase)
+│   ├── parsers/        # Parse de respostas da API
+│   └── repositories/   # Camada de repositórios
+│       ├── databases/  # Repositórios de databases
+│       └── pages/      # Repositórios de pages
+├── schemas/
+│   ├── orm/            # Schemas do ORM
+│   │   ├── database/   # DatabasesContainer, SearchPageProperty
+│   │   └── properties/ # RichText e outros
+│   └── responses/      # Schemas de respostas da API
+│       ├── databases/  # Query
+│       ├── errors/     # Error
+│       ├── pages/      # Page, Parent, properties
+│       └── users/      # User, Person, Bot
+└── types/              # Type definitions e exports
+    ├── orm/            # Types do ORM
+    └── responses/      # Types de responses
+```
+
+---
+
+## 📋 Dependências
+
+- Python >= 3.9
+- httpx - Requests HTTP assíncronos
+- pydantic >= 2.5 - Validação e serialização
+
+---
+
+## 🐛 Known Issues
+
+- Suporte parcial a tipos de propriedades (em desenvolvimento contínuo)
+- Documentação completa em progresso
+- Alguns endpoints da API Notion ainda não implementados
+
+---
+
+## 🔮 Roadmap
+
+- [ ] Support completo para Blocks API (criação e atualização)
+- [ ] Suporte completo a todos os tipos de propriedades Notion
+- [ ] Documentação completa com exemplos práticos
+- [ ] Testes unitários e de integração
+- [ ] Support para Comments API
+- [ ] Cache system para reduzir chamadas à API
+- [ ] Retry logic e rate limiting inteligente
+- [ ] CLI para geração automática de schemas a partir de databases
+
+---
+
+## 📄 Licença
+
+MIT License - Veja [LICENSE](LICENSE) para detalhes
+
+---
+
+## 🙏 Agradecimentos
+
+Desenvolvido com ❤️ por [Eduardo Riguetto](https://riguetto.dev)
+
+**Contribuições são bem-vindas!** Sinta-se livre para:
+
+- 🐛 Reportar bugs via Issues
+- 💡 Sugerir features
+- 🔧 Abrir Pull Requests
+- 📖 Melhorar a documentação
+
+---
+
+## 🔗 Links
+
+- **GitHub**: [https://github.com/riguettodev/sdk-notion](https://github.com/riguettodev/sdk-notion)
+- **PyPI**: [https://pypi.org/project/sdk-notion/](https://pypi.org/project/sdk-notion/)
+- **Documentação**: (em breve)