{
    "nome": "conector-email",
    "titulo": "Conector email",
    "dependencias": {
        "fonteSeguraImportacao": true,
        "arquivos": [
            {
                "papel": "manifesto",
                "origem": "conectores/conector-email/conector-email.json",
                "destino": "conectores/conector-email/conector-email.json",
                "obrigatorio": true
            },
            {
                "papel": "formato",
                "origem": "conectores/conector-email/formatos/formato-conector-email.json",
                "destino": "conectores/conector-email/formatos/formato-conector-email.json",
                "obrigatorio": true
            },
            {
                "papel": "handler",
                "origem": "conectores/conector-email/handlers/conector-email.php",
                "destino": "conectores/conector-email/handlers/conector-email.php",
                "obrigatorio": true
            },
            {
                "papel": "catalogo-mensagens",
                "origem": "web-api/catalogo-conector-email.json",
                "destino": "web-api/catalogo-conector-email.json",
                "obrigatorio": true
            },
            {
                "papel": "manual-usuario",
                "origem": "conectores/conector-email/manual-conector-email.html",
                "destino": "conectores/conector-email/manual-conector-email.html",
                "obrigatorio": true
            }
        ]
    },
    "descricao": "Conector responsavel por envio real de emails via SMTP e busca real de emails via IMAP/socket. Deve trocar mensagens apenas via api.php (POST HTTP) e pela escuta do siscore, sem acesso direto a outros atores.",
    "versao": "1.0.0",
    "ativo": true,
    "tipo": "conector",
    "controlador": {
        "executavel": "./escuta/runtime-conector",
        "metodoLeitura": "ler-mensagem",
        "metodoEnvio": "POST api.php",
        "regraEnvio": "somente-via-api-sem-publicacao-direta-no-espaco",
        "handlerLerMensagem": "./conectores/conector-email/handlers/conector-email.php"
    },
    "protocoloEscuta": "formatos-escuta/protocolo-mensagem-siscore.v1.json",
    "formatoConector": "conectores/conector-email/formatos/formato-conector-email.json",
    "api.php": {
        "descricao": "Endpoint HTTP local para publicacao de mensagens. Nao usar pp --api; chamar api.php diretamente via POST.",
        "url": "./api.php",
        "metodo": "POST",
        "autenticacao": {
            "header": "Authorization: Bearer <token>",
            "token": "token-externo/<cliente>.txt (unico local canonico para tokens de cliente SISC)"
        },
        "body": {
            "idmensagem": "string (obrigatorio)",
            "dados": "object (obrigatorio)",
            "origem": "conector__<nome>",
            "processoId": "string (preservar do recebido)",
            "respostaA": "string (mensagemId da mensagem recebida)"
        }
    },
    "mensagensEspaco": {
        "regraCentral": "O conector nunca fala diretamente com agentes ou outros conectores. Toda saida deve chamar api.php via POST HTTP; api.php monta o envelope canonico, registra em api-publicadas e publica em espaco/entrada.",
        "leitura": {
            "metodo": "ler-mensagem",
            "acionamentoPelaEscuta": "./escuta/runtime-conector ler-mensagem <arquivo-mensagem>",
            "fonteDeVerdade": "O arquivo JSON da mensagem. Nao usar variaveis de ambiente para processoId, mensagemId, origem ou destino.",
            "camposObrigatorios": [
                "_sistema",
                "_protocolo",
                "payload"
            ]
        },
        "envio": {
            "metodo": "POST api.php",
            "publicacaoDiretaNoEspaco": false,
            "catalogo": "web-api/catalogo-mensagens.json",
            "observacao": "O conector faz POST HTTP para api.php com idmensagem e dados. api.php resolve destino via catalogo, monta envelope canonico, registra marcador api-publicadas e escreve em espaco/entrada. A escuta valida e entrega.",
            "preservarCorrelacao": [
                "processoId",
                "respostaA",
                "escopo",
                "idempotencia"
            ]
        }
    },
    "metodos": {
        "ler-mensagem": {
            "descricao": "Ler e processar uma mensagem ja reivindicada pela escuta. Recebe o caminho do arquivo como argumento.",
            "assinatura": "ler-mensagem <arquivo-mensagem>"
        },
        "enviar-resposta": {
            "descricao": "Enviar mensagem de resposta via POST HTTP para api.php. Preservar processoId da mensagem recebida e preencher respostaA com o mensagemId original.",
            "exemplo": "curl -X POST ./api.php -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{\"idmensagem\":\"<id>\",\"dados\":{...},\"origem\":\"conector__conector-email\",\"processoId\":\"<pid>\",\"respostaA\":\"<mid>\"}'"
        }
    },
    "servicoExterno": {
        "nome": "email",
        "descricao": "Servico externo de email para envio de mensagens e recepcao/busca de emails de um endereco informado.",
        "credenciais": {
            "referencia": "secretos/conector-email.json",
            "tipo": "arquivo-json-local-restrito",
            "permissaoRecomendada": "600"
        }
    },
    "operacoes": {
        "enviar": {
            "descricao": "Enviar uma mensagem real via SMTP para o endereco de email informado.",
            "protocoloExterno": "SMTP com TLS/SSL por socket PHP",
            "entradaObrigatoria": [
                "email",
                "acao",
                "mensagem"
            ],
            "entradaOpcional": [
                "assunto"
            ],
            "regras": [
                "acao deve ser enviar.",
                "email deve conter o endereco de destino.",
                "mensagem deve conter o texto a enviar.",
                "assunto e opcional; se ausente, o handler usa Mensagem do SISC.",
                "smtp.ativo deve ser true em secretos/conector-email.json."
            ]
        },
        "receber": {
            "descricao": "Buscar emails reais do endereco informado usando IMAP por socket.",
            "protocoloExterno": "IMAP com SSL/TLS por socket PHP",
            "entradaObrigatoria": [
                "email",
                "acao"
            ],
            "saida": "Resumo JSON no stdout com id, from, subject, date e messageId dos emails encontrados.",
            "regras": [
                "acao deve ser receber.",
                "email deve conter o remetente usado na busca IMAP SEARCH FROM.",
                "mensagem nao e obrigatoria para esta operacao.",
                "recebimento.ativo deve ser true em secretos/conector-email.json."
            ]
        }
    },
    "instrucoes": [
        "Handler real implementado em conectores/conector-email/handlers/conector-email.php.",
        "Configure credenciais reais em secretos/conector-email.json com permissao 600.",
        "Para acao=enviar, informe email, acao=enviar, mensagem e opcionalmente assunto.",
        "Para acao=receber, informe email e acao=receber; o email e usado como remetente na busca IMAP.",
        "Para enviar respostas a outros atores, faca POST HTTP para api.php (nao use pp --api).",
        "Preserve processoId da mensagem recebida e preencha respostaA com o mensagemId original.",
        "Autentique chamadas para api.php com token cadastrado exclusivamente em token-externo/<cliente>.txt no header Authorization: Bearer.",
        "Nao escreva diretamente em espaco/entrada, caixas, processando, concluidas, erro, quarentena, indice ou estado."
    ],
    "manualUsuario": "conectores/conector-email/manual-conector-email.html"
}