wegoft/bellwire

O que bellwire faz?

Conecte o estado do repositório e eventos aos cartões, à caixa de entrada e ao iPhone do usuário do Bellwire. Novos projetos são Privados por padrão: o Bellwire apenas retransmite um acorde opaco enquanto o telefone busca o conteúdo diretamente do serviço HTTPS do usuário. O armazenamento hospedado é opcional e requer aprovação no aplicativo.

Fluxo de Trabalho

1. Inspecione o repositório, sua convenção de gerenciamento de segredos, testes e o estado exato (bem-sucedido ou falho) que deve acionar o evento.

2. Esclareça apenas decisões de produto que o código não pode responder: frequência de notificações, valores sensíveis e se uma interrupção de alta prioridade é justificada.

3. Certifique-se de que BELLWIRE_AGENT_TOKEN esteja disponível fora dos arquivos rastreados. Se estiver faltando, peça ao usuário o código de seis dígitos mostrado no aplicativo iOS e execute:

   bellwire_secret_dir="$(mktemp -d)"
   node <skill-dir>/scripts/bellwire.mjs bind \
     --code 123456 \
     --name "Codex no Mac" \
     --secret-output "$bellwire_secret_dir/agent-token"
   

   O CLI cria o arquivo com modo 0600 e nunca imprime o Token. Importe-o no gerenciador de segredos aprovado do usuário sem exibi-lo, depois remova o arquivo temporário. Nunca faça commit dele.

4. Execute list-projects, crie ou reutilize o projeto Bellwire. Pesquise a configuração existente antes de criar outro projeto. Nunca crie um segundo projeto apenas para alterar o modo de entrega.

5. Mantenha o projeto Privado, a menos que o usuário queira explicitamente que o Bellwire Cloud armazene conteúdo de Evento, Caixa de Entrada e Superfície:

   • Privado: implemente endpoints assinados de notificação Direct v2, caixa de entrada e superfícies; persista chaves do dispositivo, nonces de uso único, uma caixa de saída de referência opaca e a expiração de 24 horas da referência no banco de dados real do usuário. Leia direct-connections.md.
   • Hospedado: solicite a alteração com request-mode-change; pare até que o usuário conectado aprove no Bellwire. Em seguida, crie esquemas Hospedados, Superfícies e Tokens de Ingestão.

6. Para entrega Privada em tempo real, crie um token de acorde apenas, armazene-o no gerenciador de segredos real do aplicativo de origem e chame private-wakes no modo "melhor esforço" após a transação de origem e o commit do registro da caixa de saída. O Bellwire nunca deve receber título, corpo, dados, URL do logotipo, nome do projeto ou nome do serviço.

7. Escolha o primitivo de exibição:

   • Superfície: estado atual que é atualizado no local. Leia surfaces.md.
   • Evento de Caixa de Entrada: histórico durável, conclusão, falha, recuperação ou limite de decisão. No modo Privado, permanece no serviço do usuário; no modo Hospedado, use event-spec.md.

8. Use chaves de Superfície estáveis e referências opacas e aleatórias. Reutilize uma chave de idempotência estável para tentativas repetidas do mesmo acorde ou gravação Hospedada.

9. Modifique o menor ponto de acionamento confiável. Envie apenas após a operação de negócio subjacente ser confirmada.

   • Prefira uma chamada Bellwire direta pós-commit quando o aplicativo for o dono da operação de negócio.
   • Quando um provedor de pagamento, comércio, implantação ou automação for a fonte da verdade, leia webhooks.md e adicione um adaptador de webhook específico do provedor.

10. Execute testes unitários para assinatura, timestamp, chave desconhecida, alvo adulterado e repetição atômica de nonce; depois execute conformance-direct.mjs. Se o banco de dados não puder consumir atomicamente um nonce, pare e explique o bloqueio de segurança.

11. Execute os testes existentes do repositório mais um teste de acionamento focado. Nunca enfraqueça um teste de negócio para fazer o Bellwire passar.

12. Persista e implante o adaptador do lado da fonte e seus segredos através da verdadeira fonte do repositório.

