Crie a sua agenda
e mande o link, não o "que horas você pode?".

Vou construir o meu próprio sistema de agendamento (um Calendly meu), que precisa ler a minha agenda do Google e criar eventos nela. Antes do código, me guie pelo cadastro do app no Google Cloud.

Considere que eu nunca entrei no Google Cloud, que eu não sou programador e que eu vou clicar exatamente no que você mandar. Me dê o caminho em passos numerados, dizendo o NOME do botão em cada tela, e o que fazer quando a tela estiver diferente do esperado.

Preciso sair com quatro coisas: o ID do cliente, a chave secreta do cliente, o endereço de retorno cadastrado e o app publicado.

Cubra obrigatoriamente:
1. Criar o projeto e onde ativar a API do Google Agenda.
2. A tela de consentimento: que tipo de app escolher (externo), quais dados preencher, e por que eu vou ver um aviso de "app não verificado" quando eu mesmo for autorizar.
3. PUBLICAR o app, saindo do modo de Teste. Explique em uma frase por que isso é obrigatório: em modo de teste a autorização expira em 7 dias e a agenda para de funcionar sozinha, sem dar erro na tela.
4. As permissões (escopos) mínimas que eu preciso pedir pra ver os horários ocupados e criar evento, e por que não devo pedir mais que isso.
5. Criar a credencial do tipo aplicativo web, e onde colar o endereço de retorno. Me explique que esse endereço precisa ser IDÊNTICO ao que vai estar no meu código, incluindo barra final e http ou https, senão o login falha com um erro de endereço não confere.
6. O que muda quando eu subir pra internet e o endereço deixar de ser o do meu computador. Me diga pra já cadastrar os dois.

No fim, monte uma lista das quatro informações que eu devo ter em mãos e me diga onde cada uma vai ser usada. Não me mande guardar nada disso dentro do código.

Agora ligue o meu sistema na minha conta do Google. Já tenho o ID do cliente, a chave secreta e o endereço de retorno cadastrados.

O QUE PRECISA EXISTIR
1. Uma rota que começa a conexão: monta o endereço de autorização do Google e me manda pra lá.
   - Peça acesso permanente e force a tela de consentimento, senão o Google não devolve a chave permanente na segunda vez que eu conectar. Isso é a causa número um de "conectei e não funcionou".
   - Peça só as permissões necessárias: ver os horários ocupados e criar evento. Nada além disso.
2. Uma rota de retorno: recebe o código do Google, troca pela chave permanente, e guarda essa chave na tabela de chaves junto com o e-mail da conta e a data da conexão. Depois me manda de volta pro painel com uma mensagem de sucesso.
3. Uma função que, sempre que o sistema precisar falar com o Google, troca a chave permanente por uma chave temporária. Essa troca acontece em toda chamada, no servidor.
4. Uma função que pergunta ao Google quais períodos estão ocupados entre duas datas, na minha agenda principal.
5. Uma função que cria o evento na minha agenda, com convidado, e opcionalmente com link de reunião online.

REGRAS DE SEGURANÇA, sem exceção
- Chave secreta e chaves de acesso só existem no servidor, em variáveis de ambiente e no banco. Nunca em arquivo de tela, nunca numa resposta de API.
- Nenhuma rota pode devolver o conteúdo da chave. Nem pra debugar.
- No painel, a única coisa que aparece é: conectado ou não, e o e-mail da conta conectada.
- Se a chave for recusada pelo Google (revogada ou expirada), o sistema tem que mostrar "desconectado" com o botão de reconectar, e a página pública tem que dizer que a agenda está indisponível no momento, em vez de mostrar uma tela quebrada.

Me entregue os arquivos completos e o passo a passo do que eu clico pra conectar e confirmar que funcionou.

Agora o cálculo dos horários livres. É o coração do sistema.

