wegoft/bellwire

¿Qué hace bellwire?

Conecta el estado y los eventos del repositorio a las tarjetas, la bandeja de entrada y el iPhone del usuario de Bellwire. Los nuevos proyectos son Privados de manera predeterminada: Bellwire solo retransmite una señal de activación opaca mientras que el teléfono obtiene el contenido directamente del servicio HTTPS del usuario. El almacenamiento alojado es opt-in y requiere aprobación en la aplicación.

Flujo de Trabajo

1. Inspecciona el repositorio, su convención de gestión de secretos, las pruebas y el estado exacto de éxito o fallo que debería desencadenar el evento.

2. Clarifica únicamente las decisiones de producto que el código no puede responder: frecuencia de notificaciones, valores sensibles y si una interrupción de alta prioridad está justificada.

3. Asegúrate de que BELLWIRE_AGENT_TOKEN esté disponible fuera de los archivos rastreados. Si falta, pídele al usuario el código de seis dígitos que se muestra en la aplicación iOS y ejecuta:

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

   La CLI crea el archivo con modo 0600 y nunca imprime el Token. Impórtalo en el almacén de secretos aprobado por el usuario sin mostrarlo, luego elimina el archivo temporal. Nunca lo confirmes.

4. Ejecuta list-projects, luego crea o reutiliza el proyecto de Bellwire. Busca en la configuración existente antes de crear otro proyecto. Nunca crees un segundo proyecto solo para cambiar el modo de entrega.

5. Mantén el proyecto Privado a menos que el usuario quiera explícitamente que Bellwire Cloud almacene contenido de Evento, Bandeja de Entrada y Superficie:

   • Privado: implementa endpoints firmados de notificación Directa v2, bandeja de entrada y superficies; persiste las claves del dispositivo, nonces de un solo uso, una bandeja de salida de referencia opaca y la caducidad de la referencia de 24 horas en la base de datos real del usuario. Lee direct-connections.md.
   • Alojado: solicita el cambio con request-mode-change; detente hasta que el usuario conectado lo apruebe en Bellwire. Luego crea esquemas Alojados, Superficies y Tokens de Ingesta.

6. Para la entrega en tiempo real Privada, crea un token de solo activación, almacénalo en el administrador de secretos real de la aplicación fuente y llama a private-wakes de mejor esfuerzo después de que se confirme la transacción fuente y el registro de la bandeja de salida. Bellwire nunca debe recibir título, cuerpo, datos, URL del logotipo, nombre del proyecto o nombre de host del servicio.

7. Elige la primitiva de visualización:

   • Superficie: estado actual que se actualiza en su lugar. Lee surfaces.md.
   • Evento de Bandeja de Entrada: historial duradero, finalización, fallo, recuperación o un límite de decisión. En modo Privado permanece en el servicio del usuario; en modo Alojado usa event-spec.md.

8. Usa claves de Superficie estables y referencias opacas y aleatorias. Reutiliza una clave de idempotencia estable para reintentos de la misma activación o escritura Alojada.

9. Modifica el punto de activación más pequeño y confiable. Envía solo después de que se confirme la operación comercial subyacente.

   • Prefiere una llamada directa post-confirmación a Bellwire cuando la aplicación es dueña de la operación comercial.
   • Cuando un proveedor de pagos, comercio, despliegue o automatización es la fuente de verdad, lee webhooks.md y agrega un adaptador de webhook específico del proveedor.

10. Ejecuta pruebas unitarias para firma, marca de tiempo, clave desconocida, objetivo manipulado y repetición atómica de nonce; luego ejecuta conformance-direct.mjs. Si la base de datos no puede consumir un nonce de forma atómica, detente y explica el bloqueo de seguridad.

11. Ejecuta las pruebas existentes del repositorio más una prueba de activación enfocada. Nunca debilites una prueba comercial para que Bellwire pase.

12. Persiste e implementa el adaptador del lado fuente y sus secretos a través de la fuente de verdad real del repositorio.

13. Completa una operación fuente real y verifica la bandeja de salida, la aceptación de la activación, la entrega, la obtención firmada por el teléfono y el resultado mostrado usando production-verification.md. Una activación manual no es verificación de producción.

Estado de Integración

Usa estos límites exactos en los informes de progreso y finales:

• Configurado: el proyecto de Bellwire, esquema, token, Superficie o Evento de prueba existe. Esto no es una integración de producción.
• Integrado, pendiente de verificación de producción: el código del adaptador del lado fuente, los secretos de tiempo de ejecución, las pruebas enfocadas y el despliegue están presentes, pero ninguna operación fuente real ha completado la ruta.
• Verificado en producción: una operación comercial real creó el Evento o Superficie esperado, se verificó la Entrega y cualquier presentación reclamada en el dispositivo fue confirmada por el usuario.

Nunca describas send-test, una Superficie insertada manualmente o la creación de secretos como una integración de producción real.

Comandos

Usa scripts/bellwire.mjs para operaciones de la API. Por defecto usa la API alojada oficial y acepta BELLWIRE_API_URL para instalaciones autogestionadas.

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>

