@pipeline-builder/api-core 0.0.1

package/lib/errors/app-errors.js

@@ -0,0 +1,53 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+import { ErrorCode, getStatusForErrorCode } from '../types/error-codes.js';
+/**
+ * Base application error with HTTP status code and error code.
+ * Extend this for domain-specific error types.
+ */
+export class AppError extends Error {
+    statusCode;
+    code;
+    constructor(statusCode, code, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.name = 'AppError';
+    }
+}
+/** 404 — Resource not found. */
+export class NotFoundError extends AppError {
+    constructor(message) {
+        super(getStatusForErrorCode(ErrorCode.NOT_FOUND), ErrorCode.NOT_FOUND, message);
+        this.name = 'NotFoundError';
+    }
+}
+/** 403 — Insufficient permissions. */
+export class ForbiddenError extends AppError {
+    constructor(message) {
+        super(getStatusForErrorCode(ErrorCode.INSUFFICIENT_PERMISSIONS), ErrorCode.INSUFFICIENT_PERMISSIONS, message);
+        this.name = 'ForbiddenError';
+    }
+}
+/** 400 — Validation / bad request. */
+export class ValidationError extends AppError {
+    constructor(message) {
+        super(getStatusForErrorCode(ErrorCode.VALIDATION_ERROR), ErrorCode.VALIDATION_ERROR, message);
+        this.name = 'ValidationError';
+    }
+}
+/** 409 — Conflict / duplicate. */
+export class ConflictError extends AppError {
+    constructor(message) {
+        super(getStatusForErrorCode(ErrorCode.CONFLICT), ErrorCode.CONFLICT, message);
+        this.name = 'ConflictError';
+    }
+}
+/** 401 — Unauthorized / authentication required. */
+export class UnauthorizedError extends AppError {
+    constructor(message) {
+        super(getStatusForErrorCode(ErrorCode.UNAUTHORIZED), ErrorCode.UNAUTHORIZED, message);
+        this.name = 'UnauthorizedError';
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBwLWVycm9ycy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9lcnJvcnMvYXBwLWVycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDO0FBRXRDLE9BQU8sRUFBRSxTQUFTLEVBQUUscUJBQXFCLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUUzRTs7O0dBR0c7QUFDSCxNQUFNLE9BQU8sUUFBUyxTQUFRLEtBQUs7SUFFZixVQUFVO0lBQ1YsSUFBSTtJQUZ0QixZQUNrQixVQUFrQixFQUNsQixJQUFlLEVBQy9CLE9BQWU7UUFFZixLQUFLLENBQUMsT0FBTyxDQUFDLENBQUM7MEJBSkMsVUFBVTtvQkFDVixJQUFJO1FBSXBCLElBQUksQ0FBQyxJQUFJLEdBQUcsVUFBVSxDQUFDO0lBQ3pCLENBQUM7Q0FDRjtBQUVELGdDQUFnQztBQUNoQyxNQUFNLE9BQU8sYUFBYyxTQUFRLFFBQVE7SUFDekMsWUFBWSxPQUFlO1FBQ3pCLEtBQUssQ0FBQyxxQkFBcUIsQ0FBQyxTQUFTLENBQUMsU0FBUyxDQUFDLEVBQUUsU0FBUyxDQUFDLFNBQVMsRUFBRSxPQUFPLENBQUMsQ0FBQztRQUNoRixJQUFJLENBQUMsSUFBSSxHQUFHLGVBQWUsQ0FBQztJQUM5QixDQUFDO0NBQ0Y7QUFFRCxzQ0FBc0M7QUFDdEMsTUFBTSxPQUFPLGNBQWUsU0FBUSxRQUFRO0lBQzFDLFlBQVksT0FBZTtRQUN6QixLQUFLLENBQUMscUJBQXFCLENBQUMsU0FBUyxDQUFDLHdCQUF3QixDQUFDLEVBQUUsU0FBUyxDQUFDLHdCQUF3QixFQUFFLE9BQU8sQ0FBQyxDQUFDO1FBQzlHLElBQUksQ0FBQyxJQUFJLEdBQUcsZ0JBQWdCLENBQUM7SUFDL0IsQ0FBQztDQUNGO0FBRUQsc0NBQXNDO0FBQ3RDLE1BQU0sT0FBTyxlQUFnQixTQUFRLFFBQVE7SUFDM0MsWUFBWSxPQUFlO1FBQ3pCLEtBQUssQ0FBQyxxQkFBcUIsQ0FBQyxTQUFTLENBQUMsZ0JBQWdCLENBQUMsRUFBRSxTQUFTLENBQUMsZ0JBQWdCLEVBQUUsT0FBTyxDQUFDLENBQUM7UUFDOUYsSUFBSSxDQUFDLElBQUksR0FBRyxpQkFBaUIsQ0FBQztJQUNoQyxDQUFDO0NBQ0Y7QUFFRCxrQ0FBa0M7QUFDbEMsTUFBTSxPQUFPLGFBQWMsU0FBUSxRQUFRO0lBQ3pDLFlBQVksT0FBZTtRQUN6QixLQUFLLENBQUMscUJBQXFCLENBQUMsU0FBUyxDQUFDLFFBQVEsQ0FBQyxFQUFFLFNBQVMsQ0FBQyxRQUFRLEVBQUUsT0FBTyxDQUFDLENBQUM7UUFDOUUsSUFBSSxDQUFDLElBQUksR0FBRyxlQUFlLENBQUM7SUFDOUIsQ0FBQztDQUNGO0FBRUQsb0RBQW9EO0FBQ3BELE1BQU0sT0FBTyxpQkFBa0IsU0FBUSxRQUFRO0lBQzdDLFlBQVksT0FBZTtRQUN6QixLQUFLLENBQUMscUJBQXFCLENBQUMsU0FBUyxDQUFDLFlBQVksQ0FBQyxFQUFFLFNBQVMsQ0FBQyxZQUFZLEVBQUUsT0FBTyxDQUFDLENBQUM7UUFDdEYsSUFBSSxDQUFDLElBQUksR0FBRyxtQkFBbUIsQ0FBQztJQUNsQyxDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHsgRXJyb3JDb2RlLCBnZXRTdGF0dXNGb3JFcnJvckNvZGUgfSBmcm9tICcuLi90eXBlcy9lcnJvci1jb2Rlcy5qcyc7XG5cbi8qKlxuICogQmFzZSBhcHBsaWNhdGlvbiBlcnJvciB3aXRoIEhUVFAgc3RhdHVzIGNvZGUgYW5kIGVycm9yIGNvZGUuXG4gKiBFeHRlbmQgdGhpcyBmb3IgZG9tYWluLXNwZWNpZmljIGVycm9yIHR5cGVzLlxuICovXG5leHBvcnQgY2xhc3MgQXBwRXJyb3IgZXh0ZW5kcyBFcnJvciB7XG4gIGNvbnN0cnVjdG9yKFxuICAgIHB1YmxpYyByZWFkb25seSBzdGF0dXNDb2RlOiBudW1iZXIsXG4gICAgcHVibGljIHJlYWRvbmx5IGNvZGU6IEVycm9yQ29kZSxcbiAgICBtZXNzYWdlOiBzdHJpbmcsXG4gICkge1xuICAgIHN1cGVyKG1lc3NhZ2UpO1xuICAgIHRoaXMubmFtZSA9ICdBcHBFcnJvcic7XG4gIH1cbn1cblxuLyoqIDQwNCDigJQgUmVzb3VyY2Ugbm90IGZvdW5kLiAqL1xuZXhwb3J0IGNsYXNzIE5vdEZvdW5kRXJyb3IgZXh0ZW5kcyBBcHBFcnJvciB7XG4gIGNvbnN0cnVjdG9yKG1lc3NhZ2U6IHN0cmluZykge1xuICAgIHN1cGVyKGdldFN0YXR1c0ZvckVycm9yQ29kZShFcnJvckNvZGUuTk9UX0ZPVU5EKSwgRXJyb3JDb2RlLk5PVF9GT1VORCwgbWVzc2FnZSk7XG4gICAgdGhpcy5uYW1lID0gJ05vdEZvdW5kRXJyb3InO1xuICB9XG59XG5cbi8qKiA0MDMg4oCUIEluc3VmZmljaWVudCBwZXJtaXNzaW9ucy4gKi9cbmV4cG9ydCBjbGFzcyBGb3JiaWRkZW5FcnJvciBleHRlbmRzIEFwcEVycm9yIHtcbiAgY29uc3RydWN0b3IobWVzc2FnZTogc3RyaW5nKSB7XG4gICAgc3VwZXIoZ2V0U3RhdHVzRm9yRXJyb3JDb2RlKEVycm9yQ29kZS5JTlNVRkZJQ0lFTlRfUEVSTUlTU0lPTlMpLCBFcnJvckNvZGUuSU5TVUZGSUNJRU5UX1BFUk1JU1NJT05TLCBtZXNzYWdlKTtcbiAgICB0aGlzLm5hbWUgPSAnRm9yYmlkZGVuRXJyb3InO1xuICB9XG59XG5cbi8qKiA0MDAg4oCUIFZhbGlkYXRpb24gLyBiYWQgcmVxdWVzdC4gKi9cbmV4cG9ydCBjbGFzcyBWYWxpZGF0aW9uRXJyb3IgZXh0ZW5kcyBBcHBFcnJvciB7XG4gIGNvbnN0cnVjdG9yKG1lc3NhZ2U6IHN0cmluZykge1xuICAgIHN1cGVyKGdldFN0YXR1c0ZvckVycm9yQ29kZShFcnJvckNvZGUuVkFMSURBVElPTl9FUlJPUiksIEVycm9yQ29kZS5WQUxJREFUSU9OX0VSUk9SLCBtZXNzYWdlKTtcbiAgICB0aGlzLm5hbWUgPSAnVmFsaWRhdGlvbkVycm9yJztcbiAgfVxufVxuXG4vKiogNDA5IOKAlCBDb25mbGljdCAvIGR1cGxpY2F0ZS4gKi9cbmV4cG9ydCBjbGFzcyBDb25mbGljdEVycm9yIGV4dGVuZHMgQXBwRXJyb3Ige1xuICBjb25zdHJ1Y3RvcihtZXNzYWdlOiBzdHJpbmcpIHtcbiAgICBzdXBlcihnZXRTdGF0dXNGb3JFcnJvckNvZGUoRXJyb3JDb2RlLkNPTkZMSUNUKSwgRXJyb3JDb2RlLkNPTkZMSUNULCBtZXNzYWdlKTtcbiAgICB0aGlzLm5hbWUgPSAnQ29uZmxpY3RFcnJvcic7XG4gIH1cbn1cblxuLyoqIDQwMSDigJQgVW5hdXRob3JpemVkIC8gYXV0aGVudGljYXRpb24gcmVxdWlyZWQuICovXG5leHBvcnQgY2xhc3MgVW5hdXRob3JpemVkRXJyb3IgZXh0ZW5kcyBBcHBFcnJvciB7XG4gIGNvbnN0cnVjdG9yKG1lc3NhZ2U6IHN0cmluZykge1xuICAgIHN1cGVyKGdldFN0YXR1c0ZvckVycm9yQ29kZShFcnJvckNvZGUuVU5BVVRIT1JJWkVEKSwgRXJyb3JDb2RlLlVOQVVUSE9SSVpFRCwgbWVzc2FnZSk7XG4gICAgdGhpcy5uYW1lID0gJ1VuYXV0aG9yaXplZEVycm9yJztcbiAgfVxufVxuIl19

package/lib/errors/index.d.ts

@@ -0,0 +1 @@
+export * from './app-errors.js';

package/lib/errors/index.js

@@ -0,0 +1,4 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+export * from './app-errors.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZXJyb3JzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7QUFFdEMsY0FBYyxpQkFBaUIsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIENvcHlyaWdodCAyMDI2IFBpcGVsaW5lIEJ1aWxkZXIgQ29udHJpYnV0b3JzXG4vLyBTUERYLUxpY2Vuc2UtSWRlbnRpZmllcjogQXBhY2hlLTIuMFxuXG5leHBvcnQgKiBmcm9tICcuL2FwcC1lcnJvcnMuanMnO1xuIl19

package/lib/helpers/access-helpers.d.ts

@@ -0,0 +1,63 @@
+import type { Request, Response } from 'express';
+import type { Permission } from '../types/permissions.js';
+import type { Visibility } from '../types/visibility.js';
+/** The slice of a catalog entity the write gate needs. */
+export interface VisibilityWriteTarget {
+    /** Rung the row currently sits at — see {@link Visibility}. */
+    visibility?: string;
+    /** Author. The only non-admin who may touch a `private` row. */
+    createdBy?: string;
+}
+/**
+ * Check whether the caller may modify a catalog entity, per its visibility rung.
+ * The single write gate behind every pipeline / plugin / template mutation.
+ *
+ * - `public` — a system admin, or the holder of `publishPermission` (the same
+ *   permission that let them publish it in the first place, so whoever can
+ *   publish can also manage what they published)
+ * - `org` — anyone who got this far: the resource's `:write` permission plus the
+ *   org scoping the caller already passed IS the gate
+ * - `private` — the AUTHOR alone (plus system admins)
+ *
+ * The `private` branch is load-bearing on the TOMBSTONE paths (restore / purge),
+ * which are org-scoped rather than visibility-scoped because soft-delete is one
+ * shared code path — without it, any org member could resurrect someone else's
+ * personal draft. On the live paths the read predicate has already hidden the
+ * row, making this defense in depth.
+ *
+ * Returns `true` if the request may proceed; returns `false` having ALREADY sent
+ * a 403.
+ *
+ * @example
+ * ```typescript
+ * if (!requireVisibilityWriteAccess(req, res, pipeline, userId, 'pipelines:publish')) return;
+ * await pipelineService.delete(id, orgId, userId);
+ * ```
+ */
+export declare function requireVisibilityWriteAccess(req: Request, res: Response, resource: VisibilityWriteTarget, userId: string, publishPermission: Permission): boolean;
+/**
+ * Resolve the effective visibility for an entity being created or updated.
+ *
+ * `public` requires the publish capability (superadmins pass via implicit-all);
+ * a caller who asks for it without the permission is clamped to `org` rather
+ * than dropped to a personal draft — they asked to SHARE it, and `org` is the
+ * widest rung they are entitled to. Anything else passes through.
+ *
+ * `fallback` is the rung an UNSPECIFIED visibility lands on, and it is
+ * deliberately per-entity even though the ladder itself is identical everywhere:
+ *
+ * - **templates** default to `private` — draft-first is the whole point of the
+ *   personal rung; you polish a starter before publishing it.
+ * - **pipelines / plugins** default to `org` — they are team assets that deploy
+ *   shared infrastructure, so creating one must not hide it from the team. A
+ *   personal draft stays available, but opt-in.
+ *
+ * Same ladder, same gate, different centre of gravity — expressed as an argument
+ * rather than a second code path.
+ *
+ * Permission-based (not coarse-role-based): a bespoke custom Role can be granted
+ * publish rights and is no longer forced private by its `member` label. Built-in
+ * Admin/Owner bundles carry the publish permissions; the built-in Member bundle
+ * does not, so members top out at `org`.
+ */
+export declare function resolveVisibility(req: Request, requested: string | undefined, publishPermission: Permission, fallback?: Visibility): Visibility;

package/lib/helpers/access-helpers.js

@@ -0,0 +1,82 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+import { isSystemAdmin, userHasPermission } from '../middleware/auth.js';
+import { ErrorCode } from '../types/error-codes.js';
+import { sendError } from '../utils/response.js';
+/**
+ * Check whether the caller may modify a catalog entity, per its visibility rung.
+ * The single write gate behind every pipeline / plugin / template mutation.
+ *
+ * - `public` — a system admin, or the holder of `publishPermission` (the same
+ *   permission that let them publish it in the first place, so whoever can
+ *   publish can also manage what they published)
+ * - `org` — anyone who got this far: the resource's `:write` permission plus the
+ *   org scoping the caller already passed IS the gate
+ * - `private` — the AUTHOR alone (plus system admins)
+ *
+ * The `private` branch is load-bearing on the TOMBSTONE paths (restore / purge),
+ * which are org-scoped rather than visibility-scoped because soft-delete is one
+ * shared code path — without it, any org member could resurrect someone else's
+ * personal draft. On the live paths the read predicate has already hidden the
+ * row, making this defense in depth.
+ *
+ * Returns `true` if the request may proceed; returns `false` having ALREADY sent
+ * a 403.
+ *
+ * @example
+ * ```typescript
+ * if (!requireVisibilityWriteAccess(req, res, pipeline, userId, 'pipelines:publish')) return;
+ * await pipelineService.delete(id, orgId, userId);
+ * ```
+ */
+export function requireVisibilityWriteAccess(req, res, resource, userId, publishPermission) {
+    if (isSystemAdmin(req))
+        return true;
+    if (resource.visibility === 'public' && !userHasPermission(req, publishPermission)) {
+        sendError(res, 403, 'You lack permission to modify this public resource.', ErrorCode.INSUFFICIENT_PERMISSIONS);
+        return false;
+    }
+    // Fail closed on an anonymous/absent caller — an empty userId must never match
+    // an empty `createdBy` and hand over someone else's draft.
+    if (resource.visibility === 'private' && (!userId || resource.createdBy !== userId)) {
+        sendError(res, 403, 'Only the author can modify a private resource.', ErrorCode.INSUFFICIENT_PERMISSIONS);
+        return false;
+    }
+    return true;
+}
+/**
+ * Resolve the effective visibility for an entity being created or updated.
+ *
+ * `public` requires the publish capability (superadmins pass via implicit-all);
+ * a caller who asks for it without the permission is clamped to `org` rather
+ * than dropped to a personal draft — they asked to SHARE it, and `org` is the
+ * widest rung they are entitled to. Anything else passes through.
+ *
+ * `fallback` is the rung an UNSPECIFIED visibility lands on, and it is
+ * deliberately per-entity even though the ladder itself is identical everywhere:
+ *
+ * - **templates** default to `private` — draft-first is the whole point of the
+ *   personal rung; you polish a starter before publishing it.
+ * - **pipelines / plugins** default to `org` — they are team assets that deploy
+ *   shared infrastructure, so creating one must not hide it from the team. A
+ *   personal draft stays available, but opt-in.
+ *
+ * Same ladder, same gate, different centre of gravity — expressed as an argument
+ * rather than a second code path.
+ *
+ * Permission-based (not coarse-role-based): a bespoke custom Role can be granted
+ * publish rights and is no longer forced private by its `member` label. Built-in
+ * Admin/Owner bundles carry the publish permissions; the built-in Member bundle
+ * does not, so members top out at `org`.
+ */
+export function resolveVisibility(req, requested, publishPermission, fallback = 'private') {
+    if (requested === 'public') {
+        return userHasPermission(req, publishPermission) ? 'public' : 'org';
+    }
+    if (requested === 'org')
+        return 'org';
+    if (requested === 'private')
+        return 'private';
+    return fallback;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWNjZXNzLWhlbHBlcnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaGVscGVycy9hY2Nlc3MtaGVscGVycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDO0FBR3RDLE9BQU8sRUFBRSxhQUFhLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUN6RSxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFHcEQsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBVWpEOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBeUJHO0FBQ0gsTUFBTSxVQUFVLDRCQUE0QixDQUMxQyxHQUFZLEVBQ1osR0FBYSxFQUNiLFFBQStCLEVBQy9CLE1BQWMsRUFDZCxpQkFBNkI7SUFFN0IsSUFBSSxhQUFhLENBQUMsR0FBRyxDQUFDO1FBQUUsT0FBTyxJQUFJLENBQUM7SUFFcEMsSUFBSSxRQUFRLENBQUMsVUFBVSxLQUFLLFFBQVEsSUFBSSxDQUFDLGlCQUFpQixDQUFDLEdBQUcsRUFBRSxpQkFBaUIsQ0FBQyxFQUFFLENBQUM7UUFDbkYsU0FBUyxDQUNQLEdBQUcsRUFDSCxHQUFHLEVBQ0gscURBQXFELEVBQ3JELFNBQVMsQ0FBQyx3QkFBd0IsQ0FDbkMsQ0FBQztRQUNGLE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUVELCtFQUErRTtJQUMvRSwyREFBMkQ7SUFDM0QsSUFBSSxRQUFRLENBQUMsVUFBVSxLQUFLLFNBQVMsSUFBSSxDQUFDLENBQUMsTUFBTSxJQUFJLFFBQVEsQ0FBQyxTQUFTLEtBQUssTUFBTSxDQUFDLEVBQUUsQ0FBQztRQUNwRixTQUFTLENBQ1AsR0FBRyxFQUNILEdBQUcsRUFDSCxnREFBZ0QsRUFDaEQsU0FBUyxDQUFDLHdCQUF3QixDQUNuQyxDQUFDO1FBQ0YsT0FBTyxLQUFLLENBQUM7SUFDZixDQUFDO0lBRUQsT0FBTyxJQUFJLENBQUM7QUFDZCxDQUFDO0FBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXdCRztBQUNILE1BQU0sVUFBVSxpQkFBaUIsQ0FDL0IsR0FBWSxFQUNaLFNBQTZCLEVBQzdCLGlCQUE2QixFQUM3QixRQUFRLEdBQWUsU0FBUztJQUVoQyxJQUFJLFNBQVMsS0FBSyxRQUFRLEVBQUUsQ0FBQztRQUMzQixPQUFPLGlCQUFpQixDQUFDLEdBQUcsRUFBRSxpQkFBaUIsQ0FBQyxDQUFDLENBQUMsQ0FBQyxRQUFRLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQztJQUN0RSxDQUFDO0lBQ0QsSUFBSSxTQUFTLEtBQUssS0FBSztRQUFFLE9BQU8sS0FBSyxDQUFDO0lBQ3RDLElBQUksU0FBUyxLQUFLLFNBQVM7UUFBRSxPQUFPLFNBQVMsQ0FBQztJQUM5QyxPQUFPLFFBQVEsQ0FBQztBQUNsQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbmltcG9ydCB0eXBlIHsgUmVxdWVzdCwgUmVzcG9uc2UgfSBmcm9tICdleHByZXNzJztcbmltcG9ydCB7IGlzU3lzdGVtQWRtaW4sIHVzZXJIYXNQZXJtaXNzaW9uIH0gZnJvbSAnLi4vbWlkZGxld2FyZS9hdXRoLmpzJztcbmltcG9ydCB7IEVycm9yQ29kZSB9IGZyb20gJy4uL3R5cGVzL2Vycm9yLWNvZGVzLmpzJztcbmltcG9ydCB0eXBlIHsgUGVybWlzc2lvbiB9IGZyb20gJy4uL3R5cGVzL3Blcm1pc3Npb25zLmpzJztcbmltcG9ydCB0eXBlIHsgVmlzaWJpbGl0eSB9IGZyb20gJy4uL3R5cGVzL3Zpc2liaWxpdHkuanMnO1xuaW1wb3J0IHsgc2VuZEVycm9yIH0gZnJvbSAnLi4vdXRpbHMvcmVzcG9uc2UuanMnO1xuXG4vKiogVGhlIHNsaWNlIG9mIGEgY2F0YWxvZyBlbnRpdHkgdGhlIHdyaXRlIGdhdGUgbmVlZHMuICovXG5leHBvcnQgaW50ZXJmYWNlIFZpc2liaWxpdHlXcml0ZVRhcmdldCB7XG4gIC8qKiBSdW5nIHRoZSByb3cgY3VycmVudGx5IHNpdHMgYXQg4oCUIHNlZSB7QGxpbmsgVmlzaWJpbGl0eX0uICovXG4gIHZpc2liaWxpdHk/OiBzdHJpbmc7XG4gIC8qKiBBdXRob3IuIFRoZSBvbmx5IG5vbi1hZG1pbiB3aG8gbWF5IHRvdWNoIGEgYHByaXZhdGVgIHJvdy4gKi9cbiAgY3JlYXRlZEJ5Pzogc3RyaW5nO1xufVxuXG4vKipcbiAqIENoZWNrIHdoZXRoZXIgdGhlIGNhbGxlciBtYXkgbW9kaWZ5IGEgY2F0YWxvZyBlbnRpdHksIHBlciBpdHMgdmlzaWJpbGl0eSBydW5nLlxuICogVGhlIHNpbmdsZSB3cml0ZSBnYXRlIGJlaGluZCBldmVyeSBwaXBlbGluZSAvIHBsdWdpbiAvIHRlbXBsYXRlIG11dGF0aW9uLlxuICpcbiAqIC0gYHB1YmxpY2Ag4oCUIGEgc3lzdGVtIGFkbWluLCBvciB0aGUgaG9sZGVyIG9mIGBwdWJsaXNoUGVybWlzc2lvbmAgKHRoZSBzYW1lXG4gKiAgIHBlcm1pc3Npb24gdGhhdCBsZXQgdGhlbSBwdWJsaXNoIGl0IGluIHRoZSBmaXJzdCBwbGFjZSwgc28gd2hvZXZlciBjYW5cbiAqICAgcHVibGlzaCBjYW4gYWxzbyBtYW5hZ2Ugd2hhdCB0aGV5IHB1Ymxpc2hlZClcbiAqIC0gYG9yZ2Ag4oCUIGFueW9uZSB3aG8gZ290IHRoaXMgZmFyOiB0aGUgcmVzb3VyY2UncyBgOndyaXRlYCBwZXJtaXNzaW9uIHBsdXMgdGhlXG4gKiAgIG9yZyBzY29waW5nIHRoZSBjYWxsZXIgYWxyZWFkeSBwYXNzZWQgSVMgdGhlIGdhdGVcbiAqIC0gYHByaXZhdGVgIOKAlCB0aGUgQVVUSE9SIGFsb25lIChwbHVzIHN5c3RlbSBhZG1pbnMpXG4gKlxuICogVGhlIGBwcml2YXRlYCBicmFuY2ggaXMgbG9hZC1iZWFyaW5nIG9uIHRoZSBUT01CU1RPTkUgcGF0aHMgKHJlc3RvcmUgLyBwdXJnZSksXG4gKiB3aGljaCBhcmUgb3JnLXNjb3BlZCByYXRoZXIgdGhhbiB2aXNpYmlsaXR5LXNjb3BlZCBiZWNhdXNlIHNvZnQtZGVsZXRlIGlzIG9uZVxuICogc2hhcmVkIGNvZGUgcGF0aCDigJQgd2l0aG91dCBpdCwgYW55IG9yZyBtZW1iZXIgY291bGQgcmVzdXJyZWN0IHNvbWVvbmUgZWxzZSdzXG4gKiBwZXJzb25hbCBkcmFmdC4gT24gdGhlIGxpdmUgcGF0aHMgdGhlIHJlYWQgcHJlZGljYXRlIGhhcyBhbHJlYWR5IGhpZGRlbiB0aGVcbiAqIHJvdywgbWFraW5nIHRoaXMgZGVmZW5zZSBpbiBkZXB0aC5cbiAqXG4gKiBSZXR1cm5zIGB0cnVlYCBpZiB0aGUgcmVxdWVzdCBtYXkgcHJvY2VlZDsgcmV0dXJucyBgZmFsc2VgIGhhdmluZyBBTFJFQURZIHNlbnRcbiAqIGEgNDAzLlxuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBpZiAoIXJlcXVpcmVWaXNpYmlsaXR5V3JpdGVBY2Nlc3MocmVxLCByZXMsIHBpcGVsaW5lLCB1c2VySWQsICdwaXBlbGluZXM6cHVibGlzaCcpKSByZXR1cm47XG4gKiBhd2FpdCBwaXBlbGluZVNlcnZpY2UuZGVsZXRlKGlkLCBvcmdJZCwgdXNlcklkKTtcbiAqIGBgYFxuICovXG5leHBvcnQgZnVuY3Rpb24gcmVxdWlyZVZpc2liaWxpdHlXcml0ZUFjY2VzcyhcbiAgcmVxOiBSZXF1ZXN0LFxuICByZXM6IFJlc3BvbnNlLFxuICByZXNvdXJjZTogVmlzaWJpbGl0eVdyaXRlVGFyZ2V0LFxuICB1c2VySWQ6IHN0cmluZyxcbiAgcHVibGlzaFBlcm1pc3Npb246IFBlcm1pc3Npb24sXG4pOiBib29sZWFuIHtcbiAgaWYgKGlzU3lzdGVtQWRtaW4ocmVxKSkgcmV0dXJuIHRydWU7XG5cbiAgaWYgKHJlc291cmNlLnZpc2liaWxpdHkgPT09ICdwdWJsaWMnICYmICF1c2VySGFzUGVybWlzc2lvbihyZXEsIHB1Ymxpc2hQZXJtaXNzaW9uKSkge1xuICAgIHNlbmRFcnJvcihcbiAgICAgIHJlcyxcbiAgICAgIDQwMyxcbiAgICAgICdZb3UgbGFjayBwZXJtaXNzaW9uIHRvIG1vZGlmeSB0aGlzIHB1YmxpYyByZXNvdXJjZS4nLFxuICAgICAgRXJyb3JDb2RlLklOU1VGRklDSUVOVF9QRVJNSVNTSU9OUyxcbiAgICApO1xuICAgIHJldHVybiBmYWxzZTtcbiAgfVxuXG4gIC8vIEZhaWwgY2xvc2VkIG9uIGFuIGFub255bW91cy9hYnNlbnQgY2FsbGVyIOKAlCBhbiBlbXB0eSB1c2VySWQgbXVzdCBuZXZlciBtYXRjaFxuICAvLyBhbiBlbXB0eSBgY3JlYXRlZEJ5YCBhbmQgaGFuZCBvdmVyIHNvbWVvbmUgZWxzZSdzIGRyYWZ0LlxuICBpZiAocmVzb3VyY2UudmlzaWJpbGl0eSA9PT0gJ3ByaXZhdGUnICYmICghdXNlcklkIHx8IHJlc291cmNlLmNyZWF0ZWRCeSAhPT0gdXNlcklkKSkge1xuICAgIHNlbmRFcnJvcihcbiAgICAgIHJlcyxcbiAgICAgIDQwMyxcbiAgICAgICdPbmx5IHRoZSBhdXRob3IgY2FuIG1vZGlmeSBhIHByaXZhdGUgcmVzb3VyY2UuJyxcbiAgICAgIEVycm9yQ29kZS5JTlNVRkZJQ0lFTlRfUEVSTUlTU0lPTlMsXG4gICAgKTtcbiAgICByZXR1cm4gZmFsc2U7XG4gIH1cblxuICByZXR1cm4gdHJ1ZTtcbn1cblxuLyoqXG4gKiBSZXNvbHZlIHRoZSBlZmZlY3RpdmUgdmlzaWJpbGl0eSBmb3IgYW4gZW50aXR5IGJlaW5nIGNyZWF0ZWQgb3IgdXBkYXRlZC5cbiAqXG4gKiBgcHVibGljYCByZXF1aXJlcyB0aGUgcHVibGlzaCBjYXBhYmlsaXR5IChzdXBlcmFkbWlucyBwYXNzIHZpYSBpbXBsaWNpdC1hbGwpO1xuICogYSBjYWxsZXIgd2hvIGFza3MgZm9yIGl0IHdpdGhvdXQgdGhlIHBlcm1pc3Npb24gaXMgY2xhbXBlZCB0byBgb3JnYCByYXRoZXJcbiAqIHRoYW4gZHJvcHBlZCB0byBhIHBlcnNvbmFsIGRyYWZ0IOKAlCB0aGV5IGFza2VkIHRvIFNIQVJFIGl0LCBhbmQgYG9yZ2AgaXMgdGhlXG4gKiB3aWRlc3QgcnVuZyB0aGV5IGFyZSBlbnRpdGxlZCB0by4gQW55dGhpbmcgZWxzZSBwYXNzZXMgdGhyb3VnaC5cbiAqXG4gKiBgZmFsbGJhY2tgIGlzIHRoZSBydW5nIGFuIFVOU1BFQ0lGSUVEIHZpc2liaWxpdHkgbGFuZHMgb24sIGFuZCBpdCBpc1xuICogZGVsaWJlcmF0ZWx5IHBlci1lbnRpdHkgZXZlbiB0aG91Z2ggdGhlIGxhZGRlciBpdHNlbGYgaXMgaWRlbnRpY2FsIGV2ZXJ5d2hlcmU6XG4gKlxuICogLSAqKnRlbXBsYXRlcyoqIGRlZmF1bHQgdG8gYHByaXZhdGVgIOKAlCBkcmFmdC1maXJzdCBpcyB0aGUgd2hvbGUgcG9pbnQgb2YgdGhlXG4gKiAgIHBlcnNvbmFsIHJ1bmc7IHlvdSBwb2xpc2ggYSBzdGFydGVyIGJlZm9yZSBwdWJsaXNoaW5nIGl0LlxuICogLSAqKnBpcGVsaW5lcyAvIHBsdWdpbnMqKiBkZWZhdWx0IHRvIGBvcmdgIOKAlCB0aGV5IGFyZSB0ZWFtIGFzc2V0cyB0aGF0IGRlcGxveVxuICogICBzaGFyZWQgaW5mcmFzdHJ1Y3R1cmUsIHNvIGNyZWF0aW5nIG9uZSBtdXN0IG5vdCBoaWRlIGl0IGZyb20gdGhlIHRlYW0uIEFcbiAqICAgcGVyc29uYWwgZHJhZnQgc3RheXMgYXZhaWxhYmxlLCBidXQgb3B0LWluLlxuICpcbiAqIFNhbWUgbGFkZGVyLCBzYW1lIGdhdGUsIGRpZmZlcmVudCBjZW50cmUgb2YgZ3Jhdml0eSDigJQgZXhwcmVzc2VkIGFzIGFuIGFyZ3VtZW50XG4gKiByYXRoZXIgdGhhbiBhIHNlY29uZCBjb2RlIHBhdGguXG4gKlxuICogUGVybWlzc2lvbi1iYXNlZCAobm90IGNvYXJzZS1yb2xlLWJhc2VkKTogYSBiZXNwb2tlIGN1c3RvbSBSb2xlIGNhbiBiZSBncmFudGVkXG4gKiBwdWJsaXNoIHJpZ2h0cyBhbmQgaXMgbm8gbG9uZ2VyIGZvcmNlZCBwcml2YXRlIGJ5IGl0cyBgbWVtYmVyYCBsYWJlbC4gQnVpbHQtaW5cbiAqIEFkbWluL093bmVyIGJ1bmRsZXMgY2FycnkgdGhlIHB1Ymxpc2ggcGVybWlzc2lvbnM7IHRoZSBidWlsdC1pbiBNZW1iZXIgYnVuZGxlXG4gKiBkb2VzIG5vdCwgc28gbWVtYmVycyB0b3Agb3V0IGF0IGBvcmdgLlxuICovXG5leHBvcnQgZnVuY3Rpb24gcmVzb2x2ZVZpc2liaWxpdHkoXG4gIHJlcTogUmVxdWVzdCxcbiAgcmVxdWVzdGVkOiBzdHJpbmcgfCB1bmRlZmluZWQsXG4gIHB1Ymxpc2hQZXJtaXNzaW9uOiBQZXJtaXNzaW9uLFxuICBmYWxsYmFjazogVmlzaWJpbGl0eSA9ICdwcml2YXRlJyxcbik6IFZpc2liaWxpdHkge1xuICBpZiAocmVxdWVzdGVkID09PSAncHVibGljJykge1xuICAgIHJldHVybiB1c2VySGFzUGVybWlzc2lvbihyZXEsIHB1Ymxpc2hQZXJtaXNzaW9uKSA/ICdwdWJsaWMnIDogJ29yZyc7XG4gIH1cbiAgaWYgKHJlcXVlc3RlZCA9PT0gJ29yZycpIHJldHVybiAnb3JnJztcbiAgaWYgKHJlcXVlc3RlZCA9PT0gJ3ByaXZhdGUnKSByZXR1cm4gJ3ByaXZhdGUnO1xuICByZXR1cm4gZmFsbGJhY2s7XG59XG4iXX0=

package/lib/helpers/crud-helpers.d.ts

@@ -0,0 +1,9 @@
+import type { Response } from 'express';
+/**
+ * Coerce listed fields on a DB-returned record to arrays. Drizzle/pg sometimes
+ * returns `null` for jsonb columns when the row was inserted with a missing
+ * key — callers expect `[]` so map iteration doesn't crash.
+ */
+export declare function normalizeArrayFields<T extends Record<string, unknown>>(record: T, arrayFields: (keyof T)[]): T;
+/** Send a 404 NOT_FOUND error with a standard `${entityName} not found.` message. */
+export declare function sendEntityNotFound(res: Response, entityName: string): void;

package/lib/helpers/crud-helpers.js

@@ -0,0 +1,23 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+import { ErrorCode } from '../types/error-codes.js';
+import { sendError } from '../utils/response.js';
+/**
+ * Coerce listed fields on a DB-returned record to arrays. Drizzle/pg sometimes
+ * returns `null` for jsonb columns when the row was inserted with a missing
+ * key — callers expect `[]` so map iteration doesn't crash.
+ */
+export function normalizeArrayFields(record, arrayFields) {
+    const normalized = { ...record };
+    for (const field of arrayFields) {
+        if (field in normalized && !Array.isArray(normalized[field])) {
+            normalized[field] = [];
+        }
+    }
+    return normalized;
+}
+/** Send a 404 NOT_FOUND error with a standard `${entityName} not found.` message. */
+export function sendEntityNotFound(res, entityName) {
+    sendError(res, 404, `${entityName} not found.`, ErrorCode.NOT_FOUND);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3J1ZC1oZWxwZXJzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2hlbHBlcnMvY3J1ZC1oZWxwZXJzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7QUFHdEMsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBQ3BELE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUVqRDs7OztHQUlHO0FBQ0gsTUFBTSxVQUFVLG9CQUFvQixDQUNsQyxNQUFTLEVBQ1QsV0FBd0I7SUFFeEIsTUFBTSxVQUFVLEdBQUcsRUFBRSxHQUFHLE1BQU0sRUFBRSxDQUFDO0lBQ2pDLEtBQUssTUFBTSxLQUFLLElBQUksV0FBVyxFQUFFLENBQUM7UUFDaEMsSUFBSSxLQUFLLElBQUksVUFBVSxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxVQUFVLENBQUMsS0FBSyxDQUFDLENBQUMsRUFBRSxDQUFDO1lBQzVELFVBQXNDLENBQUMsS0FBZSxDQUFDLEdBQUcsRUFBRSxDQUFDO1FBQ2hFLENBQUM7SUFDSCxDQUFDO0lBQ0QsT0FBTyxVQUFVLENBQUM7QUFDcEIsQ0FBQztBQUVELHFGQUFxRjtBQUNyRixNQUFNLFVBQVUsa0JBQWtCLENBQUMsR0FBYSxFQUFFLFVBQWtCO0lBQ2xFLFNBQVMsQ0FBQyxHQUFHLEVBQUUsR0FBRyxFQUFFLEdBQUcsVUFBVSxhQUFhLEVBQUUsU0FBUyxDQUFDLFNBQVMsQ0FBQyxDQUFDO0FBQ3ZFLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHR5cGUgeyBSZXNwb25zZSB9IGZyb20gJ2V4cHJlc3MnO1xuaW1wb3J0IHsgRXJyb3JDb2RlIH0gZnJvbSAnLi4vdHlwZXMvZXJyb3ItY29kZXMuanMnO1xuaW1wb3J0IHsgc2VuZEVycm9yIH0gZnJvbSAnLi4vdXRpbHMvcmVzcG9uc2UuanMnO1xuXG4vKipcbiAqIENvZXJjZSBsaXN0ZWQgZmllbGRzIG9uIGEgREItcmV0dXJuZWQgcmVjb3JkIHRvIGFycmF5cy4gRHJpenpsZS9wZyBzb21ldGltZXNcbiAqIHJldHVybnMgYG51bGxgIGZvciBqc29uYiBjb2x1bW5zIHdoZW4gdGhlIHJvdyB3YXMgaW5zZXJ0ZWQgd2l0aCBhIG1pc3NpbmdcbiAqIGtleSDigJQgY2FsbGVycyBleHBlY3QgYFtdYCBzbyBtYXAgaXRlcmF0aW9uIGRvZXNuJ3QgY3Jhc2guXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBub3JtYWxpemVBcnJheUZpZWxkczxUIGV4dGVuZHMgUmVjb3JkPHN0cmluZywgdW5rbm93bj4+KFxuICByZWNvcmQ6IFQsXG4gIGFycmF5RmllbGRzOiAoa2V5b2YgVClbXSxcbik6IFQge1xuICBjb25zdCBub3JtYWxpemVkID0geyAuLi5yZWNvcmQgfTtcbiAgZm9yIChjb25zdCBmaWVsZCBvZiBhcnJheUZpZWxkcykge1xuICAgIGlmIChmaWVsZCBpbiBub3JtYWxpemVkICYmICFBcnJheS5pc0FycmF5KG5vcm1hbGl6ZWRbZmllbGRdKSkge1xuICAgICAgKG5vcm1hbGl6ZWQgYXMgUmVjb3JkPHN0cmluZywgdW5rbm93bj4pW2ZpZWxkIGFzIHN0cmluZ10gPSBbXTtcbiAgICB9XG4gIH1cbiAgcmV0dXJuIG5vcm1hbGl6ZWQ7XG59XG5cbi8qKiBTZW5kIGEgNDA0IE5PVF9GT1VORCBlcnJvciB3aXRoIGEgc3RhbmRhcmQgYCR7ZW50aXR5TmFtZX0gbm90IGZvdW5kLmAgbWVzc2FnZS4gKi9cbmV4cG9ydCBmdW5jdGlvbiBzZW5kRW50aXR5Tm90Rm91bmQocmVzOiBSZXNwb25zZSwgZW50aXR5TmFtZTogc3RyaW5nKTogdm9pZCB7XG4gIHNlbmRFcnJvcihyZXMsIDQwNCwgYCR7ZW50aXR5TmFtZX0gbm90IGZvdW5kLmAsIEVycm9yQ29kZS5OT1RfRk9VTkQpO1xufVxuIl19

package/lib/helpers/index.d.ts

@@ -0,0 +1,6 @@
+export * from './crud-helpers.js';
+export * from './access-helpers.js';
+export * from './restore-helpers.js';
+export * from './sse-helpers.js';
+export * from './org-hierarchy.js';
+export * from './org-hierarchy-http.js';

package/lib/helpers/index.js

@@ -0,0 +1,9 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+export * from './crud-helpers.js';
+export * from './access-helpers.js';
+export * from './restore-helpers.js';
+export * from './sse-helpers.js';
+export * from './org-hierarchy.js';
+export * from './org-hierarchy-http.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaGVscGVycy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDO0FBRXRDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHlCQUF5QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbmV4cG9ydCAqIGZyb20gJy4vY3J1ZC1oZWxwZXJzLmpzJztcbmV4cG9ydCAqIGZyb20gJy4vYWNjZXNzLWhlbHBlcnMuanMnO1xuZXhwb3J0ICogZnJvbSAnLi9yZXN0b3JlLWhlbHBlcnMuanMnO1xuZXhwb3J0ICogZnJvbSAnLi9zc2UtaGVscGVycy5qcyc7XG5leHBvcnQgKiBmcm9tICcuL29yZy1oaWVyYXJjaHkuanMnO1xuZXhwb3J0ICogZnJvbSAnLi9vcmctaGllcmFyY2h5LWh0dHAuanMnO1xuIl19

package/lib/helpers/org-hierarchy-http.d.ts

@@ -0,0 +1,74 @@
+import type { ServiceConfig } from '../types/common.js';
+/** Options shared by the platform org-hierarchy HTTP lookups. */
+export interface OrgHierarchyHttpOptions {
+    /** Platform service host/port (+ optional default timeout) for the client. */
+    service: ServiceConfig;
+    /** Service name minted into the service-auth JWT `sub` (e.g. 'compliance'). */
+    serviceName: string;
+    /**
+     * Org id embedded in the signed service token's org context. Defaults to the
+     * queried `orgId`; pass a system org id for a system-scoped lookup.
+     */
+    authOrgId?: string;
+    /** Role carried by the service token (default 'member' — least privilege). */
+    role?: 'owner' | 'admin' | 'member';
+    /** Extra request headers merged after `Authorization` (e.g. `x-org-id`). */
+    headers?: Record<string, string>;
+    /** Per-request timeout override in ms (falls back to the client default). */
+    timeout?: number;
+    /**
+     * When true, a non-2xx response THROWS instead of resolving to `undefined`.
+     * Default false (a 4xx/5xx maps to `undefined`, the fail-soft policy the
+     * message/reporting root-resolution callers rely on). A caller for whom a
+     * failed lookup must fail-CLOSED — e.g. a compliance scan, where treating a
+     * team org as parent-less would silently skip inherited blocking rules — sets
+     * this so it can distinguish "root org" (`undefined`) from "lookup failed".
+     */
+    throwOnHttpError?: boolean;
+}
+/**
+ * Resolve an org's direct parent id via platform's
+ * `GET /organization/:id/parent`. Returns `undefined` for a root org. A non-2xx
+ * response resolves to `undefined` by default, or THROWS when
+ * `throwOnHttpError` is set. Always throws on a transport failure
+ * (connection/timeout) so the caller can apply its own fallback.
+ */
+export declare function fetchParentOrgId(orgId: string, opts: OrgHierarchyHttpOptions): Promise<string | undefined>;
+/**
+ * Resolve `[self, ...descendantOrgIds]` for an org via platform's
+ * `GET /organization/:id/descendants`. Returns the id list only when it is
+ * larger than the org itself (a real subtree), else `undefined`; also
+ * `undefined` on a non-2xx response. Throws on a transport failure so the
+ * caller can apply its own fallback.
+ *
+ * This is a trust boundary: the response is validated element-by-element rather
+ * than cast — every entry must be a string, and any non-string is dropped — so
+ * a malformed payload can never smuggle a non-string into the returned
+ * `string[]`.
+ */
+export declare function fetchOrgDescendants(orgId: string, opts: OrgHierarchyHttpOptions): Promise<string[] | undefined>;
+/**
+ * Batch-resolve org id → display NAME via platform's `POST /organization/names`.
+ * Returns a lowercased `{ [orgId]: name }` map — ids the platform doesn't know
+ * are simply absent (caller falls back to the raw id).
+ *
+ * Best-effort by design: a non-2xx response (e.g. the caller isn't a service
+ * principal) or a malformed body yields `{}`, and it throws ONLY on a transport
+ * failure (connection/timeout) — matching the fail-soft policy of the other
+ * lookups here so a name-enrichment read never fails the caller's request. The
+ * response is validated entry-by-entry (only string→string pairs survive), so a
+ * malformed payload can't smuggle a non-string into the returned map.
+ */
+export declare function fetchOrgNames(orgIds: string[], opts: OrgHierarchyHttpOptions): Promise<Record<string, string>>;
+/**
+ * Check whether `userId` is an ACTIVE member of `orgId` via platform's
+ * `GET /organization/:id/members/:userId/exists`. Returns the boolean the
+ * platform reports.
+ *
+ * Returns `undefined` (— "couldn't determine") on a non-2xx response, and
+ * throws only on a transport failure (connection/timeout) — so the caller
+ * distinguishes a definitive not-a-member (`false`) from an indeterminate
+ * lookup (`undefined`) and applies its own fail-open/closed policy. The `path`
+ * differs from the parent/descendants shape, so this builds its own request.
+ */
+export declare function fetchOrgMembership(orgId: string, userId: string, opts: OrgHierarchyHttpOptions): Promise<boolean | undefined>;

package/lib/helpers/org-hierarchy-http.js

@@ -0,0 +1,144 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Org → team hierarchy lookups over HTTP against the platform service.
+ *
+ * The Mongoose-based traversal in {@link ./org-hierarchy} is for services that
+ * own the org table (platform, quota). Everyone else reads the hierarchy over
+ * the wire from platform's authoritative `/organization/:id/*` endpoints. This
+ * module centralizes the transport for those reads — URL construction, the
+ * signed service-token auth header, and timeout+retry via the shared
+ * {@link InternalHttpClient} — so compliance, reporting, and any future caller
+ * share ONE mechanism instead of each hand-rolling a `fetch`/client with its
+ * own auth and failure semantics.
+ *
+ * These functions deliberately do NOT swallow transport errors: a connection
+ * failure/timeout propagates so each caller keeps its own fallback policy (log
+ * level, degrade-to-self vs. return-undefined). A non-2xx response is treated
+ * as "no data" (returns undefined), matching what the callers previously did.
+ */
+import { getServiceAuthHeader, SYSTEM_ORG_ID } from '../middleware/auth.js';
+import { InternalHttpClient } from '../services/http-client.js';
+function buildRequest(orgId, suffix, opts) {
+    const client = new InternalHttpClient(opts.service);
+    const path = `/organization/${encodeURIComponent(orgId)}/${suffix}`;
+    const headers = {
+        Authorization: getServiceAuthHeader({
+            serviceName: opts.serviceName,
+            orgId: opts.authOrgId ?? orgId,
+            role: opts.role ?? 'member',
+        }),
+        ...opts.headers,
+    };
+    return { client, path, headers };
+}
+/**
+ * Resolve an org's direct parent id via platform's
+ * `GET /organization/:id/parent`. Returns `undefined` for a root org. A non-2xx
+ * response resolves to `undefined` by default, or THROWS when
+ * `throwOnHttpError` is set. Always throws on a transport failure
+ * (connection/timeout) so the caller can apply its own fallback.
+ */
+export async function fetchParentOrgId(orgId, opts) {
+    const { client, path, headers } = buildRequest(orgId, 'parent', opts);
+    const res = await client.get(path, { headers, timeout: opts.timeout });
+    if (res.statusCode >= 400) {
+        if (opts.throwOnHttpError) {
+            throw new Error(`parent-org lookup failed for ${orgId}: HTTP ${res.statusCode}`);
+        }
+        return undefined;
+    }
+    return res.body?.data?.parentOrgId ?? undefined;
+}
+/**
+ * Resolve `[self, ...descendantOrgIds]` for an org via platform's
+ * `GET /organization/:id/descendants`. Returns the id list only when it is
+ * larger than the org itself (a real subtree), else `undefined`; also
+ * `undefined` on a non-2xx response. Throws on a transport failure so the
+ * caller can apply its own fallback.
+ *
+ * This is a trust boundary: the response is validated element-by-element rather
+ * than cast — every entry must be a string, and any non-string is dropped — so
+ * a malformed payload can never smuggle a non-string into the returned
+ * `string[]`.
+ */
+export async function fetchOrgDescendants(orgId, opts) {
+    const { client, path, headers } = buildRequest(orgId, 'descendants', opts);
+    const res = await client.get(path, { headers, timeout: opts.timeout });
+    if (res.statusCode >= 400)
+        return undefined;
+    const ids = res.body?.data?.orgIds;
+    if (!Array.isArray(ids))
+        return undefined;
+    const orgIds = ids.filter((id) => typeof id === 'string');
+    // Only meaningful when the (validated) subtree is larger than the org itself.
+    return orgIds.length > 1 ? orgIds : undefined;
+}
+/**
+ * Batch-resolve org id → display NAME via platform's `POST /organization/names`.
+ * Returns a lowercased `{ [orgId]: name }` map — ids the platform doesn't know
+ * are simply absent (caller falls back to the raw id).
+ *
+ * Best-effort by design: a non-2xx response (e.g. the caller isn't a service
+ * principal) or a malformed body yields `{}`, and it throws ONLY on a transport
+ * failure (connection/timeout) — matching the fail-soft policy of the other
+ * lookups here so a name-enrichment read never fails the caller's request. The
+ * response is validated entry-by-entry (only string→string pairs survive), so a
+ * malformed payload can't smuggle a non-string into the returned map.
+ */
+export async function fetchOrgNames(orgIds, opts) {
+    if (orgIds.length === 0)
+        return {};
+    const client = new InternalHttpClient(opts.service);
+    const headers = {
+        Authorization: getServiceAuthHeader({
+            serviceName: opts.serviceName,
+            // A cross-org registry read, not a tenant-scoped op — default to the system
+            // org context when the caller doesn't pin one.
+            orgId: opts.authOrgId ?? SYSTEM_ORG_ID,
+            role: opts.role ?? 'member',
+        }),
+        ...opts.headers,
+    };
+    const res = await client.post('/organization/names', { orgIds }, { headers, timeout: opts.timeout });
+    if (res.statusCode >= 400)
+        return {};
+    const names = res.body?.data?.names;
+    if (!names || typeof names !== 'object')
+        return {};
+    const out = {};
+    for (const [id, name] of Object.entries(names)) {
+        if (typeof name === 'string')
+            out[id.toLowerCase()] = name;
+    }
+    return out;
+}
+/**
+ * Check whether `userId` is an ACTIVE member of `orgId` via platform's
+ * `GET /organization/:id/members/:userId/exists`. Returns the boolean the
+ * platform reports.
+ *
+ * Returns `undefined` (— "couldn't determine") on a non-2xx response, and
+ * throws only on a transport failure (connection/timeout) — so the caller
+ * distinguishes a definitive not-a-member (`false`) from an indeterminate
+ * lookup (`undefined`) and applies its own fail-open/closed policy. The `path`
+ * differs from the parent/descendants shape, so this builds its own request.
+ */
+export async function fetchOrgMembership(orgId, userId, opts) {
+    const client = new InternalHttpClient(opts.service);
+    const path = `/organization/${encodeURIComponent(orgId)}/members/${encodeURIComponent(userId)}/exists`;
+    const headers = {
+        Authorization: getServiceAuthHeader({
+            serviceName: opts.serviceName,
+            orgId: opts.authOrgId ?? orgId,
+            role: opts.role ?? 'member',
+        }),
+        ...opts.headers,
+    };
+    const res = await client.get(path, { headers, timeout: opts.timeout });
+    if (res.statusCode >= 400)
+        return undefined;
+    const isMember = res.body?.data?.isMember;
+    return typeof isMember === 'boolean' ? isMember : undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib3JnLWhpZXJhcmNoeS1odHRwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2hlbHBlcnMvb3JnLWhpZXJhcmNoeS1odHRwLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7QUFFdEM7Ozs7Ozs7Ozs7Ozs7Ozs7R0FnQkc7QUFFSCxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsYUFBYSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFDNUUsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUErQmhFLFNBQVMsWUFBWSxDQUNuQixLQUFhLEVBQ2IsTUFBZ0MsRUFDaEMsSUFBNkI7SUFFN0IsTUFBTSxNQUFNLEdBQUcsSUFBSSxrQkFBa0IsQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLENBQUM7SUFDcEQsTUFBTSxJQUFJLEdBQUcsaUJBQWlCLGtCQUFrQixDQUFDLEtBQUssQ0FBQyxJQUFJLE1BQU0sRUFBRSxDQUFDO0lBQ3BFLE1BQU0sT0FBTyxHQUEyQjtRQUN0QyxhQUFhLEVBQUUsb0JBQW9CLENBQUM7WUFDbEMsV0FBVyxFQUFFLElBQUksQ0FBQyxXQUFXO1lBQzdCLEtBQUssRUFBRSxJQUFJLENBQUMsU0FBUyxJQUFJLEtBQUs7WUFDOUIsSUFBSSxFQUFFLElBQUksQ0FBQyxJQUFJLElBQUksUUFBUTtTQUM1QixDQUFDO1FBQ0YsR0FBRyxJQUFJLENBQUMsT0FBTztLQUNoQixDQUFDO0lBQ0YsT0FBTyxFQUFFLE1BQU0sRUFBRSxJQUFJLEVBQUUsT0FBTyxFQUFFLENBQUM7QUFDbkMsQ0FBQztBQUVEOzs7Ozs7R0FNRztBQUNILE1BQU0sQ0FBQyxLQUFLLFVBQVUsZ0JBQWdCLENBQUMsS0FBYSxFQUFFLElBQTZCO0lBQ2pGLE1BQU0sRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFLE9BQU8sRUFBRSxHQUFHLFlBQVksQ0FBQyxLQUFLLEVBQUUsUUFBUSxFQUFFLElBQUksQ0FB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QUksRUFBRSxRQUFRLENBQUM7SUFDMUMsT0FBTyxPQUFPLFFBQVEsS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDO0FBQzlELENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuLyoqXG4gKiBPcmcg4oaSIHRlYW0gaGllcmFyY2h5IGxvb2t1cHMgb3ZlciBIVFRQIGFnYWluc3QgdGhlIHBsYXRmb3JtIHNlcnZpY2UuXG4gKlxuICogVGhlIE1vbmdvb3NlLWJhc2VkIHRyYXZlcnNhbCBpbiB7QGxpbmsgLi9vcmctaGllcmFyY2h5fSBpcyBmb3Igc2VydmljZXMgdGhhdFxuICogb3duIHRoZSBvcmcgdGFibGUgKHBsYXRmb3JtLCBxdW90YSkuIEV2ZXJ5b25lIGVsc2UgcmVhZHMgdGhlIGhpZXJhcmNoeSBvdmVyXG4gKiB0aGUgd2lyZSBmcm9tIHBsYXRmb3JtJ3MgYXV0aG9yaXRhdGl2ZSBgL29yZ2FuaXphdGlvbi86aWQvKmAgZW5kcG9pbnRzLiBUaGlzXG4gKiBtb2R1bGUgY2VudHJhbGl6ZXMgdGhlIHRyYW5zcG9ydCBmb3IgdGhvc2UgcmVhZHMg4oCUIFVSTCBjb25zdHJ1Y3Rpb24sIHRoZVxuICogc2lnbmVkIHNlcnZpY2UtdG9rZW4gYXV0aCBoZWFkZXIsIGFuZCB0aW1lb3V0K3JldHJ5IHZpYSB0aGUgc2hhcmVkXG4gKiB7QGxpbmsgSW50ZXJuYWxIdHRwQ2xpZW50fSDigJQgc28gY29tcGxpYW5jZSwgcmVwb3J0aW5nLCBhbmQgYW55IGZ1dHVyZSBjYWxsZXJcbiAqIHNoYXJlIE9ORSBtZWNoYW5pc20gaW5zdGVhZCBvZiBlYWNoIGhhbmQtcm9sbGluZyBhIGBmZXRjaGAvY2xpZW50IHdpdGggaXRzXG4gKiBvd24gYXV0aCBhbmQgZmFpbHVyZSBzZW1hbnRpY3MuXG4gKlxuICogVGhlc2UgZnVuY3Rpb25zIGRlbGliZXJhdGVseSBkbyBOT1Qgc3dhbGxvdyB0cmFuc3BvcnQgZXJyb3JzOiBhIGNvbm5lY3Rpb25cbiAqIGZhaWx1cmUvdGltZW91dCBwcm9wYWdhdGVzIHNvIGVhY2ggY2FsbGVyIGtlZXBzIGl0cyBvd24gZmFsbGJhY2sgcG9saWN5IChsb2dcbiAqIGxldmVsLCBkZWdyYWRlLXRvLXNlbGYgdnMuIHJldHVybi11bmRlZmluZWQpLiBBIG5vbi0yeHggcmVzcG9uc2UgaXMgdHJlYXRlZFxuICogYXMgXCJubyBkYXRhXCIgKHJldHVybnMgdW5kZWZpbmVkKSwgbWF0Y2hpbmcgd2hhdCB0aGUgY2FsbGVycyBwcmV2aW91c2x5IGRpZC5cbiAqL1xuXG5pbXBvcnQgeyBnZXRTZXJ2aWNlQXV0aEhlYWRlciwgU1lTVEVNX09SR19JRCB9IGZyb20gJy4uL21pZGRsZXdhcmUvYXV0aC5qcyc7XG5pbXBvcnQgeyBJbnRlcm5hbEh0dHBDbGllbnQgfSBmcm9tICcuLi9zZXJ2aWNlcy9odHRwLWNsaWVudC5qcyc7XG5pbXBvcnQgdHlwZSB7IFNlcnZpY2VDb25maWcgfSBmcm9tICcuLi90eXBlcy9jb21tb24uanMnO1xuXG4vKiogT3B0aW9ucyBzaGFyZWQgYnkgdGhlIHBsYXRmb3JtIG9yZy1oaWVyYXJjaHkgSFRUUCBsb29rdXBzLiAqL1xuZXhwb3J0IGludGVyZmFjZSBPcmdIaWVyYXJjaHlIdHRwT3B0aW9ucyB7XG4gIC8qKiBQbGF0Zm9ybSBzZXJ2aWNlIGhvc3QvcG9ydCAoKyBvcHRpb25hbCBkZWZhdWx0IHRpbWVvdXQpIGZvciB0aGUgY2xpZW50LiAqL1xuICBzZXJ2aWNlOiBTZXJ2aWNlQ29uZmlnO1xuICAvKiogU2VydmljZSBuYW1lIG1pbnRlZCBpbnRvIHRoZSBzZXJ2aWNlLWF1dGggSldUIGBzdWJgIChlLmcuICdjb21wbGlhbmNlJykuICovXG4gIHNlcnZpY2VOYW1lOiBzdHJpbmc7XG4gIC8qKlxuICAgKiBPcmcgaWQgZW1iZWRkZWQgaW4gdGhlIHNpZ25lZCBzZXJ2aWNlIHRva2VuJ3Mgb3JnIGNvbnRleHQuIERlZmF1bHRzIHRvIHRoZVxuICAgKiBxdWVyaWVkIGBvcmdJZGA7IHBhc3MgYSBzeXN0ZW0gb3JnIGlkIGZvciBhIHN5c3RlbS1zY29wZWQgbG9va3VwLlxuICAgKi9cbiAgYXV0aE9yZ0lkPzogc3RyaW5nO1xuICAvKiogUm9sZSBjYXJyaWVkIGJ5IHRoZSBzZXJ2aWNlIHRva2VuIChkZWZhdWx0ICdtZW1iZXInIOKAlCBsZWFzdCBwcml2aWxlZ2UpLiAqL1xuICByb2xlPzogJ293bmVyJyB8ICdhZG1pbicgfCAnbWVtYmVyJztcbiAgLyoqIEV4dHJhIHJlcXVlc3QgaGVhZGVycyBtZXJnZWQgYWZ0ZXIgYEF1dGhvcml6YXRpb25gIChlLmcuIGB4LW9yZy1pZGApLiAqL1xuICBoZWFkZXJzPzogUmVjb3JkPHN0cmluZywgc3RyaW5nPjtcbiAgLyoqIFBlci1yZXF1ZXN0IHRpbWVvdXQgb3ZlcnJpZGUgaW4gbXMgKGZhbGxzIGJhY2sgdG8gdGhlIGNsaWVudCBkZWZhdWx0KS4gKi9cbiAgdGltZW91dD86IG51bWJlcjtcbiAgLyoqXG4gICAqIFdoZW4gdHJ1ZSwgYSBub24tMnh4IHJlc3BvbnNlIFRIUk9XUyBpbnN0ZWFkIG9mIHJlc29sdmluZyB0byBgdW5kZWZpbmVkYC5cbiAgICogRGVmYXVsdCBmYWxzZSAoYSA0eHgvNXh4IG1hcHMgdG8gYHVuZGVmaW5lZGAsIHRoZSBmYWlsLXNvZnQgcG9saWN5IHRoZVxuICAgKiBtZXNzYWdlL3JlcG9ydGluZyByb290LXJlc29sdXRpb24gY2FsbGVycyByZWx5IG9uKS4gQSBjYWxsZXIgZm9yIHdob20gYVxuICAgKiBmYWlsZWQgbG9va3VwIG11c3QgZmFpbC1DTE9TRUQg4oCUIGUuZy4gYSBjb21wbGlhbmNlIHNjYW4sIHdoZXJlIHRyZWF0aW5nIGFcbiAgICogdGVhbSBvcmcgYXMgcGFyZW50LWxlc3Mgd291bGQgc2lsZW50bHkgc2tpcCBpbmhlcml0ZWQgYmxvY2tpbmcgcnVsZXMg4oCUIHNldHNcbiAgICogdGhpcyBzbyBpdCBjYW4gZGlzdGluZ3Vpc2ggXCJyb290IG9yZ1wiIChgdW5kZWZpbmVkYCkgZnJvbSBcImxvb2t1cCBmYWlsZWRcIi5cbiAgICovXG4gIHRocm93T25IdHRwRXJyb3I/OiBib29sZWFuO1xufVxuXG5mdW5jdGlvbiBidWlsZFJlcXVlc3QoXG4gIG9yZ0lkOiBzdHJpbmcsXG4gIHN1ZmZpeDogJ3BhcmVudCcgfCAnZGVzY2VuZGFudHMnLFxuICBvcHRzOiBPcmdIaWVyYXJjaHlIdHRwT3B0aW9ucyxcbik6IHsgY2xpZW50OiBJbnRlcm5hbEh0dHBDbGllbnQ7IHBhdGg6IHN0cmluZzsgaGVhZGVyczogUmVjb3JkPHN0cmluZywgc3RyaW5nPiB9IHtcbiAgY29uc3QgY2xpZW50ID0gbmV3IEludGVybmFsSHR0cENsaWVudChvcHRzLnNlcnZpY2UpO1xuICBjb25zdCBwYXRoID0gYC9vcmdhbml6YXRpb24vJHtlbmNvZGVVUklDb21wb25lbnQob3JnSWQpfS8ke3N1ZmZpeH1gO1xuICBjb25zdCBoZWFkZXJzOiBSZWNvcmQ8c3RyaW5nLCBzdHJpbmc+ID0ge1xuICAgIEF1dGhvcml6YXRpb246IGdldFNlcnZpY2VBdXRoSGVhZGVyKHtcbiAgICAgIHNlcnZpY2VOYW1lOiBvcHRzLnNlcnZpY2VOYW1lLFxuICAgICAgb3JnSWQ6IG9wdHMuYXV0aE9yZ0lkID8/IG9yZ0lkLFxuICAgICAgcm9sZTogb3B0cy5yb2xlID8/ICdtZW1iZXInLFxuICAgIH0pLFxuICAgIC4uLm9wdHMuaGVhZGVycyxcbiAgfTtcbiAgcmV0dXJuIHsgY2xpZW50LCBwYXRoLCBoZWFkZXJzIH07XG59XG5cbi8qKlxuICogUmVzb2x2ZSBhbiBvcmcncyBkaXJlY3QgcGFyZW50IGlkIHZpYSBwbGF0Zm9ybSdzXG4gKiBgR0VUIC9vcmdhbml6YXRpb24vOmlkL3BhcmVudGAuIFJldHVybnMgYHVuZGVmaW5lZGAgZm9yIGEgcm9vdCBvcmcuIEEgbm9uLTJ4eFxuICogcmVzcG9uc2UgcmVzb2x2ZXMgdG8gYHVuZGVmaW5lZGAgYnkgZGVmYXVsdCwgb3IgVEhST1dTIHdoZW5cbiAqIGB0aHJvd09uSHR0cEVycm9yYCBpcyBzZXQuIEFsd2F5cyB0aHJvd3Mgb24gYSB0cmFuc3BvcnQgZmFpbHVyZVxuICogKGNvbm5lY3Rpb24vdGltZW91dCkgc28gdGhlIGNhbGxlciBjYW4gYXBwbHkgaXRzIG93biBmYWxsYmFjay5cbiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGZldGNoUGFyZW50T3JnSWQob3JnSWQ6IHN0cmluZywgb3B0czogT3JnSGllcmFyY2h5SHR0cE9wdGlvbnMpOiBQcm9taXNlPHN0cmluZyB8IHVuZGVmaW5lZD4ge1xuICBjb25zdCB7IGNsaWVudCwgcGF0aCwgaGVhZGVycyB9ID0gYnVpbGRSZXF1ZXN0KG9yZ0lkLCAncGFyZW50Jywgb3B0cyk7XG4gIGNvbnN0IHJlcyA9IGF3YWl0IGNsaWVudC5nZXQ8eyBkYXRhPzogeyBwYXJlbnRPcmdJZD86IHN0cmluZyB8IG51bGwgfSB9PihwYXRoLCB7IGhlYWRlcnMsIHRpbWVvdXQ6IG9wdHMudGltZW91dCB9KTtcbiAgaWYgKHJlcy5zdGF0dXNDb2RlID49IDQwMCkge1xuICAgIGlmIChvcHRzLnRocm93T25IdHRwRXJyb3IpIHtcbiAgICAgIHRocm93IG5ldyBFcnJvcihgcGFyZW50LW9yZyBsb29rdXAgZmFpbGVkIGZvciAke29yZ0lkfTogSFRUUCAke3Jlcy5zdGF0dXNDb2RlfWApO1xuICAgIH1cbiAgICByZXR1cm4gdW5kZWZpbmVkO1xuICB9XG4gIHJldHVybiByZXMuYm9keT8uZGF0YT8ucGFyZW50T3JnSWQgPz8gdW5kZWZpbmVkO1xufVxuXG4vKipcbiAqIFJlc29sdmUgYFtzZWxmLCAuLi5kZXNjZW5kYW50T3JnSWRzXWAgZm9yIGFuIG9yZyB2aWEgcGxhdGZvcm0nc1xuICogYEdFVCAvb3JnYW5pemF0aW9uLzppZC9kZXNjZW5kYW50c2AuIFJldHVybnMgdGhlIGlkIGxpc3Qgb25seSB3aGVuIGl0IGlzXG4gKiBsYXJnZXIgdGhhbiB0aGUgb3JnIGl0c2VsZiAoYSByZWFsIHN1YnRyZWUpLCBlbHNlIGB1bmRlZmluZWRgOyBhbHNvXG4gKiBgdW5kZWZpbmVkYCBvbiBhIG5vbi0yeHggcmVzcG9uc2UuIFRocm93cyBvbiBhIHRyYW5zcG9ydCBmYWlsdXJlIHNvIHRoZVxuICogY2FsbGVyIGNhbiBhcHBseSBpdHMgb3duIGZhbGxiYWNrLlxuICpcbiAqIFRoaXMgaXMgYSB0cnVzdCBib3VuZGFyeTogdGhlIHJlc3BvbnNlIGlzIHZhbGlkYXRlZCBlbGVtZW50LWJ5LWVsZW1lbnQgcmF0aGVyXG4gKiB0aGFuIGNhc3Qg4oCUIGV2ZXJ5IGVudHJ5IG11c3QgYmUgYSBzdHJpbmcsIGFuZCBhbnkgbm9uLXN0cmluZyBpcyBkcm9wcGVkIOKAlCBzb1xuICogYSBtYWxmb3JtZWQgcGF5bG9hZCBjYW4gbmV2ZXIgc211Z2dsZSBhIG5vbi1zdHJpbmcgaW50byB0aGUgcmV0dXJuZWRcbiAqIGBzdHJpbmdbXWAuXG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBmZXRjaE9yZ0Rlc2NlbmRhbnRzKG9yZ0lkOiBzdHJpbmcsIG9wdHM6IE9yZ0hpZXJhcmNoeUh0dHBPcHRpb25zKTogUHJvbWlzZTxzdHJpbmdbXSB8IHVuZGVmaW5lZD4ge1xuICBjb25zdCB7IGNsaWVudCwgcGF0aCwgaGVhZGVycyB9ID0gYnVpbGRSZXF1ZXN0KG9yZ0lkLCAnZGVzY2VuZGFudHMnLCBvcHRzKTtcbiAgY29uc3QgcmVzID0gYXdhaXQgY2xpZW50LmdldDx7IGRhdGE/OiB7IG9yZ0lkcz86IHVua25vd24gfSB9PihwYXRoLCB7IGhlYWRlcnMsIHRpbWVvdXQ6IG9wdHMudGltZW91dCB9KTtcbiAgaWYgKHJlcy5zdGF0dXNDb2RlID49IDQwMCkgcmV0dXJuIHVuZGVmaW5lZDtcbiAgY29uc3QgaWRzID0gcmVzLmJvZHk/LmRhdGE/Lm9yZ0lkcztcbiAgaWYgKCFBcnJheS5pc0FycmF5KGlkcykpIHJldHVybiB1bmRlZmluZWQ7XG4gIGNvbnN0IG9yZ0lkcyA9IGlkcy5maWx0ZXIoKGlkKTogaWQgaXMgc3RyaW5nID0+IHR5cGVvZiBpZCA9PT0gJ3N0cmluZycpO1xuICAvLyBPbmx5IG1lYW5pbmdmdWwgd2hlbiB0aGUgKHZhbGlkYXRlZCkgc3VidHJlZSBpcyBsYXJnZXIgdGhhbiB0aGUgb3JnIGl0c2VsZi5cbiAgcmV0dXJuIG9yZ0lkcy5sZW5ndGggPiAxID8gb3JnSWRzIDogdW5kZWZpbmVkO1xufVxuXG4vKipcbiAqIEJhdGNoLXJlc29sdmUgb3JnIGlkIOKGkiBkaXNwbGF5IE5BTUUgdmlhIHBsYXRmb3JtJ3MgYFBPU1QgL29yZ2FuaXphdGlvbi9uYW1lc2AuXG4gKiBSZXR1cm5zIGEgbG93ZXJjYXNlZCBgeyBbb3JnSWRdOiBuYW1lIH1gIG1hcCDigJQgaWRzIHRoZSBwbGF0Zm9ybSBkb2Vzbid0IGtub3dcbiAqIGFyZSBzaW1wbHkgYWJzZW50IChjYWxsZXIgZmFsbHMgYmFjayB0byB0aGUgcmF3IGlkKS5cbiAqXG4gKiBCZXN0LWVmZm9ydCBieSBkZXNpZ246IGEgbm9uLTJ4eCByZXNwb25zZSAoZS5nLiB0aGUgY2FsbGVyIGlzbid0IGEgc2VydmljZVxuICogcHJpbmNpcGFsKSBvciBhIG1hbGZvcm1lZCBib2R5IHlpZWxkcyBge31gLCBhbmQgaXQgdGhyb3dzIE9OTFkgb24gYSB0cmFuc3BvcnRcbiAqIGZhaWx1cmUgKGNvbm5lY3Rpb24vdGltZW91dCkg4oCUIG1hdGNoaW5nIHRoZSBmYWlsLXNvZnQgcG9saWN5IG9mIHRoZSBvdGhlclxuICogbG9va3VwcyBoZXJlIHNvIGEgbmFtZS1lbnJpY2htZW50IHJlYWQgbmV2ZXIgZmFpbHMgdGhlIGNhbGxlcidzIHJlcXVlc3QuIFRoZVxuICogcmVzcG9uc2UgaXMgdmFsaWRhdGVkIGVudHJ5LWJ5LWVudHJ5IChvbmx5IHN0cmluZ+KGknN0cmluZyBwYWlycyBzdXJ2aXZlKSwgc28gYVxuICogbWFsZm9ybWVkIHBheWxvYWQgY2FuJ3Qgc211Z2dsZSBhIG5vbi1zdHJpbmcgaW50byB0aGUgcmV0dXJuZWQgbWFwLlxuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gZmV0Y2hPcmdOYW1lcyhcbiAgb3JnSWRzOiBzdHJpbmdbXSxcbiAgb3B0czogT3JnSGllcmFyY2h5SHR0cE9wdGlvbnMsXG4pOiBQcm9taXNlPFJlY29yZDxzdHJpbmcsIHN0cmluZz4+IHtcbiAgaWYgKG9yZ0lkcy5sZW5ndGggPT09IDApIHJldHVybiB7fTtcbiAgY29uc3QgY2xpZW50ID0gbmV3IEludGVybmFsSHR0cENsaWVudChvcHRzLnNlcnZpY2UpO1xuICBjb25zdCBoZWFkZXJzOiBSZWNvcmQ8c3RyaW5nLCBzdHJpbmc+ID0ge1xuICAgIEF1dGhvcml6YXRpb246IGdldFNlcnZpY2VBdXRoSGVhZGVyKHtcbiAgICAgIHNlcnZpY2VOYW1lOiBvcHRzLnNlcnZpY2VOYW1lLFxuICAgICAgLy8gQSBjcm9zcy1vcmcgcmVnaXN0cnkgcmVhZCwgbm90IGEgdGVuYW50LXNjb3BlZCBvcCDigJQgZGVmYXVsdCB0byB0aGUgc3lzdGVtXG4gICAgICAvLyBvcmcgY29udGV4dCB3aGVuIHRoZSBjYWxsZXIgZG9lc24ndCBwaW4gb25lLlxuICAgICAgb3JnSWQ6IG9wdHMuYXV0aE9yZ0lkID8/IFNZU1RFTV9PUkdfSUQsXG4gICAgICByb2xlOiBvcHRzLnJvbGUgPz8gJ21lbWJlcicsXG4gICAgfSksXG4gICAgLi4ub3B0cy5oZWFkZXJzLFxuICB9O1xuICBjb25zdCByZXMgPSBhd2FpdCBjbGllbnQucG9zdDx7IGRhdGE/OiB7IG5hbWVzPzogdW5rbm93biB9IH0+KFxuICAgICcvb3JnYW5pemF0aW9uL25hbWVzJyxcbiAgICB7IG9yZ0lkcyB9LFxuICAgIHsgaGVhZGVycywgdGltZW91dDogb3B0cy50aW1lb3V0IH0sXG4gICk7XG4gIGlmIChyZXMuc3RhdHVzQ29kZSA+PSA0MDApIHJldHVybiB7fTtcbiAgY29uc3QgbmFtZXMgPSByZXMuYm9keT8uZGF0YT8ubmFtZXM7XG4gIGlmICghbmFtZXMgfHwgdHlwZW9mIG5hbWVzICE9PSAnb2JqZWN0JykgcmV0dXJuIHt9O1xuICBjb25zdCBvdXQ6IFJlY29yZDxzdHJpbmcsIHN0cmluZz4gPSB7fTtcbiAgZm9yIChjb25zdCBbaWQsIG5hbWVdIG9mIE9iamVjdC5lbnRyaWVzKG5hbWVzIGFzIFJlY29yZDxzdHJpbmcsIHVua25vd24+KSkge1xuICAgIGlmICh0eXBlb2YgbmFtZSA9PT0gJ3N0cmluZycpIG91dFtpZC50b0xvd2VyQ2FzZSgpXSA9IG5hbWU7XG4gIH1cbiAgcmV0dXJuIG91dDtcbn1cblxuLyoqXG4gKiBDaGVjayB3aGV0aGVyIGB1c2VySWRgIGlzIGFuIEFDVElWRSBtZW1iZXIgb2YgYG9yZ0lkYCB2aWEgcGxhdGZvcm0nc1xuICogYEdFVCAvb3JnYW5pemF0aW9uLzppZC9tZW1iZXJzLzp1c2VySWQvZXhpc3RzYC4gUmV0dXJucyB0aGUgYm9vbGVhbiB0aGVcbiAqIHBsYXRmb3JtIHJlcG9ydHMuXG4gKlxuICogUmV0dXJucyBgdW5kZWZpbmVkYCAo4oCUIFwiY291bGRuJ3QgZGV0ZXJtaW5lXCIpIG9uIGEgbm9uLTJ4eCByZXNwb25zZSwgYW5kXG4gKiB0aHJvd3Mgb25seSBvbiBhIHRyYW5zcG9ydCBmYWlsdXJlIChjb25uZWN0aW9uL3RpbWVvdXQpIOKAlCBzbyB0aGUgY2FsbGVyXG4gKiBkaXN0aW5ndWlzaGVzIGEgZGVmaW5pdGl2ZSBub3QtYS1tZW1iZXIgKGBmYWxzZWApIGZyb20gYW4gaW5kZXRlcm1pbmF0ZVxuICogbG9va3VwIChgdW5kZWZpbmVkYCkgYW5kIGFwcGxpZXMgaXRzIG93biBmYWlsLW9wZW4vY2xvc2VkIHBvbGljeS4gVGhlIGBwYXRoYFxuICogZGlmZmVycyBmcm9tIHRoZSBwYXJlbnQvZGVzY2VuZGFudHMgc2hhcGUsIHNvIHRoaXMgYnVpbGRzIGl0cyBvd24gcmVxdWVzdC5cbiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGZldGNoT3JnTWVtYmVyc2hpcChcbiAgb3JnSWQ6IHN0cmluZyxcbiAgdXNlcklkOiBzdHJpbmcsXG4gIG9wdHM6IE9yZ0hpZXJhcmNoeUh0dHBPcHRpb25zLFxuKTogUHJvbWlzZTxib29sZWFuIHwgdW5kZWZpbmVkPiB7XG4gIGNvbnN0IGNsaWVudCA9IG5ldyBJbnRlcm5hbEh0dHBDbGllbnQob3B0cy5zZXJ2aWNlKTtcbiAgY29uc3QgcGF0aCA9IGAvb3JnYW5pemF0aW9uLyR7ZW5jb2RlVVJJQ29tcG9uZW50KG9yZ0lkKX0vbWVtYmVycy8ke2VuY29kZVVSSUNvbXBvbmVudCh1c2VySWQpfS9leGlzdHNgO1xuICBjb25zdCBoZWFkZXJzOiBSZWNvcmQ8c3RyaW5nLCBzdHJpbmc+ID0ge1xuICAgIEF1dGhvcml6YXRpb246IGdldFNlcnZpY2VBdXRoSGVhZGVyKHtcbiAgICAgIHNlcnZpY2VOYW1lOiBvcHRzLnNlcnZpY2VOYW1lLFxuICAgICAgb3JnSWQ6IG9wdHMuYXV0aE9yZ0lkID8/IG9yZ0lkLFxuICAgICAgcm9sZTogb3B0cy5yb2xlID8/ICdtZW1iZXInLFxuICAgIH0pLFxuICAgIC4uLm9wdHMuaGVhZGVycyxcbiAgfTtcbiAgY29uc3QgcmVzID0gYXdhaXQgY2xpZW50LmdldDx7IGRhdGE/OiB7IGlzTWVtYmVyPzogdW5rbm93biB9IH0+KHBhdGgsIHsgaGVhZGVycywgdGltZW91dDogb3B0cy50aW1lb3V0IH0pO1xuICBpZiAocmVzLnN0YXR1c0NvZGUgPj0gNDAwKSByZXR1cm4gdW5kZWZpbmVkO1xuICBjb25zdCBpc01lbWJlciA9IHJlcy5ib2R5Py5kYXRhPy5pc01lbWJlcjtcbiAgcmV0dXJuIHR5cGVvZiBpc01lbWJlciA9PT0gJ2Jvb2xlYW4nID8gaXNNZW1iZXIgOiB1bmRlZmluZWQ7XG59XG4iXX0=

package/lib/helpers/org-hierarchy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Org → team hierarchy traversal (org-team-hierarchy proposal).
+ *
+ * A "team" is an organization whose `parentOrgId` points at another org; a root
+ * org has `parentOrgId = null`. These helpers walk that single self-referential
+ * column, but hold **no database dependency** of their own: each takes a query
+ * callback so every service (platform, quota, …) can share the cycle-safe,
+ * depth-capped traversal logic while reading its own Mongoose model with its own
+ * `_id` casting rules.
+ *
+ *   - {@link resolveOrgLineageWith} — UP: direct parent + root of the chain.
+ *   - {@link resolveRootOrgIdWith}   — UP: just the root id.
+ *   - {@link isAncestorOrgWith}      — UP: is A an ancestor of B?
+ *   - {@link expandOrgScopeWith}     — DOWN: self + all descendant org ids.
+ *
+ * Every org is flat today (`parentOrgId` null on all rows), so lineage resolves
+ * to `{ rootOrgId: self }` and scope to `[self]` — i.e. these are no-ops until
+ * orgs get parents.
+ */
+/** Hard ceiling on ancestry/descendant traversal — cycle + abuse guard. */
+export declare const MAX_ORG_DEPTH = 16;
+/** Fetch an org's direct `parentOrgId`, or undefined for a root/missing org. */
+export type GetParentOrgId = (orgId: string) => Promise<string | undefined>;
+/** Fetch the direct child org ids of every org in `frontier` (one round of BFS). */
+export type GetChildOrgIds = (frontier: string[]) => Promise<string[]>;
+/** Normalize a Mixed/ObjectId/string org id to a non-empty string, or undefined. */
+export declare function toOrgIdString(v: unknown): string | undefined;
+export interface OrgLineage {
+    /** The org's direct parent id, or `undefined` when it's a root org. */
+    parentOrgId?: string;
+    /** Top of the ancestry chain. Equals the input `orgId` for a root org. */
+    rootOrgId: string;
+}
+/**
+ * Walk `parentOrgId` from `orgId` up to the root. Returns the direct parent (if
+ * any) and the root org id (the input itself when the org has no parent). On a
+ * detected cycle, a missing org, or the depth cap, traversal stops and the last
+ * reached id is treated as the root.
+ */
+export declare function resolveOrgLineageWith(orgId: string, getParent: GetParentOrgId): Promise<OrgLineage>;
+/** Walk `parentOrgId` up to the root and return just the root id. */
+export declare function resolveRootOrgIdWith(orgId: string, getParent: GetParentOrgId): Promise<string>;
+/**
+ * True when `ancestorOrgId` is an ancestor of `candidateOrgId` — i.e.
+ * `candidateOrgId` lives somewhere in the subtree rooted at `ancestorOrgId`.
+ * Walks `candidateOrgId`'s parent chain upward, depth-capped and cycle-safe.
+ * Returns `false` when the two are equal (an org is not its own ancestor) or
+ * unrelated.
+ */
+export declare function isAncestorOrgWith(ancestorOrgId: string, candidateOrgId: string, getParent: GetParentOrgId): Promise<boolean>;
+/**
+ * Expand `orgId` to itself plus every descendant org id (breadth-first over
+ * `parentOrgId`). This is the scope a parent org "sees" for visibility and
+ * analytics rollups: `[self, ...descendants]`. Returns `[orgId]` when the org
+ * has no children. Cycle-safe and depth-capped.
+ */
+export declare function expandOrgScopeWith(orgId: string, getChildren: GetChildOrgIds): Promise<string[]>;