pulse-sdk 0.0.1

package/README.md

@@ -0,0 +1,111 @@
+# Pulse SDK — TypeScript
+
+TypeScript client for Pulse Broker (gRPC). This README is written for end users and explains installation, configuration, and basic usage with practical examples.
+
+## Installation
+
+Install from npm (published package):
+
+```bash
+npm install pulse-sdk
+```
+
+Or install locally from the repository (for development):
+
+```bash
+npm install
+```
+
+To compile the TypeScript sources (optional for development/CI):
+
+```bash
+npm run build
+```
+
+Run the lightweight integration tests (a test gRPC server is started automatically):
+
+```bash
+npm test
+```
+
+## Configuration (current)
+
+Currently the SDK supports programmatic configuration only: create and pass a `PulseConfig` object when instantiating `Producer` or `Consumer`.
+
+The code exposes a `PulseConfig` interface for strong typing. Environment-file loading (e.g. `pulse.yml` or `PULSE_*` environment variables) is planned but not implemented in this initial version — for now, pass configuration directly in code.
+
+## Quick Start
+
+Import from the published package and pass configuration programmatically:
+
+```ts
+import { Producer, Consumer } from 'pulse-sdk';
+
+const cfg = { grpcUrl: 'localhost:50052', eventTypes: ['events'] };
+
+// Send a JSON-serializable event
+const producer = new Producer(cfg);
+await producer.send('events', { type: 'user.created', id: 123 });
+
+// Consume events and register a handler
+const consumer = new Consumer(cfg);
+consumer.on('events', (msg) => {
+	console.log('received', msg.payload);
+});
+await consumer.start('events', 'my-consumer');
+```
+
+### Programmatic override
+
+You can create and pass `PulseConfig` directly in code:
+
+```ts
+const cfg = { grpcUrl: '10.0.0.5:50052', eventTypes: ['events'] };
+const producer = new Producer(cfg);
+```
+
+## Technical Details
+
+- The SDK dynamically loads `pulse.proto` at runtime using `@grpc/proto-loader` and `@grpc/grpc-js`.
+- The protobuf field `bytes payload` is used to carry the message body; the SDK serializes JSON payloads into that field by default.
+- `Consumer.start()` opens a server stream (`Consume`) and dispatches incoming messages to handlers registered via `consumer.on(topic, handler)`.
+
+## Examples
+
+Producer (send multiple events):
+
+```ts
+const producer = new Producer(loadConfig());
+await producer.send('events', { type: 'login', userId: 1 });
+await producer.send('events', { type: 'logout', userId: 1 });
+```
+
+Consumer (simple processing):
+
+```ts
+const cfg = loadConfig();
+const consumer = new Consumer(cfg);
+
+consumer.on('events', (msg) => {
+	console.log('event payload', msg.payload);
+});
+
+await consumer.start('events', cfg.consumerName || 'default');
+```
+
+## Local Tests
+
+The tests in `tests/` start a lightweight gRPC test server automatically; run them with `npm test`.
+
+## FAQ (short)
+
+- Can I use decorators for handlers? Yes — TypeScript supports decorators, but this SDK does not use them by default. We can add decorator helpers later if desired.
+- How do I enable TLS / secure credentials? The client factory currently uses `createInsecure()` by default. We can expose a `credentials` option on `PulseConfig` to accept `grpc.credentials.createSsl(...)` or other credential objects.
+
+## Contributing
+
+Please open a PR with tests. The existing tests validate basic Producer/Consumer behaviour.
+
+---
+
+If you want this README expanded to mirror the Python SDK more closely (topic-level config, manual offset commits, longer examples), tell me which sections to add and I will update it.

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export interface PulseConfig {
+    grpcUrl: string;
+    eventTypes: string[];
+}
+export declare function loadConfig(config: PulseConfig): PulseConfig;

package/dist/config.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+function loadConfig(config) {
+    // Aqui pode ser expandido para ler de arquivo ou env
+    return config;
+}

package/dist/consumer.d.ts

