🧱 Organization blocks

Organization blocks are public constants, error classes, and reusable organization operations exported through blocks from @nodeblocks/backend-sdk. Functions return a neverthrow Result or Promise<Result<…>>; inspect the result before reading its value.

Inventory

Export	Kind	Inputs	Result / behavior / errors
AUDIT_STATUS_WAITING_FOR_REVIEW	Constant	None	Exact audit-status literal 'waiting_for_review'.
AUDIT_STATUS_REJECTED	Constant	None	Exact audit-status literal 'rejected'.
AUDIT_STATUS_APPROVED	Constant	None	Exact audit-status literal 'approved'.
ALLOWED_AUDIT_STATUS	Constant	None	Readonly list of allowed audit-status literals.
OrganizationBlockError	Error class	Message, optional data	Base Organization BlockError; routes map concrete subclasses.
OrganizationInvalidQueryError	Error class	Message, optional data	Invalid descendant-query parameters; routes map it to 400.
OrganizationDbError	Error class	Message, optional data	Organization database failure; routes map it to 500.
OrganizationMemberNotFoundError	Error class	Message, optional data	Missing organization member; routes map it to 404.
OrganizationMemberRoleNotFoundError	Error class	Message, optional data	Missing member role; routes map it to 404.
OrganizationBadRequestError	Error class	Message, optional data	Malformed organization request; routes map it to 400.
OrganizationChangeRequestDbError	Error class	Message, optional data	Change-request database failure; routes map it to 500.
OrganizationChangeRequestError	Error class	Message, optional data	Change-request normalization or processing failure.
OrganizationNotFoundError	Error class	Message, optional data	Missing organization; routes map it to 404.
calculateChildAncestors	Function	Parent organization	Ancestor ID array for a child organization; never errors.
createOrganization	Function	Collection, owner ID, organization, optional parent ID and ancestors	Created organization ID or OrganizationBlockError.
getOrganizationById	Function	Collection, organization ID	Organization document or not-found/database error.
findOrganizations	Function	Collection, filter	Matching organizations or database error.
updateOrganization	Function	Collection, organization ID, update payload	Update success or not-found/database error.
deleteOrganization	Function	Collection, organization ID	Deletion success or not-found/database error.
calculateDirectMemberRole	Function	Members array, identity ID	Direct member role or member/role not-found error.
checkOrganizationMemberExistence	Function	Members array, identity ID	Membership boolean or processing error.
findOrganizationMembers	Function	Collection, organization ID	Members with pagination metadata or not-found/database error.
upsertOrganizationMembers	Function	Collection, existing members, organization ID, members to upsert	Upsert success or not-found/database error.
deleteOrganizationMember	Function	Collection, organization ID, identity ID	Removal success or not-found/database error.
findOrganizationsForIdentity	Function	Collection, identity ID, optional roles filter	Organizations for the identity or database error.
buildDescendantsQuery	Function	Organization, optional depth	Descendant MongoDB filter or OrganizationInvalidQueryError.
normalizeOrganization	Function	Organization document	Organization without MongoDB _id; never errors.
normalizeOrganizations	Function	Organization array	Normalized organizations without _id; never errors.
buildOrganizationsForMemberByRoleQuery	Function	Identity ID, optional roles	MongoDB membership filter; never errors.
buildOrganizationsForMemberByIdsQuery	Function	Identity ID, organization IDs	MongoDB membership-by-ID filter; never errors.
buildOrganizationsWithDescendantsQuery	Function	Organization array	MongoDB descendant/ancestor filter; never errors.
normalizeLogoOfOwner	Function	File-storage driver, owner with logo	Owner with signed logo URL or OrganizationBlockError.
normalizeCertificateImage	Function	File-storage driver, organization	Organization with certificate image URL or error.
normalizeLogosOfOwners	Function	File-storage driver, owners	Owners with signed logo URLs or batch error.
normalizeCertificateImages	Function	File-storage driver, organizations	Organizations with certificate URLs or batch error.
normalizeLogosOfPaginatedOwners	Function	File-storage driver, paginated owners	Paginated owners with signed logo URLs or batch error.
deleteLogoOfOwner	Function	File-storage driver, owner	true or FileStorageServiceError.
extractAncestors	Function	Organization array	Unique ancestor organization IDs; never errors.
calculateInheritedMemberRole	Function	Ancestor organizations, identity ID	Highest inherited role or OrganizationMemberRoleNotFoundError.
calculateMemberRole	Function	Organization, ancestor organizations, identity ID	Direct or inherited role or role-not-found error.
calculateMemberRoleForOrganizations	Function	Organizations, ancestor organizations, identity ID	Per-organization member role info or role-not-found error.
normalizeOrganizationsForMember	Function	Organizations with member info	API-shaped member/organization pairs; never errors.
validateOrganizationName	Function	Collection, organization, organization ID, optional name	true, duplicate-name error, or database error.
createChangeRequest	Function	Change-requests collection, organization ID, identity ID, payload	Created change-request ID or database error.
buildUpdateOrganizationAfterNewChangeRequestPayload	Function	None	Audit-status update payload; never errors.
validateAuditStatus	Function	Optional audit status	true or OrganizationBadRequestError.
findChangeRequests	Function	Change-requests collection, organization ID, optional filter	Matching change requests or database error.
normalizeChangeRequest	Function	File-storage driver, raw change request	Normalized change request with certificate URL or error.
normalizeChangeRequests	Function	File-storage driver, change requests	Normalized change requests or batch error.
buildOrganizationIdFilter	Function	Organization ID	Filter object with organizationId; never errors.
buildOrganizationFollowersByFollowOrganizationIdQuery	Function	Followed organization ID	MongoDB $elemMatch filter for organization follows; never errors.

