@pushizo/node

English · Türkçe

English

Pushizo Node.js SDK — Server-side SDK for Node.js 20+ (TypeScript, ESM, built-in fetch): notifications, users, segments, journeys, campaigns, analytics and webhook signature verification. Types are generated from the Pushizo OpenAPI schema. Use it on the server only.

Status: Publishing to npm is in progress.
Durum: npm yayını hazırlanıyor.

Install from GitHub until then · O zamana kadar GitHub'dan kurulum:

npm install --allow-remote=root https://github.com/pushizo/pushizo-node/releases/download/v0.1.0/pushizo-node-0.1.0.tgz

After publication · Yayından sonra:

npm install @pushizo/node

The detailed guide below is in Turkish; code samples are language-neutral. Full documentation: docs.pushizo.com/docs/sdk/node · API reference: docs.pushizo.com/docs/api.

Türkçe

@pushizo/node

Pushizo Node.js sunucu SDK'sı. Node.js ≥ 20 (yerleşik fetch), ESM; istek ve yanıt tipleri Pushizo OpenAPI şemasından üretilen ve pakete gömülü tiplerden türetilir. Yalnızca sunucuda kullanın; API anahtarını istemci koduna gömmeyin. Ayrıntılı rehber: docs.pushizo.com/docs/sdk/node.

Başlatma

import { Pushizo } from '@pushizo/node';

const hs = new Pushizo({
  apiKey: process.env.HS_API_KEY!, // hs_live_…
  appId: process.env.HS_APP_ID, // çağrıda appId verilmezse kullanılır
  baseUrl: 'https://api.pushizo.com', // yerel: http://localhost:4000
  maxRetries: 3, // 429 her metotta; 5xx/ağ hatası GET/PUT/DELETE'te, POST/PATCH'te yalnızca Idempotency-Key varsa veya istek gönderilemediyse
  timeoutMs: 30_000,
  autoIdempotencyKey: true, // notifications.create ve users.upsert için otomatik UUID
});

Ortak davranışlar:

• Kimlik doğrulama Authorization: Bearer <apiKey> başlığıyla yapılır.
• App kapsamlı her metodun son parametresi isteğe bağlı appId'dir; verilmezse varsayılan app kullanılır.
• Hata yanıtları PushizoError (status, code, requestId, details, retryable) olarak fırlatılır.
• hs.paginate((cursor) => hs.templates.list({ cursor })) cursor sayfalı listeleri for await ile öğe öğe dolaşır.
• Analitik raporlarında format: 'csv' verilirse yanıt CSV metni (string) olarak döner.

Kaynaklar

Her public API işlemi (/sdk/v1 hariç) bir SDK metoduna karşılık gelir; eşleme tablosu src/__tests__/coverage.test.ts içinde sözleşmeye karşı test edilir.

Kaynak	Metotlar
organization	get, members, auditLogs, usage
apps	list, create, get, update
apiKeys	list, create, update, revoke, rotate
notifications	create, list, get, cancel, estimate, deliveries, history, exportEvents
users	list, upsert, search, getByAlias, getByExternalId, update, delete, getIdentity, export, addAliases, removeAlias, addSubscription
subscriptions	get, update, delete, getUserIdentity, updateByToken, setOwner
inbox	list, readAll, read, archive; ekip gelen kutusu: listCannedResponses, createCannedResponse, updateCannedResponse, deleteCannedResponse, listTeams, listAgents, getSettings, updateSettings, metrics
events	send, listDefinitions, getDefinition, updateDefinition
segments	list, create, preview, get, update, delete, usedBy, estimate
templates	list, create, get, update, delete, copyToApp, versions, render, stats
campaigns	list, create, get, update, delete, schedule, send, pause, resume, cancel, duplicate, approve, stats, deliveries, resendFailed, messages, variantStats, selectWinner
journeys	list, create, get, update, delete, saveDraft, updateNode, versions, publish, pause, resume, archive, duplicate, stats, listRuns, triggerRun, getRun, exitRun, listForUser
inAppMessages	list, create, get, update, delete, setStatus, selectWinner
preferences	listCategories, createCategory, updateCategory, deleteCategory, getUser, setUser
analytics	overview, messages, subscriptions, events, conversions, funnel, providers, engagement, retention
exports	create, list, get
imports	create (multipart CSV), list, get
channels	list, upsert, validate
suppressions	list, create, remove
webhooks	list, create, get, update, delete, rotateSecret, test, deliveries, replay, preview
dataFeeds	list, create, get, update, delete, test
contentTables	list, create (multipart CSV), get, update, delete, rows, replaceRows (multipart CSV)
warehouseExports	tables, testConnection, list, create, get, update, delete, test, run, runs
conversations	list, get, messages, reply, markRead, update, assign, updateTags, activity
smsKeywords	list, create, update, delete
whatsappTemplates	list, sync
emailDeliverability	get, update, verifyAddress, listWarmupPlans, createWarmupPlan, updateWarmupPlan, deleteWarmupPlan
zapier	me, subscribe, unsubscribe, samples
mcp	createCampaignDraft, createSegmentDraft, createTemplateDraft, createJourneyDraft, createInAppDraft, sendTest
ads	listAccounts, listAudiences, createAudience, getAudience, updateAudience, deleteAudience, syncAudience, listSyncs, createLookalike, listCampaigns, getCampaign, updateCampaign, refreshAccount, spendReport, attributionReport, ltvReport, listCapiConfigs, listCapiDeliveries, listAlertRules, createAlertRule, updateAlertRule, deleteAlertRule, listAlerts
webCampaigns	list, create, get, update, report, setStatus
forms	list, create, get, listSubmissions, submit
surveys	list, create, get, setStatus, report, listResponses, respond
landingPages	list, get, publish, unpublish