@@ -0,0 +1,10 @@
+import { PulseConfig } from './config';
+export type EventHandler = (payload: any) => void;
+export declare class Consumer {
+    private config;
+    private handlers;
+    private client;
+    constructor(config: PulseConfig);
+    on(eventType: string, handler: EventHandler): void;
+    start(topic?: string, consumerName?: string): Promise<void>;
+}

package/dist/consumer.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Consumer = void 0;
+const client_1 = require("./proto/client");
+class Consumer {
+    constructor(config) {
+        this.config = config;
+        this.handlers = {};
+        this.client = (0, client_1.createClient)(config.grpcUrl);
+    }
+    on(eventType, handler) {
+        if (!this.handlers[eventType]) {
+            this.handlers[eventType] = [];
+        }
+        this.handlers[eventType].push(handler);
+    }
+    async start(topic, consumerName = 'default') {
+        const req = { topic: topic || this.config.eventTypes[0], consumer_name: consumerName, offset: 0 };
+        const stream = this.client.Consume(req);
+        stream.on('data', (msg) => {
+            const payloadBuf = msg.payload;
+            let parsed = payloadBuf;
+            try {
+                parsed = JSON.parse(payloadBuf.toString());
+            }
+            catch (e) {
+                // keep raw buffer if not JSON
+            }
+            const handlers = this.handlers[req.topic] || [];
+            handlers.forEach(h => h({ offset: msg.offset, timestamp: msg.timestamp, payload: parsed, headers: msg.headers }));
+        });
+        return new Promise((resolve, reject) => {
+            stream.on('end', () => resolve());
+            stream.on('error', (e) => reject(e));
+        });
+    }
+}
+exports.Consumer = Consumer;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './producer';
+export * from './consumer';
+export * from './config';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./producer"), exports);
+__exportStar(require("./consumer"), exports);
+__exportStar(require("./config"), exports);

package/dist/producer.d.ts

@@ -0,0 +1,11 @@
+import { PulseConfig } from './config';
+export interface PublishResponse {
+    id: string;
+    offset: number | string;
+}
+export declare class Producer {
+    private config;
+    private client;
+    constructor(config: PulseConfig);
+    send(topic: string, payload: any, headers?: Record<string, string>): Promise<PublishResponse>;
+}

package/dist/producer.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Producer = void 0;
+const client_1 = require("./proto/client");
+class Producer {
+    constructor(config) {
+        this.config = config;
+        this.client = (0, client_1.createClient)(config.grpcUrl);
+    }
+    async send(topic, payload, headers) {
+        const req = {
+            topic,
+            payload: Buffer.from(JSON.stringify(payload)),
+            headers: headers || {},
+        };
+        return new Promise((resolve, reject) => {
+            this.client.Publish(req, (err, res) => {
+                if (err)
+                    return reject(err);
+                resolve({ id: res.id, offset: res.offset });
+            });
+        });
+    }
+}
+exports.Producer = Producer;

package/dist/proto/client.d.ts

@@ -0,0 +1,2 @@
+export type PulseClient = any;
+export declare function createClient(address: string): PulseClient;

package/dist/proto/client.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClient = createClient;
+const path_1 = __importDefault(require("path"));
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const PROTO_PATH = path_1.default.resolve(__dirname, '../../../../internal/api/proto/pulse.proto');
+const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+    keepCase: true,
+    longs: String,
+    enums: String,
+    defaults: true,
+    oneofs: true,
+});
+const loaded = grpc.loadPackageDefinition(packageDefinition).pulse.v1;
+function createClient(address) {
+    return new loaded.PulseService(address, grpc.credentials.createInsecure());
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "pulse-sdk",
+  "version": "0.0.1",
+  "description": "Pulse SDK for Node.js/TypeScript",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "prepare": "npm run build",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "@types/jest": "^29.0.0"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.8.0",
+    "protobufjs": "^7.2.0",
+    "@grpc/proto-loader": "^0.7.0"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/tests/**/*.test.ts"
+    ]
+  }
+}