@pipeline-builder/api-core 3.1.0

package/lib/utils/alias-resolver.js

@@ -0,0 +1,49 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRecipientAlias = resolveRecipientAlias;
+exports._resetAliasCache = _resetAliasCache;
+const auth_1 = require("../middleware/auth");
+/** Lazily-cached set of support aliases, parsed from SUPPORT_ALIASES on first access. */
+let _supportAliases;
+function getSupportAliases() {
+    if (!_supportAliases) {
+        const raw = process.env.SUPPORT_ALIASES || '';
+        _supportAliases = new Set(raw
+            .split(',')
+            .map(alias => alias.trim().toLowerCase())
+            .filter(alias => alias.length > 0));
+    }
+    return _supportAliases;
+}
+/**
+ * Resolve an email-like alias to an actual organization ID.
+ *
+ * If the input matches a configured support alias, it resolves to the system
+ * org ID. Otherwise the input is returned as-is (lowercased).
+ */
+function resolveRecipientAlias(recipientOrgId) {
+    const normalized = recipientOrgId.trim().toLowerCase();
+    const aliases = getSupportAliases();
+    if (aliases.has(normalized)) {
+        return {
+            resolvedOrgId: auth_1.SYSTEM_ORG_ID,
+            wasAlias: true,
+            originalValue: recipientOrgId,
+        };
+    }
+    return {
+        resolvedOrgId: normalized,
+        wasAlias: false,
+        originalValue: recipientOrgId,
+    };
+}
+/**
+ * Reset the cached aliases (for testing purposes only).
+ * @internal
+ */
+function _resetAliasCache() {
+    _supportAliases = undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWxpYXMtcmVzb2x2ZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdXRpbHMvYWxpYXMtcmVzb2x2ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7O0FBb0N0QyxzREFpQkM7QUFNRCw0Q0FFQztBQTNERCw2Q0FBbUQ7QUFFbkQseUZBQXlGO0FBQ3pGLElBQUksZUFBd0MsQ0FBQztBQUU3QyxTQUFTLGlCQUFpQjtJQUN4QixJQUFJLENBQUMsZUFBZSxFQUFFLENBQUM7UUFDckIsTUFBTSxHQUFHLEdBQUcsT0FBTyxDQUFDLEdBQUcsQ0FBQyxlQUFlLElBQUksRUFBRSxDQUFDO1FBQzlDLGVBQWUsR0FBRyxJQUFJLEdBQUcsQ0FDdkIsR0FBRzthQUNBLEtBQUssQ0FBQyxHQUFHLENBQUM7YUFDVixHQUFHLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQyxLQUFLLENBQUMsSUFBSSxFQUFFLENBQUMsV0FBVyxFQUFFLENBQUM7YUFDeEMsTUFBTSxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUMsS0FBSyxDQUFDLE1BQU0sR0FBRyxDQUFDLENBQUMsQ0FDckMsQ0FBQztJQUNKLENBQUM7SUFDRCxPQUFPLGVBQWUsQ0FBQztBQUN6QixDQUFDO0FBWUQ7Ozs7O0dBS0c7QUFDSCxTQUFnQixxQkFBcUIsQ0FBQyxjQUFzQjtJQUMxRCxNQUFNLFVBQVUsR0FBRyxjQUFjLENBQUMsSUFBSSxFQUFFLENBQUMsV0FBVyxFQUFFLENBQUM7SUFDdkQsTUFBTSxPQUFPLEdBQUcsaUJBQWlCLEVBQUUsQ0FBQztJQUVwQyxJQUFJLE9BQU8sQ0FBQyxHQUFHLENBQUMsVUFBVSxDQUFDLEVBQUUsQ0FBQztRQUM1QixPQUFPO1lBQ0wsYUFBYSxFQUFFLG9CQUFhO1lBQzVCLFFBQVEsRUFBRSxJQUFJO1lBQ2QsYUFBYSxFQUFFLGNBQWM7U0FDOUIsQ0FBQztJQUNKLENBQUM7SUFFRCxPQUFPO1FBQ0wsYUFBYSxFQUFFLFVBQVU7UUFDekIsUUFBUSxFQUFFLEtBQUs7UUFDZixhQUFhLEVBQUUsY0FBYztLQUM5QixDQUFDO0FBQ0osQ0FBQztBQUVEOzs7R0FHRztBQUNILFNBQWdCLGdCQUFnQjtJQUM5QixlQUFlLEdBQUcsU0FBUyxDQUFDO0FBQzlCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHsgU1lTVEVNX09SR19JRCB9IGZyb20gJy4uL21pZGRsZXdhcmUvYXV0aCc7XG5cbi8qKiBMYXppbHktY2FjaGVkIHNldCBvZiBzdXBwb3J0IGFsaWFzZXMsIHBhcnNlZCBmcm9tIFNVUFBPUlRfQUxJQVNFUyBvbiBmaXJzdCBhY2Nlc3MuICovXG5sZXQgX3N1cHBvcnRBbGlhc2VzOiBTZXQ8c3RyaW5nPiB8IHVuZGVmaW5lZDtcblxuZnVuY3Rpb24gZ2V0U3VwcG9ydEFsaWFzZXMoKTogU2V0PHN0cmluZz4ge1xuICBpZiAoIV9zdXBwb3J0QWxpYXNlcykge1xuICAgIGNvbnN0IHJhdyA9IHByb2Nlc3MuZW52LlNVUFBPUlRfQUxJQVNFUyB8fCAnJztcbiAgICBfc3VwcG9ydEFsaWFzZXMgPSBuZXcgU2V0KFxuICAgICAgcmF3XG4gICAgICAgIC5zcGxpdCgnLCcpXG4gICAgICAgIC5tYXAoYWxpYXMgPT4gYWxpYXMudHJpbSgpLnRvTG93ZXJDYXNlKCkpXG4gICAgICAgIC5maWx0ZXIoYWxpYXMgPT4gYWxpYXMubGVuZ3RoID4gMCksXG4gICAgKTtcbiAgfVxuICByZXR1cm4gX3N1cHBvcnRBbGlhc2VzO1xufVxuXG4vKiogUmVzdWx0IG9mIGFsaWFzIHJlc29sdXRpb24uICovXG5leHBvcnQgaW50ZXJmYWNlIEFsaWFzUmVzb2x1dGlvbiB7XG4gIC8qKiBUaGUgcmVzb2x2ZWQgb3JnYW5pemF0aW9uIElEIChlLmcuLCAnc3lzdGVtJykuICovXG4gIHJlc29sdmVkT3JnSWQ6IHN0cmluZztcbiAgLyoqIFdoZXRoZXIgdGhlIGlucHV0IHdhcyBhbiBhbGlhcyB0aGF0IGdvdCByZXNvbHZlZC4gKi9cbiAgd2FzQWxpYXM6IGJvb2xlYW47XG4gIC8qKiBUaGUgb3JpZ2luYWwgaW5wdXQgdmFsdWUsIHVzZWZ1bCBmb3IgYXVkaXQgbG9nZ2luZy4gKi9cbiAgb3JpZ2luYWxWYWx1ZTogc3RyaW5nO1xufVxuXG4vKipcbiAqIFJlc29sdmUgYW4gZW1haWwtbGlrZSBhbGlhcyB0byBhbiBhY3R1YWwgb3JnYW5pemF0aW9uIElELlxuICpcbiAqIElmIHRoZSBpbnB1dCBtYXRjaGVzIGEgY29uZmlndXJlZCBzdXBwb3J0IGFsaWFzLCBpdCByZXNvbHZlcyB0byB0aGUgc3lzdGVtXG4gKiBvcmcgSUQuIE90aGVyd2lzZSB0aGUgaW5wdXQgaXMgcmV0dXJuZWQgYXMtaXMgKGxvd2VyY2FzZWQpLlxuICovXG5leHBvcnQgZnVuY3Rpb24gcmVzb2x2ZVJlY2lwaWVudEFsaWFzKHJlY2lwaWVudE9yZ0lkOiBzdHJpbmcpOiBBbGlhc1Jlc29sdXRpb24ge1xuICBjb25zdCBub3JtYWxpemVkID0gcmVjaXBpZW50T3JnSWQudHJpbSgpLnRvTG93ZXJDYXNlKCk7XG4gIGNvbnN0IGFsaWFzZXMgPSBnZXRTdXBwb3J0QWxpYXNlcygpO1xuXG4gIGlmIChhbGlhc2VzLmhhcyhub3JtYWxpemVkKSkge1xuICAgIHJldHVybiB7XG4gICAgICByZXNvbHZlZE9yZ0lkOiBTWVNURU1fT1JHX0lELFxuICAgICAgd2FzQWxpYXM6IHRydWUsXG4gICAgICBvcmlnaW5hbFZhbHVlOiByZWNpcGllbnRPcmdJZCxcbiAgICB9O1xuICB9XG5cbiAgcmV0dXJuIHtcbiAgICByZXNvbHZlZE9yZ0lkOiBub3JtYWxpemVkLFxuICAgIHdhc0FsaWFzOiBmYWxzZSxcbiAgICBvcmlnaW5hbFZhbHVlOiByZWNpcGllbnRPcmdJZCxcbiAgfTtcbn1cblxuLyoqXG4gKiBSZXNldCB0aGUgY2FjaGVkIGFsaWFzZXMgKGZvciB0ZXN0aW5nIHB1cnBvc2VzIG9ubHkpLlxuICogQGludGVybmFsXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBfcmVzZXRBbGlhc0NhY2hlKCk6IHZvaWQge1xuICBfc3VwcG9ydEFsaWFzZXMgPSB1bmRlZmluZWQ7XG59XG4iXX0=

package/lib/utils/headers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Express 5 header type.
+ */
+type HeaderValue = string | string[] | undefined;
+/**
+ * Extract a single string from a header value that may be string | string[] | undefined.
+ *
+ * @param value - Header value from Express request
+ * @returns First value if array, the value if string, or undefined
+ *
+ * @example
+ * ```typescript
+ * const orgId = getHeaderString(req.headers['x-org-id']);
+ * const auth = getHeaderString(req.headers.authorization);
+ * ```
+ */
+export declare function getHeaderString(value: HeaderValue): string | undefined;
+export {};

package/lib/utils/headers.js

@@ -0,0 +1,24 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHeaderString = getHeaderString;
+/**
+ * Extract a single string from a header value that may be string | string[] | undefined.
+ *
+ * @param value - Header value from Express request
+ * @returns First value if array, the value if string, or undefined
+ *
+ * @example
+ * ```typescript
+ * const orgId = getHeaderString(req.headers['x-org-id']);
+ * const auth = getHeaderString(req.headers.authorization);
+ * ```
+ */
+function getHeaderString(value) {
+    if (Array.isArray(value)) {
+        return value[0];
+    }
+    return value;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaGVhZGVycy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91dGlscy9oZWFkZXJzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDOztBQW1CdEMsMENBS0M7QUFqQkQ7Ozs7Ozs7Ozs7O0dBV0c7QUFDSCxTQUFnQixlQUFlLENBQUMsS0FBa0I7SUFDaEQsSUFBSSxLQUFLLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUM7UUFDekIsT0FBTyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDbEIsQ0FBQztJQUNELE9BQU8sS0FBSyxDQUFDO0FBQ2YsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIENvcHlyaWdodCAyMDI2IFBpcGVsaW5lIEJ1aWxkZXIgQ29udHJpYnV0b3JzXG4vLyBTUERYLUxpY2Vuc2UtSWRlbnRpZmllcjogQXBhY2hlLTIuMFxuXG4vKipcbiAqIEV4cHJlc3MgNSBoZWFkZXIgdHlwZS5cbiAqL1xudHlwZSBIZWFkZXJWYWx1ZSA9IHN0cmluZyB8IHN0cmluZ1tdIHwgdW5kZWZpbmVkO1xuXG4vKipcbiAqIEV4dHJhY3QgYSBzaW5nbGUgc3RyaW5nIGZyb20gYSBoZWFkZXIgdmFsdWUgdGhhdCBtYXkgYmUgc3RyaW5nIHwgc3RyaW5nW10gfCB1bmRlZmluZWQuXG4gKlxuICogQHBhcmFtIHZhbHVlIC0gSGVhZGVyIHZhbHVlIGZyb20gRXhwcmVzcyByZXF1ZXN0XG4gKiBAcmV0dXJucyBGaXJzdCB2YWx1ZSBpZiBhcnJheSwgdGhlIHZhbHVlIGlmIHN0cmluZywgb3IgdW5kZWZpbmVkXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGNvbnN0IG9yZ0lkID0gZ2V0SGVhZGVyU3RyaW5nKHJlcS5oZWFkZXJzWyd4LW9yZy1pZCddKTtcbiAqIGNvbnN0IGF1dGggPSBnZXRIZWFkZXJTdHJpbmcocmVxLmhlYWRlcnMuYXV0aG9yaXphdGlvbik7XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGdldEhlYWRlclN0cmluZyh2YWx1ZTogSGVhZGVyVmFsdWUpOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICBpZiAoQXJyYXkuaXNBcnJheSh2YWx1ZSkpIHtcbiAgICByZXR1cm4gdmFsdWVbMF07XG4gIH1cbiAgcmV0dXJuIHZhbHVlO1xufVxuIl19

package/lib/utils/identity.d.ts

@@ -0,0 +1,61 @@
+import { HttpRequest } from '../types/http';
+/**
+ * Identity information extracted from request headers.
+ */
+export interface RequestIdentity {
+    /** Organization ID from x-org-id header */
+    readonly orgId?: string;
+    /** User ID from x-user-id header */
+    readonly userId?: string;
+    /** Request ID from x-request-id header */
+    readonly requestId?: string;
+    /** User role from x-user-role header (decoded from JWT) */
+    readonly role?: string;
+}
+/**
+ * Extract identity information from request headers.
+ *
+ * Extracts common identity headers used for multi-tenant authentication:
+ * - x-org-id: Organization identifier
+ * - x-user-id: User identifier
+ * - x-request-id: Request trace identifier
+ * - x-user-role: User role
+ *
+ * @param req - HTTP request object
+ * @returns Identity object with orgId, userId, requestId, and role
+ *
+ * @example
+ * ```typescript
+ * app.post('/api/resource', requireAuth, async (req, res) => {
+ *   const identity = getIdentity(req);
+ *
+ *   if (!identity.orgId) {
+ *     return sendError(res, 400, 'x-org-id header required');
+ *   }
+ *
+ *   // Use identity.orgId, identity.userId, etc.
+ * });
+ * ```
+ */
+export declare function getIdentity(req: HttpRequest): RequestIdentity;
+/**
+ * Validate that required identity fields are present.
+ *
+ * @param identity - Identity object to validate
+ * @param required - Array of required field names
+ * @returns Object with isValid boolean and missing fields array
+ *
+ * @example
+ * ```typescript
+ * const identity = getIdentity(req);
+ * const validation = validateIdentity(identity, ['orgId', 'userId']);
+ *
+ * if (!validation.isValid) {
+ *   return sendError(res, 400, `Missing required headers: ${validation.missing.join(', ')}`);
+ * }
+ * ```
+ */
+export declare function validateIdentity(identity: RequestIdentity, required: (keyof RequestIdentity)[]): {
+    isValid: boolean;
+    missing: string[];
+};

package/lib/utils/identity.js

@@ -0,0 +1,75 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIdentity = getIdentity;
+exports.validateIdentity = validateIdentity;
+const headers_1 = require("./headers");
+/**
+ * Extract identity information from request headers.
+ *
+ * Extracts common identity headers used for multi-tenant authentication:
+ * - x-org-id: Organization identifier
+ * - x-user-id: User identifier
+ * - x-request-id: Request trace identifier
+ * - x-user-role: User role
+ *
+ * @param req - HTTP request object
+ * @returns Identity object with orgId, userId, requestId, and role
+ *
+ * @example
+ * ```typescript
+ * app.post('/api/resource', requireAuth, async (req, res) => {
+ *   const identity = getIdentity(req);
+ *
+ *   if (!identity.orgId) {
+ *     return sendError(res, 400, 'x-org-id header required');
+ *   }
+ *
+ *   // Use identity.orgId, identity.userId, etc.
+ * });
+ * ```
+ */
+function getIdentity(req) {
+    // Prefer JWT-verified claims (req.user) over raw headers to prevent spoofing.
+    // Headers are only used as fallback or for fields not in the JWT (e.g. requestId).
+    const user = req.user;
+    return {
+        orgId: user?.organizationId || (0, headers_1.getHeaderString)(req.headers['x-org-id']),
+        userId: user?.sub
+            || user?.userId
+            || (0, headers_1.getHeaderString)(req.headers['x-user-id']),
+        requestId: (0, headers_1.getHeaderString)(req.headers['x-request-id']),
+        role: user?.role || (0, headers_1.getHeaderString)(req.headers['x-user-role']),
+    };
+}
+/**
+ * Validate that required identity fields are present.
+ *
+ * @param identity - Identity object to validate
+ * @param required - Array of required field names
+ * @returns Object with isValid boolean and missing fields array
+ *
+ * @example
+ * ```typescript
+ * const identity = getIdentity(req);
+ * const validation = validateIdentity(identity, ['orgId', 'userId']);
+ *
+ * if (!validation.isValid) {
+ *   return sendError(res, 400, `Missing required headers: ${validation.missing.join(', ')}`);
+ * }
+ * ```
+ */
+function validateIdentity(identity, required) {
+    const missing = [];
+    for (const field of required) {
+        if (!identity[field]) {
+            missing.push(`x-${field.replace(/([A-Z])/g, '-$1').toLowerCase()}`);
+        }
+    }
+    return {
+        isValid: missing.length === 0,
+        missing,
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaWRlbnRpdHkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdXRpbHMvaWRlbnRpdHkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7O0FBNEN0QyxrQ0FZQztBQW1CRCw0Q0FnQkM7QUF6RkQsdUNBQTRDO0FBaUI1Qzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBd0JHO0FBQ0gsU0FBZ0IsV0FBVyxDQUFDLEdBQWdCO0lBQzFDLDhFQUE4RTtJQUM5RSxtRkFBbUY7SUFDbkYsTUFBTSxJQUFJLEdBQUcsR0FBRyxDQUFDLElBQUksQ0FBQztJQUN0QixPQUFPO1FBQ0wsS0FBSyxFQUFFLElBQUksRUFBRSxjQUFjLElBQUksSUFBQSx5QkFBZSxFQUFDLEdBQUcsQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLENBQUM7UUFDdkUsTUFBTSxFQUFHLElBQTRDLEVBQUUsR0FBeUI7ZUFDM0UsSUFBSSxFQUFFLE1BQU07ZUFDWixJQUFBLHlCQUFlLEVBQUMsR0FBRyxDQUFDLE9BQU8sQ0FBQyxXQUFXLENBQUMsQ0FBQztRQUM5QyxTQUFTLEVBQUUsSUFBQSx5QkFBZSxFQUFDLEdBQUcsQ0FBQyxPQUFPLENBQUMsY0FBYyxDQUFDLENBQUM7UUFDdkQsSUFBSSxFQUFFLElBQUksRUFBRSxJQUFJLElBQUksSUFBQSx5QkFBZSxFQUFDLEdBQUcsQ0FBQyxPQUFPLENBQUMsYUFBYSxDQUFDLENBQUM7S0FDaEUsQ0FBQztBQUNKLENBQUM7QUFFRDs7Ozs7Ozs7Ozs7Ozs7OztHQWdCRztBQUNILFNBQWdCLGdCQUFnQixDQUM5QixRQUF5QixFQUN6QixRQUFtQztJQUVuQyxNQUFNLE9BQU8sR0FBYSxFQUFFLENBQUM7SUFFN0IsS0FBSyxNQUFNLEtBQUssSUFBSSxRQUFRLEVBQUUsQ0FBQztRQUM3QixJQUFJLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUM7WUFDckIsT0FBTyxDQUFDLElBQUksQ0FBQyxLQUFLLEtBQUssQ0FBQyxPQUFPLENBQUMsVUFBVSxFQUFFLEtBQUssQ0FBQyxDQUFDLFdBQVcsRUFBRSxFQUFFLENBQUMsQ0FBQztRQUN0RSxDQUFDO0lBQ0gsQ0FBQztJQUVELE9BQU87UUFDTCxPQUFPLEVBQUUsT0FBTyxDQUFDLE1BQU0sS0FBSyxDQUFDO1FBQzdCLE9BQU87S0FDUixDQUFDO0FBQ0osQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIENvcHlyaWdodCAyMDI2IFBpcGVsaW5lIEJ1aWxkZXIgQ29udHJpYnV0b3JzXG4vLyBTUERYLUxpY2Vuc2UtSWRlbnRpZmllcjogQXBhY2hlLTIuMFxuXG5pbXBvcnQgeyBnZXRIZWFkZXJTdHJpbmcgfSBmcm9tICcuL2hlYWRlcnMnO1xuaW1wb3J0IHsgSHR0cFJlcXVlc3QgfSBmcm9tICcuLi90eXBlcy9odHRwJztcblxuLyoqXG4gKiBJZGVudGl0eSBpbmZvcm1hdGlvbiBleHRyYWN0ZWQgZnJvbSByZXF1ZXN0IGhlYWRlcnMuXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmVxdWVzdElkZW50aXR5IHtcbiAgLyoqIE9yZ2FuaXphdGlvbiBJRCBmcm9tIHgtb3JnLWlkIGhlYWRlciAqL1xuICByZWFkb25seSBvcmdJZD86IHN0cmluZztcbiAgLyoqIFVzZXIgSUQgZnJvbSB4LXVzZXItaWQgaGVhZGVyICovXG4gIHJlYWRvbmx5IHVzZXJJZD86IHN0cmluZztcbiAgLyoqIFJlcXVlc3QgSUQgZnJvbSB4LXJlcXVlc3QtaWQgaGVhZGVyICovXG4gIHJlYWRvbmx5IHJlcXVlc3RJZD86IHN0cmluZztcbiAgLyoqIFVzZXIgcm9sZSBmcm9tIHgtdXNlci1yb2xlIGhlYWRlciAoZGVjb2RlZCBmcm9tIEpXVCkgKi9cbiAgcmVhZG9ubHkgcm9sZT86IHN0cmluZztcbn1cblxuLyoqXG4gKiBFeHRyYWN0IGlkZW50aXR5IGluZm9ybWF0aW9uIGZyb20gcmVxdWVzdCBoZWFkZXJzLlxuICpcbiAqIEV4dHJhY3RzIGNvbW1vbiBpZGVudGl0eSBoZWFkZXJzIHVzZWQgZm9yIG11bHRpLXRlbmFudCBhdXRoZW50aWNhdGlvbjpcbiAqIC0geC1vcmctaWQ6IE9yZ2FuaXphdGlvbiBpZGVudGlmaWVyXG4gKiAtIHgtdXNlci1pZDogVXNlciBpZGVudGlmaWVyXG4gKiAtIHgtcmVxdWVzdC1pZDogUmVxdWVzdCB0cmFjZSBpZGVudGlmaWVyXG4gKiAtIHgtdXNlci1yb2xlOiBVc2VyIHJvbGVcbiAqXG4gKiBAcGFyYW0gcmVxIC0gSFRUUCByZXF1ZXN0IG9iamVjdFxuICogQHJldHVybnMgSWRlbnRpdHkgb2JqZWN0IHdpdGggb3JnSWQsIHVzZXJJZCwgcmVxdWVzdElkLCBhbmQgcm9sZVxuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBhcHAucG9zdCgnL2FwaS9yZXNvdXJjZScsIHJlcXVpcmVBdXRoLCBhc3luYyAocmVxLCByZXMpID0+IHtcbiAqICAgY29uc3QgaWRlbnRpdHkgPSBnZXRJZGVudGl0eShyZXEpO1xuICpcbiAqICAgaWYgKCFpZGVudGl0eS5vcmdJZCkge1xuICogICAgIHJldHVybiBzZW5kRXJyb3IocmVzLCA0MDAsICd4LW9yZy1pZCBoZWFkZXIgcmVxdWlyZWQnKTtcbiAqICAgfVxuICpcbiAqICAgLy8gVXNlIGlkZW50aXR5Lm9yZ0lkLCBpZGVudGl0eS51c2VySWQsIGV0Yy5cbiAqIH0pO1xuICogYGBgXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBnZXRJZGVudGl0eShyZXE6IEh0dHBSZXF1ZXN0KTogUmVxdWVzdElkZW50aXR5IHtcbiAgLy8gUHJlZmVyIEpXVC12ZXJpZmllZCBjbGFpbXMgKHJlcS51c2VyKSBvdmVyIHJhdyBoZWFkZXJzIHRvIHByZXZlbnQgc3Bvb2ZpbmcuXG4gIC8vIEhlYWRlcnMgYXJlIG9ubHkgdXNlZCBhcyBmYWxsYmFjayBvciBmb3IgZmllbGRzIG5vdCBpbiB0aGUgSldUIChlLmcuIHJlcXVlc3RJZCkuXG4gIGNvbnN0IHVzZXIgPSByZXEudXNlcjtcbiAgcmV0dXJuIHtcbiAgICBvcmdJZDogdXNlcj8ub3JnYW5pemF0aW9uSWQgfHwgZ2V0SGVhZGVyU3RyaW5nKHJlcS5oZWFkZXJzWyd4LW9yZy1pZCddKSxcbiAgICB1c2VySWQ6ICh1c2VyIGFzIFJlY29yZDxzdHJpbmcsIHVua25vd24+IHwgdW5kZWZpbmVkKT8uc3ViIGFzIHN0cmluZyB8IHVuZGVmaW5lZFxuICAgICAgfHwgdXNlcj8udXNlcklkXG4gICAgICB8fCBnZXRIZWFkZXJTdHJpbmcocmVxLmhlYWRlcnNbJ3gtdXNlci1pZCddKSxcbiAgICByZXF1ZXN0SWQ6IGdldEhlYWRlclN0cmluZyhyZXEuaGVhZGVyc1sneC1yZXF1ZXN0LWlkJ10pLFxuICAgIHJvbGU6IHVzZXI/LnJvbGUgfHwgZ2V0SGVhZGVyU3RyaW5nKHJlcS5oZWFkZXJzWyd4LXVzZXItcm9sZSddKSxcbiAgfTtcbn1cblxuLyoqXG4gKiBWYWxpZGF0ZSB0aGF0IHJlcXVpcmVkIGlkZW50aXR5IGZpZWxkcyBhcmUgcHJlc2VudC5cbiAqXG4gKiBAcGFyYW0gaWRlbnRpdHkgLSBJZGVudGl0eSBvYmplY3QgdG8gdmFsaWRhdGVcbiAqIEBwYXJhbSByZXF1aXJlZCAtIEFycmF5IG9mIHJlcXVpcmVkIGZpZWxkIG5hbWVzXG4gKiBAcmV0dXJucyBPYmplY3Qgd2l0aCBpc1ZhbGlkIGJvb2xlYW4gYW5kIG1pc3NpbmcgZmllbGRzIGFycmF5XG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGNvbnN0IGlkZW50aXR5ID0gZ2V0SWRlbnRpdHkocmVxKTtcbiAqIGNvbnN0IHZhbGlkYXRpb24gPSB2YWxpZGF0ZUlkZW50aXR5KGlkZW50aXR5LCBbJ29yZ0lkJywgJ3VzZXJJZCddKTtcbiAqXG4gKiBpZiAoIXZhbGlkYXRpb24uaXNWYWxpZCkge1xuICogICByZXR1cm4gc2VuZEVycm9yKHJlcywgNDAwLCBgTWlzc2luZyByZXF1aXJlZCBoZWFkZXJzOiAke3ZhbGlkYXRpb24ubWlzc2luZy5qb2luKCcsICcpfWApO1xuICogfVxuICogYGBgXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiB2YWxpZGF0ZUlkZW50aXR5KFxuICBpZGVudGl0eTogUmVxdWVzdElkZW50aXR5LFxuICByZXF1aXJlZDogKGtleW9mIFJlcXVlc3RJZGVudGl0eSlbXSxcbik6IHsgaXNWYWxpZDogYm9vbGVhbjsgbWlzc2luZzogc3RyaW5nW10gfSB7XG4gIGNvbnN0IG1pc3Npbmc6IHN0cmluZ1tdID0gW107XG5cbiAgZm9yIChjb25zdCBmaWVsZCBvZiByZXF1aXJlZCkge1xuICAgIGlmICghaWRlbnRpdHlbZmllbGRdKSB7XG4gICAgICBtaXNzaW5nLnB1c2goYHgtJHtmaWVsZC5yZXBsYWNlKC8oW0EtWl0pL2csICctJDEnKS50b0xvd2VyQ2FzZSgpfWApO1xuICAgIH1cbiAgfVxuXG4gIHJldHVybiB7XG4gICAgaXNWYWxpZDogbWlzc2luZy5sZW5ndGggPT09IDAsXG4gICAgbWlzc2luZyxcbiAgfTtcbn1cbiJdfQ==

package/lib/utils/index.d.ts

@@ -0,0 +1,7 @@
+export * from './logger';
+export * from './response';
+export * from './params';
+export * from './headers';
+export * from './identity';
+export * from './object';
+export * from './alias-resolver';

package/lib/utils/index.js

@@ -0,0 +1,26 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+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("./logger"), exports);
+__exportStar(require("./response"), exports);
+__exportStar(require("./params"), exports);
+__exportStar(require("./headers"), exports);
+__exportStar(require("./identity"), exports);
+__exportStar(require("./object"), exports);
+__exportStar(require("./alias-resolver"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdXRpbHMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7Ozs7Ozs7Ozs7Ozs7Ozs7QUFFdEMsMkNBQXlCO0FBQ3pCLDZDQUEyQjtBQUMzQiwyQ0FBeUI7QUFDekIsNENBQTBCO0FBQzFCLDZDQUEyQjtBQUMzQiwyQ0FBeUI7QUFDekIsbURBQWlDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbmV4cG9ydCAqIGZyb20gJy4vbG9nZ2VyJztcbmV4cG9ydCAqIGZyb20gJy4vcmVzcG9uc2UnO1xuZXhwb3J0ICogZnJvbSAnLi9wYXJhbXMnO1xuZXhwb3J0ICogZnJvbSAnLi9oZWFkZXJzJztcbmV4cG9ydCAqIGZyb20gJy4vaWRlbnRpdHknO1xuZXhwb3J0ICogZnJvbSAnLi9vYmplY3QnO1xuZXhwb3J0ICogZnJvbSAnLi9hbGlhcy1yZXNvbHZlcic7XG4iXX0=

package/lib/utils/logger.d.ts

@@ -0,0 +1,28 @@
+import winston from 'winston';
+/**
+ * Create a logger instance for a service.
+ *
+ * When LOG_FORMAT=json (default), outputs structured JSON for Loki ingestion:
+ *   {"level":"info","message":"Server started","service":"pipeline","timestamp":"..."}
+ *
+ * When LOG_FORMAT=text, outputs colorized human-readable format:
+ *   2026-02-13T10:30:00.000Z info [pipeline] Server started
+ *
+ * @param serviceName - Name of the service for log identification
+ * @returns Configured Winston logger instance
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@pipeline-builder/api-core';
+ *
+ * const logger = createLogger('get-plugin');
+ * logger.info('Server started', { port: 3000 });
+ * logger.error('Database error', { error: err.message });
+ * ```
+ */
+export declare function createLogger(serviceName: string): winston.Logger;
+/**
+ * Default logger instance (service name from SERVICE_NAME env var or 'api').
+ */
+export declare const logger: winston.Logger;
+export default logger;

package/lib/utils/logger.js

@@ -0,0 +1,77 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.createLogger = createLogger;
+const winston_1 = __importDefault(require("winston"));
+const { combine, timestamp, printf, colorize, errors, json } = winston_1.default.format;
+/**
+ * Custom log format for human-readable console output.
+ */
+const consoleFormat = printf(({ level, message, timestamp, service, ...meta }) => {
+    const serviceName = service ? `[${service}]` : '';
+    const metaStr = Object.keys(meta).length ? ` ${JSON.stringify(meta)}` : '';
+    return `${timestamp} ${level} ${serviceName} ${message}${metaStr}`;
+});
+/**
+ * Create a logger instance for a service.
+ *
+ * When LOG_FORMAT=json (default), outputs structured JSON for Loki ingestion:
+ *   {"level":"info","message":"Server started","service":"pipeline","timestamp":"..."}
+ *
+ * When LOG_FORMAT=text, outputs colorized human-readable format:
+ *   2026-02-13T10:30:00.000Z info [pipeline] Server started
+ *
+ * @param serviceName - Name of the service for log identification
+ * @returns Configured Winston logger instance
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@pipeline-builder/api-core';
+ *
+ * const logger = createLogger('get-plugin');
+ * logger.info('Server started', { port: 3000 });
+ * logger.error('Database error', { error: err.message });
+ * ```
+ */
+function createLogger(serviceName) {
+    const logLevel = process.env.LOG_LEVEL || 'info';
+    const logFormat = process.env.LOG_FORMAT || 'json';
+    if (logFormat !== 'json' && logFormat !== 'text') {
+        // eslint-disable-next-line no-console -- startup warning before logger is available
+        console.warn(`Invalid LOG_FORMAT="${logFormat}", expected "json" or "text". Defaulting to "json".`);
+    }
+    const useJson = logFormat !== 'text';
+    const baseFormats = [
+        errors({ stack: true }),
+        timestamp({ format: 'YYYY-MM-DDTHH:mm:ss.SSSZ' }),
+    ];
+    if (useJson) {
+        return winston_1.default.createLogger({
+            level: logLevel,
+            defaultMeta: { service: serviceName },
+            format: combine(...baseFormats, json()),
+            transports: [new winston_1.default.transports.Console()],
+        });
+    }
+    return winston_1.default.createLogger({
+        level: logLevel,
+        defaultMeta: { service: serviceName },
+        format: combine(...baseFormats),
+        transports: [
+            new winston_1.default.transports.Console({
+                format: combine(colorize(), consoleFormat),
+            }),
+        ],
+    });
+}
+/**
+ * Default logger instance (service name from SERVICE_NAME env var or 'api').
+ */
+exports.logger = createLogger(process.env.SERVICE_NAME || 'api');
+exports.default = exports.logger;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG9nZ2VyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3V0aWxzL2xvZ2dlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsK0NBQStDO0FBQy9DLHNDQUFzQzs7Ozs7O0FBb0N0QyxvQ0FpQ0M7QUFuRUQsc0RBQThCO0FBRTlCLE1BQU0sRUFBRSxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sRUFBRSxRQUFRLEVBQUUsTUFBTSxFQUFFLElBQUksRUFBRSxHQUFHLGlCQUFPLENBQUMsTUFBTSxDQUFDO0FBRTlFOztHQUVHO0FBQ0gsTUFBTSxhQUFhLEdBQUcsTUFBTSxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsT0FBTyxFQUFFLFNBQVMsRUFBRSxPQUFPLEVBQUUsR0FBRyxJQUFJLEVBQUUsRUFBRSxFQUFFO0lBQy9FLE1BQU0sV0FBVyxHQUFHLE9BQU8sQ0FBQyxDQUFDLENBQUMsSUFBSSxPQUFPLEdBQUcsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0lBQ2xELE1BQU0sT0FBTyxHQUFHLE1BQU0sQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQyxJQUFJLElBQUksQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0lBQzNFLE9BQU8sR0FBRyxTQUFTLElBQUksS0FBSyxJQUFJLFdBQVcsSUFBSSxPQUFPLEdBQUcsT0FBTyxFQUFFLENBQUM7QUFDckUsQ0FBQyxDQUFDLENBQUM7QUFFSDs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FvQkc7QUFDSCxTQUFnQixZQUFZLENBQUMsV0FBbUI7SUFDOUMsTUFBTSxRQUFRLEdBQUcsT0FBTyxDQUFDLEdBQUcsQ0FBQyxTQUFTLElBQUksTUFBTSxDQUFDO0lBQ2pELE1BQU0sU0FBUyxHQUFHLE9BQU8sQ0FBQyxHQUFHLENBQUMsVUFBVSxJQUFJLE1BQU0sQ0FBQztJQUNuRCxJQUFJLFNBQVMsS0FBSyxNQUFNLElBQUksU0FBUyxLQUFLLE1BQU0sRUFBRSxDQUFDO1FBQ2pELG9GQUFvRjtRQUNwRixPQUFPLENBQUMsSUFBSSxDQUFDLHVCQUF1QixTQUFTLHFEQUFxRCxDQUFDLENBQUM7SUFDdEcsQ0FBQztJQUNELE1BQU0sT0FBTyxHQUFHLFNBQVMsS0FBSyxNQUFNLENBQUM7SUFFckMsTUFBTSxXQUFXLEdBQUc7UUFDbEIsTUFBTSxDQUFDLEVBQUUsS0FBSyxFQUFFLElBQUksRUFBRSxDQUFDO1FBQ3ZCLFNBQVMsQ0FBQyxFQUFFLE1BQU0sRUFBRSwwQkFBMEIsRUFBRSxDQUFDO0tBQ2xELENBQUM7SUFFRixJQUFJLE9BQU8sRUFBRSxDQUFDO1FBQ1osT0FBTyxpQkFBTyxDQUFDLFlBQVksQ0FBQztZQUMxQixLQUFLLEVBQUUsUUFBUTtZQUNmLFdBQVcsRUFBRSxFQUFFLE9BQU8sRUFBRSxXQUFXLEVBQUU7WUFDckMsTUFBTSxFQUFFLE9BQU8sQ0FBQyxHQUFHLFdBQVcsRUFBRSxJQUFJLEVBQUUsQ0FBQztZQUN2QyxVQUFVLEVBQUUsQ0FBQyxJQUFJLGlCQUFPLENBQUMsVUFBVSxDQUFDLE9BQU8sRUFBRSxDQUFDO1NBQy9DLENBQUMsQ0FBQztJQUNMLENBQUM7SUFFRCxPQUFPLGlCQUFPLENBQUMsWUFBWSxDQUFDO1FBQzFCLEtBQUssRUFBRSxRQUFRO1FBQ2YsV0FBVyxFQUFFLEVBQUUsT0FBTyxFQUFFLFdBQVcsRUFBRTtRQUNyQyxNQUFNLEVBQUUsT0FBTyxDQUFDLEdBQUcsV0FBVyxDQUFDO1FBQy9CLFVBQVUsRUFBRTtZQUNWLElBQUksaUJBQU8sQ0FBQyxVQUFVLENBQUMsT0FBTyxDQUFDO2dCQUM3QixNQUFNLEVBQUUsT0FBTyxDQUFDLFFBQVEsRUFBRSxFQUFFLGFBQWEsQ0FBQzthQUMzQyxDQUFDO1NBQ0g7S0FDRixDQUFDLENBQUM7QUFDTCxDQUFDO0FBRUQ7O0dBRUc7QUFDVSxRQUFBLE1BQU0sR0FBRyxZQUFZLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxZQUFZLElBQUksS0FBSyxDQUFDLENBQUM7QUFFdEUsa0JBQWUsY0FBTSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbmltcG9ydCB3aW5zdG9uIGZyb20gJ3dpbnN0b24nO1xuXG5jb25zdCB7IGNvbWJpbmUsIHRpbWVzdGFtcCwgcHJpbnRmLCBjb2xvcml6ZSwgZXJyb3JzLCBqc29uIH0gPSB3aW5zdG9uLmZvcm1hdDtcblxuLyoqXG4gKiBDdXN0b20gbG9nIGZvcm1hdCBmb3IgaHVtYW4tcmVhZGFibGUgY29uc29sZSBvdXRwdXQuXG4gKi9cbmNvbnN0IGNvbnNvbGVGb3JtYXQgPSBwcmludGYoKHsgbGV2ZWwsIG1lc3NhZ2UsIHRpbWVzdGFtcCwgc2VydmljZSwgLi4ubWV0YSB9KSA9PiB7XG4gIGNvbnN0IHNlcnZpY2VOYW1lID0gc2VydmljZSA/IGBbJHtzZXJ2aWNlfV1gIDogJyc7XG4gIGNvbnN0IG1ldGFTdHIgPSBPYmplY3Qua2V5cyhtZXRhKS5sZW5ndGggPyBgICR7SlNPTi5zdHJpbmdpZnkobWV0YSl9YCA6ICcnO1xuICByZXR1cm4gYCR7dGltZXN0YW1wfSAke2xldmVsfSAke3NlcnZpY2VOYW1lfSAke21lc3NhZ2V9JHttZXRhU3RyfWA7XG59KTtcblxuLyoqXG4gKiBDcmVhdGUgYSBsb2dnZXIgaW5zdGFuY2UgZm9yIGEgc2VydmljZS5cbiAqXG4gKiBXaGVuIExPR19GT1JNQVQ9anNvbiAoZGVmYXVsdCksIG91dHB1dHMgc3RydWN0dXJlZCBKU09OIGZvciBMb2tpIGluZ2VzdGlvbjpcbiAqICAge1wibGV2ZWxcIjpcImluZm9cIixcIm1lc3NhZ2VcIjpcIlNlcnZlciBzdGFydGVkXCIsXCJzZXJ2aWNlXCI6XCJwaXBlbGluZVwiLFwidGltZXN0YW1wXCI6XCIuLi5cIn1cbiAqXG4gKiBXaGVuIExPR19GT1JNQVQ9dGV4dCwgb3V0cHV0cyBjb2xvcml6ZWQgaHVtYW4tcmVhZGFibGUgZm9ybWF0OlxuICogICAyMDI2LTAyLTEzVDEwOjMwOjAwLjAwMFogaW5mbyBbcGlwZWxpbmVdIFNlcnZlciBzdGFydGVkXG4gKlxuICogQHBhcmFtIHNlcnZpY2VOYW1lIC0gTmFtZSBvZiB0aGUgc2VydmljZSBmb3IgbG9nIGlkZW50aWZpY2F0aW9uXG4gKiBAcmV0dXJucyBDb25maWd1cmVkIFdpbnN0b24gbG9nZ2VyIGluc3RhbmNlXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGltcG9ydCB7IGNyZWF0ZUxvZ2dlciB9IGZyb20gJ0BwaXBlbGluZS1idWlsZGVyL2FwaS1jb3JlJztcbiAqXG4gKiBjb25zdCBsb2dnZXIgPSBjcmVhdGVMb2dnZXIoJ2dldC1wbHVnaW4nKTtcbiAqIGxvZ2dlci5pbmZvKCdTZXJ2ZXIgc3RhcnRlZCcsIHsgcG9ydDogMzAwMCB9KTtcbiAqIGxvZ2dlci5lcnJvcignRGF0YWJhc2UgZXJyb3InLCB7IGVycm9yOiBlcnIubWVzc2FnZSB9KTtcbiAqIGBgYFxuICovXG5leHBvcnQgZnVuY3Rpb24gY3JlYXRlTG9nZ2VyKHNlcnZpY2VOYW1lOiBzdHJpbmcpOiB3aW5zdG9uLkxvZ2dlciB7XG4gIGNvbnN0IGxvZ0xldmVsID0gcHJvY2Vzcy5lbnYuTE9HX0xFVkVMIHx8ICdpbmZvJztcbiAgY29uc3QgbG9nRm9ybWF0ID0gcHJvY2Vzcy5lbnYuTE9HX0ZPUk1BVCB8fCAnanNvbic7XG4gIGlmIChsb2dGb3JtYXQgIT09ICdqc29uJyAmJiBsb2dGb3JtYXQgIT09ICd0ZXh0Jykge1xuICAgIC8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBuby1jb25zb2xlIC0tIHN0YXJ0dXAgd2FybmluZyBiZWZvcmUgbG9nZ2VyIGlzIGF2YWlsYWJsZVxuICAgIGNvbnNvbGUud2FybihgSW52YWxpZCBMT0dfRk9STUFUPVwiJHtsb2dGb3JtYXR9XCIsIGV4cGVjdGVkIFwianNvblwiIG9yIFwidGV4dFwiLiBEZWZhdWx0aW5nIHRvIFwianNvblwiLmApO1xuICB9XG4gIGNvbnN0IHVzZUpzb24gPSBsb2dGb3JtYXQgIT09ICd0ZXh0JztcblxuICBjb25zdCBiYXNlRm9ybWF0cyA9IFtcbiAgICBlcnJvcnMoeyBzdGFjazogdHJ1ZSB9KSxcbiAgICB0aW1lc3RhbXAoeyBmb3JtYXQ6ICdZWVlZLU1NLUREVEhIOm1tOnNzLlNTU1onIH0pLFxuICBdO1xuXG4gIGlmICh1c2VKc29uKSB7XG4gICAgcmV0dXJuIHdpbnN0b24uY3JlYXRlTG9nZ2VyKHtcbiAgICAgIGxldmVsOiBsb2dMZXZlbCxcbiAgICAgIGRlZmF1bHRNZXRhOiB7IHNlcnZpY2U6IHNlcnZpY2VOYW1lIH0sXG4gICAgICBmb3JtYXQ6IGNvbWJpbmUoLi4uYmFzZUZvcm1hdHMsIGpzb24oKSksXG4gICAgICB0cmFuc3BvcnRzOiBbbmV3IHdpbnN0b24udHJhbnNwb3J0cy5Db25zb2xlKCldLFxuICAgIH0pO1xuICB9XG5cbiAgcmV0dXJuIHdpbnN0b24uY3JlYXRlTG9nZ2VyKHtcbiAgICBsZXZlbDogbG9nTGV2ZWwsXG4gICAgZGVmYXVsdE1ldGE6IHsgc2VydmljZTogc2VydmljZU5hbWUgfSxcbiAgICBmb3JtYXQ6IGNvbWJpbmUoLi4uYmFzZUZvcm1hdHMpLFxuICAgIHRyYW5zcG9ydHM6IFtcbiAgICAgIG5ldyB3aW5zdG9uLnRyYW5zcG9ydHMuQ29uc29sZSh7XG4gICAgICAgIGZvcm1hdDogY29tYmluZShjb2xvcml6ZSgpLCBjb25zb2xlRm9ybWF0KSxcbiAgICAgIH0pLFxuICAgIF0sXG4gIH0pO1xufVxuXG4vKipcbiAqIERlZmF1bHQgbG9nZ2VyIGluc3RhbmNlIChzZXJ2aWNlIG5hbWUgZnJvbSBTRVJWSUNFX05BTUUgZW52IHZhciBvciAnYXBpJykuXG4gKi9cbmV4cG9ydCBjb25zdCBsb2dnZXIgPSBjcmVhdGVMb2dnZXIocHJvY2Vzcy5lbnYuU0VSVklDRV9OQU1FIHx8ICdhcGknKTtcblxuZXhwb3J0IGRlZmF1bHQgbG9nZ2VyO1xuIl19

package/lib/utils/object.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Filter an object to only include entries where the value is not `undefined`.
+ * Keeps `null`, `false`, `0`, and empty string — only removes `undefined`.
+ *
+ * Useful for building partial update payloads from validated request bodies.
+ *
+ * @example
+ * ```typescript
+ * const body = { name: 'foo', description: undefined, isActive: false };
+ * pickDefined(body); // { name: 'foo', isActive: false }
+ * ```
+ */
+export declare function pickDefined<T extends Record<string, unknown>>(obj: T): Partial<T>;

package/lib/utils/object.js

@@ -0,0 +1,21 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickDefined = pickDefined;
+/**
+ * Filter an object to only include entries where the value is not `undefined`.
+ * Keeps `null`, `false`, `0`, and empty string — only removes `undefined`.
+ *
+ * Useful for building partial update payloads from validated request bodies.
+ *
+ * @example
+ * ```typescript
+ * const body = { name: 'foo', description: undefined, isActive: false };
+ * pickDefined(body); // { name: 'foo', isActive: false }
+ * ```
+ */
+function pickDefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib2JqZWN0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3V0aWxzL29iamVjdC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsK0NBQStDO0FBQy9DLHNDQUFzQzs7QUFjdEMsa0NBSUM7QUFoQkQ7Ozs7Ozs7Ozs7O0dBV0c7QUFDSCxTQUFnQixXQUFXLENBQW9DLEdBQU07SUFDbkUsT0FBTyxNQUFNLENBQUMsV0FBVyxDQUN2QixNQUFNLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsRUFBRSxFQUFFLENBQUMsQ0FBQyxLQUFLLFNBQVMsQ0FBQyxDQUN6QyxDQUFDO0FBQ2xCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuLyoqXG4gKiBGaWx0ZXIgYW4gb2JqZWN0IHRvIG9ubHkgaW5jbHVkZSBlbnRyaWVzIHdoZXJlIHRoZSB2YWx1ZSBpcyBub3QgYHVuZGVmaW5lZGAuXG4gKiBLZWVwcyBgbnVsbGAsIGBmYWxzZWAsIGAwYCwgYW5kIGVtcHR5IHN0cmluZyDigJQgb25seSByZW1vdmVzIGB1bmRlZmluZWRgLlxuICpcbiAqIFVzZWZ1bCBmb3IgYnVpbGRpbmcgcGFydGlhbCB1cGRhdGUgcGF5bG9hZHMgZnJvbSB2YWxpZGF0ZWQgcmVxdWVzdCBib2RpZXMuXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGNvbnN0IGJvZHkgPSB7IG5hbWU6ICdmb28nLCBkZXNjcmlwdGlvbjogdW5kZWZpbmVkLCBpc0FjdGl2ZTogZmFsc2UgfTtcbiAqIHBpY2tEZWZpbmVkKGJvZHkpOyAvLyB7IG5hbWU6ICdmb28nLCBpc0FjdGl2ZTogZmFsc2UgfVxuICogYGBgXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBwaWNrRGVmaW5lZDxUIGV4dGVuZHMgUmVjb3JkPHN0cmluZywgdW5rbm93bj4+KG9iajogVCk6IFBhcnRpYWw8VD4ge1xuICByZXR1cm4gT2JqZWN0LmZyb21FbnRyaWVzKFxuICAgIE9iamVjdC5lbnRyaWVzKG9iaikuZmlsdGVyKChbLCB2XSkgPT4gdiAhPT0gdW5kZWZpbmVkKSxcbiAgKSBhcyBQYXJ0aWFsPFQ+O1xufVxuIl19

package/lib/utils/params.d.ts

@@ -0,0 +1,89 @@
+import { Request } from 'express';
+/**
+ * Express 5 parameter type.
+ */
+type ParamValue = string | string[] | undefined;
+/**
+ * Extract a single string parameter from Express 5 route params.
+ *
+ * @param params - Request params object
+ * @param key - Parameter key
+ * @returns The parameter value as a string, or undefined if not present
+ *
+ * @example
+ * ```typescript
+ * // Route: GET /plugins/:id
+ * const id = getParam(req.params, 'id');
+ * if (!id) {
+ *   return sendError(res, 400, 'Missing id parameter');
+ * }
+ * ```
+ */
+export declare function getParam(params: Record<string, ParamValue>, key: string): string | undefined;
+/**
+ * Extract the organization ID from request.
+ * Checks params, headers, and user object.
+ *
+ * @param req - Express request object
+ * @returns Organization ID or undefined
+ *
+ * @example
+ * ```typescript
+ * const orgId = getOrgId(req);
+ * if (!orgId) {
+ *   return sendError(res, 400, 'Organization ID required');
+ * }
+ * ```
+ */
+export declare function getOrgId(req: Request): string | undefined;
+/**
+ * Get the authorization header from request.
+ *
+ * @param req - Express request object
+ * @returns Authorization header value or empty string
+ */
+export declare function getAuthHeader(req: Request): string;
+/**
+ * Parse a query parameter as a boolean.
+ *
+ * @param value - Query parameter value
+ * @returns Parsed boolean or undefined
+ *
+ * @example
+ * ```typescript
+ * const isActive = parseQueryBoolean(req.query.isActive);
+ * ```
+ */
+export declare function parseQueryBoolean(value: unknown): boolean | undefined;
+/**
+ * Parse a query parameter as an integer.
+ *
+ * @param value - Query parameter value
+ * @param defaultValue - Default value if parsing fails
+ * @returns Parsed integer
+ *
+ * @example
+ * ```typescript
+ * const limit = parseQueryInt(req.query.limit, 10);
+ * const offset = parseQueryInt(req.query.offset, 0);
+ * ```
+ */
+export declare function parseQueryInt(value: unknown, defaultValue: number): number;
+/**
+ * Parse a query parameter as a string.
+ *
+ * @param value - Query parameter value
+ * @returns String value or undefined
+ *
+ * @example
+ * ```typescript
+ * const search = parseQueryString(req.query.search);
+ * ```
+ */
+export declare function parseQueryString(value: unknown): string | undefined;
+/**
+ * Parse a string to a positive integer, returning a fallback if invalid.
+ * Useful for parsing environment variables with numeric defaults.
+ */
+export declare function parsePositiveInt(value: string | undefined, fallback: number): number;
+export {};