Configuração

Estes casos lançam ArgumentError a partir da linha que continha o valor errado, em vez de surgirem como uma falha confusa no seu primeiro envio. A mensagem indica o que estava errado e o que passar em vez disso, e nunca repete uma credencial.

Construa o cliente uma vez e partilhe-o. Um cliente novo por pedido deita fora as suas ligações abertas sem qualquer ganho, e nenhum do estado que contém é específico de quem chama. Um cliente fica congelado depois de construído e pode ser usado com segurança a partir de muitas threads ao mesmo tempo, por isso um processo Puma ou Sidekiq só precisa de um, e depois de um fork o processo filho abre as suas próprias ligações.

No caso que, de outro modo, obrigaria a um cliente por chave, como uma tarefa que envia em nome de vários espaços de trabalho, passe api_key: na chamada. Substitui o cabeçalho Authorization para esse pedido e não deixa nada no cliente.

message = {from: "[email protected]", to: "[email protected]", subject: "Your invoice", text: "Attached."}workspace_key = ENV.fetch("OPENEMAIL_API_KEY") client.emails.send(message) client.emails.send(message, api_key: workspace_key) client.threads.list(folder: "inbox", api_key: workspace_key)client.webhooks.list(api_key: workspace_key)

Todos os métodos fora de temp_mail recebem-na como argumento nomeado, ao lado dos filtros de uma lista, e os métodos de temp_mail recebem antes inbox_token:. É verificada antes de o pedido ser enviado, pela mesma regra que o cliente usa, pelo que um erro de escrita lança um ArgumentError sobre a api_key passada nesta chamada em vez de um 401 sobre uma credencial que depois tem de ir procurar. Uma chamada repetida mantém a chave que lhe foi dada.

client.raw é o transporte por onde passa cada método. client.raw.request chama um caminho que nenhum método envolve ainda, aplicando a credencial, o URL base, o timeout e a política de repetições do cliente, e devolve o corpo analisado tal como um método faz.

ping = client.raw.request("/ping") label = client.raw.request("/labels", method: :post, body: {name: "Invoices"}) p ping[:ok], label[:id]

OpenEmail.create_temp_mail constrói um cliente para caixas descartáveis que não transporta nenhuma chave de API nem lê nenhuma do ambiente. Cria caixas de entrada de forma anónima, e cada leitura envia o token da caixa que create devolveu, ou o mais recente que extend devolveu, seja por chamada como inbox_token:, seja uma única vez como OpenEmail.create_temp_mail(inbox_token:).

temp_mail = OpenEmail.create_temp_mail inbox = temp_mail.createpage = temp_mail.list_messages(inbox[:id], inbox_token: inbox[:token]) p page.items.size, page.expires_at

Uma aplicação que alguém ligou por OAuth, como uma ferramenta de linha de comandos ou um agente, tem um token de acesso em vez de uma chave de API. Passe-o como access_token:, seja o próprio token, seja qualquer objeto que responda a call e o devolva, como uma lambda ou um Method. É chamado uma vez por cada chamada, e as repetições dessa chamada reutilizam o que ele devolveu, por isso renove o token dentro dele quando estiver perto de expirar e o cliente nunca terá de ser reconstruído.

tokens = {current: "token-from-your-oauth-flow"} oauth_client = OpenEmail::Client.new(access_token: -> { tokens.fetch(:current) }) me = oauth_client.me.get puts me[:clientId], me[:expiresAt] if me[:object] == "oauth_token"

Antes de uma alteração sensível, como apagar um domínio ou alterar um webhook, a API pede a um token de acesso o código de verificação que a aplicação web pediria à pessoa. A chamada lança um OpenEmail::PermissionError, um 403 cujo step_up_required? é true, e nada foi alterado. Peça um código, verifique o que a pessoa lhe der e depois faça a chamada de novo. A uma chave de API nunca é pedido.

domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" begin  client.domains.delete(domain_id)rescue OpenEmail::ApiError => error  raise unless error.step_up_required?   challenge = client.security.begin_step_up   if challenge[:method] == "email"    puts "Enter the code we emailed to #{challenge[:sentTo]}"  else    puts "Enter the code from your authenticator app, or a backup code"  end   client.security.verify_step_up(code: $stdin.gets.to_s.strip)  client.domains.delete(domain_id)end

Quando há uma versão mais recente da gem no RubyGems, o cliente di-lo uma vez por processo, na saída de erro padrão, com uma linha como ℹ openemail 0.0.2 is available, you are on 0.0.1. seguida da página da gem. A verificação é executada quando o primeiro cliente é construído, numa thread em segundo plano com um timeout de dois segundos, só quando a saída padrão é um terminal, e uma falha ao chegar ao RubyGems é ignorada.

O adaptador predefinido encontra o seu proxy com o próprio URI#find_proxy do Ruby, por isso segue as mesmas regras que o resto da biblioteca padrão: https_proxy ou HTTPS_PROXY indica o proxy, e no_proxy ou NO_PROXY lista os hosts que vão diretamente. Um nome de utilizador e uma palavra-passe no URL do proxy são enviados ao proxy, e nunca se chega a um servidor nesta máquina através de um proxy.

adapter: substitui a camada HTTP. É qualquer objeto que responda a call(request), incluindo uma lambda, e devolva um OpenEmail::HttpResponse com status, headers e body. O pedido é um OpenEmail::HttpRequest com method, url, headers, body e timeout, por isso um teste pode verificar exatamente o que teria saído.

requests = [] adapter = lambda do |request|  requests << request  OpenEmail::HttpResponse.new(    status: 200,    headers: {"content-type" => "application/json"},    body: JSON.generate({id: "msg_test", status: "sent", replayed: false})  )end test_client = OpenEmail::Client.new(api_key: "oe_test_fake", adapter:, max_retries: 0, disable_update_notice: true) sent = test_client.emails.send(from: "[email protected]", to: "[email protected]", subject: "Hi", text: "Hello") p sent[:status], requests.first.method, requests.first.url, requests.first.headers["Idempotency-Key"]p requests.first

Ao imprimir um pedido, o seu cabeçalho Authorization aparece como [redacted], por isso um log de testes nunca contém a chave.

• —Devolva um estado fora de 2xx com o envelope de erro da API como corpo, por exemplo {"error": {"type": "validation_error", "code": "invalid_parameter", "message": "..."}}, para obter a subclasse de OpenEmail::ApiError correspondente.
• —Lance Timeout::Error a partir de call, ou Net::ReadTimeout, que é um deles, para obter um OpenEmail::NetworkError cujo timeout? é true. Qualquer outro StandardError, como Errno::ECONNREFUSED, torna-se um NetworkError cujo timeout? é false.
• —NameError, TypeError e ArgumentError lançados dentro do adaptador contam como bugs dele. São lançados sem alterações e nunca são repetidos.