@jomkv/keybud-v2-contracts 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# KeyBud V2 Contracts
+
+Shared TypeScript contracts and type definitions for KeyBud V2, providing type-safe communication between frontend and backend applications.
+
+## Overview
+
+This package contains shared contracts for WebSocket events, payloads, and other common types used across the KeyBud V2 ecosystem. It ensures type safety and consistency between the frontend and backend implementations.
+
+## Installation
+
+```sh
+pnpm add @jomkv/keybud-v2-contracts
+```
+
+## Usage
+
+```typescript
+import {
+  AUTH_EVENT_NAMES,
+  MESSAGE_EVENT_NAMES,
+  type AuthClientToServerEvents,
+  type MessageServerToClientEvents,
+  type NewMessagePayload,
+} from "@jomkv/keybud-v2-contracts";
+```
+
+## Structure
+
+### WebSocket Contracts
+
+#### Authentication (`ws/auth`)
+
+Handles authentication-related WebSocket events:
+
+- **Event Names**: `AUTH_EVENT_NAMES`
+  - `SUBSCRIBE` - Client subscribes to auth events
+  - `SUBSCRIBE_SUCCESS` - Server confirms subscription
+  - `COMPLETE` - Client completes login
+
+- **Events**:
+  - `AuthClientToServerEvents` - Client-to-server event types
+  - `ServerToClientEvents` - Server-to-client event types
+
+- **Payloads**: `AuthSubscribePayload`, `AuthSubscribeSuccessPayload`
+
+#### Messages (`ws/messages`)
+
+Handles messaging-related WebSocket events:
+
+- **Event Names**: `MESSAGE_EVENT_NAMES`
+  - `SUBSCRIBE` - Client subscribes to messages
+  - `NEW_MESSAGE` - Server sends new message
+
+- **Events**:
+  - `MessageClientToServerEvents` - Client-to-server event types
+  - `MessageServerToClientEvents` - Server-to-client event types
+
+- **Payloads**: `MessageSubscribePayload`, `NewMessagePayload`
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 14.17
+- pnpm 10.17.0
+
+### Scripts
+
+```sh
+# Run tests (not yet implemented)
+pnpm test
+```
+
+### Project Configuration
+
+- **TypeScript**: Strict mode enabled with modern module resolution
+- **Package Manager**: pnpm with workspace support
+- **Module System**: ES Modules
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Add your contracts to the appropriate directory under `src/`
+4. Export new contracts from `src/index.ts`
+5. Submit a pull request
+
+## License
+
+MIT © Jom Karlo Verzosa
+
+## Repository
+
+[https://github.com/jomkv/keybud-v2-contracts](https://github.com/jomkv/keybud-v2-contracts)
+
+````# KeyBud V2 Contracts
+
+Shared TypeScript contracts and type definitions for KeyBud V2, providing type-safe communication between frontend and backend applications.
+
+## Overview
+
+This package contains shared contracts for WebSocket events, payloads, and other common types used across the KeyBud V2 ecosystem. It ensures type safety and consistency between the frontend and backend implementations.
+
+## Installation
+
+```sh
+pnpm add @jomkv/keybud-v2-contracts
+````
+
+## Usage
+
+```typescript
+import {
+  AUTH_EVENT_NAMES,
+  MESSAGE_EVENT_NAMES,
+  type AuthClientToServerEvents,
+  type MessageServerToClientEvents,
+  type NewMessagePayload,
+} from "@jomkv/keybud-v2-contracts";
+```
+
+## Structure
+
+### WebSocket Contracts
+
+#### Authentication (`ws/auth`)
+
+Handles authentication-related WebSocket events:
+
+- **Event Names**: `AUTH_EVENT_NAMES`
+  - `SUBSCRIBE` - Client subscribes to auth events
+  - `SUBSCRIBE_SUCCESS` - Server confirms subscription
+  - `COMPLETE` - Client completes login
+
+- **Events**:
+  - `AuthClientToServerEvents` - Client-to-server event types
+  - `ServerToClientEvents` - Server-to-client event types
+
+- **Payloads**: `AuthSubscribePayload`, `AuthSubscribeSuccessPayload`
+
+#### Messages (`ws/messages`)
+
+Handles messaging-related WebSocket events:
+
+- **Event Names**: `MESSAGE_EVENT_NAMES`
+  - `SUBSCRIBE` - Client subscribes to messages
+  - `NEW_MESSAGE` - Server sends new message
+
+- **Events**:
+  - `MessageClientToServerEvents` - Client-to-server event types
+  - `MessageServerToClientEvents` - Server-to-client event types
+
+- **Payloads**: `MessageSubscribePayload`, `NewMessagePayload`
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 14.17
+- pnpm 10.17.0
+
+### Scripts
+
+```sh
+# Run tests (not yet implemented)
+pnpm test
+```
+
+### Project Configuration
+
+- **TypeScript**: Strict mode enabled with modern module resolution
+- **Package Manager**: pnpm with workspace support
+- **Module System**: ES Modules
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Add your contracts to the appropriate directory under `src/`
+4. Export new contracts from `src/index.ts`
+5. Submit a pull request
+
+## License
+
+MIT © Jom Karlo Verzosa
+
+## Repository
+
+[https://github.com/jomkv/keybud-v2-contracts](https://github.com/jomkv/keybud-v2-contracts)
+
+```
+
+```

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@jomkv/keybud-v2-contracts",
+  "version": "1.0.0",
+  "description": "",
+  "keywords": [],
+  "homepage": "https://github.com/jomkv/keybud-v2-contracts#readme",
+  "bugs": {
+    "url": "https://github.com/jomkv/keybud-v2-contracts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jomkv/keybud-v2-contracts.git"
+  },
+  "license": "MIT",
+  "author": "Jom Karlo Verzosa",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "packageManager": "pnpm@10.17.0"
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./ws/auth/index.ts";
+export * from "./ws/messages/index.ts";

package/src/ws/auth/event-names.ts

@@ -0,0 +1,8 @@
+export const AUTH_EVENT_NAMES = {
+  SUBSCRIBE: "auth:subscribe",
+  SUBSCRIBE_SUCCESS: "auth:subscribe_success",
+  COMPLETE: "auth:complete", // client completes login
+} as const;
+
+export type AuthEventName =
+  (typeof AUTH_EVENT_NAMES)[keyof typeof AUTH_EVENT_NAMES];

package/src/ws/auth/events.ts

@@ -0,0 +1,14 @@
+import type { AUTH_EVENT_NAMES } from "./event-names.ts";
+import type {
+  AuthSubscribePayload,
+  AuthSubscribeSuccessPayload,
+} from "./payloads.js";
+
+export interface AuthClientToServerEvents {
+  [AUTH_EVENT_NAMES.SUBSCRIBE]: AuthSubscribePayload;
+}
+
+export interface ServerToClientEvents {
+  [AUTH_EVENT_NAMES.SUBSCRIBE_SUCCESS]: AuthSubscribeSuccessPayload;
+  [AUTH_EVENT_NAMES.COMPLETE]: {};
+}

package/src/ws/auth/index.ts

@@ -0,0 +1,3 @@
+export * from "./event-names.ts";
+export * from "./events.ts";
+export * from "./payloads.ts";

package/src/ws/auth/payloads.ts

@@ -0,0 +1,7 @@
+export interface AuthSubscribePayload {
+  sessionId: string;
+}
+
+export interface AuthSubscribeSuccessPayload {
+  sessionId: string;
+}

package/src/ws/messages/event-names.ts

@@ -0,0 +1,7 @@
+export const MESSAGE_EVENT_NAMES = {
+  SUBSCRIBE: "message:subscribe",
+  NEW_MESSAGE: "message:new",
+} as const;
+
+export type MessageEventName =
+  (typeof MESSAGE_EVENT_NAMES)[keyof typeof MESSAGE_EVENT_NAMES];

package/src/ws/messages/events.ts

@@ -0,0 +1,10 @@
+import type { MESSAGE_EVENT_NAMES } from "./event-names.ts";
+import type { MessageSubscribePayload, NewMessagePayload } from "./payloads.js";
+
+export interface MessageClientToServerEvents {
+  [MESSAGE_EVENT_NAMES.SUBSCRIBE]: MessageSubscribePayload;
+}
+
+export interface MessageServerToClientEvents {
+  [MESSAGE_EVENT_NAMES.NEW_MESSAGE]: NewMessagePayload;
+}

package/src/ws/messages/index.ts

@@ -0,0 +1,3 @@
+export * from "./event-names.ts";
+export * from "./events.ts";
+export * from "./payloads.ts";

package/src/ws/messages/payloads.ts

@@ -0,0 +1,12 @@
+export interface NewMessagePayload {
+  id: number;
+  senderId: number;
+  conversationId: number;
+  content: string;
+  createdAt: Date;
+  readAt?: Date;
+}
+
+export interface MessageSubscribePayload {
+  userId: number;
+}

package/tsconfig.json

@@ -0,0 +1,48 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    // "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+
+    // Custom
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  }
+}