wegoft/bellwire

bellwire은(는) 무엇을 하나요?

리포지토리 상태와 이벤트를 사용자의 Bellwire 카드, 인박스, iPhone에 연결합니다. 새 프로젝트는 기본적으로 비공개(Private)입니다. Bellwire는 불투명한 웨이크(wake)만 중계하며, 폰은 사용자의 HTTPS 서비스에서 직접 콘텐츠를 가져옵니다. 호스팅 저장소는 옵트인(opt-in) 방식이며 앱에서 승인이 필요합니다.

워크플로우

1. 리포지토리, 비밀 관리 규칙, 테스트, 이벤트를 트리거해야 하는 정확한 성공 또는 실패 상태를 검사합니다.

2. 코드로 답할 수 없는 제품 결정(알림 빈도, 민감한 값, 높은 우선순위 인터럽션 정당성 여부)만 명확히 합니다.

3. BELLWIRE_AGENT_TOKEN이 추적 파일 외부에서 사용 가능한지 확인합니다. 없으면 iOS 앱에 표시된 여섯 자리 코드를 사용자에게 요청하고 다음을 실행합니다:

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

   CLI는 파일을 모드 0600으로 생성하며 토큰을 절대 출력하지 않습니다. 토큰을 표시하지 않고 사용자가 승인한 비밀 저장소로 가져온 후 임시 파일을 제거합니다. 절대 커밋하지 마십시오.

4. list-projects를 실행한 후 Bellwire 프로젝트를 생성하거나 재사용합니다. 다른 프로젝트를 생성하기 전에 기존 구성을 검색합니다. 전달 모드를 변경하기 위해 두 번째 프로젝트를 생성하지 마십시오.

5. 사용자가 Bellwire Cloud가 이벤트, 인박스, 서피스 콘텐츠를 저장하기를 명시적으로 원하지 않는 한 프로젝트를 비공개(Private)로 유지합니다:

   • 비공개: 서명된 Direct v2 알림, 인박스, 서피스 엔드포인트를 구현합니다. 디바이스 키, 일회용 논스, 불투명 참조 아웃박스, 24시간 참조 만료를 사용자의 실제 데이터베이스에 유지합니다. direct-connections.md를 읽으십시오.
   • 호스팅: request-mode-change로 변경을 요청합니다. 로그인한 사용자가 Bellwire에서 승인할 때까지 중단합니다. 그런 다음 호스팅 스키마, 서피스, 수집 토큰을 생성합니다.

6. 비공개 런타임 전달의 경우 웨이크 전용 토큰을 생성하여 소스 앱의 실제 비밀 관리자에 저장하고, 소스 트랜잭션과 아웃박스 레코드 커밋 후 최선 노력(best-effort)으로 private-wakes를 호출합니다. Bellwire는 제목, 본문, 데이터, 로고 URL, 프로젝트 이름, 서비스 호스트 이름을 절대 수신해서는 안 됩니다.

7. 표시 기본 요소를 선택합니다:

   • 서피스(Surface): 현재 상태를 제자리에서 업데이트합니다. surfaces.md를 읽으십시오.
   • 인박스 이벤트(Inbox event): 지속적인 기록, 완료, 실패, 복구 또는 결정 경계입니다. 비공개 모드에서는 사용자의 서비스에 유지됩니다. 호스팅 모드에서는 event-spec.md를 사용합니다.

8. 안정적인 서피스 키와 불투명하고 무작위적인 참조를 사용합니다. 동일한 웨이크 또는 호스팅 쓰기의 재시도에는 안정적인 멱등성 키를 재사용합니다.

9. 가장 작은 안정적인 트리거 지점을 수정합니다. 기본 비즈니스 연산이 커밋된 후에만 전송합니다.

   • 애플리케이션이 비즈니스 연산을 소유하는 경우 직접 사후 커밋 Bellwire 호출을 선호합니다.
   • 결제, 커머스, 배포 또는 자동화 제공자가 진실 공급원(source of truth)인 경우 webhooks.md를 읽고 제공자별 웹훅 어댑터를 추가합니다.

