@mereb/shared-packages 0.0.5

package/README.md

@@ -0,0 +1,44 @@
+# Shared Mereb Backend Packages
+
+This package exposes the shared Fastify/OpenTelemetry helpers used across the backend services. It is built independently with TypeScript and published as `@services/shared`.
+
+## Local development
+
+```bash
+pnpm install
+pnpm --filter @services/shared lint
+pnpm --filter @services/shared typecheck
+pnpm --filter @services/shared build
+```
+
+The compiled JavaScript and type definitions land in `dist/`.
+
+## Jenkins publishing workflow
+
+The folder contains its own `Jenkinsfile` plus `.ci/ci.yml` so it can run through the `mereb-jenkins` shared library just like the services do.
+
+1. **Version bump** – run `pnpm --filter @services/shared version:bump` (optionally pass `major` or `minor`). The script inspects the latest `v*` tag and updates `package.json` to the next version so the release tag and package stay in sync.
+2. **Push to `main`** – Jenkins runs the branch build. After it lints/builds, the `release.autoTag` stage (configured with `allowDirty: true` because the build leaves `node_modules/` around) creates and pushes the next `v<semver>` tag.
+3. **Release stages** – in the same build, the new `releaseStages` block uses that tag (`RELEASE_TAG`) to run `pnpm publish` and then the `release.github` stage publishes release notes.
+4. **Jenkins job** – create a Multibranch Pipeline pointing at this repository. Tags are optional now, but still enable tag discovery if you want Jenkins to react to manual tags.
+5. **Credentials** – add an `npm-registry-token` secret text credential in Jenkins for npm publish, plus `github-credentials` for tagging/GitHub releases. The pipeline writes the npm token to `.npmrc` during the publish stage.
+6. **Registry override (optional)** – set the job environment variable `NPM_REGISTRY` if you publish somewhere other than `https://registry.npmjs.org`.
+
+Every successful `main` build with a version bump now produces a tag, publishes the package, and creates GitHub release notes without waiting for a second job.
+
+> Tip: The bump script accepts `major`, `minor`, or `patch` (default) so you can control which segment changes: `pnpm --filter @services/shared version:bump minor`.
+
+> The repo installs a Husky `pre-commit` hook that automatically runs `pnpm run version:bump` and stages `services/shared/package.json`, keeping the version aligned with the next release tag before every commit. Jenkins sets `HUSKY=0` (see `.ci/ci.yml`) so the hook never runs in CI; locally you can bypass it with `HUSKY=0 git commit ...`.
+
+## Manual publish (fallback)
+
+If you need to publish outside Jenkins:
+
+```bash
+cd services/shared
+pnpm install
+pnpm lint && pnpm typecheck && pnpm build
+NPM_TOKEN=... pnpm publish --registry https://registry.npmjs.org --no-git-checks
+```
+
+Ensure the git tag matches the package version before publishing so the CI job can take over again on the next release.

package/dist/auth/jwks.d.ts

@@ -0,0 +1,12 @@
+import { type JWTPayload } from 'jose';
+import type { IncomingHttpHeaders } from 'node:http';
+export interface VerifyJwtOptions {
+    issuer: string;
+    audience?: string | string[];
+    cacheTtlMs?: number;
+}
+export declare function initJwks(issuer: string): Promise<void>;
+export declare function verifyJwt(token: string, { issuer, audience }: VerifyJwtOptions): Promise<JWTPayload>;
+export declare function extractUserId(payload: JWTPayload): string | undefined;
+export declare function parseAuthHeader(headers: IncomingHttpHeaders): string | undefined;
+//# sourceMappingURL=jwks.d.ts.map

package/dist/auth/jwks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../../src/auth/jwks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAIrD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,iBAI5C;AAED,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,gBAAgB,uBAYvC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,sBAEhD;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,mBAAmB,GAC3B,MAAM,GAAG,SAAS,CAMpB"}

package/dist/auth/jwks.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initJwks = initJwks;
+exports.verifyJwt = verifyJwt;
+exports.extractUserId = extractUserId;
+exports.parseAuthHeader = parseAuthHeader;
+const jose_1 = require("jose");
+let jwks;
+async function initJwks(issuer) {
+    jwks = (0, jose_1.createRemoteJWKSet)(new URL(`${issuer.replace(/\/$/, '')}/protocol/openid-connect/certs`));
+}
+async function verifyJwt(token, { issuer, audience }) {
+    if (!jwks) {
+        await initJwks(issuer);
+    }
+    const { payload } = await (0, jose_1.jwtVerify)(token, jwks, {
+        issuer,
+        audience
+    });
+    return payload;
+}
+function extractUserId(payload) {
+    return typeof payload.sub === 'string' ? payload.sub : undefined;
+}
+function parseAuthHeader(headers) {
+    const auth = headers.authorization;
+    if (!auth || !auth.startsWith('Bearer ')) {
+        return undefined;
+    }
+    return auth.slice('Bearer '.length);
+}

package/dist/cache/redis.d.ts

