wegoft/bellwire

Que fait bellwire ?

Connectez l'état du dépôt et les événements aux cartes Bellwire, à la boîte de réception et à l'iPhone de l'utilisateur. Les nouveaux projets sont Privés par défaut : Bellwire ne relaie qu'un signal opaque pendant que le téléphone récupère directement le contenu depuis le service HTTPS de l'utilisateur. Le stockage hébergé est optionnel et nécessite une approbation dans l'application.

Workflow

1. Inspectez le dépôt, sa convention de gestion des secrets, ses tests et l'état exact (réussi ou échoué) qui doit déclencher l'événement.

2. Clarifiez uniquement les décisions produit que le code ne peut pas répondre : fréquence des notifications, valeurs sensibles et si une interruption de haute priorité est justifiée.

3. Assurez-vous que BELLWIRE_AGENT_TOKEN est disponible en dehors des fichiers suivis. S'il manque, demandez à l'utilisateur le code à six chiffres affiché dans l'application iOS et exécutez :

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

   L'interface en ligne de commande crée le fichier avec le mode 0600 et n'affiche jamais le jeton. Importez-le dans le gestionnaire de secrets approuvé de l'utilisateur sans l'afficher, puis supprimez le fichier temporaire. Ne le commitez jamais.

4. Exécutez list-projects, puis créez ou réutilisez le projet Bellwire. Recherchez la configuration existante avant de créer un autre projet. Ne créez jamais un second projet simplement pour changer le mode de livraison.

5. Gardez le projet Privé sauf si l'utilisateur souhaite explicitement que Bellwire Cloud stocke le contenu des Événements, de la Boîte de réception et des Surfaces :

   • Privé : implémentez les points de terminaison signés Direct v2 (notification, boîte de réception et surfaces) ; persistez les clés de l'appareil, les nonces à usage unique, une boîte d'envoi de référence opaque et l'expiration de la référence (24 heures) dans la base de données réelle de l'utilisateur. Lisez direct-connections.md.
   • Hébergé : demandez le changement avec request-mode-change ; arrêtez-vous jusqu'à ce que l'utilisateur connecté l'approuve dans Bellwire. Créez ensuite les schémas, les Surfaces et les Jetons d'ingestion hébergés.

6. Pour la livraison en mode Privé, créez un jeton de réveil uniquement, stockez-le dans le gestionnaire de secrets réel de l'application source et appelez private-wakes au mieux après la transaction source et l'enregistrement de la boîte d'envoi. Bellwire ne doit jamais recevoir de titre, de corps, de données, d'URL de logo, de nom de projet ou de nom d'hôte du service.

7. Choisissez la primitive d'affichage :

   • Surface : état actuel qui se met à jour sur place. Lisez surfaces.md.
   • Événement de boîte de réception : historique durable, achèvement, échec, récupération ou une limite de décision. En mode Privé, il reste dans le service de l'utilisateur ; en mode Hébergé, utilisez event-spec.md.

8. Utilisez des clés de Surface stables et des références opaques et aléatoires. Réutilisez une clé d'idempotence stable pour les tentatives de réveil ou d'écriture hébergée.

9. Modifiez le point de déclenchement fiable le plus petit. Envoyez uniquement après que l'opération métier sous-jacente a été validée.

   • Préférez un appel Bellwire direct post-validation lorsque l'application possède l'opération métier.
   • Lorsqu'un fournisseur de paiement, de commerce, de déploiement ou d'automatisation est la source de vérité, lisez webhooks.md et ajoutez un adaptateur webhook spécifique au fournisseur.

10. Exécutez les tests unitaires pour la signature, l'horodatage, la clé inconnue, la cible falsifiée et la relecture atomique de nonce ; puis exécutez conformance-direct.mjs. Si la base de données ne peut pas consommer atomiquement un nonce, arrêtez-vous et expliquez le blocage de sécurité.

11. Exécutez les tests existants du dépôt ainsi qu'un test de déclenchement ciblé. N'affaiblissez jamais un test métier pour faire passer Bellwire.

12. Persistez et déployez l'adaptateur côté source et ses secrets via la source de vérité réelle du dépôt.

13. Effectuez une opération source réelle et vérifiez la boîte d'envoi, l'acceptation du réveil, la livraison, la récupération signée par le téléphone et le résultat affiché en utilisant production-verification.md. Un réveil manuel n'est pas une vérification de production.

Statut d'intégration

Utilisez ces limites exactes dans les rapports d'avancement et finaux :

• Configuré : le projet Bellwire, le schéma, le jeton, la Surface ou l'Événement de test existe. Ce n'est pas une intégration de production.
• Intégré, en attente de vérification de production : le code de l'adaptateur côté source, les secrets d'exécution, les tests ciblés et le déploiement sont présents, mais aucune opération source réelle n'a terminé le chemin.
• Vérifié en production : une opération métier réelle a créé l'Événement ou la Surface attendu, la Livraison a été vérifiée et toute présentation revendiquée sur l'appareil a été confirmée par l'utilisateur.

Ne décrivez jamais send-test, une Surface insérée manuellement ou la création d'un secret comme une intégration de production réelle.

Commandes

Utilisez scripts/bellwire.mjs pour les opérations API. Il utilise par défaut l'API hébergée officielle et accepte BELLWIRE_API_URL pour les installations auto-hébergées.

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>

