@mttickets12/common 1.0.22 → 1.0.25

package/README.md

@@ -0,0 +1,228 @@
+# Common Package
+
+Shared code package for microservices in the ticketing system.
+
+## Overview
+
+The `@mttickets12/common` package contains shared code used across all microservices, including error classes, event definitions, middleware, and base classes for event handling.
+
+## Installation
+
+This package is published to npm. Install it in your service:
+
+```bash
+npm install @mttickets12/common
+```
+
+For local development, use `npm link`:
+
+```bash
+# In common directory
+npm link
+
+# In service directory
+npm link @mttickets12/common
+```
+
+## Building
+
+Build the package:
+
+```bash
+npm run build
+```
+
+This compiles TypeScript to JavaScript in the `build/` directory.
+
+## Publishing
+
+Publish to npm:
+
+```bash
+npm run pub
+```
+
+This will:
+1. Clean the build directory
+2. Build the package
+3. Increment patch version
+4. Publish to npm
+
+## Contents
+
+### Errors
+
+Custom error classes for consistent error handling:
+
+- `BadRequestError` - 400 status code
+- `NotAuthorizedError` - 401 status code
+- `NotFoundError` - 404 status code
+- `RequestValidationError` - 400 status code (validation errors)
+- `DatabaseValidationError` - 400 status code (database errors)
+- `CustomError` - Base error class
+
+### Middleware
+
+Express middleware functions:
+
+- `currentUser` - Extracts and validates JWT token, sets `req.currentUser`
+- `requireAuth` - Ensures user is authenticated
+- `validateRequest` - Validates request using express-validator
+- `errorHandler` - Centralized error handling middleware
+
+### Events
+
+Event-driven architecture components:
+
+#### Base Classes
+- `BaseListener` - Abstract base class for event listeners
+- `BasePublisher` - Abstract base class for event publishers
+
+#### Event Types
+- `TicketCreatedEvent`
+- `TicketUpdatedEvent`
+- `OrderCreatedEvent`
+- `OrderCancelledEvent`
+- `ExpirationCompleteEvent`
+- `PaymentCreatedEvent`
+
+#### Subjects
+Type-safe event subject constants:
+- `Subject.TicketCreated`
+- `Subject.TicketUpdated`
+- `Subject.OrderCreated`
+- `Subject.OrderCancelled`
+- `Subject.ExpirationComplete`
+- `Subject.PaymentCreated`
+
+## Usage Examples
+
+### Using Middleware
+
+```typescript
+import { requireAuth, currentUser } from '@mttickets12/common';
+import express from 'express';
+
+const router = express.Router();
+
+// Protected route
+router.get('/api/orders', currentUser, requireAuth, async (req, res) => {
+  // req.currentUser is available here
+  res.send({ userId: req.currentUser!.id });
+});
+```
+
+### Using Error Classes
+
+```typescript
+import { NotFoundError, BadRequestError } from '@mttickets12/common';
+
+if (!ticket) {
+  throw new NotFoundError();
+}
+
+if (price < 0) {
+  throw new BadRequestError('Price must be positive');
+}
+```
+
+### Creating Event Listeners
+
+```typescript
+import { Listener, TicketCreatedEvent, Subjects } from '@mttickets12/common';
+import { Message } from 'node-nats-streaming';
+
+class TicketCreatedListener extends Listener<TicketCreatedEvent> {
+  readonly subject = Subjects.TicketCreated;
+  queueGroupName = 'orders-service';
+
+  async onMessage(data: TicketCreatedEvent['data'], msg: Message) {
+    // Handle event
+    console.log('Ticket created:', data);
+    msg.ack();
+  }
+}
+```
+
+### Creating Event Publishers
+
+```typescript
+import { Publisher, TicketCreatedEvent, Subjects } from '@mttickets12/common';
+
+class TicketCreatedPublisher extends Publisher<TicketCreatedEvent> {
+  readonly subject = Subjects.TicketCreated;
+}
+
+// Usage
+await new TicketCreatedPublisher(natsClient).publish({
+  id: 'ticket_id',
+  title: 'Concert',
+  price: 50,
+  userId: 'user_id',
+  version: 0
+});
+```
+
+### Using Validation Middleware
+
+```typescript
+import { validateRequest } from '@mttickets12/common';
+import { body } from 'express-validator';
+
+router.post(
+  '/api/tickets',
+  [
+    body('title').notEmpty().withMessage('Title is required'),
+    body('price').isFloat({ gt: 0 }).withMessage('Price must be greater than 0')
+  ],
+  validateRequest,
+  async (req, res) => {
+    // Request is validated here
+  }
+);
+```
+
+## Type Safety
+
+The package is written in TypeScript and provides full type safety:
+- Event data types
+- Error types
+- Middleware request types
+
+## Versioning
+
+The package follows semantic versioning:
+- **Patch** (1.0.x) - Bug fixes, no breaking changes
+- **Minor** (1.x.0) - New features, backward compatible
+- **Major** (x.0.0) - Breaking changes
+
+When updating the package:
+1. Make changes
+2. Update version: `npm version patch|minor|major`
+3. Build: `npm run build`
+4. Publish: `npm publish --access public`
+
+## Dependencies
+
+- **express** - Web framework types
+- **express-validator** - Request validation
+- **jsonwebtoken** - JWT types
+- **cookie-session** - Session types
+- **node-nats-streaming** - NATS types
+
+## Development
+
+1. **Make changes** to TypeScript files in `src/`
+2. **Build** the package: `npm run build`
+3. **Test** in consuming services
+4. **Publish** when ready: `npm run pub`
+
+## Contributing
+
+When adding new shared code:
+1. Ensure it's truly shared across services
+2. Maintain backward compatibility
+3. Add proper TypeScript types
+4. Update this README
+5. Test in at least one consuming service
+

