signalbird - Node.js / TypeScript

Signalbird Telsiz istemcisi. Tek işi vardır: projenizden bir kanala mesaj yazmak.

Bildirimin kime gideceği, hangi kanaldan (push/e-posta), sessiz saatlerde ne olacağı ve aynı mesajın kaç kez uyarı üreteceği panelde, kanal ayarlarında durur. Kodunuzda bunlar yoktur ve olmamalıdır: bildirim kuralını değiştirmek için uygulamanızı yeniden yayınlamanız gerekmesin.

proje  →  penyu.io                     (anahtarın sahibi)
kanal  →  critical, info, deploy…      (bildirim kuralı burada)
olay   →  tek bir kayıt

Kurulum

npm install signalbird

Node 18+ gerekir. Paketin hiçbir bağımlılığı yoktur - Node'un yerleşik fetch'i kullanılır.

Anahtar

Panelde Telsiz → Projeler → Yeni proje ile bir proje açın. Sunucu anahtarı (sb_secret_live_…) size bir kez gösterilir; veritabanında yalnız özeti saklanır, kapattıktan sonra okunamaz, yalnız yenilenebilir.

# .env
SIGNALBIRD_DOMAIN_KEY=sb_secret_live_xxxxxxxxxxxxxxxxxxxxxxxx
SIGNALBIRD_SOURCE=api-01     # opsiyonel: hangi sunucudan geldiği

Bu anahtar gizlidir ve tarayıcıya gömülemez. Sunucu, Origin başlığı taşıyan bir istekte gizli anahtarı reddeder (SECRET_KEY_IN_BROWSER). Tarayıcı için Tarayıcı SDK'sı ve açık anahtar kullanılır.

Hızlı başlangıç

import { signalbird } from 'signalbird'

await signalbird().critical('critical', 'ödeme servisi yanıt vermiyor', {
  service: 'iyzico',
  attempt: 3,
})

await signalbird().info('info', 'ahmet@x.com yeni hesap oluşturdu')

signalbird() SIGNALBIRD_DOMAIN_KEY ortam değişkeninden kurulur ve tekildir.

Kendi istemcinizi kurmak isterseniz:

import { SignalbirdClient } from 'signalbird'

const sb = new SignalbirdClient({
  domainKey: process.env.SIGNALBIRD_DOMAIN_KEY!,
  source: 'api-01',
  timeout: 5000,
  throwOnError: false,   // üretimde kapalı kalmalı
})

Metotlar

Metot	Açıklama
log({ channel, message, level?, context?, source? })	Temel çağrı
debugLog(channel, message, context?)	debug seviyesi
info(channel, message, context?)	info seviyesi
warn(channel, message, context?)	warn seviyesi
error(channel, message, context?)	error seviyesi
critical(channel, message, context?)	critical seviyesi
batch(events)	En fazla 100 kayıt
captureUncaught(channel?)	Yakalanmamış hataları bağlar

Hepsi { ok, eventId?, code?, status? } döndürür.

Seviye kanalın varsayılanını ezer

level göndermezseniz kanalın kendi seviyesi geçerlidir. İstemci burada bir varsayılan uydurmaz.

Toplu gönderim

Kısmi başarı normaldir (kota tam ortada dolabilir), o yüzden sonuç tek bir durum değil satır satır döner:

const result = await signalbird().batch([
  { key: 'info', message: 'iş 1 bitti' },
  { key: 'info', message: 'iş 2 bitti' },
])

// { accepted: 2, total: 2, results: { 0: { ok: true, eventId: 'rev_…' }, … } }

Başarısız satırlar otomatik yeniden denenmez: aynı logu iki kez yazmak da bir maliyettir, kararı çağıran verir.

Yakalanmamış hatalar

signalbird().captureUncaught('critical')

Kancayı takar ama süreci öldürmeye devam eder: uncaughtException sonrası süreci ayakta tutmak, bozuk durumdaki bir uygulamayı çalıştırmaya devam etmek demektir; log göndermek bunu meşrulaştırmaz.

Express

import express from 'express'
import { signalbird } from 'signalbird'

const app = express()

signalbird().captureUncaught('critical')

app.use(async (err, req, res, next) => {
  await signalbird().error('api', err.message, {
    method: req.method,
    path: req.path,
  })
  res.status(500).json({ error: 'Internal Server Error' })
})

Next.js

