@yaghmori/notification-service 0.1.1

package/dist/nest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest.d.ts","sourceRoot":"","sources":["../src/nest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAGpE,MAAM,MAAM,4BAA4B,GAAG,eAAe,GAAG;IAC3D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,qBAAqB,CAOvB"}

package/dist/nest.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notificationTcpClient = notificationTcpClient;
+const microservices_1 = require("@nestjs/microservices");
+const config_1 = require("./config");
+const generated_1 = require("./generated");
+function notificationTcpClient(options = {}) {
+    const { host, port } = (0, config_1.resolveTcpEndpoint)(options);
+    return {
+        name: options.name ?? generated_1.INJECTION_TOKEN,
+        transport: microservices_1.Transport.TCP,
+        options: { host, port },
+    };
+}
+//# sourceMappingURL=nest.js.map

package/dist/nest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest.js","sourceRoot":"","sources":["../src/nest.ts"],"names":[],"mappings":";;AASA,sDASC;AAjBD,yDAAkD;AAClD,qCAAoE;AACpE,2CAA8C;AAM9C,SAAgB,qBAAqB,CACnC,UAAwC,EAAE;IAE1C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAA,2BAAkB,EAAC,OAAO,CAAC,CAAC;IACnD,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,2BAAe;QACrC,SAAS,EAAE,yBAAS,CAAC,GAAG;QACxB,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+/** Payload for Kafka `notification.send.requested` / TCP create. */
+export declare const sendNotificationRequestSchema: z.ZodObject<{
+    userId: z.ZodString;
+    eventKey: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    channels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    emailTemplate: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    actionUrl: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    eventKey: string;
+    title?: string | undefined;
+    body?: string | undefined;
+    channels?: string[] | undefined;
+    emailTemplate?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    actionUrl?: string | undefined;
+    tenantId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    userId: string;
+    eventKey: string;
+    title?: string | undefined;
+    body?: string | undefined;
+    channels?: string[] | undefined;
+    emailTemplate?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    actionUrl?: string | undefined;
+    tenantId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export type SendNotificationRequest = z.infer<typeof sendNotificationRequestSchema>;
+export declare const listNotificationsRequestSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    unreadOnly: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    userId?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    unreadOnly?: boolean | undefined;
+}, {
+    userId?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    unreadOnly?: boolean | undefined;
+}>;
+export type ListNotificationsRequest = z.infer<typeof listNotificationsRequestSchema>;
+export declare const getNotificationsRequestSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    unreadOnly: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    userId?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    unreadOnly?: boolean | undefined;
+}, {
+    userId?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    unreadOnly?: boolean | undefined;
+}>;
+export type GetNotificationsRequest = ListNotificationsRequest;
+export declare const markAsReadRequestSchema: z.ZodObject<{
+    id: z.ZodString;
+    userId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    userId?: string | undefined;
+}, {
+    id: string;
+    userId?: string | undefined;
+}>;
+export type MarkAsReadRequest = z.infer<typeof markAsReadRequestSchema>;
+export declare const createNotificationRequestSchema: z.ZodObject<{
+    userId: z.ZodString;
+    eventKey: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    channels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    emailTemplate: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    actionUrl: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    eventKey: string;
+    title?: string | undefined;
+    body?: string | undefined;
+    channels?: string[] | undefined;
+    emailTemplate?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    actionUrl?: string | undefined;
+    tenantId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    userId: string;
+    eventKey: string;
+    title?: string | undefined;
+    body?: string | undefined;
+    channels?: string[] | undefined;
+    emailTemplate?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    actionUrl?: string | undefined;
+    tenantId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export type CreateNotificationRequest = SendNotificationRequest;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,oEAAoE;AACpE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;EAKzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;EAAiC,CAAC;AAC5E,MAAM,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;AAE/D,eAAO,MAAM,uBAAuB;;;;;;;;;EAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAgC,CAAC;AAC7E,MAAM,MAAM,yBAAyB,GAAG,uBAAuB,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNotificationRequestSchema = exports.markAsReadRequestSchema = exports.getNotificationsRequestSchema = exports.listNotificationsRequestSchema = exports.sendNotificationRequestSchema = void 0;
+const zod_1 = require("zod");
+const nonEmptyStringSchema = zod_1.z.string().min(1);
+const dataObjectSchema = zod_1.z.record(zod_1.z.string(), zod_1.z.unknown());
+/** Payload for Kafka `notification.send.requested` / TCP create. */
+exports.sendNotificationRequestSchema = zod_1.z.object({
+    userId: nonEmptyStringSchema,
+    eventKey: nonEmptyStringSchema,
+    title: zod_1.z.string().optional(),
+    body: zod_1.z.string().optional(),
+    channels: zod_1.z.array(zod_1.z.string()).optional(),
+    emailTemplate: zod_1.z.string().optional(),
+    data: dataObjectSchema.optional(),
+    actionUrl: zod_1.z.string().optional(),
+    tenantId: zod_1.z.string().optional(),
+    metadata: dataObjectSchema.optional(),
+});
+exports.listNotificationsRequestSchema = zod_1.z.object({
+    userId: nonEmptyStringSchema.optional(),
+    limit: zod_1.z.number().int().min(1).max(100).optional(),
+    offset: zod_1.z.number().int().min(0).optional(),
+    unreadOnly: zod_1.z.boolean().optional(),
+});
+exports.getNotificationsRequestSchema = exports.listNotificationsRequestSchema;
+exports.markAsReadRequestSchema = zod_1.z.object({
+    id: nonEmptyStringSchema,
+    userId: nonEmptyStringSchema.optional(),
+});
+exports.createNotificationRequestSchema = exports.sendNotificationRequestSchema;
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,MAAM,oBAAoB,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC/C,MAAM,gBAAgB,GAAG,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAE3D,oEAAoE;AACvD,QAAA,6BAA6B,GAAG,OAAC,CAAC,MAAM,CAAC;IACpD,MAAM,EAAE,oBAAoB;IAC5B,QAAQ,EAAE,oBAAoB;IAC9B,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,QAAQ,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxC,aAAa,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,IAAI,EAAE,gBAAgB,CAAC,QAAQ,EAAE;IACjC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,QAAQ,EAAE,gBAAgB,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAGU,QAAA,8BAA8B,GAAG,OAAC,CAAC,MAAM,CAAC;IACrD,MAAM,EAAE,oBAAoB,CAAC,QAAQ,EAAE;IACvC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAClD,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1C,UAAU,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAGU,QAAA,6BAA6B,GAAG,sCAA8B,CAAC;AAG/D,QAAA,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9C,EAAE,EAAE,oBAAoB;IACxB,MAAM,EAAE,oBAAoB,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAGU,QAAA,+BAA+B,GAAG,qCAA6B,CAAC"}

package/docs/BEST_PRACTICES.md

@@ -0,0 +1,8 @@
+# Best practices — notification-service client
+
+- **HTTP** for inbox list / mark-read / health / SSE from apps with `x-api-key`.
+- **TCP** for internal Nest↔Nest or .NET↔Nest (`NotificationServiceTcpClient`).
+- **Kafka** for async delivery (`NotificationService.Topics.SendRequested` → sent/failed).
+- Configure with `NOTIFICATION_SERVICE_*` env or `NotificationServiceOptions` — any host/port.
+- Keep TCP private; do not expose `TCP_PORT` publicly.
+- Prefer Kafka for fan-out delivery; use TCP/HTTP for synchronous inbox ops.

package/docs/NUGET_TRUSTED_PUBLISHING.md

@@ -0,0 +1,20 @@
+# Publish .NET SDK to nuget.org (Trusted Publishing)
+
+No long-lived API key required.
+
+→ [Trusted Publishing on nuget.org](https://learn.microsoft.com/en-us/nuget/nuget-org/trusted-publishing)
+
+## Quick setup
+
+1. nuget.org → **Trusted Publishing** → policy:
+   - Repository owner: `yaghmori`
+   - Repository: `notification-service`
+   - Workflow: `cd-main.yml` (filename only)
+2. GitHub → Settings → Secrets and variables → Actions → **Variables** → `NUGET_USER` = nuget.org **username** (not email, not API key).
+3. CD uses `permissions.id-token: write` + `NuGet/login@v1` → temp key → `dotnet nuget push`.
+
+Private repos: one successful login within 7 days permanently activates the policy.
+
+After it works, revoke any old nuget.org API keys / `NUGET_TOKEN`.
+
+Package id: `Yaghmori.NotificationService`.

package/docs/PROTOCOL_GUIDE.md

@@ -0,0 +1,208 @@
+# Multi-protocol client guide (notification-service)
+
+Integration guide for calling **notification-service** from **Node.js** and **.NET** over **HTTP**, **NestJS TCP**, and **Kafka**. Scope is notification inbox + multi-channel delivery.
+
+| Artifact | Location |
+|----------|----------|
+| Truth file | `packages/client/contracts.json` |
+| Node SDK | `@yaghmori/notification-service` (`packages/client`) |
+| .NET SDK | `Yaghmori.NotificationService` (`sdk/dotnet/Yaghmori.NotificationService`) |
+| Docker | `ghcr.io/yaghmori/notification-service` |
+
+```bash
+cd packages/client && pnpm run codegen
+```
+
+Emits TS (`src/generated.ts`) and C# (`NotificationService.g.cs`).
+
+---
+
+## 1. Protocol selection
+
+| Protocol | Sync? | Auth on wire | Typical callers | Network |
+|----------|-------|--------------|-----------------|---------|
+| **HTTP** | Yes | `x-api-key` / Bearer JWT | Apps, gateways, inbox UI | Public or private; authenticate unless `AUTH_DISABLED` |
+| **NestJS TCP** | Request/response | None (trust network) | Nest / .NET mesh | Private VPC / mesh only |
+| **Kafka** | Async | Cluster SASL/SSL | Fan-out delivery, retries, audit | Private Kafka; idempotent producers |
+
+1. External clients → **HTTP + API key** (list / mark-read / health; SSE for live inbox).
+2. Internal Nest / .NET → **TCP** for create / get / mark-read / archive.
+3. “Deliver this notification eventually” → **Kafka** `notification.send.requested` (+ consume `sent` / `failed`).
+
+Do **not** expose Nest TCP publicly. Use `x-api-key`, not `Authorization: Bearer <api-key>`.
+
+---
+
+## 2. Address resolution
+
+Package defaults (`ports.tcp = 4004`, `ports.http = 3000`) are **local compose suggestions**.
+
+**HTTP base URL:** options `baseUrl` → `NOTIFICATION_SERVICE_URL` → `http://{HOST}:{HTTP_PORT|3000}`
+
+**TCP:** options → `NOTIFICATION_SERVICE_HOST` + `NOTIFICATION_SERVICE_TCP_PORT` → `127.0.0.1:4004`
+
+**Kafka:** options → `KAFKA_BROKERS` / `KAFKA_BOOTSTRAP_SERVERS` → `localhost:9092`
+
+| Role | Variable |
+|------|----------|
+| Service HTTP listen | `PORT` |
+| Service TCP listen | `TCP_PORT` |
+| Client HTTP | `NOTIFICATION_SERVICE_URL` or host + `NOTIFICATION_SERVICE_HTTP_PORT` |
+| Client TCP | `NOTIFICATION_SERVICE_HOST` + `NOTIFICATION_SERVICE_TCP_PORT` |
+| Client auth | `NOTIFICATION_SERVICE_API_KEY` / `NOTIFICATION_SERVICE_BEARER` |
+
+```bash
+docker run --rm -p 8080:8080 -p 5004:5004 \
+  -e PORT=8080 -e TCP_PORT=5004 \
+  -e AUTH_API_KEYS=dev-key-1 \
+  ghcr.io/yaghmori/notification-service:latest
+
+export NOTIFICATION_SERVICE_URL=http://127.0.0.1:8080
+export NOTIFICATION_SERVICE_HOST=127.0.0.1
+export NOTIFICATION_SERVICE_TCP_PORT=5004
+export NOTIFICATION_SERVICE_API_KEY=dev-key-1
+```
+
+---
+
+## 3. Authentication (HTTP)
+
+| Mode | Config |
+|------|--------|
+| API keys | Admin keys or `AUTH_API_KEYS=k1,k2` → `x-api-key` / `Authorization: ApiKey …` |
+| JWT | `JWT_SECRET` → `Authorization: Bearer <jwt>` |
+| Disabled | `AUTH_DISABLED=true` — trusted mesh only |
+| Public | `@Public()` e.g. `GET /health` |
+
+TCP/Kafka use network trust + broker SASL, not `x-api-key`.
+
+---
+
+## 4. HTTP
+
+| Constant | Path | Purpose |
+|----------|------|---------|
+| `LIST` | `GET /notifications` | Inbox list (query: userId, limit, offset, unreadOnly) |
+| `STREAM` | `GET /notifications/stream` | SSE live feed |
+| `MARK_READ` | `POST /notifications/{id}/read` | Mark one read |
+| `MARK_READ_ALL` | `POST /notifications/read-all` | Mark all read |
+| `ARCHIVE` / `ARCHIVE_ALL` | archive paths | Soft-remove from inbox |
+| `DELETE` | `DELETE /notifications/{id}` | Delete |
+| `HEALTH` | `GET /health` | Liveness |
+
+Node SDK exposes `list`, `markRead`, `health`. .NET: `ListAsync`, `MarkReadAsync`, `HealthAsync`.
+
+Timeouts: 10–30s for inbox APIs; health &lt; 5s. Retry 408/429/5xx only.
+
+---
+
+## 5. NestJS TCP
+
+Framing: `<utf8-byte-length>#<json>`
+
+Request: `{ "pattern": "notification.create_notification", "data": { … }, "id": "<uuid>" }`  
+Response: `{ "err": null, "response": { … }, "id": "<uuid>" }`
+
+| Constant | Pattern |
+|----------|---------|
+| `GET_NOTIFICATIONS` | `notification.get_notifications` |
+| `GET_NOTIFICATION_BY_ID` | `notification.get_notification_by_id` |
+| `CREATE_NOTIFICATION` | `notification.create_notification` |
+| `MARK_AS_READ` | `notification.mark_as_read` |
+| `MARK_ALL_AS_READ` | `notification.mark_all_as_read` |
+| `ARCHIVE_NOTIFICATION` | `notification.archive_notification` |
+| `DELETE_NOTIFICATION` | `notification.delete_notification` |
+| `HEALTH_CHECK` | `health.check` |
+
+.NET helpers: `CreateAsync` / `GetNotificationsAsync` on `NotificationServiceTcpClient`. Prefer private networks; set connect + read timeouts.
+
+---
+
+## 6. Kafka
+
+| Role | Topic constant | Topic | Event type |
+|------|----------------|-------|------------|
+| Command | `SEND_REQUESTED` | `notification.send.requested` | `evt.notification.message.send.v1` |
+| Lifecycle | `SENT` | `notification.sent` | `evt.notification.message.sent.v1` |
+| Lifecycle | `FAILED` | `notification.failed` | `evt.notification.message.failed.v1` |
+
+**Send payload** (camelCase JSON):
+
+```json
+{
+  "userId": "user-1",
+  "eventKey": "order.shipped",
+  "title": "Order shipped",
+  "body": "Your order is on the way.",
+  "channels": ["in-app", "email"],
+  "emailTemplate": "optional-template",
+  "data": { "orderId": "1" },
+  "actionUrl": "https://app.example.com/orders/1",
+  "tenantId": "optional",
+  "metadata": {}
+}
+```
+
+Producer defaults: `acks=all`, idempotence, retries ≥ 3, headers `content-type` + `x-event-type`.  
+Consumer: manual commit after side effects; dedicated `group.id`.
+
+Kafka env: `KAFKA_BROKERS`, `KAFKA_CLIENT_ID`, `KAFKA_SSL`, `KAFKA_SASL_*` (aliases `KAFKA_USERNAME` / `KAFKA_PASSWORD`).
+
+---
+
+## 7. Node.js
+
+```ts
+import {
+  createNotificationHttpClient,
+  notificationTcpClient,
+  NotificationKafka,
+  NotificationService,
+} from '@yaghmori/notification-service';
+
+const http = createNotificationHttpClient({
+  baseUrl: process.env.NOTIFICATION_SERVICE_URL,
+  auth: { apiKey: process.env.NOTIFICATION_SERVICE_API_KEY! },
+});
+await http.list({ userId: 'u1' });
+await http.markRead(id);
+await http.health();
+
+// Nest: ClientsModule.register([notificationTcpClient()])
+// Kafka: NotificationKafka.sendRequested + NotificationKafka.connection()
+```
+
+---
+
+## 8. .NET
+
+```csharp
+services.AddNotificationServiceClient(o =>
+{
+    o.ApiKey = Environment.GetEnvironmentVariable("NOTIFICATION_SERVICE_API_KEY");
+});
+
+using var http = new NotificationServiceHttpClient(new NotificationServiceOptions());
+await http.ListAsync(userId: "u1");
+await http.MarkReadAsync(id);
+await http.HealthAsync();
+
+await using var tcp = new NotificationServiceTcpClient(new NotificationServiceOptions());
+await tcp.CreateAsync(new SendNotificationRequest
+{
+    UserId = "u1",
+    EventKey = "order.shipped",
+    Title = "Order shipped",
+    Body = "On the way",
+});
+await tcp.GetNotificationsAsync(new { userId = "u1" });
+
+using var kafka = new NotificationKafkaProducer(new NotificationKafkaOptions());
+await kafka.PublishSendRequestedAsync(new SendNotificationRequest
+{
+    UserId = "u1",
+    EventKey = "order.shipped",
+});
+```
+
+Constants live in generated `NotificationService.g.cs` (`Patterns`, `HttpPaths`, `Topics`, `EventTypes`).

package/docs/USAGE.md

@@ -0,0 +1,153 @@
+# Full SDK usage — @yaghmori/notification-service
+
+HTTP inbox + TCP RPC + Kafka send topics + auth. Deploy on **any host/port**; configure the SDK.
+
+## Install / run
+
+```bash
+pnpm add @yaghmori/notification-service zod
+docker pull ghcr.io/yaghmori/notification-service:latest
+```
+
+```bash
+docker run --rm -p 3000:3000 -p 4004:4004 \
+  -e PORT=3000 -e TCP_PORT=4004 \
+  -e AUTH_API_KEYS=dev-key \
+  -e DATABASE_URL=... \
+  ghcr.io/yaghmori/notification-service:latest
+```
+
+## Configure address / ports
+
+| | Client options | Client env | Service env |
+|--|----------------|------------|-------------|
+| HTTP | `baseUrl` / `host`+`port` | `NOTIFICATION_SERVICE_URL` or `HOST`+`HTTP_PORT` | `PORT` |
+| TCP | `notificationTcpClient({ host, port })` | `NOTIFICATION_SERVICE_HOST`, `NOTIFICATION_SERVICE_TCP_PORT` | `TCP_PORT` |
+| Kafka | `NotificationKafka.connection()` | `KAFKA_BROKERS`, SASL_*, SSL | same |
+
+## Auth (HTTP)
+
+| Mode | Service config | Client |
+|------|----------------|--------|
+| API key | `AUTH_API_KEYS=k1,k2` | `auth: { apiKey }` → `x-api-key` |
+| JWT | `JWT_SECRET` + Bearer with `serviceName` | `auth: { bearerToken }` |
+| Open | `AUTH_DISABLED=true` | omit auth |
+| Health | always public | `GET /health` |
+
+TCP: private network. Kafka: broker SASL/SSL via env (not HTTP API keys).
+
+```ts
+import { createNotificationHttpClient } from '@yaghmori/notification-service';
+
+const notifications = createNotificationHttpClient({
+  baseUrl: process.env.NOTIFICATION_SERVICE_URL,
+  auth: { apiKey: process.env.NOTIFICATION_SERVICE_API_KEY! },
+});
+```
+
+## HTTP
+
+```ts
+await notifications.list({ userId: 'user-1', unreadOnly: true, limit: 20 });
+await notifications.markRead(notificationId);
+await notifications.health();
+```
+
+Paths: `NotificationService.httpPaths.LIST` → `/notifications`, etc. SSE stream is `STREAM` → `/notifications/stream` (wire your own EventSource; HTTP client focuses on list/mark-read/health).
+
+## NestJS TCP
+
+```ts
+import { Module, Inject, Injectable } from '@nestjs/common';
+import { ClientsModule, ClientProxy } from '@nestjs/microservices';
+import {
+  notificationTcpClient,
+  NotificationService,
+  PATTERNS,
+} from '@yaghmori/notification-service';
+import { firstValueFrom } from 'rxjs';
+
+@Module({
+  imports: [
+    ClientsModule.register([
+      notificationTcpClient({
+        host: process.env.NOTIFICATION_SERVICE_HOST,
+        port: Number(process.env.NOTIFICATION_SERVICE_TCP_PORT) || 4004,
+      }),
+    ]),
+  ],
+})
+export class AppModule {}
+
+@Injectable()
+export class NotifyFacade {
+  constructor(@Inject(NotificationService.token) private readonly client: ClientProxy) {}
+
+  create(payload: {
+    userId: string;
+    eventKey: string;
+    title?: string;
+    body?: string;
+  }) {
+    return firstValueFrom(
+      this.client.send(PATTERNS.CREATE_NOTIFICATION, payload),
+    );
+  }
+
+  list(userId: string) {
+    return firstValueFrom(
+      this.client.send(PATTERNS.GET_NOTIFICATIONS, { userId }),
+    );
+  }
+}
+```
+
+## Kafka — request a send
+
+```ts
+import { Kafka } from 'kafkajs';
+import {
+  NotificationKafka,
+  sendNotificationRequestSchema,
+} from '@yaghmori/notification-service';
+
+const conn = NotificationKafka.connection();
+const kafka = new Kafka(conn);
+const producer = kafka.producer();
+await producer.connect();
+
+const payload = sendNotificationRequestSchema.parse({
+  userId: 'user-1',
+  eventKey: 'order.shipped',
+  title: 'Order shipped',
+  body: 'Your order is on the way.',
+  channels: ['in-app', 'email'],
+  actionUrl: 'https://app.example.com/orders/1',
+});
+
+await producer.send({
+  topic: NotificationKafka.sendRequested, // notification.send.requested
+  messages: [
+    {
+      key: payload.userId,
+      value: JSON.stringify(payload),
+      headers: {
+        'content-type': 'application/json',
+        'x-event-type': NotificationKafka.eventTypes.SEND,
+      },
+    },
+  ],
+});
+```
+
+Lifecycle topics: `notification.sent`, `notification.failed`.
+
+## Constants
+
+```ts
+import { NotificationService } from '@yaghmori/notification-service';
+
+NotificationService.ports; // { tcp: 4004, http: 3000 }
+NotificationService.patterns.CREATE_NOTIFICATION;
+NotificationService.topics.SEND_REQUESTED;
+```

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@yaghmori/notification-service",
+  "version": "0.1.1",
+  "description": "Client SDK for notification-service — inbox HTTP/SSE, Nest TCP patterns, Kafka send topics, Zod DTOs",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./nest": {
+      "types": "./dist/nest.d.ts",
+      "default": "./dist/nest.js"
+    }
+  },
+  "files": [
+    "dist",
+    "contracts.json",
+    "README.md",
+    "docs"
+  ],
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/microservices": "^11.0.0",
+    "rxjs": "^7.8.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/microservices": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/microservices": "^11.0.0",
+    "@types/node": "^22.15.3",
+    "rxjs": "^7.8.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yaghmori/notification-service.git",
+    "directory": "packages/client"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "codegen": "node scripts/codegen.cjs",
+    "build": "pnpm run codegen && tsc -p tsconfig.json",
+    "check-types": "tsc -p tsconfig.json --noEmit"
+  }
+}