10. 서명, 타임스탬프, 알 수 없는 키, 변조된 대상, 원자적 논스 재사용에 대한 단위 테스트를 실행한 후 conformance-direct.mjs를 실행합니다. 데이터베이스가 논스를 원자적으로 소비할 수 없으면 중단하고 안전 차단기를 설명합니다.

11. 리포지토리의 기존 테스트와 집중 트리거 테스트를 실행합니다. Bellwire를 통과시키기 위해 비즈니스 테스트를 약화시키지 마십시오.

12. 소스 측 어댑터와 그 비밀을 리포지토리의 실제 진실 공급원을 통해 유지 및 배포합니다.

13. 실제 소스 연산 하나를 완료하고 아웃박스, 웨이크 수락, 전달, 서명된 폰 가져오기(fetch), 표시된 결과를 production-verification.md를 사용하여 확인합니다. 수동 웨이크는 프로덕션 검증이 아닙니다.

통합 상태

진행 상황 및 최종 보고서에서 다음 정확한 경계를 사용하십시오:

• 구성됨(Configured): Bellwire 프로젝트, 스키마, 토큰, 서피스 또는 테스트 이벤트가 존재합니다. 이는 프로덕션 통합이 아닙니다.
• 통합됨, 프로덕션 검증 대기 중(Integrated, awaiting production verification): 소스 측 어댑터 코드, 런타임 비밀, 집중 테스트 및 배포가 존재하지만 실제 소스 연산이 경로를 완료하지 않았습니다.
• 프로덕션 검증됨(Production verified): 실제 비즈니스 연산이 예상된 이벤트 또는 서피스를 생성했으며, 전달이 확인되었고, 주장된 디바이스 프레젠테이션이 사용자에 의해 확인되었습니다.

send-test, 수동으로 업서트(upsert)된 서피스 또는 비밀 생성을 실제 프로덕션 통합으로 설명하지 마십시오.

명령어

API 작업에는 scripts/bellwire.mjs를 사용합니다. 기본적으로 공식 호스팅 API를 사용하며 자체 호스팅 설치의 경우 BELLWIRE_API_URL을 허용합니다.

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>

검증, 폐기, 삭제 및 암호화 명령어는 node <skill-dir>/scripts/bellwire.mjs --help를 실행하십시오. 비밀을 반환하는 명령어는 --secret-output가 필요합니다. 토큰을 채팅 또는 명령어 출력으로 읽지 마십시오.

delete-project는 영구적이며 프로젝트의 스키마, 토큰, 이벤트, 전달 및 라이브 서피스에 연쇄적으로 적용됩니다. 정확한 프로젝트 ID를 확인하고 실행하기 전에 명시적인 사용자 의도를 요구하십시오.

기계가 읽을 수 있는 비밀 아닌 출력에는 --json을 사용하십시오. 다른 작업을 추가하거나 오류 응답을 진단할 때는 api.md를 읽으십시오.

어댑터 라우팅

• Node.js, Cloudflare Worker, Shell 및 GitHub Actions 패턴은 adapters.md를 읽으십시오.
• Stripe 유사 결제 이벤트 또는 Bellwire 업데이트 전에 타사 콜백을 수신할 때는 webhooks.md를 읽고 제공자별 웹훅 어댑터를 추가하십시오.
• 프로젝트의 기존 HTTP 클라이언트를 선호하십시오. 단일 요청을 위해 SDK 종속성을 추가하지 마십시오.
• 이벤트 전송을 제한된 부작용(bounded side effect)으로 취급하십시오: 타임아웃을 설정하고 페이로드 로깅을 피하며 알림 실패가 비즈니스 연산에 영향을 미칠 수 있는지 명시적으로 결정하십시오. 비즈니스 연산이 성공한 후 기본값은 최선 노력(best-effort)입니다.
• 생성된 diff, 테스트 스냅샷, CI 로그 및 오류 텔레메트리에서 토큰 값을 유지하지 마십시오.

비공개 규칙