Sunucu tarafında (route handler, server action, app/api/**) doğrudan kullanılır. İstemci bileşenlerinde kullanmayın - anahtar paketle birlikte tarayıcıya iner.

// app/api/webhook/route.ts
import { signalbird } from 'signalbird'

export async function POST(req: Request) {
  try {
    // …
  } catch (error) {
    await signalbird().error('webhook', (error as Error).message)
    throw error
  }
}

Davranış kuralları

• Sessiz hata varsayılandır. Telsiz erişilemezse çağrı ok: false döner ve uygulamanız çalışmaya devam eder. Log göndermek, ödeme akışını çökertmek için geçerli bir sebep değildir. Geliştirmede throwOnError: true.
• Tanımsız kanal düşürülmez. İlk log('odeme-hatasi', …) çağrısında kanal kendiliğinden açılır ve panelde "otomatik açıldı" işaretiyle görünür. Yeni kanal sessizdir - kuralı ekip koyar.
• Kritik seviye sessiz saatleri deler.
• Tekrar bastırma kaydı değil bildirimi susturur. Aynı mesaj kanalın dedupe süresi içinde tekrar gelirse ikinci bildirim gitmez, kayıt tutulur.

Ziyaretçi kimliği doğrulaması - identityHash

Sohbet widget'ı ve uygulama SDK'sı oturum açmış kullanıcıyı external_id ile tanıtır. Açık anahtar sayfada durduğu için Signalbird bu kimliği ancak yanında sizin sunucunuzda üretilmiş geçerli bir hash varsa güvenilir sayar (2.7.0). Hash olmadan ziyaretçi kişi kaydına bağlanmaz, cihazı o kullanıcıya push hedefi olarak bağlanmaz ve kanal ajanının araçları kimliği yalnız visitor.unverified altında görür.

import { signalbird } from 'signalbird'

const hash = signalbird().identityHash(user.id)   // new SignalbirdClient({ domainKey }).identityHash(...)

Gizli anahtarı zaten tutan Telsiz istemcisinin üzerindedir; ayrı kurulum gerekmez. Algoritma (her dilde aynı çıktı):

identity_hash = hex( HMAC-SHA256( hex(SHA-256(sb_secret_live_…)), external_id ) )

Anahtar gizli anahtarın SHA-256 özetidir (sunucu anahtarı düz saklamaz). Kullanım: Widget - Kimlik doğrulaması, Uygulama SDK'sı.

Sürüm bildirimi

SDK her istekte sürümünü bildirir: X-Signalbird-Sdk: node/<sürüm>. Yeni bir sürüm yayınlandığında API yanıtında Signalbird-Sdk-Status: outdated (ya da artık desteklenmiyorsa unsupported) döner ve SDK süreç başına bir kez uyarı yazar (console.warn). Uyarı hata değildir: isteğin sonucu değişmez.

Panelde Domainler → [domain] → Anahtarlar her anahtarın hangi SDK sürümüyle kullanıldığını gösterir; eski sürümdeki anahtarlar için panelin tepesinde bir uyarı şeridi ve bildirim çıkar. Güncellemek için:

npm i signalbird@latest

Hata kodları

Kod	Anlamı
INVALID_KEY	Anahtar yok, yanlış ya da proje pasif
SECRET_KEY_IN_BROWSER	Gizli anahtar tarayıcıdan kullanıldı
MODULE_DISABLED	Paketinizde Telsiz (logger) modülü yok
LIMIT_REACHED	Aylık kayıt limitiniz doldu
CHANNEL_DISABLED	Kanal kapalı - kayıt yazılmaz, kota da harcanmaz

Paketin diğer yüzeyleri

Bu sayfa Telsiz'i anlatır. Aynı paket üç yüzey daha taşır:

Yüzey	Giriş	Ne yapar
Gönderim	SignalbirdMessaging	e-posta, SMS, push; kişi, liste, kampanya; webhook imzası
Yönetim	SignalbirdManagement, management()	Telsiz projesi/kanalı, sohbet gelen kutusu, uygulama ve cihaz
Uygulama	signalbird/app · /react · /vue · /angular · /react-native	son kullanıcıya canlı sohbet ve push kaydı

import { signalbird, management, SignalbirdMessaging } from 'signalbird'

await signalbird().critical('critical', 'ödeme servisi öldü')              // Telsiz
await management().createModuleKey('logger', { name: 'ödeme-servisi' })           // Yönetim
await new SignalbirdMessaging({ domainKey }).sendEmail({ /* … */ })           // Gönderim

Telsiz sb_secret_live_…, diğer ikisi sb_… anahtarı ister. Yanlış aileden anahtar verirseniz istemciyi kurarken WRONG_KEY_TYPE alırsınız.