# RiLiGar Payments: Master Implementation Guide (LLM-Ready)

> Este é o guia definitivo para integrar o RiLiGar Payments — o hub que coloca múltiplos gateways de pagamento (Stripe, Mercado Pago, Hotmart) atrás de uma API só, com planos, assinaturas e controle de acesso por funcionalidade.

> **Modelo mental em uma frase:** um *projeto* guarda *gateways*; cada gateway guarda *planos*; um cliente assina um plano e ganha as *funcionalidades* vinculadas a ele. O SDK React lê isso e libera ou bloqueia partes da sua aplicação.

## 0. Se o usuário ainda não tem conta, você se provisiona sozinho

Você **não precisa** pedir chave antes de começar. O device flow do RiLiGar Auth
dá a você uma sessão sem navegador: a pessoa lê um código de 8 caracteres que
chega por e-mail, informa a você, e o resto do percurso é seu.

```bash
# 1. sessão (a única interação humana do percurso)
POST https://auth.worker.myinfrastructure.click/auth/code/start   {"email":"..."}
POST https://auth.worker.myinfrastructure.click/auth/code/verify  {"email":"...","code":"ABCD-EFGH"}  → JWT
```

```bash
# 2. o projeto
POST https://payments.worker.myinfrastructure.click/projects  -H "authorization: Bearer <JWT>"
     {"name":"Meu SaaS"}
# → 201 {"message":"...","data":{"id":"...","publicKey":"pk_...","secretKey":"sk_..."}}
```

Esta rota **exige o JWT**: uma `sk_` de projeto recebe `403 "Criar projeto exige o token do RiLiGar Auth"`. As chaves são recuperáveis depois, por `GET /projects`.

Estouro de plano vem como `402` com `reason: "plan_limit"` — diga ao usuário qual plano libera, e **não tente contornar**.

O percurso completo dos cinco produtos, e o que a RiLiGar é: https://myinfrastructure.click/llms.txt

Se o usuário já tem as chaves, peça — é mais rápido. Se não tem conta, use o caminho acima em vez de parar. Nunca gere código com `pk_xxx` de placeholder fingindo que terminou.

## 1. Estrutura do Sistema (Architecture)

- **Projeto** — a unidade de topo. Tem `publicKey` (vai para o front-end) e `secretKey` (fica no seu servidor). Um projeto por produto seu.
- **Gateway** — uma credencial de provedor dentro do projeto. Um projeto pode ter vários (ex.: Stripe produção e Stripe sandbox). O plano pertence ao gateway, não ao projeto.
- **Plano** — nome, preço em **centavos**, moeda e ciclo (`month` | `year`). Criar um plano aqui também o cria no provedor.
- **Funcionalidade** — um `slug` que a sua aplicação consulta. Vinculada a um ou mais planos.
- **Assinatura** — o vínculo entre um `userId` seu e um plano, com `status` vindo do provedor.

Runtime: Cloudflare Workers + D1. Base da API: `https://payments.worker.myinfrastructure.click`.

## 2. Conexão e Autenticação (User Access)

O SDK do navegador autentica com a `publicKey` — ela identifica o projeto e só alcança rotas `/sdk/v1/*`, que expõem planos públicos e as permissões de UM usuário.

```bash
bun add @riligar/payments-react
```

```jsx
import { PaymentsProvider } from '@riligar/payments-react'

<PaymentsProvider
    publicKey="pk_..."          // do painel, aba Painel do projeto
    gatewayId="..."             // opcional: filtra os planos de um gateway
    userId={user.id}            // o SEU id de usuário — a chave do vínculo
    customerEmail={user.email}  // necessário para o portal do cliente
    apiBase="https://payments.worker.myinfrastructure.click"
>
    <App />
</PaymentsProvider>
```

`userId` é o identificador do usuário **no seu banco**, não no provedor. É por ele que as assinaturas são procuradas — mantenha-o estável.

## 3. Referência do SDK (Manipulation)

### Componentes