• 각 참조에 대해 최소 128비트의 무작위 비트를 생성하고 22–200자의 URL 안전 문자로 인코딩하십시오. 주문, 이메일, 작업, 고객 또는 타임스탬프에서 파생시키지 마십시오.
• 웨이크를 보내기 전에 데이터베이스 기반 아웃박스에 알림 세부 정보를 작성하십시오. 최대 24시간 후에 참조를 만료하십시오.
• 웨이크 호출은 제한되고(bounded) 커밋 후 최선 노력(best-effort)입니다. Bellwire를 사용할 수 없기 때문에 실제 비즈니스 연산을 롤백하지 마십시오.
• MONTHLY_SIGNAL_LIMIT_REACHED는 반환된 UTC 재설정 시간 또는 업그레이드까지 종료 상태입니다. 이를 반복하거나 재시도하지 마십시오.
• 비공개 세부 정보 및 인박스 응답은 사용자의 서비스에서 오며 폰에 30일 동안 캐시될 수 있습니다. Bellwire Cloud는 이를 절대 수신하지 않습니다.

호스팅 이벤트 규칙

• payment.success, deployment.failed 또는 agent.waiting과 같은 소문자 점으로 구분된 이름을 사용하십시오.
• 인박스, 알림, 딥 링크 또는 진단에 필요한 필드만 포함하십시오.
• 알림 템플릿에서 민감한 필드를 참조하지 마십시오. API가 이를 거부합니다.
• 호스팅 멱등성을 위해 주문 ID, 배포 ID, 작업 ID 또는 실행 ID를 사용하십시오. 이러한 식별자를 비공개 참조로 노출하지 마십시오.
• 고빈도 진행 이벤트를 피하십시오. 완료, 실패, 복구 및 결정 필요 경계를 선호하십시오.
• priority: high를 요청하기 전에 명시적인 사용자 승인을 요청하십시오.

서피스 규칙

• sales-today, prod-api 또는 nightly-backup과 같은 의미 있는 안정적인 키를 재사용하십시오.
• 일상적인 업데이트 중에 할당된 displayOrder를 유지하십시오. 사용자가 카드 재정렬을 명시적으로 요청할 때만 변경하십시오.
• 표시 준비가 된 값을 보내십시오. 예를 들어, 소스 시스템에서 수익을 계산하고 ¥2,430을 보내십시오. Bellwire는 원시 이벤트에서 비즈니스 집계를 추론하지 않습니다.
• 비공개 또는 고객 파생 메트릭의 경우 서명된 Bellwire Direct 엔드포인트를 선호하여 카드 페이로드가 Bellwire 저장소에 절대 들어가지 않도록 하십시오.
• 지원되는 기본 유형 중 하나를 선택하십시오. HTML, JavaScript, Swift, CSS 또는 임의 렌더링 명령을 포함하지 마십시오.
• 빈번한 진행 상황 및 메트릭 업데이트에는 서피스를 선호하고 이벤트 인박스를 넘치지 않도록 하십시오.
• 대상이 예상되고 사용자에게 안전한 경우에만 open_url 작업을 사용하십시오.
• 프로젝트 로고는 5MB 이하의 공개 HTTPS 이미지여야 합니다. Bellwire는 이를 네이티브 아바타 및 확장된 리치 알림에 사용하며, 이미지가 없거나 다운로드할 수 없으면 프로젝트 모노그램(monogram)으로 대체합니다.

검증 및 복구

설정이 실패하면 troubleshooting.md를 읽으십시오. 다음 순서로 확인하십시오:

1. API 연결 가능성 및 관리 토큰 범위.
2. 프로젝트 ID 및 활성 스키마 버전.
3. 실제 런타임에서의 비밀 가용성.
4. 페이로드 유형 및 필수 필드.
5. 안정적인 Idempotency-Key 동작.
6. 배포된 버전에 소스 어댑터 존재 및 실제 소스 연산.
7. 이벤트 세부 정보, 서피스 상태 및 전달 상태.
8. iOS 알림 권한, 디바이스 등록 및 샌드박스 대 프로덕션 APNs 환경.

사용자가 요청하거나 손상이 의심되지 않는 한 작동 중인 토큰을 순환, 폐기 또는 교체하지 마십시오.