User Listing API — Developer Guide

Overview

The User Listing API provides platform administrators with full visibility into all registered Visitors, Malet Owners, and Organizations on the Mallnline platform. Exposed through the nodes subgraph (apps/nodes), these admin-only queries bypass individual privacy settings and aggregate cross-service activity statistics into a single response.

All operations are gated behind dual-layer access control: the @RequirePermission(Permission.MANAGE_USERS) decorator guard and a runtime PLATFORM_ADMIN role check.

Architecture

graph TD
    A["AdminUsersResolver"] --> B["AdminUsersService"]
    B --> C["User Model (MongoDB)"]
    B --> D["Follow Model (MongoDB)"]
    B --> E["Collection Model (MongoDB)"]

    A -- "admin header" --> F["@RequirePermission(MANAGE_USERS)"]
    A -- "runtime" --> G["assertPlatformAdmin(actor)"]

    subgraph "Activity Stats (Local)"
        D -- "countDocuments" --> H["followersCount"]
        D -- "countDocuments" --> I["followingCount"]
        E -- "countDocuments" --> J["collectionsCount"]
    end

    subgraph "Activity Stats (Federation Stubs)"
        K["ordersCount = 0"]
        L["bookingsCount = 0"]
        M["blogPostsCount = 0"]
    end

    style F fill:#dc2626,color:#fff
    style G fill:#dc2626,color:#fff
    style K fill:#6b7280,color:#fff
    style L fill:#6b7280,color:#fff
    style M fill:#6b7280,color:#fff

How It Fits Together

The nodes subgraph already owns the User entity — profile data, preferences, privacy settings, and the follow/collection graphs. The admin API adds a privileged view of this data:

• Privacy bypass: Normal user queries respect profileVisibility: PRIVATE and contentVisibility: ANONYMOUS. Admin queries return real profile data regardless of these settings.
• Activity aggregation: Each AdminUserNode includes a UserActivityStats object with counts pulled from the local Follow and Collection models. Cross-service counts (Murchases, bookings, blog posts) default to 0 and are designed for future federation enrichment.
• Text search: The search filter performs case-insensitive partial matching across userId, displayName, and email fields simultaneously.

GraphQL API

List All Users (Paginated)

The primary query returns a cursor-paginated connection with optional search and sort:

query AdminUsers($first: Int, $after: String, $filter: AdminUserFilter) {
	adminUsers(first: $first, after: $after, filter: $filter) {
		edges {
			node {
				id
				userId
				displayName
				email
				bio
				location
				avatarUrl
				website
				company
				createdAt
				updatedAt
				isPrivate
				contentVisibility
				activityStats {
					followersCount
					followingCount
					collectionsCount
					ordersCount
					bookingsCount
					blogPostsCount
				}
			}
			cursor
		}
		pageInfo {
			hasNextPage
			hasPreviousPage
			startCursor
			endCursor
		}
		totalCount
	}
}

Variables:

{
	"first": 20,
	"after": null,
	"filter": {
		"search": "alice",
		"sortBy": "DISPLAY_NAME",
		"sortOrder": "ASC"
	}
}

Total Platform User Count

A lightweight query for dashboard widgets:

query {
	adminUserCount
}

Returns a single Int — the total number of registered users on the platform.

Single User Detail

Fetch a single user's full admin view by their federated ID:

query AdminUser($id: ID!) {
	adminUser(id: $id) {
		id
		userId
		displayName
		email
		bio
		location
		avatarUrl
		website
		company
		createdAt
		updatedAt
		isPrivate
		contentVisibility
		activityStats {
			followersCount
			followingCount
			collectionsCount
			ordersCount
			bookingsCount
			blogPostsCount
		}
	}
}

Returns a NotFoundError if the user does not exist.

Type Reference

AdminUserNode

The admin-specific view of a Visitor or Malet Owner profile:

UserActivityStats

Cross-service activity statistics aggregated per user:

Note: Cross-service stats are currently set to 0 by the nodes subgraph. When owning subgraphs (murchases, services, blogs) add @provides fields to the AdminUserNode type, the Gateway will automatically compose the real values.