```jsx
import { Pricing, PortalButton, FeatureControl, Billing } from '@riligar/payments-react'

// Tabela de preços — lista os planos do gateway e leva ao checkout.
<Pricing
    gatewayId="..."
    successUrl={window.location.origin + '/conta?pagamento=ok'}
    cancelUrl={window.location.origin + '/precos'}
    promoBadge="LANÇAMENTO"     // opcional
    title="" subtitle=""        // vazios quando a página já tem cabeçalho
/>

// Portal do provedor — trocar cartão, ver faturas, cancelar.
<PortalButton returnUrl={window.location.href} label="Gerenciar assinatura" />

// Controle de acesso — esconde o que o plano não inclui.
<FeatureControl featureId="relatorios-avancados-x7k2" fallback={<Upgrade />}>
    <RelatorioAvancado />
</FeatureControl>

// Tudo-em-um: Pricing + portal num cartão só.
<Billing publicKey="pk_..." gatewayId="..." userId={user.id} />
```

### Hooks

```jsx
import { useHasFeature, useCheckout, usePortal } from '@riligar/payments-react'

const liberado = useHasFeature('relatorios-avancados-x7k2')  // boolean
const { createCheckout } = useCheckout()
const { openPortal } = usePortal()
```

`useHasFeature` casa pelo **slug** da funcionalidade (e, por compatibilidade, pelo nome do plano). O slug está no painel, em Funcionalidades — copie de lá, não invente.

## 4. Referência da API (HTTP)

Rotas públicas do SDK, autenticadas por `publicKey`:

| Método | Rota | Devolve |
| --- | --- | --- |
| GET | `/sdk/v1/plans?publicKey=&gatewayId=` | Planos públicos do gateway |
| GET | `/sdk/v1/permissions?publicKey=&userId=` | `{ hasActiveSubscription, subscriptions[], features[] }` |
| POST | `/checkout` | Sessão de checkout no provedor |
| POST | `/account` | Sessão do portal do cliente |
| PUT | `/customers` | Atualiza dados do cliente |
| POST | `/webhook/:gatewayId` | Onde o provedor avisa sobre pagamento e cancelamento |

Rotas de administração (usadas pelo painel): `/projects`, `/gateways/:projectId`, `/plans/:gatewayId`, `/features`, `/plan-features`, `/subscriptions/:projectId`, `/dashboard/:projectId`, `POST /gateways/:id/test`, `POST /gateways/:id/auto-setup`.

## 5. Webhooks

Sem webhook o provedor cobra e **ninguém fica sabendo**: a assinatura não aparece no painel e `useHasFeature` continua devolvendo `false`.

1. No painel, abra o gateway e copie a URL de webhook (`/webhook/:gatewayId`).
2. Cadastre-a no painel do provedor, ou use **Configurar automaticamente** (Stripe).
3. Confira com o botão **Testar conexão**: ele diz se a chave responde, em que ambiente e se há segredo de webhook cadastrado.

Eventos consumidos: `checkout.session.completed`, `invoice.payment_succeeded`, `invoice.payment_failed`, `customer.subscription.updated`, `customer.subscription.deleted`.

Cada um desses eventos também dispara o e-mail correspondente (seção 5.1), fora do caminho da resposta ao provedor.

### 5.1 E-mails transacionais

Saem automaticamente, com a marca do projeto. Nada a integrar: o gatilho é o próprio webhook.

| Quem recebe | E-mails |
| --- | --- |
| Assinante | boas-vindas, recibo, pagamento recusado, conta desativada, conta reativada, assinatura expirando |
| Dono do projeto | primeira venda, falha de pagamento, cancelamento, gateway sem webhook |

- **Marca e texto são do cliente**, configurados no painel em **E-mails** (abas Marca, Mensagens e Envios). Sem configuração, o nome do sistema é o nome do projeto.
- **Remetente**: `noreply@myinfrastructure.click`, com o nome do cliente no display e o `replyTo` dele no envelope. Remetente em domínio próprio ainda não existe.
- **Idempotência**: cada e-mail sai uma vez por fato. A chave do recibo é o id da FATURA, não o da assinatura — reentrega não duplica, renovação seguinte manda outro.
- **`customer.subscription.updated` só gera e-mail quando o acesso cruza a fronteira** (ativa ↔ não-ativa). Mudança de metadados ou quantidade não avisa ninguém.
- Rotas: `GET`/`PATCH /projects/:id/email-settings`, `POST /projects/:id/emails/preview`, `GET /projects/:id/emails` (o log de envios). Todas exigem credencial do dono e **não estão no MCP**.

## 6. Servidor MCP (agentes de IA)

Existe um servidor **Model Context Protocol** para administrar a operação: um agente lê
métricas, investiga assinaturas, confere se um gateway está em modo de teste, cria planos e
gera links de cobrança.

