wegoft/bellwire

Was macht bellwire?

Verbinden Sie Repository-Zustand und Ereignisse mit den Bellwire-Karten, dem Posteingang und dem iPhone des Benutzers. Neue Projekte sind standardmäßig privat: Bellwire übermittelt nur einen undurchsichtigen Weckruf, während das Telefon den Inhalt direkt vom HTTPS-Dienst des Benutzers abruft. Gehosteter Speicher ist optional und erfordert die Zustimmung in der App.

Arbeitsablauf

1. Überprüfen Sie das Repository, seine Konvention zur Geheimnisverwaltung, Tests und den genauen erfolgreichen oder fehlgeschlagenen Zustand, der das Ereignis auslösen soll.

2. Klären Sie nur Produktentscheidungen, die Code nicht beantworten kann: Benachrichtigungshäufigkeit, sensible Werte und ob eine Unterbrechung mit hoher Priorität gerechtfertigt ist.

3. Stellen Sie sicher, dass BELLWIRE_AGENT_TOKEN außerhalb von getrackten Dateien verfügbar ist. Fehlt es, fragen Sie den Benutzer nach dem sechsstelligen Code aus der iOS-App und führen Sie Folgendes aus:

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

   Das CLI erstellt die Datei mit Modus 0600 und gibt das Token nie aus. Importieren Sie es in den zugelassenen Geheimnisspeicher des Benutzers, ohne es anzuzeigen, und entfernen Sie dann die temporäre Datei. Führen Sie es niemals ein.

4. Führen Sie list-projects aus, und erstellen oder verwenden Sie das Bellwire-Projekt erneut. Durchsuchen Sie die vorhandene Konfiguration, bevor Sie ein weiteres Projekt erstellen. Erstellen Sie niemals ein zweites Projekt nur, um den Übermittlungsmodus zu ändern.

5. Behalten Sie das Projekt im privaten Modus, es sei denn, der Benutzer möchte ausdrücklich, dass Bellwire Cloud Ereignis-, Posteingangs- und Oberflächeninhalte speichert:

   • Privat: Implementieren Sie signierte Direct v2-Benachrichtigungs-, Posteingangs- und Oberflächenendpunkte; persistieren Sie Geräteschlüssel, einmalige Nonces, ein undurchsichtiges Referenz-Postausgang und den 24-Stunden-Referenzablauf in der echten Datenbank des Benutzers. Lesen Sie direct-connections.md.
   • Gehostet: Fordern Sie die Änderung mit request-mode-change an; warten Sie, bis der angemeldete Benutzer sie in Bellwire genehmigt hat. Erstellen Sie dann gehostete Schemas, Oberflächen und Ingest-Tokens.

6. Erstellen Sie für die private Laufzeitzustellung ein reines Weck-Token, speichern Sie es im echten Geheimnisverwalter der Quell-App und rufen Sie private-wakes bestmöglich nach der Quelltransaktion und dem Outbox-Datensatz-Commit auf. Bellwire darf niemals Titel, Text, Daten, Logo-URL, Projektname oder Diensthostnamen erhalten.

7. Wählen Sie das Anzeigeprimitiv:

   • Oberfläche: aktueller Zustand, der aktualisiert wird. Lesen Sie surfaces.md.
   • Posteingangsereignis: dauerhafter Verlauf, Abschluss, Fehler, Wiederherstellung oder eine Entscheidungsgrenze. Im privaten Modus bleibt es im Dienst des Benutzers; im gehosteten Modus verwenden Sie event-spec.md.

8. Verwenden Sie stabile Oberflächenschlüssel und undurchsichtige, zufällige Referenzen. Verwenden Sie einen stabilen Idempotenzschlüssel für Wiederholungen desselben Weckrufs oder desselben gehosteten Schreibvorgangs.

9. Ändern Sie den kleinsten zuverlässigen Auslösepunkt. Senden Sie erst, nachdem der zugrunde liegende Geschäftsvorgang abgeschlossen ist.

   • Bevorzugen Sie einen direkten Bellwire-Aufruf nach dem Commit, wenn die Anwendung den Geschäftsvorgang besitzt.
   • Wenn ein Zahlungs-, Handels-, Bereitstellungs- oder Automatisierungsanbieter die Quelle der Wahrheit ist, lesen Sie webhooks.md und fügen Sie einen anbieterspezifischen Webhook-Adapter hinzu.

