@qelos/api-kit 3.11.11 → 4.0.0

package/dist/api-version.d.ts

@@ -0,0 +1,37 @@
+import type { NextFunction, Request, Response } from 'express';
+/** Latest API version when no `Accept-Version` header and no `/api/vN/` URL prefix. */
+export declare const LATEST_API_VERSION = "v1";
+export declare const SUPPORTED_API_VERSIONS: Set<string>;
+/**
+ * Strips `/api/vN` from the URL path so existing `/api/...` mounts keep matching.
+ * Only applies to paths under `/api/` (not `/internal-api/`).
+ */
+export declare function stripApiVersionFromUrl(fullUrl: string): {
+    rewritten: string;
+    pathVersion?: string;
+};
+export declare function normalizeAcceptVersionHeader(raw: string | undefined): string | undefined;
+export declare function resolveApiVersion(pathVersion: string | undefined, acceptHeaderRaw: string | undefined, latest: string, supported: Set<string>): {
+    version: string;
+} | {
+    error: string;
+    status: number;
+};
+export type ApiVersionMiddlewareOptions = {
+    latest?: string;
+    supported?: Set<string>;
+};
+export declare function apiVersionMiddleware(options?: ApiVersionMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
+export declare function setApiVersionResponseHeader(req: Request, res: Response): void;
+/**
+ * Use with `http-proxy-middleware` `onProxyRes` so proxied API responses include `X-API-Version`.
+ */
+export declare function onProxyResSetApiVersion(_proxyRes: NodeJS.ReadableStream, req: Request, res: Response): void;
+declare global {
+    namespace Express {
+        interface Request {
+            /** Resolved API version (e.g. `v1`) after gateway middleware runs. */
+            apiVersion?: string;
+        }
+    }
+}

package/dist/api-version.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_API_VERSIONS = exports.LATEST_API_VERSION = void 0;
+exports.stripApiVersionFromUrl = stripApiVersionFromUrl;
+exports.normalizeAcceptVersionHeader = normalizeAcceptVersionHeader;
+exports.resolveApiVersion = resolveApiVersion;
+exports.apiVersionMiddleware = apiVersionMiddleware;
+exports.setApiVersionResponseHeader = setApiVersionResponseHeader;
+exports.onProxyResSetApiVersion = onProxyResSetApiVersion;
+/** Latest API version when no `Accept-Version` header and no `/api/vN/` URL prefix. */
+exports.LATEST_API_VERSION = 'v1';
+exports.SUPPORTED_API_VERSIONS = new Set([exports.LATEST_API_VERSION]);
+/**
+ * Strips `/api/vN` from the URL path so existing `/api/...` mounts keep matching.
+ * Only applies to paths under `/api/` (not `/internal-api/`).
+ */
+function stripApiVersionFromUrl(fullUrl) {
+    const qIndex = fullUrl.indexOf('?');
+    const path = qIndex >= 0 ? fullUrl.slice(0, qIndex) : fullUrl;
+    const query = qIndex >= 0 ? fullUrl.slice(qIndex) : '';
+    const m = path.match(/^\/api\/(v\d+)(\/.*)?$/);
+    if (!m) {
+        return { rewritten: fullUrl };
+    }
+    const rest = m[2] ?? '/';
+    const rewrittenPath = '/api' + rest;
+    return { rewritten: rewrittenPath + query, pathVersion: m[1] };
+}
+function normalizeAcceptVersionHeader(raw) {
+    if (raw === undefined || raw === null) {
+        return undefined;
+    }
+    const t = String(raw).trim().toLowerCase();
+    if (!t) {
+        return undefined;
+    }
+    if (!/^v\d+$/.test(t)) {
+        return undefined;
+    }
+    return t;
+}
+function resolveApiVersion(pathVersion, acceptHeaderRaw, latest, supported) {
+    const headerVersion = normalizeAcceptVersionHeader(acceptHeaderRaw);
+    const headerPresent = typeof acceptHeaderRaw === 'string' && acceptHeaderRaw.trim().length > 0;
+    if (headerPresent && !headerVersion) {
+        return { error: 'Invalid Accept-Version header', status: 400 };
+    }
+    if (pathVersion && headerVersion && pathVersion !== headerVersion) {
+        return {
+            error: 'Accept-Version header does not match URL version prefix',
+            status: 400,
+        };
+    }
+    const resolved = pathVersion ?? headerVersion ?? latest;
+    if (!supported.has(resolved)) {
+        return { error: `Unsupported API version: ${resolved}`, status: 400 };
+    }
+    return { version: resolved };
+}
+function apiVersionMiddleware(options = {}) {
+    const latest = options.latest ?? exports.LATEST_API_VERSION;
+    const supported = options.supported ?? exports.SUPPORTED_API_VERSIONS;
+    return function handleApiVersion(req, res, next) {
+        const { rewritten, pathVersion } = stripApiVersionFromUrl(req.url);
+        if (rewritten !== req.url) {
+            req.url = rewritten;
+        }
+        const rawHeader = req.headers['accept-version'];
+        const headerStr = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+        const resolved = resolveApiVersion(pathVersion, headerStr, latest, supported);
+        if ('error' in resolved) {
+            res.status(resolved.status).json({ message: resolved.error }).end();
+            return;
+        }
+        req.apiVersion = resolved.version;
+        next();
+    };
+}
+function setApiVersionResponseHeader(req, res) {
+    const version = req.apiVersion ?? exports.LATEST_API_VERSION;
+    res.setHeader('X-API-Version', version);
+}
+/**
+ * Use with `http-proxy-middleware` `onProxyRes` so proxied API responses include `X-API-Version`.
+ */
+function onProxyResSetApiVersion(_proxyRes, req, res) {
+    setApiVersionResponseHeader(req, res);
+}
+//# sourceMappingURL=api-version.js.map

package/dist/api-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-version.js","sourceRoot":"","sources":["../src/api-version.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export * from './user-middlewares';
 export * from './emit-internal-event';
 export * from './response-error';
 export * from './request-utils';
+export * from './api-version';

package/dist/index.js

@@ -22,4 +22,5 @@ __exportStar(require("./user-middlewares"), exports);
 __exportStar(require("./emit-internal-event"), exports);
 __exportStar(require("./response-error"), exports);
 __exportStar(require("./request-utils"), exports);
+__exportStar(require("./api-version"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA0B;AAC1B,wCAAqB;AACrB,2CAAwB;AACxB,qDAAkC;AAClC,qDAAkC;AAClC,wDAAqC;AACrC,mDAAiC;AACjC,kDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA0B;AAC1B,wCAAqB;AACrB,2CAAwB;AACxB,qDAAkC;AAClC,qDAAkC;AAClC,wDAAqC;AACrC,mDAAiC;AACjC,kDAAgC;AAChC,gDAA8B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qelos/api-kit",
-  "version": "3.11.11",
+  "version": "4.0.0",
   "description": "API-Kit package to help with qelos infrastructure and reuse capabilities across services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,9 +18,11 @@
   "gitHead": "13468bc51557291935b96b1aeaa837b8b52861e8",
   "devDependencies": {
     "@types/node": "^22.5.4",
+    "tsx": "^4.20.4",
     "typescript": "^5.4.5"
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "node --import tsx --test \"src/**/*.test.ts\""
   }
 }

package/src/api-version.test.ts

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  LATEST_API_VERSION,
+  normalizeAcceptVersionHeader,
+  resolveApiVersion,
+  SUPPORTED_API_VERSIONS,
+  stripApiVersionFromUrl,
+} from './api-version';
+
+test('stripApiVersionFromUrl leaves non-versioned URLs unchanged', () => {
+  assert.equal(stripApiVersionFromUrl('/api/foo').rewritten, '/api/foo');
+  assert.equal(stripApiVersionFromUrl('/internal-api/health').rewritten, '/internal-api/health');
+});
+
+test('stripApiVersionFromUrl rewrites /api/v1 prefix and preserves query', () => {
+  const r = stripApiVersionFromUrl('/api/v1/blueprints/x?a=1');
+  assert.equal(r.rewritten, '/api/blueprints/x?a=1');
+  assert.equal(r.pathVersion, 'v1');
+});
+
+test('stripApiVersionFromUrl maps bare /api/v1 to /api/', () => {
+  const r = stripApiVersionFromUrl('/api/v1');
+  assert.equal(r.rewritten, '/api/');
+  assert.equal(r.pathVersion, 'v1');
+});
+
+test('normalizeAcceptVersionHeader', () => {
+  assert.equal(normalizeAcceptVersionHeader('v1'), 'v1');
+  assert.equal(normalizeAcceptVersionHeader('V1'), 'v1');
+  assert.equal(normalizeAcceptVersionHeader('  v2  '), 'v2');
+  assert.equal(normalizeAcceptVersionHeader('bad'), undefined);
+  assert.equal(normalizeAcceptVersionHeader(''), undefined);
+  assert.equal(normalizeAcceptVersionHeader(undefined), undefined);
+});
+
+test('resolveApiVersion defaults to latest', () => {
+  const r = resolveApiVersion(undefined, undefined, LATEST_API_VERSION, SUPPORTED_API_VERSIONS);
+  assert.ok(!('error' in r));
+  if ('version' in r) {
+    assert.equal(r.version, LATEST_API_VERSION);
+  }
+});
+
+test('resolveApiVersion uses path over header when equal', () => {
+  const r = resolveApiVersion('v1', 'v1', LATEST_API_VERSION, SUPPORTED_API_VERSIONS);
+  assert.ok(!('error' in r));
+  if ('version' in r) {
+    assert.equal(r.version, 'v1');
+  }
+});
+
+test('resolveApiVersion rejects path/header mismatch', () => {
+  const r = resolveApiVersion('v1', 'v2', LATEST_API_VERSION, SUPPORTED_API_VERSIONS);
+  assert.ok('error' in r);
+});
+
+test('resolveApiVersion rejects unsupported version', () => {
+  const r = resolveApiVersion(undefined, 'v99', LATEST_API_VERSION, SUPPORTED_API_VERSIONS);
+  assert.ok('error' in r);
+});
+
+test('resolveApiVersion rejects invalid header when header present', () => {
+  const r = resolveApiVersion(undefined, 'nope', LATEST_API_VERSION, SUPPORTED_API_VERSIONS);
+  assert.ok('error' in r);
+});

package/src/api-version.ts

@@ -0,0 +1,124 @@
+import type { NextFunction, Request, Response } from 'express';
+
+/** Latest API version when no `Accept-Version` header and no `/api/vN/` URL prefix. */
+export const LATEST_API_VERSION = 'v1';
+
+export const SUPPORTED_API_VERSIONS = new Set<string>([LATEST_API_VERSION]);
+
+/**
+ * Strips `/api/vN` from the URL path so existing `/api/...` mounts keep matching.
+ * Only applies to paths under `/api/` (not `/internal-api/`).
+ */
+export function stripApiVersionFromUrl(fullUrl: string): {
+  rewritten: string;
+  pathVersion?: string;
+} {
+  const qIndex = fullUrl.indexOf('?');
+  const path = qIndex >= 0 ? fullUrl.slice(0, qIndex) : fullUrl;
+  const query = qIndex >= 0 ? fullUrl.slice(qIndex) : '';
+
+  const m = path.match(/^\/api\/(v\d+)(\/.*)?$/);
+  if (!m) {
+    return { rewritten: fullUrl };
+  }
+  const rest = m[2] ?? '/';
+  const rewrittenPath = '/api' + rest;
+  return { rewritten: rewrittenPath + query, pathVersion: m[1] };
+}
+
+export function normalizeAcceptVersionHeader(raw: string | undefined): string | undefined {
+  if (raw === undefined || raw === null) {
+    return undefined;
+  }
+  const t = String(raw).trim().toLowerCase();
+  if (!t) {
+    return undefined;
+  }
+  if (!/^v\d+$/.test(t)) {
+    return undefined;
+  }
+  return t;
+}
+
+export function resolveApiVersion(
+  pathVersion: string | undefined,
+  acceptHeaderRaw: string | undefined,
+  latest: string,
+  supported: Set<string>
+): { version: string } | { error: string; status: number } {
+  const headerVersion = normalizeAcceptVersionHeader(acceptHeaderRaw);
+  const headerPresent = typeof acceptHeaderRaw === 'string' && acceptHeaderRaw.trim().length > 0;
+
+  if (headerPresent && !headerVersion) {
+    return { error: 'Invalid Accept-Version header', status: 400 };
+  }
+
+  if (pathVersion && headerVersion && pathVersion !== headerVersion) {
+    return {
+      error: 'Accept-Version header does not match URL version prefix',
+      status: 400,
+    };
+  }
+
+  const resolved = pathVersion ?? headerVersion ?? latest;
+
+  if (!supported.has(resolved)) {
+    return { error: `Unsupported API version: ${resolved}`, status: 400 };
+  }
+
+  return { version: resolved };
+}
+
+export type ApiVersionMiddlewareOptions = {
+  latest?: string;
+  supported?: Set<string>;
+};
+
+export function apiVersionMiddleware(options: ApiVersionMiddlewareOptions = {}) {
+  const latest = options.latest ?? LATEST_API_VERSION;
+  const supported = options.supported ?? SUPPORTED_API_VERSIONS;
+
+  return function handleApiVersion(req: Request, res: Response, next: NextFunction) {
+    const { rewritten, pathVersion } = stripApiVersionFromUrl(req.url);
+    if (rewritten !== req.url) {
+      req.url = rewritten;
+    }
+
+    const rawHeader = req.headers['accept-version'];
+    const headerStr = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+
+    const resolved = resolveApiVersion(pathVersion, headerStr, latest, supported);
+    if ('error' in resolved) {
+      res.status(resolved.status).json({ message: resolved.error }).end();
+      return;
+    }
+
+    req.apiVersion = resolved.version;
+    next();
+  };
+}
+
+export function setApiVersionResponseHeader(req: Request, res: Response) {
+  const version = req.apiVersion ?? LATEST_API_VERSION;
+  res.setHeader('X-API-Version', version);
+}
+
+/**
+ * Use with `http-proxy-middleware` `onProxyRes` so proxied API responses include `X-API-Version`.
+ */
+export function onProxyResSetApiVersion(
+  _proxyRes: NodeJS.ReadableStream,
+  req: Request,
+  res: Response
+) {
+  setApiVersionResponseHeader(req, res);
+}
+
+declare global {
+  namespace Express {
+    interface Request {
+      /** Resolved API version (e.g. `v1`) after gateway middleware runs. */
+      apiVersion?: string;
+    }
+  }
+}

package/src/index.ts

@@ -5,4 +5,5 @@ export * from './internal-service'
 export * from './user-middlewares'
 export * from './emit-internal-event'
 export * from './response-error';
-export * from './request-utils';
+export * from './request-utils';
+export * from './api-version';

package/tsconfig.json

@@ -17,6 +17,7 @@
   },
   "exclude": [
     "node_modules",
-    "dist"
+    "dist",
+    "**/*.test.ts"
   ],
 }