@@ -0,0 +1,7 @@
+import { type RedisClientType } from '@redis/client';
+export interface RedisOptions {
+    url: string;
+}
+export declare function getRedisClient(options: RedisOptions): Promise<RedisClientType>;
+export declare function disconnectRedis(): Promise<void>;
+//# sourceMappingURL=redis.d.ts.map

package/dist/cache/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/cache/redis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAOnE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CASpF;AAED,wBAAsB,eAAe,kBAKpC"}

package/dist/cache/redis.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRedisClient = getRedisClient;
+exports.disconnectRedis = disconnectRedis;
+const client_1 = require("@redis/client");
+const pino_1 = __importDefault(require("pino"));
+const logger = (0, pino_1.default)({ name: 'redis' });
+let client;
+async function getRedisClient(options) {
+    if (!client) {
+        client = (0, client_1.createClient)({ url: options.url });
+        client.on('error', (err) => {
+            logger.error({ err }, 'Redis connection error');
+        });
+        await client.connect();
+    }
+    return client;
+}
+async function disconnectRedis() {
+    if (client) {
+        await client.disconnect();
+        client = undefined;
+    }
+}

package/dist/config/env.d.ts

@@ -0,0 +1,10 @@
+export interface EnvConfigOptions<T extends string> {
+    defaults?: Partial<Record<T, string>>;
+    required?: T[];
+}
+export declare function loadEnv(path?: string): void;
+export declare function getEnv<T extends string>(key: T, fallback?: string): string;
+export declare function mustGetEnv<T extends string>(keys: T[]): Record<T, string>;
+export declare function getBooleanEnv(key: string, fallback?: boolean): boolean;
+export declare function getNumberEnv(key: string, fallback?: number): number;
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;CAChB;AAED,wBAAgB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,QAKpC;AAED,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAM1E;AAED,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CASzE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAMpE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAanE"}