Exécutez node <skill-dir>/scripts/bellwire.mjs --help pour les commandes de validation, de révocation, de suppression et de chiffrement. Les commandes qui retournent des secrets nécessitent --secret-output ; ne lisez jamais leur Jeton dans le chat ou la sortie de commande.

delete-project est permanent et se propage en cascade aux schémas, jetons, événements, livraisons et Surfaces actives du projet. Résolvez l'ID exact du projet et exigez une intention explicite de l'utilisateur avant de l'exécuter.

Utilisez --json pour une sortie non secrète lisible par machine. Lisez api.md lors de l'ajout d'une autre opération ou du diagnostic d'une réponse d'erreur.

Routage des adaptateurs

• Lisez adapters.md pour les modèles Node.js, Cloudflare Worker, Shell et GitHub Actions.
• Lisez webhooks.md lorsque vous recevez des événements de paiement de type Stripe ou tout rappel tiers avant de mettre à jour Bellwire.
• Préférez le client HTTP existant du projet. N'ajoutez pas de dépendance SDK pour une seule requête.
• Traitez l'envoi d'événements comme un effet de bord borné : définissez un délai d'attente, évitez de journaliser les charges utiles et décidez explicitement si l'échec de la notification peut affecter l'opération métier. Par défaut, faites au mieux après la réussite de l'opération métier.
• Gardez les valeurs des jetons en dehors des diffs générés, des instantanés de test, des journaux CI et de la télémétrie d'erreur.

Règles privées

• Générez au moins 128 bits aléatoires pour chaque référence et encodez-la en 22 à 200 caractères sûrs pour les URL. Ne la dérivez jamais d'une commande, d'un e-mail, d'une tâche, d'un client ou d'un horodatage.
• Écrivez les détails de la notification dans une boîte d'envoi basée sur une base de données avant d'envoyer le réveil. Faites expirer la référence après au maximum 24 heures.
• Un appel de réveil est borné et au mieux après validation. N'annulez pas l'opération métier réelle parce que Bellwire est indisponible.
• MONTHLY_SIGNAL_LIMIT_REACHED est terminal jusqu'à l'heure de réinitialisation UTC renvoyée ou une mise à niveau. Ne bouclez pas et ne réessayez pas.
• Les détails privés et les réponses de la boîte de réception proviennent du service de l'utilisateur et peuvent être mis en cache sur le téléphone pendant 30 jours ; Bellwire Cloud ne les reçoit jamais.

Règles des événements hébergés

• Utilisez des noms en points minuscules comme payment.success, deployment.failed ou agent.waiting.
• Incluez uniquement les champs nécessaires pour la boîte de réception, la notification, le lien profond ou le diagnostic.
• Ne référencez jamais un champ sensible dans un modèle de notification ; l'API le rejette.
• Utilisez les IDs de commande, IDs de déploiement, IDs de tâche ou IDs d'exécution pour l'idempotence hébergée. N'exposez pas ces identifiants comme références privées.
• Évitez les événements de progression à haute fréquence. Préférez les limites d'achèvement, d'échec, de récupération et de décision requise.
• Demandez une approbation explicite de l'utilisateur avant de demander priority: high.

Règles des Surfaces

• Réutilisez une clé stable significative comme sales-today, prod-api ou nightly-backup.
• Préservez le displayOrder attribué lors des mises à jour de routine. Modifiez-le uniquement lorsque l'utilisateur demande explicitement de réorganiser une carte.
• Envoyez des valeurs prêtes à afficher. Par exemple, calculez le revenu dans le système source et envoyez 2 430 € ; Bellwire n'infère pas d'agrégation métier à partir d'événements bruts.
• Pour les métriques privées ou dérivées du client, préférez un point de terminaison Bellwire Direct signé afin que la charge utile de la carte n'entre jamais dans le stockage Bellwire.
• Choisissez l'un des types natifs pris en charge. N'intégrez jamais de HTML, JavaScript, Swift, CSS ou d'instructions de rendu arbitraires.
• Préférez une Surface pour les mises à jour fréquentes de progression et de métriques ; évitez d'inonder la boîte de réception des événements.
• Utilisez les actions open_url uniquement lorsque la destination est attendue et sûre pour l'utilisateur.
• Les logos de projet doivent être des images HTTPS publiques ne dépassant pas 5 Mo. Bellwire les utilise dans les avatars natifs et les notifications enrichies étendues, puis utilise un monogramme de projet si l'image est manquante ou ne peut pas être téléchargée.

Vérification et récupération

Si la configuration échoue, lisez troubleshooting.md. Vérifiez dans cet ordre :

1. Accessibilité de l'API et portée du jeton de gestion.
2. ID du projet et version active du schéma.
3. Disponibilité du secret dans l'environnement d'exécution réel.
4. Type de charge utile et champs obligatoires.
5. Comportement stable de l'Idempotency-Key.
6. Présence de l'adaptateur source dans la version déployée et une opération source réelle.
7. Détail de l'événement, état de la Surface et statut de la livraison.
8. Autorisation de notification iOS, enregistrement de l'appareil et environnement APNs sandbox vs production.

Ne faites jamais pivoter, révoquez ou remplacez un jeton fonctionnel sauf si l'utilisateur l'a demandé ou si une compromission est suspectée.