d2l-auth-sdk-dev-fecaf 0.1.3

Um SDK Python robusto e simples para gerenciar autenticação OAuth2 com a API do Brightspace (D2L).

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:

git clone https://github.com/seu-usuario/d2l-auth-sdk.git
cd d2l-auth-sdk
pip install .

Ou instale as dependências diretamente:

pip install -r requirements.txt

⚙️ Configuração

Crie um arquivo .env na raiz do seu projeto com as seguintes variáveis:

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:

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:

# 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.

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):

python -m build

Como publicar uma atualização no PyPI

Passo	Comando / ação
1	Aumentar version no setup.py (ex.: 0.1.2)
2	python -m build (com build instalado)
3	Ter conta + token no PyPI
4	twine upload dist/* (ou twine upload --repository testpypi dist/* para Test PyPI)
5	pip install --upgrade d2l-auth-sdk-dev-fecaf

📄 Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.