A REGRA, na ordem
1. Comece na data de hoje e vá até o limite da janela de agendamento (por exemplo 30 dias).
2. Para cada dia, pegue as janelas de atendimento daquele dia da semana, que vêm da minha configuração (posso ter mais de uma janela no mesmo dia, por exemplo manhã e tarde).
3. Corte cada janela em pedaços do tamanho da reunião, um começando onde o outro termina. Um pedaço só existe se ele couber inteiro dentro da janela.
4. Remova todo pedaço que encoste em qualquer período ocupado da minha agenda. Ocupado é o que o Google respondeu, esticado pelo respiro configurado antes e depois. Encostar de raspão já elimina.
5. Remova todo pedaço que comece antes da antecedência mínima (por exemplo, nada pra daqui a menos de 4 horas).
6. Devolva a lista de dias, cada um com os horários que sobraram, já com a etiqueta no horário local (formato 09:00) e o instante exato em formato universal.

FUSO HORÁRIO, o assunto mais perigoso do projeto
- Use uma biblioteca de datas séria, não a data nativa da linguagem.
- Toda conta acontece no meu fuso configurado. O que vai e volta pelas APIs é sempre em formato universal.
- Um dia começa e termina no MEU fuso, não no fuso do servidor. O servidor vai rodar em outro país, e é assim que aparece aquele bug de o horário das 21h sumir ou de aparecer um dia a mais no fim da lista.
- Teste especificamente a virada de mês e o horário de verão de outros países.

COMO ISSO PRECISA SER ESCRITO
- Uma função pura, que recebe a configuração, a lista de períodos ocupados e o instante atual, e devolve a grade. Sem chamar internet, sem ler banco, sem usar a hora do sistema por dentro.
- É essa função que a rota chama depois de perguntar ao Google o que está ocupado.

TESTE, obrigatório
Escreva testes automáticos pra essa função, sem internet, cobrindo:
- Dia com uma reunião no meio: os horários certos somem, os outros ficam.
- Reunião que começa 10 minutos depois do início de um horário: aquele horário some.
- Respiro configurado: some também o horário colado no compromisso.
- Antecedência mínima: hoje só aparece o que está além dela.
- Dia sem janela de atendimento: lista vazia, sem quebrar.
- Última janela do horizonte: não pode aparecer um dia a mais nem faltar o último.
Rode os testes e me mostre o resultado antes de seguir.

Agora a página pública, que é o link que eu vou mandar pras pessoas. Ela tem três passos e uma tela de sucesso.

LAYOUT
- Coluna da esquerda fixa, com o meu nome, o título e o subtítulo da página (todos vindos da configuração) e três informações curtas: a duração da reunião, que o link da chamada vai junto no convite e qual é o fuso.
- Coluna da direita com o passo atual. Em cima do passo, uma etiqueta pequena "passo 1 de 3".

PASSO 1, o assunto
- Lista dos tipos de reunião que estão na minha configuração, um por linha, clicáveis.
- Se a lista estiver vazia, esse passo não existe e a pessoa começa no calendário.

PASSO 2, dia e hora
- Calendário do MÊS, não uma régua de dias deitada. Régua vira rolagem lateral no celular e derruba a conversão.
- Dia sem horário fica apagado e não clicável. Dia com horário fica clicável, e o dia escolhido fica marcado na cor de destaque.
- Setas pra mudar de mês, sem passar do limite da janela de agendamento.
- Ao escolher o dia, os horários daquele dia aparecem ao lado, em grade de dois por linha, no formato 09:00.
- Uma linha discreta em cima mostrando o tipo escolhido, com um "trocar" que volta ao passo 1.

PASSO 3, quem é
- Nome, e-mail e um campo opcional de "sobre o que quer conversar".
- Um resumo em cima do formulário: dia, horário e duração, por extenso.
- Botão de voltar e botão de confirmar. Enquanto envia, o botão vira "Agendando..." e trava, pra não criar dois eventos.

TELA DE SUCESSO
- Confirmação com o dia e a hora por extenso, o aviso de que o convite foi pro e-mail informado e, quando houver, o link da chamada.

REGRAS
- Zero rolagem lateral em 390px de largura. Teste isso.
- Se a agenda não estiver conectada, ou se der erro ao buscar os horários, mostre uma mensagem em português explicando e um jeito de falar comigo. Nunca uma tela em branco.
- Enquanto carrega, esqueleto cinza, nunca a palavra "carregando".
- Nada de emoji na interface.
Me entregue o arquivo completo e o que testar.