Details

AUDIT_STATUS_WAITING_FOR_REVIEW

Implementation

Exact audit-status literal used by Organization audit workflows.

Used by Custom composition only.

AUDIT_STATUS_REJECTED

Implementation

Exact audit-status literal used by Organization audit workflows.

Used by Custom composition only.

AUDIT_STATUS_APPROVED

Implementation

Exact audit-status literal used by Organization audit workflows.

Used by Custom composition only.

ALLOWED_AUDIT_STATUS

Implementation

Exact readonly list: 'waiting_for_review', 'rejected', and 'approved'.

Used by Custom composition only.

OrganizationBlockError

Implementation

OrganizationBlockError extends BlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by Custom composition only.

OrganizationInvalidQueryError

Implementation

OrganizationInvalidQueryError extends OrganizationBlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by findOrganizationDescendantsRoute.

OrganizationDbError

Implementation

OrganizationDbError extends OrganizationBlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by getOrganizationMemberRoleRoute, findOrganizationsForMemberRoute, findOrganizationDescendantsRoute, createChangeRequestRoute, getOrganizationFollowersRoute.

OrganizationMemberNotFoundError

Implementation

OrganizationMemberNotFoundError extends OrganizationBlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by getOrganizationMemberRoleRoute, findOrganizationsForMemberRoute.

OrganizationMemberRoleNotFoundError

Implementation

OrganizationMemberRoleNotFoundError extends OrganizationBlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by getOrganizationMemberRoleRoute, findOrganizationsForMemberRoute.

OrganizationBadRequestError

Implementation

OrganizationBadRequestError extends OrganizationBlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by createChangeRequestRoute.

OrganizationChangeRequestDbError

Implementation

OrganizationChangeRequestDbError extends OrganizationBlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by createChangeRequestRoute, findChangeRequestsForOrganizationRoute.

OrganizationChangeRequestError

Implementation

OrganizationChangeRequestError extends OrganizationBlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by findChangeRequestsForOrganizationRoute.

OrganizationNotFoundError

Implementation

OrganizationNotFoundError extends OrganizationBlockError. It carries the block failure; the consuming route maps it to an HTTP response only where its source pipeline explicitly does so.

Used by getOrganizationFollowersRoute.

calculateChildAncestors

Implementation

Signature: export async function calculateChildAncestors( parentOrganization: Record<string, unknown> ): Promise<Result<string[], never>>

Calculates ancestors array for a child organization based on parent organization.

Used by createOrganizationRoute.

createOrganization

Implementation

Signature: export const createOrganization = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], ownerId: string, organization: Record<string, unknown>, parentId?: string, ancestors: string[] = [] ): Promise<Result<string, OrganizationBlockError>> =>

Creates a new organization in the database with the specified owner.

Used by createOrganizationRoute.

getOrganizationById

Implementation

Signature: export const getOrganizationById = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], organizationId: string ): Promise<Result<WithId<Document>, Error>> =>

Retrieves an organization by its ID from the database.

Used by createOrganizationRoute, getOrganizationRoute, updateOrganizationRoute, updateOrganizationAsAdminRoute, deleteOrganizationRoute, getOrganizationMemberRoleRoute, checkOrganizationMemberExistenceRoute, upsertOrganizationMembersRoute, findOrganizationDescendantsRoute, createChangeRequestRoute, getOrganizationFollowersRoute.

findOrganizations

Implementation

Signature: export const findOrganizations = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], filter: Record<string, unknown> ): Promise<Result<Record<string, unknown>[], Error>> =>

Finds organizations in the database based on the provided filter criteria.

Used by findOrganizationsRoute, getOrganizationMemberRoleRoute, findOrganizationsForMemberRoute, findOrganizationDescendantsRoute.

updateOrganization

Implementation