package/build/events/base-listener.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Listener = void 0;
+const api_1 = require("@opentelemetry/api");
+const tracer = api_1.trace.getTracer('nats-listener');
 class Listener {
     constructor(client) {
         this.ackWait = 5 * 1000;
@@ -19,7 +21,39 @@ class Listener {
         subscription.on("message", (msg) => {
             console.log(`Message received: ${this.subject} / ${this.queueGroupName}`);
             const parsedData = this.parseMessage(msg);
-            this.onMessage(parsedData, msg);
+            // Extract tracing context from message
+            const tracingContext = parsedData._tracing;
+            delete parsedData._tracing; // Remove tracing data from actual data
+            // Create span for message processing
+            const span = tracer.startSpan(`nats.listen.${this.subject}`, {
+                attributes: {
+                    'messaging.system': 'nats',
+                    'messaging.destination': this.subject,
+                    'messaging.operation': 'receive',
+                    'messaging.queue': this.queueGroupName,
+                },
+            });
+            // If we have tracing context, link to parent span
+            if (tracingContext) {
+                span.setAttributes({
+                    'messaging.trace_id': tracingContext.traceId,
+                    'messaging.parent_span_id': tracingContext.spanId,
+                });
+            }
+            // Execute message handler within span context
+            api_1.trace.setSpan(api_1.context.active(), span);
+            try {
+                this.onMessage(parsedData, msg);
+                span.setStatus({ code: 1 }); // OK
+            }
+            catch (error) {
+                span.recordException(error);
+                span.setStatus({ code: 2, message: error.message }); // ERROR
+                throw error;
+            }
+            finally {
+                span.end();
+            }
         });
     }
     parseMessage(msg) {

package/build/events/base-publisher.js

@@ -1,21 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Publisher = void 0;
+const api_1 = require("@opentelemetry/api");
+const tracer = api_1.trace.getTracer('nats-publisher');
 class Publisher {
     constructor(client) {
         this.client = client;
     }
-    publish(data) {
-        return new Promise((resolve, reject) => {
-            const dataString = JSON.stringify(data);
-            this.client.publish(this.subject, dataString, (err) => {
-                if (err) {
-                    return reject(err);
-                }
-                console.log("Event published to subject", this.subject);
-                resolve();
-            });
+    async publish(data) {
+        const span = tracer.startSpan(`nats.publish.${this.subject}`, {
+            attributes: {
+                'messaging.system': 'nats',
+                'messaging.destination': this.subject,
+                'messaging.operation': 'publish',
+            },
         });
+        try {
+            // Inject tracing context into data
+            const spanContext = span.spanContext();
+            const dataWithTracing = {
+                ...data,
+                _tracing: {
+                    traceId: spanContext.traceId,
+                    spanId: spanContext.spanId,
+                    traceFlags: spanContext.traceFlags.toString(),
+                },
+            };
+            return new Promise((resolve, reject) => {
+                const dataString = JSON.stringify(dataWithTracing);
+                this.client.publish(this.subject, dataString, (err) => {
+                    if (err) {
+                        span.recordException(err);
+                        span.setStatus({ code: 2, message: err.message }); // ERROR
+                        span.end();
+                        return reject(err);
+                    }
+                    span.setStatus({ code: 1 }); // OK
+                    span.end();
+                    console.log("Event published to subject", this.subject);
+                    resolve();
+                });
+            });
+        }
+        catch (error) {
+            span.recordException(error);
+            span.setStatus({ code: 2, message: error.message });
+            span.end();
+            throw error;
+        }
     }
 }
 exports.Publisher = Publisher;

package/build/events/payment-created-event.d.ts

@@ -0,0 +1,9 @@
+import { Subjects } from "./subjects";
+export interface PaymentCreatedEvent {
+    subject: Subjects.PaymentCreated;
+    data: {
+        id: string;
+        orderId: string;
+        stripeId: string;
+    };
+}

package/build/events/payment-created-event.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/events/subjects.d.ts

@@ -3,5 +3,6 @@ export declare enum Subjects {
     TicketUpdated = "ticket:updated",
     OrderCreated = "order:created",
     OrderCancelled = "order:cancelled",
-    ExpirationComplete = "expiration:complete"
+    ExpirationComplete = "expiration:complete",
+    PaymentCreated = "payment:created"
 }

package/build/events/subjects.js

@@ -8,4 +8,5 @@ var Subjects;
     Subjects["OrderCreated"] = "order:created";
     Subjects["OrderCancelled"] = "order:cancelled";
     Subjects["ExpirationComplete"] = "expiration:complete";
+    Subjects["PaymentCreated"] = "payment:created";
 })(Subjects || (exports.Subjects = Subjects = {}));

package/build/index.d.ts

@@ -17,3 +17,7 @@ export * from "./events/types/order-status";
 export * from "./events/order-cancelled-event";
 export * from "./events/order-created-event";
 export * from "./events/expiration-complete-event";
+export * from "./events/payment-created-event";
+export * from "./tracing/tracer";
+export * from "./tracing/nats-tracing";
+export * from "./tracing/setup";

package/build/index.js

@@ -33,3 +33,7 @@ __exportStar(require("./events/types/order-status"), exports);
 __exportStar(require("./events/order-cancelled-event"), exports);
 __exportStar(require("./events/order-created-event"), exports);
 __exportStar(require("./events/expiration-complete-event"), exports);
+__exportStar(require("./events/payment-created-event"), exports);
+__exportStar(require("./tracing/tracer"), exports);
+__exportStar(require("./tracing/nats-tracing"), exports);
+__exportStar(require("./tracing/setup"), exports);

package/build/tracing/nats-tracing.d.ts

@@ -0,0 +1,23 @@
+import { Span } from '@opentelemetry/api';
+import { Message } from 'node-nats-streaming';
+export interface TracingContext {
+    traceId?: string;
+    spanId?: string;
+    traceFlags?: string;
+}
+/**
+ * Extract tracing context from NATS message
+ */
+export declare const extractTracingContext: (msg: Message) => TracingContext | undefined;
+/**
+ * Inject tracing context into message data
+ */
+export declare const injectTracingContext: (data: any, span: Span) => any;
+/**
+ * Create a span for NATS event publishing
+ */
+export declare const createPublishSpan: (eventName: string, data: any) => Span;
+/**
+ * Create a span for NATS event listening
+ */
+export declare const createListenSpan: (eventName: string, msg: Message) => Span;

package/build/tracing/nats-tracing.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createListenSpan = exports.createPublishSpan = exports.injectTracingContext = exports.extractTracingContext = void 0;
+const api_1 = require("@opentelemetry/api");
+const tracer = api_1.trace.getTracer('nats-tracing');
+/**
+ * Extract tracing context from NATS message
+ */
+const extractTracingContext = (msg) => {
+    try {
+        const data = msg.getData();
+        const parsed = JSON.parse(data.toString());
+        return parsed._tracing;
+    }
+    catch (error) {
+        return undefined;
+    }
+};
+exports.extractTracingContext = extractTracingContext;
+/**
+ * Inject tracing context into message data
+ */
+const injectTracingContext = (data, span) => {
+    const spanContext = span.spanContext();
+    return {
+        ...data,
+        _tracing: {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags.toString(),
+        },
+    };
+};
+exports.injectTracingContext = injectTracingContext;
+/**
+ * Create a span for NATS event publishing
+ */
+const createPublishSpan = (eventName, data) => {
+    return tracer.startSpan(`nats.publish.${eventName}`, {
+        attributes: {
+            'messaging.system': 'nats',
+            'messaging.destination': eventName,
+            'messaging.operation': 'publish',
+        },
+    });
+};
+exports.createPublishSpan = createPublishSpan;
+/**
+ * Create a span for NATS event listening
+ */
+const createListenSpan = (eventName, msg) => {
+    const context = (0, exports.extractTracingContext)(msg);
+    return tracer.startSpan(`nats.listen.${eventName}`, {
+        attributes: {
+            'messaging.system': 'nats',
+            'messaging.destination': eventName,
+            'messaging.operation': 'receive',
+        },
+    });
+};
+exports.createListenSpan = createListenSpan;

package/build/tracing/setup.d.ts

@@ -0,0 +1 @@
+export declare const setupTracing: (serviceName: string) => import("@opentelemetry/sdk-node").NodeSDK | null;

package/build/tracing/setup.js

@@ -0,0 +1,14 @@
+"use strict";
+// This file should be imported at the very top of your service's index.ts file
+// BEFORE any other imports to ensure tracing is initialized early
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupTracing = void 0;
+const tracer_1 = require("./tracer");
+const setupTracing = (serviceName) => {
+    // Only initialize if JAEGER_ENABLED is true (default: true in production)
+    if (process.env.JAEGER_ENABLED !== 'false') {
+        return (0, tracer_1.initTracer)(serviceName);
+    }
+    return null;
+};
+exports.setupTracing = setupTracing;

package/build/tracing/tracer.d.ts

@@ -0,0 +1,2 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+export declare const initTracer: (serviceName: string) => NodeSDK;

package/build/tracing/tracer.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initTracer = void 0;
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const auto_instrumentations_node_1 = require("@opentelemetry/auto-instrumentations-node");
+const exporter_jaeger_1 = require("@opentelemetry/exporter-jaeger");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const initTracer = (serviceName) => {
+    const jaegerExporter = new exporter_jaeger_1.JaegerExporter({
+        endpoint: process.env.JAEGER_ENDPOINT || 'http://jaeger-srv:14268/api/traces',
+    });
+    const sdk = new sdk_node_1.NodeSDK({
+        resource: new resources_1.Resource({
+            [semantic_conventions_1.SemanticResourceAttributes.SERVICE_NAME]: serviceName,
+        }),
+        traceExporter: jaegerExporter,
+        instrumentations: [
+            (0, auto_instrumentations_node_1.getNodeAutoInstrumentations)({
+                // Disable fs instrumentation to reduce noise
+                '@opentelemetry/instrumentation-fs': {
+                    enabled: false,
+                },
+            }),
+        ],
+    });
+    sdk.start();
+    console.log(`Tracing initialized for service: ${serviceName}`);
+    return sdk;
+};
+exports.initTracer = initTracer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mttickets12/common",
-  "version": "1.0.22",
+  "version": "1.0.25",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "files": [
@@ -20,6 +20,13 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "@opentelemetry/api": "^1.8.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.45.0",
+    "@opentelemetry/core": "^1.24.0",
+    "@opentelemetry/exporter-jaeger": "^1.24.0",
+    "@opentelemetry/resources": "^1.24.0",
+    "@opentelemetry/sdk-node": "^0.50.0",
+    "@opentelemetry/semantic-conventions": "^1.24.0",
     "@types/cookie-session": "^2.0.49",
     "@types/express": "^4.17.21",
     "@types/jsonwebtoken": "^9.0.10",