10. Führen Sie Komponententests für Signatur, Zeitstempel, unbekannten Schlüssel, manipuliertes Ziel und atomare Nonce-Wiedergabe durch; führen Sie dann conformance-direct.mjs aus. Wenn die Datenbank eine Nonce nicht atomar konsumieren kann, brechen Sie ab und erklären Sie das Sicherheitshindernis.

11. Führen Sie die vorhandenen Tests des Repositorys sowie einen fokussierten Auslösetest durch. Schwächen Sie niemals einen Geschäftstest, damit Bellwire besteht.

12. Persistieren und bereitstellen Sie den quellseitigen Adapter und seine Geheimnisse über die echte Quelle der Wahrheit des Repositorys.

13. Führen Sie einen echten Quellvorgang aus und überprüfen Sie den Postausgang, die Wake-Annahme, die Zustellung, den signierten Telefonabruf und das angezeigte Ergebnis mit production-verification.md. Ein manueller Wake ist keine Produktionsverifizierung.

Integrationsstatus

Verwenden Sie diese genauen Grenzen in Fortschritts- und Abschlussberichten:

• Konfiguriert: das Bellwire-Projekt, Schema, Token, die Oberfläche oder das Testereignis existiert. Dies ist keine Produktionsintegration.
• Integriert, wartet auf Produktionsverifizierung: quellseitiger Adaptercode, Laufzeitgeheimnisse, fokussierte Tests und Bereitstellung sind vorhanden, aber kein echter Quellvorgang hat den Pfad abgeschlossen.
• Produktionsverifiziert: ein echter Geschäftsvorgang hat das erwartete Ereignis oder die Oberfläche erstellt, die Zustellung wurde überprüft und jede behauptete Gerätepräsentation wurde vom Benutzer bestätigt.

Beschreiben Sie send-test, eine manuell eingefügte Oberfläche oder die Erstellung von Geheimnissen niemals als tatsächliche Produktionsintegration.

Befehle

Verwenden Sie scripts/bellwire.mjs für API-Operationen. Es verwendet standardmäßig die offizielle gehostete API und akzeptiert BELLWIRE_API_URL für selbst gehostete Installationen.

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>

Führen Sie node <skill-dir>/scripts/bellwire.mjs --help für Validierungs-, Widerrufs-, Lösch- und Verschlüsselungsbefehle aus. Befehle, die Geheimnisse zurückgeben, erfordern --secret-output; lesen Sie ihr Token niemals in Chat oder Befehlsausgabe.

delete-project ist dauerhaft und kaskadiert durch die Schemas, Token, Ereignisse, Zustellungen und Live-Oberflächen des Projekts. Lösen Sie die genaue Projekt-ID auf und fordern Sie eine explizite Benutzerabsicht an, bevor Sie sie ausführen.

Verwenden Sie --json für maschinenlesbare, nicht geheime Ausgabe. Lesen Sie api.md, wenn Sie eine weitere Operation hinzufügen oder eine Fehlerantwort diagnostizieren.

Adapter-Routing

• Lesen Sie adapters.md für Node.js-, Cloudflare Worker-, Shell- und GitHub Actions-Muster.
• Lesen Sie webhooks.md, wenn Sie Stripe-ähnliche Zahlungsereignisse oder einen anderen Drittanbieter-Callback erhalten, bevor Sie Bellwire aktualisieren.
• Bevorzugen Sie das vorhandene HTTP-Client des Projekts. Fügen Sie keine SDK-Abhängigkeit für eine einzelne Anfrage hinzu.
• Behandeln Sie das Senden von Ereignissen als begrenzten Seiteneffekt: Setzen Sie ein Timeout, vermeiden Sie das Protokollieren von Nutzlasten, und entscheiden Sie explizit, ob ein Benachrichtigungsfehler den Geschäftsvorgang beeinträchtigen darf. Standardmäßig erfolgt der Sendevorgang bestmöglich nach erfolgreichem Geschäftsvorgang.
• Halten Sie Token-Werte aus generierten Diffs, Test-Snapshots, CI-Protokollen und Fehlertelemetrie fern.

Private Regeln