13. Complete uma operação de fonte real e verifique a caixa de saída, aceitação do acorde, entrega, busca assinada pelo telefone e resultado exibido usando production-verification.md. Um acorde manual não é verificação de produção.

Status de Integração

Use estes limites exatos em relatórios de progresso e finais:

• Configurado: o projeto Bellwire, esquema, token, Superfície ou Evento de teste existe. Isso não é uma integração de produção.
• Integrado, aguardando verificação de produção: código adaptador do lado da fonte, segredos de execução, testes focados e implantação estão presentes, mas nenhuma operação de fonte real concluiu o caminho.
• Verificado em produção: uma operação de negócio real criou o Evento ou Superfície esperado, a Entrega foi verificada e qualquer apresentação reivindicada no dispositivo foi confirmada pelo usuário.

Nunca descreva send-test, uma Superfície inserida manualmente ou criação de segredo como uma integração de produção real.

Comandos

Use scripts/bellwire.mjs para operações da API. Ele usa como padrão a API hospedada oficial e aceita BELLWIRE_API_URL para instalações auto-hospedadas.

bellwire_secret_dir="$(mktemp -d)"
node <skill-dir>/scripts/bellwire.mjs list-projects
node <skill-dir>/scripts/bellwire.mjs create-project --name "VideoSays" --logo-url "https://videosays.com/logo.png"
node <skill-dir>/scripts/bellwire.mjs create-wake-token --project <id> --name production --secret-output "$bellwire_secret_dir/wake-token"
node <skill-dir>/scripts/bellwire.mjs generate-reference
node <skill-dir>/scripts/bellwire.mjs send-wake --project <id> --reference <opaque-ref> --idempotency-key <stable-key>
node <skill-dir>/scripts/bellwire.mjs request-mode-change --project <id> --to hosted
node <skill-dir>/scripts/bellwire.mjs update-project --project <id> --logo-url "https://cdn.example.com/logo.png"
node <skill-dir>/scripts/bellwire.mjs set-project-order --project <id> --order 10
node <skill-dir>/scripts/bellwire.mjs delete-project --project <id>
node <skill-dir>/scripts/bellwire.mjs create-schema --project <id> --file event-spec.json
node <skill-dir>/scripts/bellwire.mjs create-token --project <id> --name production --secret-output "$bellwire_secret_dir/ingest-token"
node <skill-dir>/scripts/bellwire.mjs upsert-surface --project <id> --key prod-api --file surface.json
node <skill-dir>/scripts/bellwire.mjs list-surfaces --project <id>
node <skill-dir>/scripts/bellwire.mjs list-direct-recoveries
node <skill-dir>/scripts/bellwire.mjs set-surface-order --project <id> --key prod-api --order 20
node <skill-dir>/scripts/bellwire.mjs send-test --project <id> --file test-event.json
node <skill-dir>/scripts/bellwire.mjs event --event <event-id>
node <skill-dir>/scripts/bellwire.mjs health --project <id>
node <skill-dir>/scripts/bellwire.mjs publish-direct-connection \
  --device-key-id <id> \
  --agreement-public-key <base64> \
  --file direct-connection.json
node <skill-dir>/scripts/conformance-direct.mjs \
  --manifest direct-connection.json \
  --device-key-id <id> \
  --reference <known-test-reference>

Execute node <skill-dir>/scripts/bellwire.mjs --help para comandos de validação, revogação, exclusão e criptografia. Comandos que retornam segredos exigem --secret-output; nunca leia o Token deles no chat ou na saída do comando.

delete-project é permanente e se propaga pelos esquemas, tokens, eventos, entregas e Superfícies ativas do projeto. Resolva o ID exato do projeto e exija intenção explícita do usuário antes de executá-lo.

Use --json para saída não secreta legível por máquina. Leia api.md ao adicionar outra operação ou diagnosticar uma resposta de erro.

Roteamento de Adaptador