Webhook alıcıları için verifyWebhookSignature ve constructWebhookEvents dışa aktarılır.

Örnekler

// Bildirim ve kitle tahmini
await hs.notifications.estimate({ target: { included_segments: ['seg_vip'] } });
const { id } = await hs.notifications.create({
  idempotencyKey: `order-${orderId}`,
  target: { include_aliases: { external_id: [userId] } },
  contents: { tr: 'Siparişin yolda', en: 'Your order has shipped' },
});
await hs.notifications.exportEvents(id); // CSV işi; tamamlanınca download_url

// Segment ve kampanya yaşam döngüsü
const segment = await hs.segments.create({
  name: 'VIP',
  definition: { all: [{ field: 'tag:plan', op: 'eq', value: 'pro' }] },
});
await hs.segments.estimate(segment.id, { force: true });
const campaign = await hs.campaigns.create({
  name: 'Bahar indirimi',
  audience: { segments: [segment.id] },
  template_id: 'tpl_…',
});
await hs.campaigns.schedule(campaign.id, { send_at: '2026-11-01T09:00:00Z' });
await hs.campaigns.stats(campaign.id);

// Şablon render önizlemesi ve başka app'e kopyalama
await hs.templates.render('tpl_…', { channel: 'email', user: { external_id: 'u-1' } });
await hs.templates.copyToApp('tpl_…', { target_app_id: 'app_…' });

// Analitik (JSON veya CSV)
const report = await hs.analytics.messages({ from: '2026-10-01T00:00:00Z', compare: true });
const csv: string = await hs.analytics.messages({ format: 'csv' });

// İçe aktarma (multipart; Blob, Uint8Array veya metin)
await hs.imports.create({ type: 'csv_users', file: csvText, filename: 'kullanicilar.csv' });

// Kullanıcı kutusu ve token ile abonelik güncelleme
await hs.inbox.readAll('external_id', 'u-1');
await hs.subscriptions.updateByToken('email', '[e-mail]', { status: 'unsubscribed' });

// API anahtarı: düz anahtar yalnızca bu yanıtta döner, loglamayın
const created = await hs.apiKeys.create({ name: 'ci', scopes: ['notifications:write'] });

A/B testi ve tercihler

// Kampanya varyantları `variants` ile tanımlanır; `ab_test.winner` otomatik kazanan seçimini açar.
const cmp = await hs.campaigns.create({
  name: 'Bahar',
  variants: [
    { name: 'A', weight_percent: 45, content: { contents: { tr: 'Bahar indirimi' } } },
    { name: 'B', weight_percent: 45, content: { contents: { tr: '%20 indirim' } } },
    { name: 'Kontrol', weight_percent: 10, is_control: true },
  ],
  ab_test: { enabled: true, test_percentage: 30, winner: { mode: 'auto', metric: 'click_rate', evaluate_after_minutes: 120 } },
});
const stats = await hs.campaigns.variantStats(cmp.id); // varyant bazlı oranlar + anlamlılık
await hs.campaigns.selectWinner(cmp.id, { variant_id: stats.variants[0]!.variant_id }); // elle seçim

// Kategoriler ve kullanıcı tercihleri (kategoriye kapalı kullanıcıya o kategori gönderilmez)
await hs.preferences.createCategory({ key: 'marketing', name: { tr: 'Pazarlama', en: 'Marketing' } });
await hs.preferences.setUser('external_id', 'u-1', {
  preferences: [{ category: 'marketing', channel: 'email', opted_in: false }],
});
await hs.templates.stats('tpl_1');
await hs.analytics.retention({ weeks: 8 });

Journey'ler

Journey'ler taslak graf üzerinde düzenlenir, publish ile yeni sürüm olarak yayınlanır; çalışan kullanıcılar girdikleri sürümde kalır. Graf React Flow biçimindedir (nodes, edges; düğüm türleri ve ayarlar için docs/journeys.md).