Agora a rota que marca a reunião de verdade.

O QUE ELA FAZ, na ordem
1. Recebe o horário escolhido, o nome, o e-mail, a observação e o tipo de reunião.
2. Valida tudo: e-mail com formato válido, nome preenchido, horário no formato certo.
3. RECONFERE a disponibilidade no servidor, perguntando de novo ao Google, imediatamente antes de criar. Nunca confie no que o navegador mandou: entre a pessoa abrir a página e clicar em confirmar podem ter passado dez minutos, e o horário pode ter sido tomado. Se não estiver mais livre, devolva um erro claro dizendo pra escolher outro horário, e a tela volta pro calendário já atualizado.
4. Verifica que o horário escolhido realmente existe na grade calculada. Não aceite um horário que veio "de fora" da grade, mesmo que esteja livre na agenda. Isso impede alguém de marcar às 3 da manhã mexendo na requisição.
5. Cria o evento na minha agenda com:
   - Título no formato "{tipo} · {nome da pessoa}", pra eu bater o olho na agenda e saber o que é. Se não houver tipo, use o título padrão da configuração.
   - Descrição com o e-mail, a observação e de onde veio o agendamento.
   - A pessoa como convidada, pra ela receber o convite por e-mail.
   - Link de reunião online criado automaticamente, quando estiver ligado na configuração.
6. Guarda um registro no meu banco: nome, e-mail, observação, tipo, início, fim, o identificador do evento e o link da chamada.
7. Devolve pro navegador só o que a tela precisa mostrar. Nada de dado interno.

ERROS, tratados como gente
- Google fora do ar ou chave recusada: mensagem em português, sem termo técnico, e o registro do erro no servidor.
- Se o evento for criado no Google mas falhar ao gravar no meu banco, NÃO diga que deu erro pra pessoa. O compromisso existe. Grave o problema pra eu ver depois.
- Clique duplo no botão não pode criar dois eventos.

Depois de pronto, faça o teste de verdade comigo: marcar um horário, abrir a minha agenda do Google e confirmar que o evento está lá com o convite e o link. Só considere o passo concluído depois disso.

Agora o meu painel, numa rota separada, protegido por uma senha só minha guardada em variável de ambiente do servidor.

BLOCO 1, CONEXÃO
- Mostra se a agenda está conectada e o e-mail da conta. Botão "Conectar" quando não estiver, "Reconectar" quando estiver.
- Nunca mostre a chave de acesso, nem parte dela.

BLOCO 2, DIAS E HORÁRIOS
- Uma linha por dia da semana, com uma marcação pra ligar e desligar o dia e dois campos de hora (de e até).
- Dia desligado fica apagado e não entra no cálculo.
- Abaixo, quatro campos: duração da reunião em minutos, respiro entre reuniões em minutos, antecedência mínima em horas e janela de agendamento em dias.
- Uma chave pra ligar e desligar a criação automática do link de reunião online.

BLOCO 3, TIPOS DE REUNIÃO
- Lista editável, com adicionar e remover.
- Uma frase explicando que a pessoa escolhe um tipo antes de marcar e que ele entra no título do evento junto com o nome dela, e que deixar a lista vazia faz o passo desaparecer.

BLOCO 4, TEXTOS
- Meu nome, título e subtítulo da página pública, e o título padrão do evento na agenda.

COMPORTAMENTO
- Salvar grava a configuração inteira de uma vez, e mostra uma confirmação discreta.
- Validação antes de salvar: hora final maior que a inicial, duração maior que zero, janela de agendamento maior que zero. Erro explicado em português, no campo.
- A página pública lê essa configuração a cada visita, então o que eu mudar aqui vale na próxima vez que alguém abrir o link. Sem cache que atrapalhe.
- Precisa funcionar bem no celular, porque é de lá que eu vou mudar meu horário na correria.

Me entregue os arquivos completos e o que testar.

Agora crie uma segunda página de agendamento, numa rota separada, feita pra ser embutida dentro de outra página minha (no fim de um formulário, por exemplo). A página principal continua exatamente como está.

