# Integrações prontas — galeria

Dez projetos prontos para cenários típicos. Cada receita é um único ficheiro, sem etapa de *build*. Insere a tua chave de API → executa com `npx tsx` ou `python` → funciona.

Todas as receitas abaixo são *copiar-colar-prontas*: a chave é passada pelo *header* `X-Api-Key`, as requisições usam `fetch` ou `requests` padrão. SDKs em TypeScript/Python estão planeadas — por enquanto, isto é suficiente.

## O que tem na galeria

| # | Receita | Stack | Caso de uso |
|---|---|---|---|
| 1 | Horóscopo diário por SMS | Twilio + Node.js | *Cron* que envia o horóscopo diário aos utilizadores por SMS |
| 2 | Bot do Discord `/chart` | discord.js | Comando *slash* — qualquer pessoa no chat constrói um mapa natal |
| 3 | Chamada de função do OpenAI | openai + Node.js | O GPT vai buscar os mapas sozinho através de *tool calls* |
| 4 | Bot do Slack `/synastry` | @slack/bolt | Comando de equipa que calcula a compatibilidade com um único comando |
| 5 | Enriquecimento do Notion | @notionhq/client | Data de nascimento na base de dados → mapa natal completo automaticamente |
| 6 | *Cache* do Cloudflare Worker | CF Workers KV | *Cache* *edge* de requisições idênticas por 30 dias |
| 7 | Ferramentas MCP do Claude | @astroway/mcp | O Claude Desktop/Code chama a API como uma ferramenta *native* |
| 8 | Exportação de previsão para CSV | Python + pandas | Previsão de 12 meses → CSV para BI/Tableau |
| 9 | UI de retificação no Streamlit | Python + Streamlit | Interface interativa para retificação da hora de nascimento |
| 10 | Serviço de compatibilidade em FastAPI | Python + FastAPI | Serviço HTTP para aplicações de *dating*: 2 mapas → *score* |

## Como usar

1. Copia o ficheiro da receita desejada para o teu projeto.
2. Instala as dependências indicadas no cabeçalho do ficheiro (`npm install ...` ou `pip install ...`).
3. Define as variáveis de ambiente (pelo menos `ASTROWAY_API_KEY`).
4. Executa.

## Padrões na galeria

- **Script pontual** (1, 5, 8) — processamento em lote no estilo *cron*.
- **Bot de longa duração** (2, 4) — ligação permanente, ouve comandos *slash*.
- **Serviço HTTP** (10) — *drop-in* REST com a tua autorização.
- **Função *edge*** (6) — camada de *cache* entre o cliente e a API.
- **Integração com ferramentas de LLM** (3, 7) — exposição de *endpoints* como funções para IA.
- **UI** (9) — *front-ends* interativos.

## Ainda não coberto

Se o teu cenário não estiver na lista (por exemplo: bot do Telegram, *workflow* do n8n, ação do Zapier, *widget* embutido no site) — **envia um e-mail para [api@astroway.info](mailto:api@astroway.info?subject=Integration%20recipe)** com a descrição. Adicionamos receitas com base em pedidos reais, não adivinhamos.