Ejecuta node <skill-dir>/scripts/bellwire.mjs --help para comandos de validación, revocación, borrado y cifrado. Los comandos que devuelven secretos requieren --secret-output; nunca leas su Token en el chat o la salida del comando.

delete-project es permanente y se propaga en cascada a través de los esquemas, tokens, eventos, entregas y Superficies activas del proyecto. Resuelve el ID exacto del proyecto y requiere intención explícita del usuario antes de ejecutarlo.

Usa --json para salida legible por máquina no secreta. Lee api.md cuando agregues otra operación o diagnostiques una respuesta de error.

Enrutamiento del Adaptador

• Lee adapters.md para patrones de Node.js, Cloudflare Worker, Shell y GitHub Actions.
• Lee webhooks.md cuando recibas eventos de pago similares a Stripe o cualquier callback de terceros antes de actualizar Bellwire.
• Prefiere el cliente HTTP existente del proyecto. No agregues una dependencia de SDK para una sola solicitud.
• Trata el envío de eventos como un efecto secundario acotado: establece un tiempo de espera, evita registrar cargas útiles y decide explícitamente si el fallo de la notificación puede afectar la operación comercial. Por defecto, hazlo de mejor esfuerzo después de que la operación comercial tenga éxito.
• Mantén los valores de los tokens fuera de los diffs generados, las instantáneas de prueba, los registros de CI y la telemetría de errores.

Reglas Privadas

• Genera al menos 128 bits aleatorios para cada referencia y codifícala como caracteres seguros para URL de 22 a 200 caracteres. Nunca la derives de un pedido, correo electrónico, tarea, cliente o marca de tiempo.
• Escribe los detalles de la notificación en una bandeja de salida respaldada por una base de datos antes de enviar la activación. Haz que la referencia expire después de un máximo de 24 horas.
• Una llamada de activación es acotada y de mejor esfuerzo después de la confirmación. No reviertas la operación comercial real porque Bellwire no esté disponible.
• MONTHLY_SIGNAL_LIMIT_REACHED es terminal hasta que llegue la hora UTC de reinicio devuelta o se realice una actualización. No hagas bucles ni reintentes.
• Los detalles Privados y las respuestas de la Bandeja de Entrada provienen del servicio del usuario y pueden almacenarse en caché en el teléfono durante 30 días; Bellwire Cloud nunca los recibe.

Reglas de Eventos Alojados

• Usa nombres punteados en minúscula como payment.success, deployment.failed o agent.waiting.
• Incluye solo los campos necesarios para la bandeja de entrada, la notificación, el enlace profundo o el diagnóstico.
• Nunca hagas referencia a un campo sensible en una plantilla de notificación; la API lo rechaza.
• Usa IDs de pedido, IDs de despliegue, IDs de tarea o IDs de ejecución para la idempotencia Alojada. No expongas esos identificadores como referencias Privadas.
• Evita eventos de progreso de alta frecuencia. Prefiere límites de finalización, fallo, recuperación y decisión requerida.
• Solicita la aprobación explícita del usuario antes de solicitar priority: high.

Reglas de Superficie

• Reutiliza una clave estable significativa como sales-today, prod-api o nightly-backup.
• Preserva el displayOrder asignado durante las actualizaciones rutinarias. Cámbialo solo cuando el usuario solicite explícitamente reordenar una tarjeta.
• Envía valores listos para mostrar. Por ejemplo, calcula los ingresos en el sistema fuente y envía ¥2,430; Bellwire no infiere agregación comercial de eventos sin procesar.
• Para métricas privadas o derivadas del cliente, prefiere un endpoint Bellwire Direct firmado para que la carga útil de la tarjeta nunca ingrese al almacenamiento de Bellwire.
• Elige uno de los tipos nativos admitidos. Nunca incrustes instrucciones de representación HTML, JavaScript, Swift, CSS o arbitrarias.
• Prefiere una Superficie para actualizaciones frecuentes de progreso y métricas; evita inundar la bandeja de entrada de Eventos.
• Usa acciones open_url solo cuando el destino sea esperado y seguro para el usuario.
• Los logotipos de los proyectos deben ser imágenes HTTPS públicas de no más de 5 MB. Bellwire los usa en avatares nativos y notificaciones enriquecidas expandidas, y luego recurre a un monograma del proyecto si la imagen falta o no se puede descargar.

Verificación y Recuperación

Si la configuración falla, lee troubleshooting.md. Verifica en este orden:

1. Accesibilidad de la API y alcance del token de administración.
2. ID del proyecto y versión activa del esquema.
3. Disponibilidad del secreto en el tiempo de ejecución real.
4. Tipo de carga útil y campos requeridos.
5. Comportamiento estable de Idempotency-Key.
6. Presencia del adaptador fuente en la versión desplegada y una operación fuente real.
7. Detalle del evento, estado de la Superficie y estado de la Entrega.
8. Permiso de notificación de iOS, registro del dispositivo y entorno APNs de sandbox versus producción.

Nunca rotes, revoques ni reemplaces un token que funcione a menos que el usuario lo haya solicitado o se sospeche un compromiso.