pulse-sdk 0.0.1 → 0.0.3

package/README.md

@@ -28,11 +28,58 @@ Run the lightweight integration tests (a test gRPC server is started automatical
 npm test
 ```
 
-## Configuration (current)
+## Configuration
 
-Currently the SDK supports programmatic configuration only: create and pass a `PulseConfig` object when instantiating `Producer` or `Consumer`.
+The SDK supports configuration via (in priority order):
 
-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.
+1. Programmatic: pass a `PulseConfig` object when creating `Producer` or `Consumer`.
+2. Environment variables: `PULSE_GRPC_URL`, `PULSE_EVENT_TYPES` (comma-separated), `PULSE_CONSUMER_NAME`.
+3. File: a `pulse.yml` or `pulse.yaml` file placed at the process working directory or in `~/.pulse/pulse.yml`.
+
+The SDK exposes two helpers:
+
+- `loadConfig(configPath?: string): PulseConfig` — reads `pulse.yml` / env and returns a merged config object.
+- `initFromConfig(cfg: PulseConfig): Promise<void>` — calls the broker `CreateTopic` RPC for every topic declared in `cfg.topics`. This lets the SDK create any required topics automatically at startup (useful for tests or first-run).
+
+Example `pulse.yml`:
+
+```yaml
+grpcUrl: localhost:5556
+eventTypes:
+	- events
+	- transactions
+consumerName: my-consumer
+topics:
+	- name: events
+		fifo: false
+	- name: transactions
+		fifo: true
+```
+
+Usage example (auto-create topics then start):
+
+```ts
+import { loadConfig, initFromConfig, Producer, Consumer } from 'pulse-sdk';
+
+async function main() {
+	const cfg = loadConfig(); // reads pulse.yml or environment
+	await initFromConfig(cfg); // create topics listed in cfg.topics (no-op if none)
+
+	const producer = new Producer(cfg);
+	await producer.send('events', { type: 'user.created', id: 1 });
+
+	const consumer = new Consumer(cfg);
+	consumer.on('events', (msg) => console.log('received', msg.payload));
+	await consumer.start('events', cfg.consumerName || 'default');
+}
+
+main().catch(console.error);
+```
+
+Notes:
+- `initFromConfig` calls the gRPC `CreateTopic` RPC. If the broker responds with an error for a topic that already exists, the SDK logs a warning and continues.
+- Ensure the broker is running and reachable at `cfg.grpcUrl` before calling `initFromConfig`.
+- The SDK bundles `pulse.proto` inside the package so consumers do not need to copy proto files into their projects.
 
 ## Quick Start
 

package/dist/config.d.ts

@@ -1,5 +1,14 @@
+export interface TopicConfig {
+    name: string;
+    fifo?: boolean;
+    retention_bytes?: number;
+    retention_time?: number;
+}
 export interface PulseConfig {
     grpcUrl: string;
     eventTypes: string[];
+    consumerName?: string;
+    topics?: TopicConfig[];
 }
-export declare function loadConfig(config: PulseConfig): PulseConfig;
+export declare function loadConfig(configPath?: string): PulseConfig;
+export declare function initFromConfig(cfg: PulseConfig): Promise<void>;

package/dist/config.js

@@ -1,7 +1,71 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = loadConfig;
-function loadConfig(config) {
-    // Aqui pode ser expandido para ler de arquivo ou env
-    return config;
+exports.initFromConfig = initFromConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const client_1 = require("./proto/client");
+const DEFAULTS = {
+    grpcUrl: 'localhost:50052',
+    eventTypes: ['events'],
+};
+function loadConfig(configPath) {
+    const candidates = [
+        configPath,
+        path_1.default.resolve(process.cwd(), 'pulse.yml'),
+        path_1.default.resolve(process.cwd(), 'pulse.yaml'),
+        path_1.default.join(os_1.default.homedir(), '.pulse', 'pulse.yml'),
+    ].filter(Boolean);
+    let fileCfg = {};
+    for (const p of candidates) {
+        if (p && fs_1.default.existsSync(p)) {
+            const raw = fs_1.default.readFileSync(p, 'utf8');
+            const parsed = js_yaml_1.default.load(raw);
+            fileCfg = parsed || {};
+            break;
+        }
+    }
+    const envCfg = {};
+    if (process.env.PULSE_GRPC_URL)
+        envCfg.grpcUrl = process.env.PULSE_GRPC_URL;
+    if (process.env.PULSE_EVENT_TYPES)
+        envCfg.eventTypes = process.env.PULSE_EVENT_TYPES.split(',');
+    if (process.env.PULSE_CONSUMER_NAME)
+        envCfg.consumerName = process.env.PULSE_CONSUMER_NAME;
+    const merged = Object.assign({}, DEFAULTS, fileCfg, envCfg);
+    // Ensure eventTypes array exists
+    if (!merged.eventTypes)
+        merged.eventTypes = DEFAULTS.eventTypes;
+    return merged;
+}
+// Initialize topics from config using gRPC CreateTopic RPC.
+async function initFromConfig(cfg) {
+    if (!cfg.topics || cfg.topics.length === 0)
+        return;
+    const client = (0, client_1.createClient)(cfg.grpcUrl);
+    for (const t of cfg.topics) {
+        const req = {
+            topic: t.name || t['name'],
+            fifo: !!t.fifo,
+            retention_bytes: t.retention_bytes || 0,
+            retention_time: t.retention_time || 0,
+        };
+        await new Promise((resolve, reject) => {
+            client.CreateTopic(req, (err, res) => {
+                if (err) {
+                    // If topic exists the server may return an error; log and continue
+                    console.warn('CreateTopic error for', req.topic, err.message || err);
+                    resolve();
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
 }

package/dist/proto/client.js

@@ -37,10 +37,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createClient = createClient;
+const fs_1 = __importDefault(require("fs"));
 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');
+// Prefer the proto bundled with the package (dist/proto/pulse.proto).
+// In development (when running from source), fall back to the repository proto.
+const bundledProto = path_1.default.resolve(__dirname, 'pulse.proto');
+const repoProto = path_1.default.resolve(__dirname, '../../../../internal/api/proto/pulse.proto');
+let PROTO_PATH = bundledProto;
+if (!fs_1.default.existsSync(bundledProto)) {
+    // fallback to repo proto for local development
+    PROTO_PATH = repoProto;
+}
 const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
     keepCase: true,
     longs: String,

package/dist/proto/pulse.proto

@@ -0,0 +1,64 @@
+syntax = "proto3";
+
+package pulse.v1;
+
+option go_package = "pulse/pkg/proto";
+
+service PulseService {
+  // Publish sends a message to a topic.
+  rpc Publish(PublishRequest) returns (PublishResponse);
+
+  // Consume reads messages from a topic as a stream.
+  rpc Consume(ConsumeRequest) returns (stream ConsumeResponse);
+
+  // CommitOffset commits the offset for a consumer group.
+  rpc CommitOffset(CommitOffsetRequest) returns (CommitOffsetResponse);
+
+  // CreateTopic creates a new topic.
+  rpc CreateTopic(CreateTopicRequest) returns (CreateTopicResponse);
+}
+
+message PublishRequest {
+  string topic = 1;
+  bytes payload = 2;
+  map<string, string> headers = 3;
+}
+
+message PublishResponse {
+  string id = 1;
+  uint64 offset = 2;
+}
+
+message ConsumeRequest {
+  string topic = 1;
+  string consumer_name = 2;
+  uint64 offset = 3; // Optional: start from specific offset. If 0, continues from last committed.
+}
+
+message ConsumeResponse {
+  uint64 offset = 1;
+  int64 timestamp = 2;
+  bytes payload = 3;
+  map<string, string> headers = 4;
+}
+
+message CommitOffsetRequest {
+  string topic = 1;
+  string consumer_name = 2;
+  uint64 offset = 3;
+}
+
+message CommitOffsetResponse {
+  bool success = 1;
+}
+
+message CreateTopicRequest {
+  string topic = 1;
+  bool fifo = 2;
+  int64 retention_bytes = 3;
+  int64 retention_time = 4; // Nanoseconds
+}
+
+message CreateTopicResponse {
+  bool success = 1;
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "pulse-sdk",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Pulse SDK for Node.js/TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
+    "postbuild": "node scripts/copy-proto.js",
     "test": "jest"
   },
   "author": "",
@@ -22,12 +23,14 @@
     "typescript": "^5.0.0",
     "jest": "^29.0.0",
     "ts-jest": "^29.0.0",
-    "@types/jest": "^29.0.0"
+    "@types/jest": "^29.0.0",
+    "@types/js-yaml": "^4.0.5"
   },
   "dependencies": {
     "@grpc/grpc-js": "^1.8.0",
     "protobufjs": "^7.2.0",
-    "@grpc/proto-loader": "^0.7.0"
+    "@grpc/proto-loader": "^0.7.0",
+    "js-yaml": "^4.1.0"
   },
   "jest": {
     "preset": "ts-jest",