d2l-auth-sdk-dev-fecaf 0.1.2
Um SDK Python robusto e simples para gerenciar autenticação OAuth2 com a API do Brightspace (D2L).
Requires Python: >=3.6

# D2L Auth SDK

Um SDK Python robusto e simples para gerenciar autenticação OAuth2 com a API do Brightspace (D2L).

Este projeto facilita a integração com a API do D2L, gerenciando automaticamente o ciclo de vida dos tokens de acesso (obtenção, armazenamento e renovação), com suporte integrado para notificações de erro via Google Chat.

## ✨ Funcionalidades

*   **Autenticação OAuth2 Simplificada**: Abstrai a complexidade do fluxo de autorização.
*   **Renovação Automática**: Gerencia transparentemente a expiração e renovação de tokens usando refresh tokens.
*   **Notificações de Monitoramento**: Envia alertas em tempo real para o Google Chat em caso de falhas críticas.
*   **Gestão de Escopos**: Flexibilidade para definir permissões granulares de acesso.
*   **Persistência Segura**: Armazena tokens localmente para reutilização entre execuções.

## 🚀 Instalação

### Pré-requisitos

*   Python 3.7 ou superior.
*   Credenciais de desenvolvedor Brightspace (Client ID e Client Secret).

### Instalando via pip (Localmente)

Clone o repositório e instale em modo editável:

```bash
git clone https://github.com/seu-usuario/d2l-auth-sdk.git
cd d2l-auth-sdk
pip install .
```

Ou instale as dependências diretamente:

```bash
pip install -r requirements.txt
```

## ⚙️ Configuração

Crie um arquivo `.env` na raiz do seu projeto com as seguintes variáveis:

```env
CLIENT_ID=seu_client_id
CLIENT_SECRET=seu_client_secret
STATE=uma_string_aleatoria_de_seguranca
WEBHOOK_GOOGLE_CHAT=https://chat.googleapis.com/v1/spaces/...
```

| Variável | Descrição | Obrigatório |
| :--- | :--- | :---: |
| `CLIENT_ID` | Seu ID de cliente da API Brightspace. | Sim |
| `CLIENT_SECRET` | Seu segredo de cliente da API Brightspace. | Sim |
| `STATE` | String arbitrária para proteção CSRF. | Sim |
| `WEBHOOK_GOOGLE_CHAT` | URL do webhook para receber alertas de erro. | Não |

## 📖 Como Usar

### 1. Inicialização

Importe a classe `D2lAuthManager` e configure os escopos necessários:

```python
from d2l_auth_sdk.d2l_auth import D2lAuthManager

# Defina os escopos que sua aplicação precisa
SCOPES = [
    'core:*:*',
    'grades:*:read',
    'users:profile:read'
]

# Inicialize o gerenciador
auth_manager = D2lAuthManager(
    scopes=SCOPES,
    token_file_d2l='token_d2l.json' # Arquivo onde o token será salvo
)
```

### 2. Autenticação Inicial (Primeira vez)

Na primeira execução, você precisará autorizar a aplicação manualmente:

```python
# Inicia o fluxo de autenticação
# Isso irá gerar uma URL para você abrir no navegador
auth_manager.authenticate()
```

Siga as instruções no terminal:
1.  Abra a URL gerada.
2.  Faça login no Brightspace e autorize o acesso.
3.  Você será redirecionado para uma página (ex: localhost ou uma URL de callback).
4.  Copie a URL final do navegador e cole no terminal quando solicitado.

### 3. Uso Diário (Renovação Automática)

Para fazer chamadas à API, obtenha um token válido. O SDK cuidará da renovação se ele estiver expirado.

```python
try:
    # Obtém um token de acesso válido (renova automaticamente se necessário)
    access_token = auth_manager.manage_token()
    
    # Use o token em suas requisições
    headers = {'Authorization': f'Bearer {access_token}'}
    response = requests.get('https://seu-lms.brightspace.com/d2l/api/lp/1.43/users/whoami', headers=headers)
    
    print(response.json())

except Exception as e:
    print(f"Erro na autenticação: {e}")
```

## 🛠️ Desenvolvimento

Para contribuir com o projeto:

1.  Crie um ambiente virtual: `python -m venv .venv`
2.  Ative o ambiente: `.venv\Scripts\activate` (Windows) ou `source .venv/bin/activate` (Linux/Mac)
3.  Instale as dependências de desenvolvimento: `pip install build twine`

### Construindo o Pacote

Para gerar os arquivos de distribuição (`.tar.gz` e `.whl`):

```bash
python -m build
```

## 📄 Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.