camposcloud-sdk 0.1.2
SDK Campos Cloud
License: MIT
Requires Python: >=3.8

# 🚀 Campos Cloud Python SDK

SDK oficial em Python para interagir com a API do Campos Cloud - uma plataforma de hospedagem de aplicações em nuvem.

## 📦 Instalação

```bash
pip install camposcloud-sdk
```

## 🔑 Configuração

Para usar o SDK, você precisa de um token de autenticação da Campos Cloud:

```python
from campos_sdk import CamposClient

# Inicializar o cliente
client = CamposClient(token="seu_token_aqui")
```

## 👤 Gerenciamento de Usuários

### Obter informações do usuário

```python
# Buscar dados do usuário atual
user = client.users.get_me()

print(f"Nome: {user.name}")
print(f"ID: {user._id}")
print(f"2FA Ativo: {user.isEmail2FAEnabled}")
print(f"Plano Gratuito: {user.hasClaimedFreePlan}")
```

## 🚀 Gerenciamento de Aplicações

### Listar aplicações

```python
# Buscar todas as aplicações
apps = client.applications.getApplications()

for app in apps:
    print(f"App: {app.name} - Status: {app.status}")
```

### Obter aplicação específica

```python
# Buscar uma aplicação específica (retorna wrapper com métodos)
app = client.applications.getApplication("app_id")

print(f"Nome: {app.name}")
print(f"Status: {app.status}")

# Ou buscar apenas os dados (sem wrapper)
app_data = client.applications.getApplicationData("app_id")
```

### Controlar aplicações

```python
# Iniciar aplicação
app = client.applications.startApplication("app_id")

# Parar aplicação
app = client.applications.stopApplication("app_id")

# Reiniciar aplicação
app = client.applications.restartApplication("app_id")

# Ou usar o wrapper
app = client.applications.getApplication("app_id")
app.start()
app.stop()
app.restart()
```

### Criar nova aplicação

```python
# Ler arquivo ZIP da aplicação
with open("minha_app.zip", "rb") as f:
    app_file = f.read()

# Criar aplicação
new_app = client.applications.createApplication(
    appName="Minha Nova App",
    file=app_file,
    mainFile="app.py",
    memoryMB=512,
    runtimeEnvironment="python",
    exposedViaWeb=True,
    autoRestartEnabled=True,
    startupCommand="python app.py",
    teamId="team_id_opcional"
)

print(f"App criada: {new_app.name}")
```

### Atualizar aplicação

```python
updated_app = client.applications.updateApplication(
    app_id="app_id",
    appName="Nome Atualizado",
    memoryMB=1024,
    runtimeEnvironment="python",
    startupCommand="python main.py",
    mainFile="main.py",
    autoRestartEnabled=True,
    exposedViaWeb=False,
    environmentVariables=[
        {"name": "ENV_VAR", "value": "valor"}
    ]
)
```

### Deletar aplicação

```python
# Deletar aplicação
client.applications.deleteApplication("app_id")

# Ou usar o wrapper
app = client.applications.getApplication("app_id")
app.delete()
```

## 📁 Gerenciamento de Arquivos

### Listar arquivos da aplicação

```python
# Listar arquivos
files = client.applications.getApplicationFiles("app_id")

for file in files:
    print(f"Arquivo: {file.name}")
    print(f"Caminho: {file.path}")
    print(f"É arquivo: {file.isFile}")
    print(f"É diretório: {file.isDirectory}")
    print(f"Tamanho: {file.size} bytes")

# Ou usar o wrapper
app = client.applications.getApplication("app_id")
files = app.getFiles()
```

### Upload de arquivo

```python
# Fazer upload de um arquivo
response = client.applications.uploadApplicationFile("app_id", "/caminho/para/arquivo.py")
print(response.message)
```

### Deletar arquivos

```python
# Deletar múltiplos arquivos
response = client.applications.deleteApplicationFile("app_id", ["arquivo1.py", "arquivo2.py"])

print(f"Sucessos: {response.success}")
print(f"Falhas: {response.failed}")

# Ou usar o wrapper
app = client.applications.getApplication("app_id")
response = app.deleteFiles(["arquivo1.py", "arquivo2.py"])
```

### Download de arquivo

```python
# Fazer download de arquivo
client.applications.downloadApplicationFile(
    app_id="app_id",
    file_id="file_id",
    file_path="/caminho/local/arquivo.py"
)
```

## 🎯 Wrapper de Aplicação

O SDK oferece um wrapper conveniente que combina dados e métodos:

```python
# Obter wrapper da aplicação
app = client.applications.getApplication("app_id")

# Acessar dados
print(app.name)
print(app.status)
print(app.id)

# Executar ações
app.start()
app.stop()
app.restart()

# Gerenciar arquivos
files = app.getFiles()
app.deleteFiles(["arquivo.py"])

# Atualizar aplicação
app.update(
    appName="Novo Nome",
    memoryMB=1024
)

# Deletar aplicação
app.delete()
```

## 🚨 Tratamento de Erros

O SDK define exceções específicas para diferentes tipos de erro:

```python
from campos_sdk.errors import (
    ApiError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    ServerError,
    NetworkError
)

try:
    user = client.users.get_me()
except AuthenticationError:
    print("Token inválido ou expirado")
except NotFoundError:
    print("Recurso não encontrado")
except ValidationError:
    print("Dados inválidos")
except NetworkError:
    print("Erro de conexão")
except ServerError:
    print("Erro interno do servidor")
except ApiError as e:
    print(f"Erro da API: {e.message} (Status: {e.status_code})")
```

## 📊 Modelos de Dados

### User

```python
user.name                  # Nome do usuário
user._id                   # ID único
user.isEmail2FAEnabled     # 2FA ativo
user.hasClaimedFreePlan    # Plano gratuito reclamado
user.activeSessions        # Lista de sessões ativas
```

### Session

```python
session.id           # ID da sessão
session.device       # Dispositivo
session.ip           # Endereço IP
session.browser      # Navegador
session.lastActive   # Última atividade (datetime)
```

### Application

```python
app.id        # ID da aplicação
app.name      # Nome
app.status    # Status atual
```

### AppFile

```python
file.name         # Nome do arquivo
file.path         # Caminho completo
file.isFile       # É arquivo
file.isDirectory  # É diretório
file.size         # Tamanho em bytes
file.createdAt    # Data de criação
file.modifiedAt   # Data de modificação
```

## 📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.

## 🤝 Contribuindo

1. Faça um fork do projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request

## 📞 Suporte

- **Documentação**: [docs.camposcloud.com](https://docs.camposcloud.com)
- **Issues**: [GitHub Issues](https://github.com/Hamertingo/camposcloud-py-sdk/issues)
- **Discord**: [Servidor da Campos Cloud](https://discord.gg/camposcloud)