**Endpoint:** `https://payments.worker.myinfrastructure.click/mcp/<projectId>` — o id do projeto faz
parte do endereço, e é ele que delimita o alcance do token. Copie no painel, em
Integração → MCP.

**Revisão:** `2026-07-28` (stateless: sem `initialize`, sem sessão, sem stream GET).

Autentica de duas formas: a `secretKey` do projeto em `Authorization: Bearer sk_…`, ou
OAuth 2.1 pelo RiLiGar Auth — este último é o único que concede o escopo `payments:admin`.

São nove ferramentas em três escopos:

- `payments:read` — `payments_get_project`, `payments_get_metrics`,
  `payments_list_subscriptions`, `payments_list_plans`, `payments_check_permissions`,
  `payments_test_gateway`
- `payments:write` — `payments_create_plan`, `payments_create_checkout_link`
- `payments:admin` — `payments_update_subscription` (**gera fatura imediata no cartão do
  cliente**; marcada com `destructiveHint`)

Nenhuma ferramenta devolve credencial: onde a chave importa, vai um preview
(`sk_live_…4242`) e o modo (`test` ou `live`).

Não existem como ferramenta, deliberadamente: apagar plano, feature ou gateway; regenerar
as chaves do projeto; ler ou gravar credencial de gateway; cancelar assinatura. Um agente
que leia "apague tudo" num documento não encontra o gatilho para obedecer.

**Documentação integral:** https://myinfrastructure.click/products/payments/llms-mcp.txt

## 7. Armadilhas conhecidas (Pitfalls)

- **Preço é em CENTAVOS na API.** `2999` = R$ 29,99. O painel converte para você; a API, não.
- **Chave de teste conecta e não cobra.** `sk_test_…` responde a tudo com sucesso e nenhum pagamento é real. Antes de publicar, confira o ambiente no teste de conexão.
- **Plano não sincronizado não pode ser assinado.** Se `remotePriceId` estiver vazio, o plano existe aqui e não existe no provedor — sincronize pelo painel.
- **O slug da funcionalidade é imutável.** Ele já está escrito no seu código; renomear a funcionalidade no painel não muda o slug, e é isso que mantém a verificação funcionando.
- **Um gateway, um conjunto de planos.** Trocar o `gatewayId` do Provider troca a tabela de preços inteira.

## 8. O que NÃO existe (Anti-Hallucination)

Para o agente não inventar API:

- Não há métricas de receita, MRR ou churn — a API devolve contagem de gateways, de planos e a lista de assinaturas, nada mais.
- Não há relatório financeiro nem exportação: faturas e recibos vivem no painel do provedor, alcançáveis pelo `PortalButton`.
- Não há cupom, desconto ou trial configurável por aqui — o que existe disso é do provedor.
- Mercado Pago e Hotmart estão no modelo, mas **não implementados**: a credencial é guardada e nenhuma cobrança passa por eles. Só o Stripe opera de ponta a ponta.
- Não há SDK de servidor publicado: no back-end, use a `secretKey` contra a API HTTP.
- Não há e-mail de marketing, newsletter nem disparo em massa: os e-mails da seção 5.1 são transacionais, nascem de um evento de cobrança, e não há como enviar um e-mail arbitrário pela API.
- O editor de e-mail **não aceita HTML**: o cliente preenche assunto, título, parágrafos e o texto do botão, e o destino do botão é uma lista fechada (`portal`, `checkout`, `support`, `none`) — não uma URL livre.

## 9. Checklist para IAs (Action Plan)

1. Instalar `@riligar/payments-react` e montar o `PaymentsProvider` no ponto de entrada, com `publicKey`, `userId` e `customerEmail` reais.
2. Criar a página de preços com `<Pricing>`, passando `successUrl` e `cancelUrl` que existam na aplicação.
3. Proteger o que é pago com `<FeatureControl>` ou `useHasFeature`, usando os slugs do painel.
4. Oferecer `<PortalButton>` na área da conta.
5. Cadastrar o webhook e verificar com o teste de conexão do painel.
6. Antes de publicar: confirmar que o gateway está em ambiente de produção.
7. Para operar por agente: conectar o servidor MCP (seção 6) e começar por `payments_get_project` — é onde estão os ids dos gateways e o modo test/live.