@develit-services/notification 0.5.0 → 0.6.0

package/README.md

@@ -0,0 +1,239 @@
+# Notification Service
+
+Microsluzba pro odesilani notifikaci (email, SMS, Slack, push). Postavena na Cloudflare Workers s D1 databazi.
+
+## Obsah
+
+- [Architektura](#architektura)
+- [Kanaly notifikaci](#kanaly-notifikaci)
+- [Queue processing](#queue-processing)
+- [Konektory](#konektory)
+- [RPC akce](#rpc-akce)
+- [Audit logging](#audit-logging)
+- [Databazove schema](#databazove-schema)
+- [Error Codes](#error-codes)
+
+## Architektura
+
+Sluzba se sklada z:
+
+- **Akce (Actions)** - RPC endpointy pro odesilani notifikaci
+- **Queue handler** - Asynchronni zpracovani notifikaci z fronty
+- **Konektory** - Abstrakce nad API externich sluzeb (Ecomail, Twilio, Slack)
+- **Audit log** - Zaznamenani vsech odeslanych notifikaci do D1
+
+Bindings:
+- `NOTIFICATION_D1` - Cloudflare D1 databaze
+- `NOTIFICATIONS_QUEUE` - Fronta pro asynchronni zpracovani
+- `SECRETS_STORE` - Service binding na secrets store
+- `SLACK_WEBHOOK` - Webhook URL pro Slack notifikace
+
+## Kanaly notifikaci
+
+| Kanal | Konektor | Stav |
+|-------|----------|------|
+| Email | Ecomail | Aktivni |
+| SMS | Twilio | Aktivni |
+| Slack | Slack Webhook | Aktivni |
+| Webhook | WebhookConnector | Aktivni |
+| Push | - | Neimplementovano |
+
+## Queue processing
+
+Notifikace lze odesilat synchronne (primo) nebo asynchronne (pres frontu).
+
+### Async flow (vychozi)
+
+```
+public-send-email / public-send-sms
+  │
+  ▼
+NOTIFICATIONS_QUEUE
+  │
+  ▼
+Queue handler (switch dle type)
+  ├─ email   → _sendEmail()
+  ├─ sms     → _sendSms()
+  ├─ slack   → sendSlackNotification()
+  ├─ webhook → _sendWebhook()
+  └─ push    → _sendPushNotification() (501)
+  │
+  ├─ success → message.ack()
+  └─ error   → message.retry() (exponential backoff, base 60s)
+```
+
+### Sync flow
+
+`public-send-email-sync` vola `_sendEmail()` primo bez fronty.
+
+### Queue message
+
+```typescript
+{
+  type: 'email' | 'sms' | 'pushNotification' | 'slack' | 'webhook'
+  metadata: {
+    userAgent?: string
+    ip?: string
+    initiator: { service: string, userId?: string }
+  }
+  payload: {
+    email?: IEmail
+    sms?: ISms
+    pushNotification?: IPushNotification
+    slack?: ISlack
+    webhook?: IWebhook
+  }
+}
+```
+
+## Konektory
+
+### Ecomail (email)
+
+Provider pro transakcni emaily. Podporuje:
+- Plain text a HTML emaily (`/transactional/send-message`)
+- Template emaily s merge vars (`/transactional/send-template`)
+- Prilohy (base64, max 10 priloh, celkem 25MB)
+- CC, BCC, Reply-To
+
+Omezeni: Ecomail odmita emaily s `localhost` v template variables - connector automaticky nahradi `localhost` za `origin`.
+
+### Twilio (SMS)
+
+Provider pro SMS pres Twilio Messaging Service.
+
+### Slack (webhook)
+
+Odesilani notifikaci pres Slack Incoming Webhook. Timeout 3s.
+
+### Webhook (HTTP callback)
+
+Odesilani podepsanych HTTP POST callbacku na URL zadanou callerem. Timeout 10s.
+
+Kazdy webhook je automaticky podepsan RSA-PKCS1-v1_5 (SHA-256) podpisem. Privatni klic se nacita ze Secrets Store (`NOTIFICATION_SERVICE_WEBHOOK_SIGNING_KEY`). Podpis se odesila v hlavicce `X-Webhook-Signature` (base64).
+
+#### Generovani klicu
+
+```bash
+# Private key (base64, jedna radka) → ulozit do Secrets Store jako NOTIFICATION_SERVICE_WEBHOOK_SIGNING_KEY
+openssl genrsa 4096 2>/dev/null | base64 -w0
+
+# Public key z private key → poskytnout prijemcum webhooku v API docs
+echo "<PRIVATE_KEY_BASE64>" | base64 -d | openssl rsa -pubout 2>/dev/null | base64 -w0
+```
+
+> Na macOS pouzit `base64` bez `-w0` (macOS verze nevypisuje newlines).
+
+#### Overeni podpisu na strane prijemce
+
+Podpis je `RSA-PKCS1-v1_5` se `SHA-256`, odeslany v hlavicce `X-Webhook-Signature` jako base64 string. Overeni:
+
+```bash
+# Ulozit raw body requestu do souboru
+echo -n '{"type":"payment.created","data":{...}}' > body.json
+
+# Dekodovat podpis z hlavicky
+echo -n "<hodnota X-Webhook-Signature>" | base64 -d > signature.bin
+
+# Overit
+openssl dgst -sha256 -verify webhook_public.pem -signature signature.bin body.json
+# Vystup: "Verified OK" nebo "Verification Failure"
+```
+
+Nebo programove (Node.js):
+
+```javascript
+const crypto = require('crypto')
+
+function verifyWebhook(rawBody, signatureBase64, publicKeyBase64) {
+  const publicKey = Buffer.from(publicKeyBase64, 'base64').toString('utf-8')
+  const verifier = crypto.createVerify('RSA-SHA256')
+  verifier.update(rawBody)
+  return verifier.verify(publicKey, signatureBase64, 'base64')
+}
+```
+
+## RPC akce
+
+Notification service je **RPC worker** - vsechny akce dostupne pres Cloudflare Worker binding.
+
+### Verejne akce
+
+| Akce | Popis |
+|------|-------|
+| `public-send-email` | Zaradi email do fronty (async) |
+| `public-send-email-sync` | Odesle email primo (sync) |
+| `public-send-sms` | Zaradi SMS do fronty (async) |
+| `send-slack-notification` | Odesle Slack notifikaci (sync) |
+| `send-webhook` | Zaradi webhook do fronty (async) |
+
+### Interni akce
+
+| Akce | Popis |
+|------|-------|
+| `private-send-email` | Odesle email pres konektor + audit log |
+| `private-send-sms` | Odesle SMS pres konektor + audit log |
+| `private-send-webhook` | Odesle webhook pres konektor + audit log |
+| `send-push-notification` | Neimplementovano (501) |
+
+### Vstupy
+
+Vsechny akce vyzaduji `metadata` objekt:
+
+```typescript
+metadata: {
+  userAgent?: string
+  ip?: string        // IPv4 nebo IPv6
+  initiator: {
+    service: string  // nazev volajici sluzby
+    userId?: string
+  }
+}
+```
+
+**Email** podporuje: `to`, `cc`, `bcc`, `replyTo`, `from`, `subject`, `text`, `html`, `templateId`, `templateVariables`, `attachments`.
+
+**SMS** podporuje: `message`, `to`.
+
+**Slack** podporuje: `message`.
+
+**Webhook** podporuje: `url`, `payload` (libovolny JSON objekt), `headers` (volitelne custom HTTP headers).
+
+## Audit logging
+
+Kazdy uspesne odeslany email a SMS se zaznamenava do audit logu.
+
+Zaznamenavane udaje: event type, IP adresa, user agent, popis (JSON vstupu), initiator service, initiator user ID.
+
+## Databazove schema
+
+### audit_log
+
+| Sloupec | Typ | Popis |
+|---------|-----|-------|
+| `id` | text | UUID |
+| `createdAt` | timestamp | Cas vytvoreni |
+| `event` | text | `EMAIL` \| `SMS` \| `PUSH_NOTIFICATION` \| `SLACK` |
+| `ip` | text | IP adresa (nullable) |
+| `userAgent` | text | User agent (nullable) |
+| `description` | text | JSON dump vstupu (nullable) |
+| `initiatorService` | text | Nazev volajici sluzby |
+| `initiatorUserId` | text | ID uzivatele (nullable) |
+
+## Error Codes
+
+Format: `{CATEGORY}-N-{NUMBER}`
+
+| Code | Status | Popis |
+|------|--------|-------|
+| `CONN-N-01` | 502 | Ecomail: failed to send email |
+| `CONN-N-02` | 502 | Ecomail: failed to send template email |
+| `CONN-N-03` | 502 | Twilio: failed to send SMS |
+| `CONN-N-04` | 502 | Slack: failed to send notification |
+| `CONN-N-05` | 504 | Slack: request timed out |
+| `CONN-N-06` | 502 | Webhook: delivery failed |
+| `CONN-N-07` | 504 | Webhook: request timed out |
+| `VALID-N-01` | 404 | Unsupported email provider |
+| `VALID-N-02` | 404 | Unsupported SMS provider |
+| `SYS-N-01` | 501 | Push notifications not implemented |
+| `SYS-N-02` | 500 | Webhook signing key not configured |

package/dist/database/schema.cjs

@@ -1,9 +1,7 @@
 'use strict';
 
-const database_schema = require('../shared/notification.4b3eUEIG.cjs');
-require('@develit-io/backend-sdk');
-require('drizzle-orm/sqlite-core');
+const schema = {
+	__proto__: null
+};
 
-
-
-exports.auditLog = database_schema.auditLog;
+exports.schema = schema;

package/dist/database/schema.d.cts

@@ -1,2 +1,6 @@
-export { a as auditLog } from '../shared/notification.BWLPh6Gb.cjs';
-import 'drizzle-orm/sqlite-core';
+declare namespace schema {
+  export {
+  };
+}
+
+export { schema as s };

package/dist/database/schema.d.mts

@@ -1,2 +1,6 @@
-export { a as auditLog } from '../shared/notification.BWLPh6Gb.mjs';
-import 'drizzle-orm/sqlite-core';
+declare namespace schema {
+  export {
+  };
+}
+
+export { schema as s };

package/dist/database/schema.d.ts

@@ -1,2 +1,6 @@
-export { a as auditLog } from '../shared/notification.BWLPh6Gb.js';
-import 'drizzle-orm/sqlite-core';
+declare namespace schema {
+  export {
+  };
+}
+
+export { schema as s };

package/dist/database/schema.mjs

@@ -1,3 +1,5 @@
-export { a as auditLog } from '../shared/notification.C0X8Orrh.mjs';
-import '@develit-io/backend-sdk';
-import 'drizzle-orm/sqlite-core';
+const schema = {
+	__proto__: null
+};
+
+export { schema as s };