DIFERENÇAS DESSA VERSÃO
- Abre DIRETO no calendário. Sem o passo de escolher o assunto.
- Layout enxuto: sem a coluna da esquerda, sem título grande, sem rodapé, com menos respiro. Calendário e horários lado a lado já em tela média, pra caber sem rolagem.
- Os textos dessa página são próprios, editáveis no painel, separados dos da página principal.
- O evento criado por aqui usa uma etiqueta própria no título, também editável no painel, pra eu saber que aquele agendamento veio do formulário.

O TRUQUE DA ALTURA (é isso que separa um embed bom de um ruim)
- Quando essa página estiver dentro de um quadro em outra página, ela precisa AVISAR a altura real do conteúdo pra página de fora, por mensagem entre janelas, toda vez que a altura mudar (trocou de mês, escolheu um dia, apareceu o formulário).
- A página de fora escuta essa mensagem e ajusta a altura do quadro. Resultado: nada de rolagem dentro da rolagem.
- Me entregue também o trecho que eu colo na página de fora pra escutar e ajustar, e um valor de altura padrão pro caso da mensagem não chegar.
- Reaproveite o MESMO componente da página principal, com uma variação de modo. Não crie uma cópia: duas cópias divergem em uma semana.

Me diga como testar isso de verdade, embutindo a página dentro de outra página minha, e o que eu devo ver em cada tamanho de tela.

Minha agenda funciona na minha máquina. Quero ela no ar, de graça, num link que eu possa mandar hoje.

Me guie clicado, assumindo que eu não sei o que é terminal:
1. Como subir o projeto pra internet.
2. Onde cadastrar as variáveis de ambiente (endereço e chave do banco, ID e chave secreta do Google, e a senha do meu painel) e por que elas não podem estar no código.
3. IMPORTANTE: assim que eu tiver o endereço definitivo, o que exatamente eu preciso voltar a fazer no Google Cloud pra o login funcionar no ar. Me diga onde clicar e o que colar. Explique que se o endereço de retorno não bater exatamente, o login falha com erro de endereço não confere.
4. Depois de tudo no ar, eu preciso conectar a minha conta de novo por lá. Me guie.
5. Como ligar um domínio próprio.

CHECAGEM FINAL, faça comigo em ordem:
- Abrir o link numa aba anônima: os horários aparecem?
- Os horários batem com a minha agenda real? Marque um compromisso qualquer no meu Google agora e recarregue: aquele horário sumiu?
- Marcar de verdade um horário de teste. O evento apareceu na minha agenda, com o convite e com o link da chamada?
- O convidado recebeu o e-mail?
- Marcar em outro fuso: mude o fuso do meu computador e confira se o horário continua correto.
- O painel sem senha devolve erro?
- A chave do Google aparece em algum lugar do que chega no navegador? Procure e me prove que não.
- No celular, tem rolagem lateral em alguma tela?
Depois disso, apague o evento de teste.

Pare de construir. Agora ataque o próprio trabalho como o usuário mais desastrado possível, e como o calendário mais bagunçado possível.

Vá atrás de tudo que quebra, especificamente:
- Duas pessoas escolhendo o mesmo horário quase ao mesmo tempo: o segundo recebe um erro claro ou cria um evento por cima?
- A pessoa deixa a página aberta por uma hora e clica em confirmar: o sistema reconfere antes de criar?
- Compromisso que atravessa a meia-noite, e compromisso de dia inteiro na minha agenda: derrubam os horários daquele dia?
- Um compromisso "livre" ou "talvez" na minha agenda: está sendo tratado como ocupado sem necessidade?
- Virada de mês no calendário: o mês seguinte carrega os horários certos? Dá pra navegar além da janela permitida?
- Meia-noite, e horários colados no fim da janela de atendimento: aparece um horário que termina depois do meu expediente?
- Fuso: alguém abrindo o link de Portugal ou dos Estados Unidos vê o horário certo? O que o e-mail do convite mostra?
- Horário de verão em outro país, e o meu próprio fuso: a conta continua certa?
- E-mail com espaço no fim, nome com acento e aspas, observação com 3 mil caracteres.
- Clique duplo no confirmar. Voltar do navegador depois de confirmar. Recarregar no meio.
- Agenda desconectada: a página pública explica o que houve ou quebra?
- Dia sem nenhum horário livre: fica clicável por engano?