AdminUserFilter

Enums

enum AdminUserSortField {
  CREATED_AT    // Sort by account creation date (default)
  DISPLAY_NAME  // Alphabetical by display name
  EMAIL         // Alphabetical by email
}

enum AdminSortDirection {
  ASC   // Ascending (oldest first / A→Z)
  DESC  // Descending (newest first / Z→A)
}

Access Control

Dual-Layer Security

The User Listing API uses defense-in-depth access control:

1. Declarative guard — @RequirePermission(Permission.MANAGE_USERS) on each resolver method. This is processed by the NestJS guard pipeline before the method executes.

2. Runtime check — assertPlatformAdmin(actor) verifies the actor's role === 'PLATFORM_ADMIN' at the start of each method body. This catches edge cases where the permission system may not have the latest role data.

@Query(() => AdminUserConnection)
@RequirePermission(Permission.MANAGE_USERS)
@HandleErrors()
async adminUsers(
  @Args() paging: AdminUserPagingArgs,
  @Args('filter', { nullable: true }) filter: AdminUserFilter,
  @CurrentActor() actor: Actor,
): Promise<AdminUserConnection> {
  this.assertPlatformAdmin(actor); // Runtime defense-in-depth
  // ...
}

Authentication Header

The Gateway forwards the user header from the Auth service to downstream subgraphs. For admin access, the header must contain a PLATFORM_ADMIN role:

{
	"id": "admin-user-id",
	"login": "admin",
	"role": "PLATFORM_ADMIN"
}

Requests without authentication or with a non-admin role receive a ForbiddenException.

Privacy Bypass

Normal User queries in the nodes subgraph respect privacy settings:

The AdminUsersService.listUsers() method queries the User model directly without applying privacy filters. The isPrivate and contentVisibility fields are returned so admins can see each user's privacy settings without those settings affecting the query results.

Module Structure

apps/nodes/src/actors/user/
├── admin-users.types.ts          # GraphQL types, enums, connection types
├── admin-users.service.ts        # Paginated listing + activity stats
├── admin-users.service.spec.ts   # 14 unit tests
├── admin-users.resolver.ts       # Admin-only resolver (3 queries)
├── admin-users.resolver.spec.ts  # 10 unit tests
└── user.module.ts                # Registers service + resolver + Follow/Collection models

apps/nodes/test/
└── admin-users.e2e-spec.ts       # 10 E2E tests

Cross-Service Integration

Dependency Map

Federation Enrichment (Future)

When owning subgraphs contribute @provides annotations to the AdminUserNode type, the cross-service stats will be automatically resolved by the federation gateway:

Testing

Unit Tests

# Run admin-users unit tests (24 tests across 2 suites)
npm run test -- apps/nodes --testPathPattern="admin-users"

Key coverage areas:

• AdminUsersService: Pagination, hasNextPage detection, text search filter, regex escaping, sort (field + direction), empty results, user count, user-by-ID, private profile detection, activity stats aggregation, cross-service stubs
• AdminUsersResolver: Connection construction, access control (admin/non-admin/unauthenticated), filter pass-through, cursor forwarding, limit capping (max 100), user count delegation, single user detail, not-found error

E2E Tests

# Run admin-users E2E tests (10 tests)
npx jest --config apps/nodes/test/jest-e2e.json --testPathPattern="admin-users" --detectOpenHandles

Covers:

• Paginated user listing with all fields and activity stats
• PRIVATE profile visibility bypass for admins
• Text search filtering (by display name)
• Unauthenticated request rejection
• Non-admin user rejection (with error message assertion)
• Total user count query
• Single user detail query with full field coverage
• 404 for non-existent user IDs
• Admin access enforcement on all three queries

Related

• Analytics Aggregation API — Companion admin-only API for revenue and Murchase analytics
• Privacy & Security APIs — Privacy bypass logic and content visibility settings
• Organizations & Permissions — MANAGE_USERS permission and PLATFORM_ADMIN role check used for access control
• Platform Admin Provisioning — Dedicated platform_admins table backing the PLATFORM_ADMIN role