Signature: export const updateOrganization = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], organizationId: string, organization: Record<string, unknown> ): Promise<Result<boolean, Error>> =>

Updates an organization in the database with the provided data.

Used by updateOrganizationRoute, updateOrganizationAsAdminRoute, createChangeRequestRoute.

deleteOrganization

Implementation

Signature: export const deleteOrganization = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], organizationId: string ): Promise<Result<boolean, Error>> =>

Deletes an organization from the database by its ID.

Used by deleteOrganizationRoute.

calculateDirectMemberRole

Implementation

Signature: export function calculateDirectMemberRole( members: OrganizationMember[], identityId: string ): Result< string, OrganizationMemberNotFoundError | OrganizationMemberRoleNotFoundError >

Calculates the direct role of a member within an organization.

Used by Custom composition only.

checkOrganizationMemberExistence

Implementation

Signature: export const checkOrganizationMemberExistence = async ( members: OrganizationMember[], identityId: string ): Promise<Result<boolean, Error>> =>

Checks if a specific identity is a member of an organization.

Used by checkOrganizationMemberExistenceRoute.

findOrganizationMembers

Implementation

Signature: export const findOrganizationMembers = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], organizationId: string ): Promise<Result<OrganizationMember[], Error>> =>

Retrieves all members of an organization with pagination metadata.

Used by findOrganizationMembersRoute.

upsertOrganizationMembers

Implementation

Signature: export const upsertOrganizationMembers = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], existingMembers: OrganizationMember[] = [], organizationId: string, membersToUpsert: OrganizationMember[] ): Promise<Result<boolean, Error>> =>

Updates or inserts organization members by merging with existing members.

Used by upsertOrganizationMembersRoute.

deleteOrganizationMember

Implementation

Signature: export const deleteOrganizationMember = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], organizationId: string, identityId: string ): Promise<Result<boolean, Error>> =>

Removes a specific member from an organization using MongoDB $pull operation.

Used by deleteOrganizationMemberRoute.

findOrganizationsForIdentity

Implementation

Signature: export const findOrganizationsForIdentity = async ( organizationsCollection: OrganizationServiceDataStore['organizations'], identityId: string, roles?: string ): Promise< Result<

Finds all organizations where a specific identity is a member, optionally filtered by roles.

Used by Custom composition only.

buildDescendantsQuery

Implementation

Signature: export function buildDescendantsQuery( organization: Record<string, unknown>, depth?: string | number ): Result<Record<string, unknown>, OrganizationInvalidQueryError>

Builds MongoDB query for finding descendant organizations in hierarchy.

Used by findOrganizationDescendantsRoute.

normalizeOrganization

Implementation

Signature: export function normalizeOrganization( organization: Record<string, unknown> ): Result<Record<string, unknown>, never>

Removes MongoDB _id field from organization data.

Used by Custom composition only.

normalizeOrganizations

Implementation

Signature: export function normalizeOrganizations( organizations: Record<string, unknown>[] ): Result<Record<string, unknown>[], never>

Normalizes array of organizations by removing _id fields from each.

Used by findOrganizationDescendantsRoute.

buildOrganizationsForMemberByRoleQuery

Implementation

Signature: export function buildOrganizationsForMemberByRoleQuery( identityId: string, roles?: string ): Result<Record<string, unknown>, never>

Builds a MongoDB query to find organizations where a specific identity is a member, optionally filtered by roles.

Used by findOrganizationsForMemberRoute.

buildOrganizationsForMemberByIdsQuery

Implementation

Signature: export function buildOrganizationsForMemberByIdsQuery( identityId: string, organizationIds: string[] ): Result<Record<string, unknown>, never>

Builds a MongoDB query to find organizations by IDs where a specific identity is a member.

Used by getOrganizationMemberRoleRoute, findOrganizationsForMemberRoute.

buildOrganizationsWithDescendantsQuery

Implementation

Signature: export function buildOrganizationsWithDescendantsQuery( organizations: Record<string, unknown>[] ): Result<Record<string, unknown>, never>

Builds a MongoDB query to find organizations by their own IDs or by ancestor IDs.

Used by findOrganizationsForMemberRoute.

normalizeLogoOfOwner

Implementation

Signature: export async function normalizeLogoOfOwner< T extends

Normalizes owner logo by converting objectId to signed download URL.

Used by createOrganizationRoute, getOrganizationRoute, updateOrganizationRoute, updateOrganizationAsAdminRoute.

normalizeCertificateImage

Implementation

