@flowdular/sdk 0.2.4 → 0.3.1

package/modules/users/src/client/api.ts

@@ -1,21 +1,25 @@
-import type { TenantMember } from '@flowdular/sdk/modules/auth';
+import type { TenantMember, TenantMemberSort } from '@flowdular/sdk/modules/auth';
 import { t } from '@flowdular/sdk/client/i18n';
 import type {
 	CreateUserInput,
-	UserDirectory,
+	MemberBulkOutcome,
+	UsersContext,
 } from '../services/users-service.ts';
 
 interface ErrorEnvelope {
-	readonly error?: { readonly message?: string };
+	readonly error?: { readonly code?: string; readonly message?: string };
 }
 
 export class ApiError extends Error {
 	readonly status: number;
+	/** Stable server code; '' when the response carried none. */
+	readonly code: string;
 
-	constructor(status: number, message: string) {
+	constructor(status: number, message: string, code = '') {
 		super(message);
 		this.name = 'ApiError';
 		this.status = status;
+		this.code = code;
 	}
 }
 
@@ -25,6 +29,7 @@ async function payload<T>(response: Response): Promise<T> {
 		throw new ApiError(
 			response.status,
 			value.error?.message ?? t('users.error.request'),
+			value.error?.code ?? '',
 		);
 	}
 	return value;
@@ -47,12 +52,57 @@ async function post<T>(
 	return payload<T>(response);
 }
 
-export async function loadTenantUsers(): Promise<UserDirectory> {
-	const response = await fetch('/api/users', {
+/* exports.core owns the job, its file and the screen that hands it over, so the
+   Members screen only starts one: what comes back is the job as that screen
+   will show it, and nothing here models it. */
+export async function startListExport(
+	list: string,
+	csrfToken: string,
+): Promise<void> {
+	await post<unknown>('/api/exports/start', { list }, csrfToken);
+}
+
+export interface MemberListRequest {
+	readonly sort: TenantMemberSort;
+	readonly direction: 'asc' | 'desc';
+	readonly limit: number;
+	/** A prefix of the display name or the address; '' narrows nothing. */
+	readonly query: string;
+	readonly status: '' | 'active' | 'disabled';
+	/** The cursor that opens this page; null asks for the first one. */
+	readonly cursor: string | null;
+}
+
+export interface MemberListPage {
+	readonly items: readonly TenantMember[];
+	readonly page: { readonly nextCursor: string | null; readonly limit: number };
+}
+
+/** One server-sorted, server-narrowed, server-paged listing; the screen narrows nothing. */
+export async function loadTenantUsers(
+	request: MemberListRequest,
+): Promise<MemberListPage> {
+	const parameters = new URLSearchParams({
+		sort: request.sort,
+		direction: request.direction,
+		limit: String(request.limit),
+	});
+	if (request.query !== '') parameters.set('q', request.query);
+	if (request.status !== '') parameters.set('status', request.status);
+	if (request.cursor !== null) parameters.set('cursor', request.cursor);
+	const response = await fetch('/api/users?' + parameters.toString(), {
 		headers: { accept: 'application/json' },
 		credentials: 'same-origin',
 	});
-	return payload<UserDirectory>(response);
+	return payload<MemberListPage>(response);
+}
+
+export async function loadUsersContext(): Promise<UsersContext> {
+	const response = await fetch('/api/users/context', {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	return payload<UsersContext>(response);
 }
 
 export async function createTenantUser(
@@ -105,18 +155,62 @@ export async function assignMemberRole(
 	).user;
 }
 
-export async function setMemberStatus(
+/* The operator's global account block reaches every workspace the account
+   belongs to, so no workspace screen calls it and this client has no fetch for
+   POST /api/users/status. The drawer shows the account state read-only and
+   changes workspace access through setMembershipStatus below. */
+
+export interface MembershipStatusResult {
+	readonly accountId: string;
+	readonly status: 'active' | 'disabled';
+}
+
+/* Access to this workspace only. auth.core owns the membership and enforces the
+   self-target and last-owner rules, so the call goes to its administration
+   route directly, as the invitation and session routes above do. */
+export async function setMembershipStatus(
 	accountId: string,
 	status: 'active' | 'disabled',
 	csrfToken: string,
-): Promise<TenantMember> {
+): Promise<MembershipStatusResult> {
 	return (
-		await post<MemberResponse>(
-			'/api/users/status',
+		await post<{ readonly membership: MembershipStatusResult }>(
+			'/api/auth/memberships/status',
 			{ accountId, status },
 			csrfToken,
 		)
-	).user;
+	).membership;
+}
+
+type OutcomesResponse = { readonly outcomes: readonly MemberBulkOutcome[] };
+
+/* Workspace access for the selected rows, one outcome per id. */
+export async function setMembershipStatusMany(
+	accountIds: readonly string[],
+	status: 'active' | 'disabled',
+	csrfToken: string,
+): Promise<readonly MemberBulkOutcome[]> {
+	return (
+		await post<OutcomesResponse>(
+			'/api/users/status-many',
+			{ accountIds, status },
+			csrfToken,
+		)
+	).outcomes;
+}
+
+export async function assignRoleMany(
+	accountIds: readonly string[],
+	role: string,
+	csrfToken: string,
+): Promise<readonly MemberBulkOutcome[]> {
+	return (
+		await post<OutcomesResponse>(
+			'/api/users/role-many',
+			{ accountIds, role },
+			csrfToken,
+		)
+	).outcomes;
 }
 
 export async function removeMember(

package/modules/users/src/client/contribution.tsrx

@@ -16,6 +16,10 @@ export interface UsersClientContributionOptions {
 
 const ROLES_READ = 'auth.roles.read';
 const ROLES_MANAGE = 'auth.roles.manage';
+/* exports.core's own scope, held here as a string the same way the auth role
+   scopes are: a deployment without that module grants it to nobody, so the
+   action is simply absent rather than offered and refused. */
+const EXPORTS_MANAGE = 'exports.lists.manage';
 
 export function createUsersClientContribution(
 	options: UsersClientContributionOptions,
@@ -61,6 +65,7 @@ export function createUsersClientContribution(
 					<UsersView
 						csrfToken={options.csrfToken}
 						canManage={has(USER_PERMISSIONS.manage)}
+						canExport={has(EXPORTS_MANAGE)}
 					/>,
 			},
 			{

package/modules/users/src/client/member-columns.tsrx

@@ -6,19 +6,26 @@ export function memberColumns(
 	roleNames: ReadonlyMap<string, string>,
 ): readonly TableColumn<TenantMember>[] {
 	return [
+		/* The two keys the server sorts by are the two sortable columns, so a
+   header click names the sort key as it is. */
 		{
-			key: 'user',
+			key: 'displayName',
 			header: t('users.table.user'),
-			width: '32%',
-			cell: (user) => <span class="ui-cell">
-				<b>{user.displayName}</b>
-				<small>{user.email}</small>
-			</span>,
+			width: '22%',
+			value: (user) => user.displayName,
+			cell: (user) => <b>{user.displayName}</b>,
+		},
+		{
+			key: 'email',
+			header: t('users.table.email'),
+			width: '24%',
+			value: (user) => user.email,
+			cell: (user) => <span>{user.email}</span>,
 		},
 		{
 			key: 'role',
 			header: t('users.table.role'),
-			width: '18%',
+			width: '14%',
 			cell: (user) =>
 				<Tag tone={user.role === 'owner' ? 'ink' : 'neutral'}>
 					{roleNames.get(user.role) ?? user.role}
@@ -29,11 +36,17 @@ export function memberColumns(
 			header: t('users.table.status'),
 			width: '28%',
 			cell: (user) => <span class="ui-table__state">
-				<Tag tone={user.status === 'active' ? 'success' : 'neutral'} dot>
-					{user.status === 'active'
+				<Tag
+					tone={user.membershipStatus === 'active' ? 'success' : 'neutral'}
+					dot
+				>
+					{user.membershipStatus === 'active'
 						? t('users.status.active')
 						: t('users.status.disabled')}
 				</Tag>
+				{user.status === 'disabled'
+					? <small>{t('users.status.blocked')}</small>
+					: null}
 				{user.passwordChangeRequired
 					? <small>{t('users.status.passwordResetPending')}</small>
 					: null}

package/modules/users/src/client/state.ts

@@ -1,6 +1,12 @@
-import type { TenantMember } from '@flowdular/sdk/modules/auth';
+import type { TenantMember, TenantMemberSort } from '@flowdular/sdk/modules/auth';
+import { t } from '@flowdular/sdk/client/i18n';
+import type { TableSort } from '@flowdular/sdk/ui';
 import { cell, createStore } from 'segment-state';
-import type { UserDirectory } from '../services/users-service.ts';
+import type {
+	MemberBulkOutcome,
+	UsersContext,
+} from '../services/users-service.ts';
+import { ApiError, type MemberListPage } from './api.ts';
 
 export type UsersStatus =
 	| 'idle'
@@ -9,14 +15,51 @@ export type UsersStatus =
 	| 'denied'
 	| 'error';
 
+export type MemberStatusFilter = '' | 'active' | 'disabled';
+
+export const DEFAULT_MEMBER_SORTING: readonly TableSort[] = [
+	{ key: 'displayName', desc: false },
+];
+
+/**
+ * The cursor that opened each page the reader has visited: page 0 has none,
+ * and page n holds the cursor page n - 1 answered. Going back reuses the stored
+ * cursor; a page past the stack cannot be opened.
+ */
+export type PageCursors = readonly (string | null)[];
+
+/** One listing as the server answers it: the page, its order and its filters. */
+export interface Listing {
+	readonly pageIndex: number;
+	readonly pageSize: number;
+	readonly sorting: readonly TableSort[];
+	readonly query: string;
+	readonly status: MemberStatusFilter;
+	readonly cursors: PageCursors;
+}
+
 export function createUsersClientState() {
 	const store = createStore({
 		users: cell<readonly TenantMember[]>([]),
-		roles: cell<UserDirectory['roles']>([]),
+		roles: cell<UsersContext['roles']>([]),
 		grantableScopes: cell<readonly string[]>([]),
-		actor: cell<UserDirectory['actor'] | null>(null),
+		actor: cell<UsersContext['actor'] | null>(null),
 		passwordMinLength: 12,
+		memberCount: 0,
 		query: '',
+		/** The term the rows on screen answer; typing moves `query` ahead of it. */
+		appliedQuery: '',
+		statusFilter: cell<MemberStatusFilter>(''),
+		sorting: cell<readonly TableSort[]>(DEFAULT_MEMBER_SORTING),
+		pageIndex: 0,
+		pageSize: 25,
+		cursors: cell<PageCursors>([null]),
+		nextCursor: cell<string | null>(null),
+		filtersOpen: false,
+		selectedIds: cell<ReadonlySet<string>>(new Set()),
+		confirmDeactivateMany: false,
+		roleDialogOpen: false,
+		bulkRole: '',
 		formOpen: false,
 		formSession: 0,
 		inviteOpen: false,
@@ -25,18 +68,140 @@ export function createUsersClientState() {
 		status: cell<UsersStatus>('idle'),
 		error: '',
 		notice: '',
+		/* A started export outlives the click that started it, so it carries its
+		   own line to the Exports screen instead of the notice every other action
+		   shares and the next one overwrites. */
+		exportStarted: false,
 	});
 	return { store, state: store.state };
 }
 
 export type UsersClientState = ReturnType<typeof createUsersClientState>;
 
+/** The server's sort key and direction behind the table's sorting state. */
+export function memberSort(sorts: readonly TableSort[]): {
+	readonly sort: TenantMemberSort;
+	readonly direction: 'asc' | 'desc';
+} {
+	const first = sorts[0] ?? DEFAULT_MEMBER_SORTING[0]!;
+	return {
+		sort: first.key === 'email' ? 'email' : 'displayName',
+		direction: first.desc ? 'desc' : 'asc',
+	};
+}
+
+/** The cursor that opens `pageIndex`, or undefined when the reader never reached it. */
+export function pageCursor(
+	cursors: PageCursors,
+	pageIndex: number,
+): string | null | undefined {
+	return pageIndex < cursors.length ? cursors[pageIndex] : undefined;
+}
+
+/**
+ * Records what the page at `pageIndex` answered: the cursor of the page after
+ * it, or nothing when it was the last. Pages beyond the next one are dropped,
+ * since the set may have changed under them.
+ */
+export function rememberNextCursor(
+	cursors: PageCursors,
+	pageIndex: number,
+	nextCursor: string | null,
+): PageCursors {
+	const kept = cursors.slice(0, pageIndex + 1);
+	return nextCursor === null ? kept : [...kept, nextCursor];
+}
+
+export function resetPageCursors(): PageCursors {
+	return [null];
+}
+
+/**
+ * What a loaded page writes to the screen. The selection is emptied with every
+ * listing, on a page, sort or filter change as much as on a refresh, because a
+ * selected id names a row the reader saw on the page that is being replaced.
+ */
+export function loadedListing(
+	next: Listing,
+	page: MemberListPage,
+): {
+	readonly users: readonly TenantMember[];
+	readonly appliedQuery: string;
+	readonly pageIndex: number;
+	readonly cursors: PageCursors;
+	readonly nextCursor: string | null;
+	readonly selectedIds: ReadonlySet<string>;
+} {
+	return {
+		users: page.items,
+		appliedQuery: next.query,
+		pageIndex: next.pageIndex,
+		cursors: rememberNextCursor(
+			next.cursors,
+			next.pageIndex,
+			page.page.nextCursor,
+		),
+		nextCursor: page.page.nextCursor,
+		selectedIds: new Set(),
+	};
+}
+
+/** The selected rows a bulk action may name: on screen and never the acting principal. */
+export function bulkTargets(
+	users: readonly TenantMember[],
+	selected: ReadonlySet<string>,
+	actorAccountId: string | undefined,
+): readonly string[] {
+	return users
+		.filter(
+			(user) =>
+				selected.has(user.accountId) && user.accountId !== actorAccountId,
+		)
+		.map((user) => user.accountId);
+}
+
+/** How many ids each outcome covered, for the toast after a bulk action. */
+export function bulkOutcomeCounts(outcomes: readonly MemberBulkOutcome[]): {
+	readonly updated: number;
+	readonly missing: number;
+	readonly refused: number;
+} {
+	let updated = 0;
+	let missing = 0;
+	let refused = 0;
+	for (const entry of outcomes) {
+		if (entry.outcome === 'updated') updated += 1;
+		else if (entry.outcome === 'not-found') missing += 1;
+		else refused += 1;
+	}
+	return { updated, missing, refused };
+}
+
+export function searchPending(query: string, applied: string): boolean {
+	return query.trim() !== applied;
+}
+
+/* The server ordered the page, so a changed row keeps its place until the next
+   read; a row that is not on this page changes nothing here. */
 export function replaceMember(
 	users: readonly TenantMember[],
 	member: TenantMember,
 ): readonly TenantMember[] {
-	const others = users.filter((user) => user.accountId !== member.accountId);
-	return [...others, member].sort((left, right) =>
-		left.displayName.localeCompare(right.displayName),
+	return users.map((user) =>
+		user.accountId === member.accountId ? member : user,
 	);
 }
+
+/* The membership route answers with stable codes; each one gets the sentence
+   that says what to do instead, and anything else keeps the server message. */
+export function membershipStatusMessage(error: unknown): string {
+	const code = error instanceof ApiError ? error.code : '';
+	if (code === 'SELF_TARGET') return t('users.membership.errorSelf');
+	if (code === 'LAST_OWNER') return t('users.membership.errorLastOwner');
+	if (code === 'OWNER_REQUIRED')
+		return t('users.membership.errorOwnerRequired');
+	if (code === 'ACCOUNT_NOT_FOUND') return t('users.membership.errorNotFound');
+	return error instanceof Error && error.message !== ''
+		? error.message
+		: t('users.membership.error');
+}

package/modules/users/src/domain/lists.ts

@@ -0,0 +1,9 @@
+/**
+ * The id exports.core holds this module's member list under: the module id
+ * followed by the list key, which is the namespace rule its catalogue enforces.
+ *
+ * It lives here rather than next to the declaration so the screen that starts a
+ * job and the server that declares the list name one string, without the client
+ * bundle importing `@flowdular/sdk/server` to read it.
+ */
+export const MEMBER_EXPORT_LIST_ID = 'users.core.members';

package/modules/users/src/index.ts

@@ -25,3 +25,14 @@ export const moduleDefinition = {
 
 export { USER_PERMISSIONS } from './acl/permissions.ts';
 export type { CreateUserInput } from './services/users-service.ts';
+export { MEMBER_EXPORT_LIST_ID } from './domain/lists.ts';
+export { createMemberListExport } from './services/member-export.ts';
+export {
+	createMemberImportPort,
+	MEMBER_IMPORT_PORT_KEY,
+} from './services/member-import.ts';
+export {
+	createMemberSearchProvider,
+	MEMBER_SEARCH_PROVIDER_KEY,
+	MEMBER_SEARCH_SCAN_LIMIT,
+} from './services/member-search.ts';

package/modules/users/src/platform.ts

@@ -2,10 +2,59 @@ import type {
 	PlatformServerComposition,
 	PlatformServerContext,
 } from '@flowdular/sdk/modules/auth/server';
+import {
+	EXPORT_LISTS_CAPABILITY,
+	type ExportLists,
+} from '@flowdular/sdk/modules/exports';
+import {
+	IMPORT_PORTS_CAPABILITY,
+	type ImportPorts,
+} from '@flowdular/sdk/modules/import';
+import {
+	SEARCH_PROVIDERS_CAPABILITY,
+	type SearchProviderRegistry,
+} from '@flowdular/sdk/modules/search';
 import { createUserRoutes } from './api/endpoints.ts';
+import { createMemberListExport } from './services/member-export.ts';
+import { createMemberImportPort } from './services/member-import.ts';
+import { createMemberSearchProvider } from './services/member-search.ts';
 
 export function createServerComposition(
 	context: PlatformServerContext,
 ): PlatformServerComposition {
-	return { routes: createUserRoutes(context.auth) };
+	/* search.core is a declared dependency, so it has composed and its registry
+	   is still open. The capability stays optional all the same: a deployment
+	   that leaves search out still composes this module. */
+	context.capabilities
+		.get<SearchProviderRegistry>(SEARCH_PROVIDERS_CAPABILITY)
+		?.register('users.core', [createMemberSearchProvider(context.auth)]);
+	/* Same contract for import.core: declared dependency, optional capability,
+	   registration while the registry is open. */
+	context.capabilities
+		.get<ImportPorts>(IMPORT_PORTS_CAPABILITY)
+		?.register('users.core', [createMemberImportPort(context.auth)]);
+	/* And for exports.core, except that its capability is optional and an
+	   optional requirement does not order its provider first, so the registry may
+	   not exist yet while this module composes. It is asked for twice, once here
+	   and once at start, because exports.core registers during composition and
+	   seals in its own start hook, which runs after this one whenever it composed
+	   after this module. Without exports.core both attempts answer nothing and
+	   the screens still work. The declaration opens no database and reads no
+	   member either way: the list is walked later, under the principal the job
+	   was started by. */
+	let registered = false;
+	const registerLists = (): void => {
+		if (registered) return;
+		const lists = context.capabilities.get<ExportLists>(
+			EXPORT_LISTS_CAPABILITY,
+		);
+		if (!lists) return;
+		registered = true;
+		lists.register('users.core', [createMemberListExport(context.auth)]);
+	};
+	registerLists();
+	return {
+		routes: createUserRoutes(context.auth),
+		start: () => registerLists(),
+	};
 }

package/modules/users/src/services/member-export.ts

@@ -0,0 +1,51 @@
+import { defineListExport, type DefinedListExport } from '@flowdular/sdk/server';
+import type { TenantMember } from '@flowdular/sdk/modules/auth';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import { USER_PERMISSIONS } from '../acl/permissions.ts';
+import { MEMBER_EXPORT_LIST_ID } from '../domain/lists.ts';
+
+/**
+ * The workspace's members as a CSV export. Every read goes through the auth
+ * administration port, under the tenant of the principal the job was started
+ * by and behind the permission the Members screen itself needs, so a file can
+ * never carry a row that screen would not have shown.
+ *
+ * The walk is the port's own paged listing, so one page of L members costs one
+ * statement over L rows and an export of M members reads M rows in total. Its
+ * keyset is the account id, not the display name the unpaged roll is ordered
+ * by: an account id never changes, so a member renamed while a long walk runs
+ * cannot cross a page boundary and be written twice or skipped, and a member
+ * removed mid-walk does not strand the cursor, because the next page is
+ * whatever still sorts after the id it names.
+ */
+export function createMemberListExport(auth: AuthRuntime): DefinedListExport {
+	return defineListExport<TenantMember>({
+		id: MEMBER_EXPORT_LIST_ID,
+		label: 'Members',
+		permission: USER_PERMISSIONS.read,
+		columns: [
+			{ key: 'email', header: 'E-mail', value: (row) => row.email },
+			{
+				key: 'displayName',
+				header: 'Display name',
+				value: (row) => row.displayName,
+			},
+			{ key: 'role', header: 'Role', value: (row) => row.role },
+			/* This workspace's own status for the member, which is what the
+			   Members screen shows; the account-level block belongs to the
+			   deployment operator and is not this workspace's to report. */
+			{ key: 'status', header: 'Status', value: (row) => row.membershipStatus },
+			{
+				key: 'joinedAt',
+				header: 'Joined at',
+				value: (row) => new Date(row.createdAt),
+			},
+		],
+		page: async (principal, cursor, limit) => {
+			const page = await (
+				await auth.service()
+			).listTenantMembers(principal.tenantId, { cursor, limit });
+			return { rows: page.members, nextCursor: page.nextCursor };
+		},
+	});
+}