Escreva a lista numerada, do mais grave pro mais bobo, com o que acontece na prática e em que arquivo está. Não conserte ainda.
Depois conserte um por um, na ordem, dizendo o que mudou.
No fim, rode a varredura de novo do zero. Repita até uma passagem inteira não achar nada novo.

Compare a minha página de agendamento com o Calendly, o Cal.com e o SavvyCal.

Liste 10 diferenças concretas de acabamento. Nada de "melhorar o design", quero item objetivo:
- Como o dia disponível se diferencia do indisponível sem depender só de cor.
- O que acontece no instante entre clicar no dia e os horários aparecerem.
- Tamanho e área de toque dos dias no celular.
- Como o horário selecionado se destaca.
- Onde fica o resumo do que a pessoa escolheu, e se ele acompanha ela até o fim.
- O texto do botão em cada passo (genérico contra específico).
- Como o fuso é comunicado sem assustar.
- O estado de erro quando o horário foi tomado no meio do caminho.
- A tela de sucesso: ela dá o próximo passo ou só agradece?
- Peso e tamanho de fonte na hierarquia dia, hora, resumo.

Regras: não invente cor nova nem fonte nova, nada de emoji, nada de sombra pesada. Estado de carregando é esqueleto.
Aplique uma de cada vez e me diga o que mudou.

Esqueça que você construiu isso. Você é uma pessoa mal intencionada que abriu o meu link de agendamento e apertou F12. Seus objetivos: entrar na minha agenda, encher ela de lixo ou descobrir o que eu tenho marcado.

Liste tudo que você tentaria e o resultado real, considerando o meu código:
- Achar a chave do Google ou a do banco no que chegou no navegador. Vasculhe e me prove se tem ou não tem.
- Marcar um horário fora do meu expediente, mandando um horário qualquer direto pra rota.
- Marcar um horário no passado, ou daqui a dois anos.
- Marcar 200 reuniões em um minuto e encher a minha semana. Existe algum limite?
- Descobrir o que eu tenho marcado: a resposta da rota de horários vaza título, participante ou alguma informação dos meus compromissos ocupados? Ela deveria devolver só "livre" ou "ocupado".
- Colocar HTML ou script no nome e na observação e ver se executa no meu painel ou entra torto no convite do Google.
- Colocar um e-mail de terceiro pra fazer o meu sistema mandar convite indesejado em nome dele.
- Chamar o painel e as rotas de configuração sem a senha.
- Ficar chamando a rota de horários mil vezes por minuto: isso pode me derrubar ou estourar a cota da API do Google?

Para cada item: o que eu tentei, o que aconteceu, e se é um buraco.
Se algo passar, me entregue a correção pronta e a explicação em português.
No fim, diga em uma frase o risco real que sobra mesmo com tudo certo.

Alguma coisa quebrou. Antes de mexer em qualquer linha, investigue.

O que eu fiz e o que aconteceu: DESCREVA AQUI
O que eu esperava: DESCREVA AQUI
Onde quebrou: na página pública, no login do Google, na hora de marcar ou no painel?
Console do navegador (F12, aba Console): COLE A MENSAGEM VERMELHA, OU ESCREVA "nada"
Terminal onde o projeto roda: COLE O ERRO, OU ESCREVA "nada"
A agenda aparece como conectada no painel? SIM OU NÃO

Siga exatamente esta ordem:
1. Diga em uma frase a sua hipótese da causa, apontando o arquivo, e diga se o problema é do meu código ou da configuração no Google.
2. Liste outras duas causas possíveis.
3. Diga o teste mais rápido pra saber qual das três é a verdadeira, e o que eu devo ver em cada caso.
4. Só com a causa confirmada, faça a correção mínima. Não reescreva arquivo inteiro, não mude o visual, não aproveite pra melhorar outra coisa.
5. Diga o que mudou e o que eu clico pra confirmar.

Se for configuração do Google, me diga exatamente em qual tela clicar, passo a passo.
Se não tiver certeza, diga que não tem certeza e me peça o que falta. Chutar correção é proibido.