const journey = await hs.journeys.create({ name: 'Sipariş sonrası' });
await hs.journeys.saveDraft(journey.id, {
  graph: {
    nodes: [
      { id: 'trg', type: 'trigger', position: { x: 0, y: 0 }, data: { trigger: { kind: 'api' } } },
      {
        id: 'push',
        type: 'send_push',
        position: { x: 0, y: 120 },
        data: { content: { contents: { tr: 'Siparişin yolda', en: 'Your order has shipped' } } },
      },
      { id: 'end', type: 'exit', position: { x: 0, y: 240 }, data: {} },
    ],
    edges: [
      { id: 'e1', source: 'trg', target: 'push', sourceHandle: 'next' },
      { id: 'e2', source: 'push', target: 'end', sourceHandle: 'next' },
    ],
  },
  settings: { re_entry: { mode: 'after_exit' } },
});
const { version, issues } = await hs.journeys.publish(journey.id); // issues: doğrulama uyarıları

// API tetikleyicisi: kullanıcı external_id, user_id veya alias ile seçilir
const { entered, run, reason } = await hs.journeys.triggerRun(journey.id, {
  external_id: 'u-1',
  context: { order_id: 'o-42' },
});
if (entered && run) await hs.journeys.getRun(journey.id, run.id);
await hs.journeys.stats(journey.id, { version }); // düğüm bazında sayaçlar ve hedef dönüşümü
for await (const r of hs.paginate((cursor) =>
  hs.journeys.listRuns(journey.id, { status: 'waiting', cursor }),
)) {
  console.log(r.id, r.current_node_id);
}

Gelen kutusu, reklam raporlama ve web büyüme

// Ekip gelen kutusu: durum, atama, etiket ve metrikler
await hs.conversations.assign('cnv_1', { team_id: 'team_1', assignee_id: null });
await hs.conversations.updateTags('cnv_1', { add: { plan: 'pro' }, remove: ['lead'] });
await hs.conversations.update('cnv_1', { status: 'resolved' });
const metrics = await hs.inbox.metrics({ from: '2026-10-01T00:00:00Z', channel: 'chat' });
await hs.inbox.createCannedResponse({ shortcut: 'iade', title: 'İade', body: 'Merhaba {{ contact.name }}, iadeniz alındı.' });

// Reklam raporlama ve bütçe uyarıları; from/to zorunlu
const spend = await hs.ads.spendReport({ from: '2026-10-01', to: '2026-10-31', group_by: 'campaign' });
const attribution = await hs.ads.attributionReport({ from: '2026-10-01', to: '2026-10-31', model: 'time_decay' });
await hs.ads.updateCampaign('ade_1', { status: 'paused' }); // platforma da yazılır
await hs.ads.createAlertRule({ name: 'Günlük tavan', kind: 'daily_spend', threshold: 500, recipients: ['[e-mail]'] });

// Web büyüme: kampanya taslak oluşur, setStatus ile yayınlanır
const popup = await hs.webCampaigns.create({
  name: 'Bülten pop-up',
  display: { layout: 'popup', blocks: [{ type: 'title', text: { tr: 'Bültenimize katılın' } }], form_id: 'frm_1' },
  trigger: { kind: 'exit_intent' },
});
await hs.webCampaigns.setStatus(popup.id, 'active');
await hs.forms.submit('frm_1', { values: { email: '[e-mail]' }, external_id: 'u-1' }); // sunucu tarafı gönderim
for await (const s of hs.paginate((cursor) => hs.forms.listSubmissions('frm_1', { status: 'confirmed', cursor }))) {
  console.log(s.id);
}
const nps = await hs.surveys.report('srv_1', { days: 30 });
await hs.landingPages.publish('lp_1');

Geliştirme

npx vitest run --project unit sdk/node   # birim + sözleşme kapsamı testleri
npx tsc --noEmit -p sdk/node
npx eslint sdk/node
npm run build -w @pushizo/node        # dist/

Support · Destek

• Guide · Rehber: docs.pushizo.com/docs/sdk/node
• API reference & OpenAPI · API referansı ve OpenAPI: docs.pushizo.com/docs/api · pushizo-openapi
• Bugs & ideas · Hata ve öneri: Issues
• Security · Güvenlik: please do not open public issues; email [e-mail] · herkese açık issue açmayın, bu adrese yazın.
• Help · Destek: [e-mail]

This repository is mirrored automatically from the Pushizo main repository on every release. Please open an issue instead of a pull request; fixes land in the main repository and ship with the next release. Bu depo her sürümde Pushizo ana deposundan otomatik yansıtılır. Pull request yerine issue açın; düzeltmeler ana depoda yapılır ve bir sonraki sürümle buraya gelir.

Released under the MIT License · MIT lisanslıdır — LICENSE.