Signature: export async function normalizeCertificateImage( fileStorageDriver: FileStorageDriver, organization: Record<string, unknown> &

Normalizes organization certificate image by generating signed download URL.

Used by getOrganizationRoute, updateOrganizationRoute, updateOrganizationAsAdminRoute.

normalizeLogosOfOwners

Implementation

Signature: export async function normalizeLogosOfOwners< T extends

Normalizes logos for multiple owners by converting objectIds to signed URLs.

Used by findOrganizationsRoute, findOrganizationsForMemberRoute.

normalizeCertificateImages

Implementation

Signature: export async function normalizeCertificateImages( fileStorageDriver: FileStorageDriver, organizations: (Record<string, unknown> &

Normalizes certificate image URLs for multiple organizations using file storage driver.

Used by findOrganizationsRoute, findOrganizationsForMemberRoute.

normalizeLogosOfPaginatedOwners

Implementation

Signature: export async function normalizeLogosOfPaginatedOwners< T extends

Normalizes logos for paginated owners by converting objectIds to signed URLs.

Used by Custom composition only.

deleteLogoOfOwner

Implementation

Signature: export async function deleteLogoOfOwner< T extends

Deletes logo file from file storage for organization owner.

Used by deleteOrganizationRoute.

extractAncestors

Implementation

Signature: export function extractAncestors( organizations: Record<string, unknown>[] ): Result<string[], never>

Extracts all unique ancestor organization IDs from a list of organizations.

Used by findOrganizationsForMemberRoute.

calculateInheritedMemberRole

Implementation

Signature: export function calculateInheritedMemberRole( ancestorOrganizations: Record<string, unknown>[], identityId: string ): Result<

Calculates the highest inherited member role for an identity from a set of ancestor organizations.

Used by Custom composition only.

calculateMemberRole

Implementation

Signature: export function calculateMemberRole( organization: Record<string, unknown>, ancestorOrganizations: Record<string, unknown>[], identityId: string ): Result<

Calculates the member role (direct or inherited) for a single organization and identity.

Used by getOrganizationMemberRoleRoute.

calculateMemberRoleForOrganizations

Implementation

Signature: export async function calculateMemberRoleForOrganizations( organizations: Record<string, unknown>[], ancestorOrganizations: Record<string, unknown>[], identityId: string ): Promise< Result<

Calculates member role information (direct and inherited) for each organization in a list.

Used by findOrganizationsForMemberRoute.

normalizeOrganizationsForMember

Implementation

Signature: export function normalizeOrganizationsForMember( organizationsWithMemberInfo: Record<string, unknown>[] ): Result<Record<string, unknown>[], never>

Normalizes organizations for member response by structuring the data according to the API specification.

Used by findOrganizationsForMemberRoute.

validateOrganizationName

Implementation

Signature: export async function validateOrganizationName( organizationsCollection: OrganizationServiceDataStore['organizations'], organization:

Organization name uniqueness validation against organization owners.

Used by createChangeRequestRoute.

createChangeRequest

Implementation

Signature: export const createChangeRequest = async ( organizationChangeRequestsCollection: Collection, organizationId: string, identityId: string, changeRequest: Record<string, string> &

Organization change request creation in database.

Used by createChangeRequestRoute.

buildUpdateOrganizationAfterNewChangeRequestPayload

Implementation

Signature: export function buildUpdateOrganizationAfterNewChangeRequestPayload(): Result<

Organization audit status update payload after new change request.

Used by createChangeRequestRoute.

validateAuditStatus

Implementation

Signature: export const validateAuditStatus = ( auditStatus?: string ): Result<boolean, OrganizationBadRequestError> =>

Organization audit status validation for change request workflows.

Used by updateOrganizationAsAdminRoute.

findChangeRequests

Implementation

Signature: export async function findChangeRequests( organizationChangeRequestsCollection: Collection, organizationId: string ): Promise< Result<Record<string, unknown>[], OrganizationChangeRequestDbError> >

Organization change requests retrieval for an organization with optional filters.

Used by findChangeRequestsForOrganizationRoute.

normalizeChangeRequest

Implementation

Signature: export async function normalizeChangeRequest( fileStorageDriver: FileStorageDriver, rawChangeRequest: Record<string, unknown> &

Normalizes organization change request data with certificate image URL generation.

Used by Custom composition only.

normalizeChangeRequests

Implementation

Signature: export async function normalizeChangeRequests( fileStorageDriver: FileStorageDriver, changeRequests: Record<string, unknown>[] ): Promise<Result<Record<string, unknown>[], OrganizationChangeRequestError>>

Normalizes multiple organization change requests with file storage URL generation.

Used by findChangeRequestsForOrganizationRoute.

buildOrganizationIdFilter

Implementation

Signature: export function buildOrganizationIdFilter( organizationId: string ): Result<

Builds organization ID filter object for database queries.

Used by Custom composition only.

buildOrganizationFollowersByFollowOrganizationIdQuery

Implementation

Signature: export function buildOrganizationFollowersByFollowOrganizationIdQuery< T extends

Builds MongoDB query filter to find organizations that follow a specific organization.

Used by getOrganizationFollowersRoute.