@togatherlabs/event-sdk 1.0.0

package/README.md

@@ -0,0 +1,200 @@
+# togather-shared-events
+
+This repository contains **event schemas** for the **toGather event-driven backend system**. We use **Protocol Buffers (Protobuf)** as the messaging format for events. It provides **type-safe code** generation for **TypeScript** and **Python**, enabling services in different languages to share a consistent event schema.
+
+
+## Table of Contents
+
+1. [Directory Structure](#directory-structure)
+2. [Development](#development)
+
+   * [Adding New Proto Files](#adding-new-proto-files)
+   * [Linting](#linting)
+   * [Code Generation](#code-generation)
+3. [Using Generated Code](#using-generated-code)
+
+   * [TypeScript](#typescript)
+   * [Python](#python)
+4. [Best Practices](#best-practices)
+5. [Troubleshooting](#troubleshooting)
+
+
+## Directory Structure
+
+Protobuf files should follow a **domain/version-based structure**:
+
+```
+proto/
+└── <domain>/
+    └── <version>/
+        └── <event>.proto
+```
+
+Example:
+
+```
+proto/user/create/v1/user.proto
+```
+
+* **Domain**: The feature or module (e.g., `user`)
+* **Version**: The event schema version (e.g., `v1`)
+
+> This structure ensures forward-compatibility and makes schema evolution manageable.
+
+
+
+## Development
+
+### Adding New Proto Files
+
+1. Place your `.proto` file in the appropriate `proto/<domain>/<version>` folder.
+2. Define the `package` in the `.proto` file to match the folder structure.
+
+Example for `user.create.v1`:
+
+```proto
+syntax = "proto3";
+
+package user.create.v1;
+
+message UserCreated {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+  int64 created_at = 4;
+}
+```
+
+### Linting
+
+Lint your proto files to ensure consistency and adherence to standards:
+
+```bash
+pnpm buf:lint
+```
+
+> This checks for things like missing packages, incorrect directory structure, and other style issues.
+
+### Code Generation
+
+Generate TypeScript and Python code from your proto files:
+
+```bash
+pnpm buf:generate
+```
+The generated code is placed in the `gen/` directory:
+
+  ```
+  gen/ts/...
+  gen/python/...
+  ```
+
+> **Tip:** Keep `buf.gen.yaml` updated if you add new languages or plugins.
+
+
+## Using Generated Code
+
+### TypeScript
+
+**Dependencies:**
+
+```bash
+pnpm add @bufbuild/protobuf@^2.9.0
+```
+
+**Example usage:**
+
+```ts
+import { UserCreated, UserCreatedSchema } from '../gen/ts/user/create/v1/user_pb';
+import { create, toBinary, fromBinary, toJson } from '@bufbuild/protobuf';
+
+// Create a new message
+const newUser: UserCreated = create(UserCreatedSchema, {
+  id: "1",
+  name: "Abhiram",
+  email: "abhiram.ars@gmail.com",
+  createdAt: BigInt(Date.now()),
+});
+
+// Serialize to binary
+const buffer = toBinary(UserCreatedSchema, newUser);
+
+// Deserialize from binary
+const decoded = fromBinary(UserCreatedSchema, buffer);
+
+// Convert to JSON
+const json = toJson(UserCreatedSchema, decoded);
+```
+
+> **Tip:** Use `toBinary`/`fromBinary` for Kafka or network transmission. Use `toJson`/`fromJson` for logging or debugging.
+
+### Python
+
+**Dependencies:**
+
+```bash
+pip install protobuf
+```
+
+**Example usage:**
+
+```python
+from gen.python.user.create.v1 import user_pb2
+
+# Create a new message
+msg = user_pb2.UserCreated(
+    id="1",
+    name="Abhiram",
+    email="abhiram@gmail.com",
+    created_at=int(1728512345123),
+)
+
+# Serialize to bytes
+binary_data = msg.SerializeToString()
+
+# Deserialize from bytes
+decoded = user_pb2.UserCreated()
+decoded.ParseFromString(binary_data)
+
+print(decoded)
+```
+
+> **Tip:** Python type hints can be added with `mypy-protobuf` or community plugins for full static type checking.
+
+
+
+## Best Practices
+
+1. **Package and folder alignment**
+
+   * `package` in `.proto` must match folder structure (`proto/<domain>/<version>`).
+
+2. **Versioning**
+
+   * Always increment the version folder (`v1`, `v2`, etc.) when changing message formats to avoid breaking consumers.
+
+3. **Type safety**
+
+   * Use the generated schemas rather than manually constructing messages.
+   * In TypeScript, always use `create()`; in Python, use the generated `UserCreated` class.
+
+4. **Schema evolution**
+
+   * Avoid renaming or deleting existing fields; mark them deprecated instead.
+   * Use `int64` for timestamps, `string` for IDs/emails, etc.
+
+
+## Troubleshooting
+
+* **ModuleNotFoundError in Python**
+
+  * Ensure `gen/` folder is in your `PYTHONPATH`.
+  * Add `__init__.py` files in each subfolder if needed.
+
+* **TypeScript errors with missing `$typeName` or `UserCreated`**
+
+  * Make sure you are importing the **schema** (`UserCreatedSchema`) and using `create()` instead of instantiating the type directly.
+
+* **Buf generation issues**
+
+  * Run `pnpm buf:lint` first to catch package/directory mismatches.

package/gen/ts/user/create/v1/user_pb.d.ts

@@ -0,0 +1,38 @@
+// @generated by protoc-gen-es v2.9.0 with parameter "target=js+dts,import_extension=none"
+// @generated from file user/create/v1/user.proto (package user.create.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file user/create/v1/user.proto.
+ */
+export declare const file_user_create_v1_user: GenFile;
+
+/**
+ * @generated from message user.create.v1.UserCreated
+ */
+export declare type UserCreated = Message<"user.create.v1.UserCreated"> & {
+  /**
+   * @generated from field: string id = 1;
+   */
+  id: string;
+
+  /**
+   * @generated from field: string email = 2;
+   */
+  email: string;
+
+  /**
+   * @generated from field: int64 created_at = 3;
+   */
+  createdAt: bigint;
+};
+
+/**
+ * Describes the message user.create.v1.UserCreated.
+ * Use `create(UserCreatedSchema)` to create a new message.
+ */
+export declare const UserCreatedSchema: GenMessage<UserCreated>;
+

package/gen/ts/user/create/v1/user_pb.js

@@ -0,0 +1,19 @@
+// @generated by protoc-gen-es v2.9.0 with parameter "target=js+dts,import_extension=none"
+// @generated from file user/create/v1/user.proto (package user.create.v1, syntax proto3)
+/* eslint-disable */
+
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
+
+/**
+ * Describes the file user/create/v1/user.proto.
+ */
+export const file_user_create_v1_user = /*@__PURE__*/
+  fileDesc("Chl1c2VyL2NyZWF0ZS92MS91c2VyLnByb3RvEg51c2VyLmNyZWF0ZS52MSI8CgtVc2VyQ3JlYXRlZBIKCgJpZBgBIAEoCRINCgVlbWFpbBgCIAEoCRISCgpjcmVhdGVkX2F0GAMgASgDQnkKEmNvbS51c2VyLmNyZWF0ZS52MUIJVXNlclByb3RvUAGiAgNVQ1iqAg5Vc2VyLkNyZWF0ZS5WMcoCDlVzZXJcQ3JlYXRlXFYx4gIaVXNlclxDcmVhdGVcVjFcR1BCTWV0YWRhdGHqAhBVc2VyOjpDcmVhdGU6OlYxYgZwcm90bzM");
+
+/**
+ * Describes the message user.create.v1.UserCreated.
+ * Use `create(UserCreatedSchema)` to create a new message.
+ */
+export const UserCreatedSchema = /*@__PURE__*/
+  messageDesc(file_user_create_v1_user, 0);
+

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@togatherlabs/event-sdk",
+  "version": "1.0.0",
+  "description": "Shared Protobuf event schemas and generated code for toGather microservices",
+  "main": "./gen/ts/index.js",
+  "types": "./gen/ts/index.d.ts",
+  "files": [
+    "gen/ts"
+  ],
+  "keywords": [],
+  "type": "module",
+  "author": "toGather team",
+  "license": "ISC",
+  "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@commitlint/cz-commitlint": "^20.1.0",
+    "commitizen": "^4.3.1",
+    "husky": "^9.1.7",
+    "inquirer": "^9.3.8"
+  },
+  "config": {
+    "commitizen": {
+      "path": "@commitlint/cz-commitlint"
+    }
+  },
+  "dependencies": {
+    "@bufbuild/buf": "^1.58.0",
+    "@bufbuild/protobuf": "^2.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "commit": "git-cz",
+    "buf:lint": "buf lint",
+    "buf:generate": "buf generate"
+  }
+}