Metadata-Version: 2.5
Name: shade-plugins-google
Version: 0.1.1
Summary: Ler e escrever no Google Sheets e listar, baixar e enviar no Google Drive, com o token OAuth da conexão da plataforma.
Author: ShadeOne
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: shade-sdk<0.23,>=0.22.3
Description-Content-Type: text/markdown

# shade-plugins-google

Lê e escreve no Google Sheets e lista, baixa e envia arquivos no Google Drive de dentro de um robô
do [`shade-sdk`](https://pypi.org/project/shade-sdk/). A conta Google é a conexão OAuth da
plataforma: o robô recebe só o token de acesso, sob demanda, e nunca vê a senha nem o refresh
token. Só a biblioteca padrão do Python: nenhuma dependência além do `shade-sdk`.

No `shade.toml` do robô, os hosts das APIs vão em `[hosts] permitidos` e a conexão em `[conexoes]`:

```toml
[hosts]
permitidos = ["sheets.googleapis.com", "www.googleapis.com"]

[conexoes]
nomes = ["google-drive"]

[plugins]
google = "0.1.1"
```

```python
import shade_plugins_google as google

# Leitura: a qualquer momento, inclusive no ensaio.
for pedido in google.ler_planilha("1AbC...", "Pedidos!A1:D"):  # uma linha por dict
    ...
for arquivo in google.listar_arquivos(nome="comprovante", tipo="application/pdf"):
    google.baixar_arquivo(arquivo["id"])  # grava em google/<nome> no diretório de trabalho

# Escrita: só dentro de item.efetivar() (no ensaio não roda).
with item.efetivar("registrar na planilha"):
    google.escrever_linha("1AbC...", "Pedidos!A1", [item["pedido"], item["cliente"], "ok"])

with item.efetivar("guardar o comprovante"):
    google.enviar_arquivo("comprovante.pdf", pasta="1XyZ...")
```

## A conta e o escopo

- Na plataforma, conecte a conta em **Conectores → Google Drive**. O robô usa a conexão de quem
  aprovou a versão dele; no ensaio antes da aprovação, a de quem a enviou.
- A conexão pede os escopos `spreadsheets` (qualquer planilha que a conta veja) e `drive.file`
  (no Drive, só o que o próprio app enviou ou que a conta abriu com ele: `listar_arquivos` e
  `baixar_arquivo` não veem o resto do Drive, e a `pasta` de `enviar_arquivo` também tem de ser
  uma que o app vê). Uma conexão feita antes de o escopo `spreadsheets` existir precisa ser
  refeita.
- No laptop (`shade run`), ponha um token de acesso da sua conta em `SHADE_TOKEN_GOOGLE_DRIVE`
  (no `.env`). O do Google costuma valer uma hora, e o laptop não renova.

## O que o plugin garante

- **Um envio, um arquivo:** `enviar_arquivo` marca o arquivo com uma chave derivada do item, do
  nome da efetivação e da ordem do envio, e procura a marca antes de criar: uma nova execução do
  mesmo item acha o arquivo que já subiu, em vez de criar outro. A busca do Drive pode demorar a
  enxergar um arquivo recém-criado, então o plugin não depende dela dentro da chamada: o envio
  leva um id que o próprio Drive reserva (`files.generateIds`), e, se a resposta se perde, o
  pedido repetido leva o mesmo id. O Drive responde `409` (esse id já é um arquivo) e o plugin lê
  o arquivo pelo id. Se o Drive não der o id, o plugin só confirma o envio sem resposta pela
  busca e nunca cria de novo: sem achar a marca, o erro é `GoogleIncerto` e o item fica retido
  para conferência. Quem refaz um item retido por `GoogleIncerto` deve conferir o Drive antes: um
  envio refeito logo depois, antes de a busca enxergar o arquivo, cria outro.
- **Linha sem duplicata escondida:** o Sheets não reconhece repetição, então `escrever_linha` só
  repete o que certamente não chegou (a conexão recusada, o `429`). Se o pedido saiu e a
  confirmação não veio, o erro é `GoogleIncerto` e o item fica retido para conferência.
- **Texto é texto:** `escrever_linha` grava cru (`RAW`): `=HYPERLINK(...)` vira texto, nunca
  fórmula.
- **Token renovado pela plataforma:** o `401` troca o token uma vez e repete o pedido, que não
  teve efeito. O `429` que sobra das retentativas é `GoogleNaoSaiu`: o Google limitou antes de
  aplicar.
- **Prazo:** `timeout=` (30 s) vale para a chamada inteira, retentativas incluídas. Cada chamada
  vira um evento com a operação, o host, a duração e o status, sem conteúdo nem token.

## Limites desta versão

- O envio é de um pedido só, até 5 MB.
- Arquivos nativos do Google (Docs, Planilhas, Apresentações) não se baixam; a planilha se lê com
  `ler_planilha`.

Licença Apache-2.0.