• Generieren Sie mindestens 128 zufällige Bits für jede Referenz und kodieren Sie sie als 22–200 URL-sichere Zeichen. Leiten Sie sie niemals von einer Bestellung, E-Mail, Aufgabe, Kunden oder einem Zeitstempel ab.
• Schreiben Sie Benachrichtigungsdetails in einen datenbankgestützten Postausgang, bevor Sie den Weckruf senden. Lassen Sie die Referenz nach spätestens 24 Stunden ablaufen.
• Ein Weckruf ist begrenzt und erfolgt bestmöglich nach dem Commit. Führen Sie keinen Rollback des echten Geschäftsvorgangs durch, weil Bellwire nicht verfügbar ist.
• MONTHLY_SIGNAL_LIMIT_REACHED ist endgültig, bis zur zurückgegebenen UTC-Zurücksetzungszeit oder einem Upgrade. Wiederholen oder versuchen Sie es nicht erneut.
• Private Detail- und Posteingangsantworten stammen vom Dienst des Benutzers und können bis zu 30 Tage auf dem Telefon zwischengespeichert werden; Bellwire Cloud erhält sie nie.

Regeln für gehostete Ereignisse

• Verwenden Sie kleingeschriebene Punktnamen wie payment.success, deployment.failed oder agent.waiting.
• Fügen Sie nur Felder ein, die für den Posteingang, die Benachrichtigung, den Deep Link oder die Diagnose benötigt werden.
• Verweisen Sie niemals auf ein sensibles Feld in einer Benachrichtigungsvorlage; die API lehnt es ab.
• Verwenden Sie Bestell-IDs, Bereitstellungs-IDs, Aufgaben-IDs oder Ausführungs-IDs für die gehostete Idempotenz. Machen Sie diese Identifikatoren nicht als private Referenzen sichtbar.
• Vermeiden Sie hochfrequente Fortschrittsereignisse. Bevorzugen Sie Abschluss-, Fehler-, Wiederherstellungs- und Entscheidungsgrenzen.
• Fragen Sie nach expliziter Benutzerzustimmung, bevor Sie priority: high anfordern.

Oberflächenregeln

• Verwenden Sie einen aussagekräftigen, stabilen Schlüssel wie sales-today, prod-api oder nightly-backup.
• Bewahren Sie die zugewiesene displayOrder bei routinemäßigen Aktualisierungen. Ändern Sie sie nur, wenn der Benutzer ausdrücklich darum bittet, eine Karte neu anzuordnen.
• Senden Sie anzeigefertige Werte. Berechnen Sie z. B. den Umsatz im Quellsystem und senden Sie ¥2.430; Bellwire leitet keine Geschäftsaggregation aus Rohdatenereignissen ab.
• Bevorzugen Sie für private oder kundenbezogene Metriken einen signierten Bellwire Direct-Endpunkt, damit die Kartennutzlast niemals in den Bellwire-Speicher gelangt.
• Wählen Sie einen der unterstützten nativen Typen. Betten Sie niemals HTML, JavaScript, Swift, CSS oder willkürliche Rendering-Anweisungen ein.
• Bevorzugen Sie eine Oberfläche für häufige Fortschritts- und Metrikaktualisierungen; vermeiden Sie eine Überflutung des Ereignis-Posteingangs.
• Verwenden Sie open_url-Aktionen nur, wenn das Ziel erwartet und für den Benutzer sicher ist.
• Projektlogos müssen öffentliche HTTPS-Bilder mit einer maximalen Größe von 5 MB sein. Bellwire verwendet sie in nativen Avataren und erweiterten Rich-Benachrichtigungen und fällt auf ein Projektmonogramm zurück, wenn das Bild fehlt oder nicht heruntergeladen werden kann.

Verifizierung und Wiederherstellung

Wenn die Einrichtung fehlschlägt, lesen Sie troubleshooting.md. Überprüfen Sie in dieser Reihenfolge:

1. API-Erreichbarkeit und Management-Token-Bereich.
2. Projekt-ID und aktive Schema-Version.
3. Verfügbarkeit von Geheimnissen in der tatsächlichen Laufzeit.
4. Nutzlasttyp und erforderliche Felder.
5. Stabiles Idempotency-Key-Verhalten.
6. Vorhandensein des Quelladapters in der bereitgestellten Version und ein echter Quellvorgang.
7. Ereignisdetails, Oberflächenzustand und Zustellungsstatus.
8. iOS-Benachrichtigungsberechtigung, Geräteregistrierung und Sandbox- vs. Produktions-APNs-Umgebung.

Rotieren, widerrufen oder ersetzen Sie niemals ein funktionierendes Token, es sei denn, der Benutzer hat es angefordert oder ein Kompromittierungsverdacht besteht.