• Leia adapters.md para padrões Node.js, Worker do Cloudflare, Shell e GitHub Actions.
• Leia webhooks.md ao receber eventos de pagamento do tipo Stripe ou qualquer callback de terceiros antes de atualizar o Bellwire.
• Prefira o cliente HTTP existente do projeto. Não adicione uma dependência de SDK para uma única requisição.
• Trate o envio de eventos como um efeito colateral limitado: defina um timeout, evite registrar payloads e decida explicitamente se a falha de notificação pode afetar a operação de negócio. Por padrão, use "melhor esforço" após a operação de negócio ser bem-sucedida.
• Mantenha os valores dos tokens fora de diffs gerados, snapshots de teste, logs de CI e telemetria de erros.

Regras Privadas

• Gere pelo menos 128 bits aleatórios para cada referência e codifique-a em 22–200 caracteres seguros para URL. Nunca a derive de um pedido, e-mail, tarefa, cliente ou timestamp.
• Escreva detalhes da notificação em uma caixa de saída baseada em banco de dados antes de enviar o acorde. Expire a referência após no máximo 24 horas.
• Uma chamada de acorde é limitada e de "melhor esforço" após o commit. Não reverta a operação de negócio real porque o Bellwire está indisponível.
• MONTHLY_SIGNAL_LIMIT_REACHED é terminal até o horário de reinício UTC retornado ou um upgrade. Não faça loop ou tente novamente.
• As respostas de detalhe Privado e Caixa de Entrada vêm do serviço do usuário e podem ser armazenadas em cache no telefone por 30 dias; o Bellwire Cloud nunca as recebe.

Regras de Evento Hospedado

• Use nomes pontilhados em minúsculas, como payment.success, deployment.failed ou agent.waiting.
• Inclua apenas os campos necessários para a caixa de entrada, notificação, link profundo ou diagnóstico.
• Nunca faça referência a um campo sensível em um modelo de notificação; a API o rejeita.
• Use IDs de pedido, IDs de implantação, IDs de tarefa ou IDs de execução para idempotência Hospedada. Não exponha esses identificadores como referências Privadas.
• Evite eventos de progresso de alta frequência. Prefira limites de conclusão, falha, recuperação e decisão necessária.
• Peça aprovação explícita do usuário antes de solicitar priority: high.

Regras de Superfície

• Reutilize uma chave estável significativa, como sales-today, prod-api ou nightly-backup.
• Preserve o displayOrder atribuído durante atualizações de rotina. Altere-o apenas quando o usuário solicitar explicitamente reordenar um cartão.
• Envie valores prontos para exibição. Por exemplo, calcule a receita no sistema de origem e envie ¥2.430; o Bellwire não infere agregação de negócios a partir de eventos brutos.
• Para métricas privadas ou derivadas de clientes, prefira um endpoint Bellwire Direct assinado para que o payload do cartão nunca entre no armazenamento do Bellwire.
• Escolha um dos tipos nativos suportados. Nunca incorpore HTML, JavaScript, Swift, CSS ou instruções de renderização arbitrárias.
• Prefira uma Superfície para atualizações frequentes de progresso e métricas; evite inundar a caixa de entrada de Eventos.
• Use ações open_url apenas quando o destino for esperado e seguro para o usuário.
• Os logotipos do projeto devem ser imagens HTTPS públicas com no máximo 5 MB. O Bellwire as usa em avatares nativos e notificações rich expandidas, e usa um monograma do projeto como fallback se a imagem estiver faltando ou não puder ser baixada.

Verificação e Recuperação

Se a configuração falhar, leia troubleshooting.md. Verifique nesta ordem:

1. Acessibilidade da API e escopo do token de gerenciamento.
2. ID do projeto e versão ativa do esquema.
3. Disponibilidade de segredos no ambiente de execução real.
4. Tipo de payload e campos obrigatórios.
5. Comportamento estável do Idempotency-Key.
6. Presença do adaptador de fonte na versão implantada e uma operação de fonte real.
7. Detalhe do evento, estado da Superfície e status da Entrega.
8. Permissão de notificação iOS, registro do dispositivo e ambiente APNs de sandbox versus produção.

Nunca gire, revogue ou substitua um token funcional a menos que o usuário tenha solicitado ou haja suspeita de comprometimento.