package/dist/config/env.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEnv = loadEnv;
+exports.getEnv = getEnv;
+exports.mustGetEnv = mustGetEnv;
+exports.getBooleanEnv = getBooleanEnv;
+exports.getNumberEnv = getNumberEnv;
+const dotenv_1 = __importDefault(require("dotenv"));
+let loaded = false;
+function loadEnv(path) {
+    if (!loaded) {
+        dotenv_1.default.config(path ? { path } : undefined);
+        loaded = true;
+    }
+}
+function getEnv(key, fallback) {
+    const value = process.env[key] ?? fallback;
+    if (value === undefined) {
+        throw new Error(`Missing required environment variable ${key}`);
+    }
+    return value;
+}
+function mustGetEnv(keys) {
+    return keys.reduce((acc, key) => {
+        const value = process.env[key];
+        if (value === undefined) {
+            throw new Error(`Missing required environment variable ${key}`);
+        }
+        acc[key] = value;
+        return acc;
+    }, {});
+}
+function getBooleanEnv(key, fallback = false) {
+    const value = process.env[key];
+    if (value === undefined) {
+        return fallback;
+    }
+    return ['true', '1', 'yes', 'on'].includes(value.toLowerCase());
+}
+function getNumberEnv(key, fallback) {
+    const value = process.env[key];
+    if (value === undefined) {
+        if (fallback === undefined) {
+            throw new Error(`Missing required numeric environment variable ${key}`);
+        }
+        return fallback;
+    }
+    const numeric = Number(value);
+    if (Number.isNaN(numeric)) {
+        throw new Error(`Environment variable ${key} must be a number`);
+    }
+    return numeric;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './auth/jwks';
+export * from './cache/redis';
+export * from './config/env';
+export * from './logger';
+export * from './messaging/kafka';
+export * from './observability/otel';
+export * from './media/s3';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+"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("./auth/jwks"), exports);
+__exportStar(require("./cache/redis"), exports);
+__exportStar(require("./config/env"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./messaging/kafka"), exports);
+__exportStar(require("./observability/otel"), exports);
+__exportStar(require("./media/s3"), exports);

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+import pino from 'pino';
+export declare function createLogger(name: string): pino.Logger<never, boolean>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,+BASxC"}

package/dist/logger.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+const pino_1 = __importDefault(require("pino"));
+function createLogger(name) {
+    return (0, pino_1.default)({
+        name,
+        level: process.env.LOG_LEVEL ?? 'info',
+        transport: process.env.NODE_ENV === 'production'
+            ? undefined
+            : { target: 'pino-pretty', options: { translateTime: 'SYS:standard' } }
+    });
+}

package/dist/media/s3.d.ts

@@ -0,0 +1,3 @@
+export declare function signMediaUrl(key: string): string;
+export declare function signUploadKey(ownerId: string, filename: string): string;
+//# sourceMappingURL=s3.d.ts.map

package/dist/media/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/media/s3.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvE"}

package/dist/media/s3.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signMediaUrl = signMediaUrl;
+exports.signUploadKey = signUploadKey;
+function signMediaUrl(key) {
+    const base = process.env.MEDIA_CDN_ORIGIN ?? 'https://cdn.example.com';
+    return `${base.replace(/\/$/, '')}/${key}`;
+}
+function signUploadKey(ownerId, filename) {
+    const timestamp = Date.now();
+    return `users/${ownerId}/${timestamp}-${filename}`;
+}

package/dist/messaging/kafka.d.ts

@@ -0,0 +1,6 @@
+import { Kafka, type KafkaConfig, type Producer, type Consumer } from 'kafkajs';
+export declare function getKafka(config: KafkaConfig): Kafka;
+export declare function getProducer(config: KafkaConfig): Promise<Producer>;
+export declare function createConsumer(config: KafkaConfig, groupId: string): Promise<Consumer>;
+export declare function disconnectProducer(): Promise<void>;
+//# sourceMappingURL=kafka.d.ts.map

package/dist/messaging/kafka.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kafka.d.ts","sourceRoot":"","sources":["../../src/messaging/kafka.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAKhF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,SAK3C;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAMxE;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAK5F;AAED,wBAAsB,kBAAkB,kBAKvC"}

package/dist/messaging/kafka.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKafka = getKafka;
+exports.getProducer = getProducer;
+exports.createConsumer = createConsumer;
+exports.disconnectProducer = disconnectProducer;
+const kafkajs_1 = require("kafkajs");
+let kafkaInstance;
+let producerInstance;
+function getKafka(config) {
+    if (!kafkaInstance) {
+        kafkaInstance = new kafkajs_1.Kafka(config);
+    }
+    return kafkaInstance;
+}
+async function getProducer(config) {
+    if (!producerInstance) {
+        producerInstance = getKafka(config).producer();
+        await producerInstance.connect();
+    }
+    return producerInstance;
+}
+async function createConsumer(config, groupId) {
+    const kafka = getKafka(config);
+    const consumer = kafka.consumer({ groupId });
+    await consumer.connect();
+    return consumer;
+}
+async function disconnectProducer() {
+    if (producerInstance) {
+        await producerInstance.disconnect();
+        producerInstance = undefined;
+    }
+}

package/dist/observability/otel.d.ts

@@ -0,0 +1,8 @@
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+export interface OtelConfig {
+    serviceName: string;
+    otlpEndpoint?: string;
+    instrumentations?: Instrumentation[];
+}
+export declare function initTelemetry({ serviceName, otlpEndpoint, instrumentations }: OtelConfig): void;
+//# sourceMappingURL=otel.d.ts.map

package/dist/observability/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/observability/otel.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAOtE,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;CACtC;AAED,wBAAgB,aAAa,CAAC,EAC5B,WAAW,EACX,YAAY,EACZ,gBAAqB,EACtB,EAAE,UAAU,QA0BZ"}

package/dist/observability/otel.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initTelemetry = initTelemetry;
+const api_1 = require("@opentelemetry/api");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+const exporter_trace_otlp_grpc_1 = require("@opentelemetry/exporter-trace-otlp-grpc");
+const instrumentation_1 = require("@opentelemetry/instrumentation");
+api_1.diag.setLogger(new api_1.DiagConsoleLogger(), api_1.DiagLogLevel.INFO);
+let initialized = false;
+function initTelemetry({ serviceName, otlpEndpoint, instrumentations = [] }) {
+    if (initialized) {
+        return;
+    }
+    const resource = new resources_1.Resource({
+        [semantic_conventions_1.SemanticResourceAttributes.SERVICE_NAME]: serviceName
+    });
+    const provider = new sdk_trace_node_1.NodeTracerProvider({ resource });
+    if (otlpEndpoint) {
+        provider.addSpanProcessor(new sdk_trace_base_1.BatchSpanProcessor(new exporter_trace_otlp_grpc_1.OTLPTraceExporter({ url: otlpEndpoint })));
+    }
+    provider.register();
+    if (instrumentations.length) {
+        (0, instrumentation_1.registerInstrumentations)({ instrumentations });
+    }
+    initialized = true;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@mereb/shared-packages",
+  "version": "0.0.5",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@fastify/cors": "^9.0.1",
+    "@fastify/rate-limit": "^10.2.0",
+    "@fastify/sensible": "^5.6.0",
+    "@fastify/under-pressure": "^9.0.3",
+    "@opentelemetry/api": "^1.8.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.52.0",
+    "@opentelemetry/host-metrics": "^0.36.2",
+    "@opentelemetry/instrumentation": "^0.52.0",
+    "@opentelemetry/instrumentation-fastify": "^0.52.0",
+    "@opentelemetry/instrumentation-http": "^0.52.0",
+    "@opentelemetry/resources": "^1.8.0",
+    "@opentelemetry/sdk-metrics": "^1.18.0",
+    "@opentelemetry/sdk-trace-base": "^1.18.0",
+    "@opentelemetry/sdk-trace-node": "^1.18.0",
+    "@opentelemetry/semantic-conventions": "^1.23.0",
+    "@redis/client": "^1.5.12",
+    "dotenv": "^16.4.5",
+    "jose": "^5.2.3",
+    "kafkajs": "^2.2.4",
+    "pino": "^9.2.0",
+    "pino-pretty": "^10.3.1"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "@types/node": "^20.12.7",
+    "eslint": "^8.57.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf dist",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "typecheck": "tsc --noEmit",
+    "version:bump": "node ./scripts/bump-version.mjs"
+  }
+}