@flowdular/sdk 0.2.4 → 0.3.1

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

@@ -0,0 +1,222 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type {
+	GroupSortKey,
+	IssuedScimToken,
+	ListDirection,
+	ProvisioningEvent,
+	ProvisioningOperation,
+	ProvisioningOutcome,
+	ScimGroupMapping,
+	ScimToken,
+	ScimTokenStatus,
+	TokenSortKey,
+} from '../domain/types.ts';
+
+interface ErrorEnvelope {
+	readonly error?: {
+		readonly code?: string;
+		readonly message?: string;
+	};
+}
+
+/** A failed request with the server's stable code, so a screen can translate it. */
+export class DirectoryApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+
+	constructor(status: number, code: string, message: string) {
+		super(message);
+		this.name = 'DirectoryApiError';
+		this.status = status;
+		this.code = code;
+	}
+}
+
+/**
+ * The server message is English and written for an operator. A code this module
+ * knows becomes translated copy; anything else keeps the server's own sentence
+ * rather than hiding what went wrong behind a generic line.
+ */
+export function directoryErrorMessage(
+	error: unknown,
+	fallbackKey: string,
+): string {
+	if (error instanceof DirectoryApiError) {
+		const key = 'directory.error.code.' + error.code;
+		const translated = t(key);
+		if (translated !== key) return translated;
+		return error.message;
+	}
+	if (error instanceof Error && error.message !== '') return error.message;
+	return t(fallbackKey);
+}
+
+async function payload<T>(response: Response): Promise<T> {
+	const value = (await response.json()) as T & ErrorEnvelope;
+	if (!response.ok) {
+		throw new DirectoryApiError(
+			response.status,
+			value.error?.code ?? 'REQUEST_FAILED',
+			value.error?.message ?? t('directory.error.request'),
+		);
+	}
+	return value;
+}
+
+async function get<T>(path: string): Promise<T> {
+	return payload<T>(
+		await fetch(path, {
+			headers: { accept: 'application/json' },
+			credentials: 'same-origin',
+		}),
+	);
+}
+
+async function post<T>(
+	path: string,
+	body: unknown,
+	csrfToken: string,
+): Promise<T> {
+	return payload<T>(
+		await fetch(path, {
+			method: 'POST',
+			headers: {
+				'content-type': 'application/json',
+				'x-csrf-token': csrfToken,
+			},
+			credentials: 'same-origin',
+			body: JSON.stringify(body),
+		}),
+	);
+}
+
+/** One page of a screen list; the cursor is opaque and the server's own. */
+export interface ListPagePayload<Record> {
+	readonly items: readonly Record[];
+	readonly page: { readonly nextCursor: string | null };
+}
+
+interface ListRequest<Key extends string> {
+	readonly q: string;
+	readonly sort: Key;
+	readonly direction: ListDirection;
+	readonly cursor: string | null;
+	readonly limit: number;
+}
+
+function listSearch(
+	request: ListRequest<string>,
+	extra: Readonly<Record<string, string>> = {},
+): string {
+	const parameters = new URLSearchParams();
+	if (request.q !== '') parameters.set('q', request.q);
+	for (const [key, value] of Object.entries(extra)) {
+		if (value !== '') parameters.set(key, value);
+	}
+	parameters.set('sort', request.sort);
+	parameters.set('direction', request.direction);
+	parameters.set('limit', String(request.limit));
+	if (request.cursor !== null) parameters.set('cursor', request.cursor);
+	return '?' + parameters.toString();
+}
+
+export interface TokenListRequest extends ListRequest<TokenSortKey> {
+	readonly status: ScimTokenStatus | '';
+}
+
+export function loadScimTokens(
+	request: TokenListRequest,
+): Promise<ListPagePayload<ScimToken>> {
+	return get<ListPagePayload<ScimToken>>(
+		'/api/directory/tokens' + listSearch(request, { status: request.status }),
+	);
+}
+
+export function createScimToken(
+	input: { readonly label: string; readonly expiresAt: number | null },
+	csrfToken: string,
+): Promise<IssuedScimToken> {
+	return post<IssuedScimToken>('/api/directory/tokens', input, csrfToken);
+}
+
+export function rotateScimToken(
+	id: string,
+	expiresAt: number | null,
+	csrfToken: string,
+): Promise<IssuedScimToken> {
+	return post<IssuedScimToken>(
+		'/api/directory/tokens/rotate',
+		{ id, expiresAt },
+		csrfToken,
+	);
+}
+
+export async function revokeScimToken(
+	id: string,
+	csrfToken: string,
+): Promise<ScimToken> {
+	return (
+		await post<{ readonly token: ScimToken }>(
+			'/api/directory/tokens/revoke',
+			{ id },
+			csrfToken,
+		)
+	).token;
+}
+
+export type GroupListRequest = ListRequest<GroupSortKey>;
+
+export function loadGroupMappings(
+	request: GroupListRequest,
+): Promise<ListPagePayload<ScimGroupMapping>> {
+	return get<ListPagePayload<ScimGroupMapping>>(
+		'/api/directory/groups' + listSearch(request),
+	);
+}
+
+export interface GroupMappingContextPayload {
+	readonly roles: readonly string[];
+	readonly defaultRole: string;
+}
+
+/** What the mapping form needs beside the rows: read once, not per page. */
+export function loadGroupMappingContext(): Promise<GroupMappingContextPayload> {
+	return get<GroupMappingContextPayload>('/api/directory/groups/context');
+}
+
+export async function mapGroup(
+	input: {
+		readonly id: string;
+		readonly roleKey: string | null;
+		readonly precedence: number;
+	},
+	csrfToken: string,
+): Promise<ScimGroupMapping> {
+	return (
+		await post<{ readonly group: ScimGroupMapping }>(
+			'/api/directory/groups/map',
+			input,
+			csrfToken,
+		)
+	).group;
+}
+
+export interface ProvisioningEventPage {
+	readonly items: readonly ProvisioningEvent[];
+	readonly page: { readonly nextCursor: string | null };
+}
+
+export function loadProvisioningEvents(query: {
+	readonly operation: ProvisioningOperation | '';
+	readonly outcome: ProvisioningOutcome | '';
+	readonly cursor: string | null;
+}): Promise<ProvisioningEventPage> {
+	const parameters = new URLSearchParams();
+	if (query.operation !== '') parameters.set('operation', query.operation);
+	if (query.outcome !== '') parameters.set('outcome', query.outcome);
+	if (query.cursor !== null) parameters.set('cursor', query.cursor);
+	const search = parameters.toString();
+	return get<ProvisioningEventPage>(
+		'/api/directory/provisioning-events' + (search === '' ? '' : '?' + search),
+	);
+}

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

@@ -0,0 +1,46 @@
+import { type ModuleClientContribution } from '@flowdular/sdk/client';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import { DIRECTORY_PERMISSIONS } from '../acl/permissions.ts';
+import { GroupMappingsView } from './GroupMappingsView.tsrx';
+import { directoryNavigation, DIRECTORY_VIEWS } from './navigation.ts';
+import { ProvisioningLogView } from './ProvisioningLogView.tsrx';
+import { ScimTokensView } from './ScimTokensView.tsrx';
+
+export interface DirectoryClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+}
+
+export function createDirectoryClientContribution(
+	options: DirectoryClientContributionOptions,
+): ModuleClientContribution {
+	const canManage = options.scopes.includes(DIRECTORY_PERMISSIONS.manage);
+	return {
+		moduleId: 'directory.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: directoryNavigation,
+		views: [
+			{
+				id: DIRECTORY_VIEWS.tokens,
+				render: () =>
+					<ScimTokensView
+						csrfToken={options.csrfToken}
+						canManage={canManage}
+					/>,
+			},
+			{
+				id: DIRECTORY_VIEWS.groups,
+				render: () =>
+					<GroupMappingsView
+						csrfToken={options.csrfToken}
+						canManage={canManage}
+					/>,
+			},
+			{
+				id: DIRECTORY_VIEWS.log,
+				render: () => <ProvisioningLogView />,
+			},
+		],
+	};
+}

package/modules/directory/src/client/index.ts

@@ -0,0 +1,22 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createDirectoryClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export { createDirectoryClientContribution } from './contribution.tsrx';
+export type { DirectoryClientContributionOptions } from './contribution.tsrx';
+export { directoryNavigation, DIRECTORY_VIEWS } from './navigation.ts';
+export { GroupMappingsView } from './GroupMappingsView.tsrx';
+export { ProvisioningLogView } from './ProvisioningLogView.tsrx';
+export { ScimTokensView } from './ScimTokensView.tsrx';
+
+/* Canonical entry used by the generated platform composition. */
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({
+		csrfToken: context.csrfToken,
+		scopes: context.scopes,
+	});
+}

package/modules/directory/src/client/navigation.ts

@@ -0,0 +1,57 @@
+import type { NavigationContribution } from '@flowdular/sdk/client';
+import { t } from '@flowdular/sdk/client/i18n';
+import { DIRECTORY_PERMISSIONS } from '../acl/permissions.ts';
+
+/** The view ids the contribution registers and every entry points at. */
+export const DIRECTORY_VIEWS = {
+	tokens: 'directory-tokens',
+	groups: 'directory-groups',
+	log: 'directory-log',
+} as const;
+
+/* Labels are read every render so a locale change reaches an entry the shell
+   built once. */
+export const directoryNavigation: readonly NavigationContribution[] = [
+	{
+		id: 'directory.navigation.tokens',
+		viewId: DIRECTORY_VIEWS.tokens,
+		group: 'Administration',
+		get label() {
+			return t('directory.navigation.tokens');
+		},
+		glyph: 'key',
+		get description() {
+			return t('directory.navigation.tokensDescription');
+		},
+		scope: DIRECTORY_PERMISSIONS.read,
+		order: 70,
+	},
+	{
+		id: 'directory.navigation.groups',
+		viewId: DIRECTORY_VIEWS.groups,
+		group: 'Administration',
+		get label() {
+			return t('directory.navigation.groups');
+		},
+		glyph: 'users',
+		get description() {
+			return t('directory.navigation.groupsDescription');
+		},
+		scope: DIRECTORY_PERMISSIONS.provisioningRead,
+		order: 71,
+	},
+	{
+		id: 'directory.navigation.log',
+		viewId: DIRECTORY_VIEWS.log,
+		group: 'Administration',
+		get label() {
+			return t('directory.navigation.log');
+		},
+		glyph: 'activity',
+		get description() {
+			return t('directory.navigation.logDescription');
+		},
+		scope: DIRECTORY_PERMISSIONS.provisioningRead,
+		order: 72,
+	},
+];

package/modules/directory/src/client/presentation.ts

@@ -0,0 +1,143 @@
+import type { TableEmpty, TagTone } from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client/i18n';
+import type {
+	ProvisioningOperation,
+	ProvisioningOutcome,
+	ScimToken,
+	ScimTokenStatus,
+} from '../domain/types.ts';
+import type { ScreenStatus } from './state.ts';
+
+function formatted(value: number): string {
+	return new Intl.DateTimeFormat(activeLocale(), {
+		dateStyle: 'medium',
+		timeStyle: 'short',
+	}).format(value);
+}
+
+/** Epoch milliseconds as the reader's local date and time. */
+export function timestampLabel(value: number | null): string {
+	if (value === null) return t('directory.common.never');
+	return formatted(value);
+}
+
+/** What a row says a token is, which an expiry can differ from its status on. */
+export type TokenDisplayStatus = ScimTokenStatus | 'expired';
+
+/**
+ * An active token past its expiry authenticates nothing, and rotation carries
+ * the stored expiry forward, so the row names the expiry rather than showing
+ * the stored status alone.
+ */
+export function tokenDisplayStatus(
+	token: Pick<ScimToken, 'status' | 'expiresAt'>,
+	at: number = Date.now(),
+): TokenDisplayStatus {
+	return token.status === 'active' &&
+		token.expiresAt !== null &&
+		token.expiresAt <= at
+		? 'expired'
+		: token.status;
+}
+
+export function tokenStatusLabel(status: TokenDisplayStatus): string {
+	return t('directory.tokens.status.' + status);
+}
+
+export function tokenStatusTone(status: TokenDisplayStatus): TagTone {
+	if (status === 'active') return 'success';
+	return status === 'expired' ? 'warning' : 'neutral';
+}
+
+/** The copy of a row action: its name, and why it is refused. */
+export interface ActionCopy {
+	readonly label: string;
+	readonly disabled: boolean;
+	/** Why the action is refused, empty while it is allowed. */
+	readonly reason: string;
+}
+
+/**
+ * What the rotate action says about this token. Rotation carries the stored
+ * expiry forward and the server refuses one that has already passed, so an
+ * expired token is revoked rather than rotated. The label is the name of the
+ * action whatever the token is, and the refusal travels as the reason, which
+ * the table renders as the button's accessible description: an action whose
+ * name changes under the reader is a different action.
+ */
+export function rotateAction(
+	token: Pick<ScimToken, 'status' | 'expiresAt'>,
+	at: number = Date.now(),
+): ActionCopy {
+	const reason =
+		tokenDisplayStatus(token, at) === 'active'
+			? ''
+			: t('directory.tokens.action.rotateRefused');
+	return {
+		label: t('directory.tokens.action.rotate'),
+		disabled: reason !== '',
+		reason,
+	};
+}
+
+export function operationLabel(operation: ProvisioningOperation): string {
+	return t('directory.log.operation.' + operation);
+}
+
+export function outcomeLabel(outcome: ProvisioningOutcome): string {
+	return t('directory.log.outcome.' + outcome);
+}
+
+export function outcomeTone(outcome: ProvisioningOutcome): TagTone {
+	if (outcome === 'applied') return 'success';
+	return outcome === 'unchanged' ? 'neutral' : 'danger';
+}
+
+/** A refusal code is stable server text; unknown codes stay readable as they are. */
+export function reasonLabel(reason: string | null): string {
+	if (reason === null || reason === '') return '';
+	const key = 'directory.reason.' + reason;
+	const translated = t(key);
+	return translated === key ? reason : translated;
+}
+
+/** A local `datetime-local` value as epoch milliseconds, or null when empty. */
+export function expiryToTimestamp(value: string): number | null {
+	if (value.trim() === '') return null;
+	const parsed = Date.parse(value);
+	return Number.isNaN(parsed) ? null : parsed;
+}
+
+function pad(part: number): string {
+	return String(part).padStart(2, '0');
+}
+
+/**
+ * Epoch milliseconds as the `YYYY-MM-DDTHH:mm` a datetime field carries. The
+ * parts are read in the reader's own zone, because the control holds a local
+ * wall-clock reading and never an instant.
+ */
+export function expiryFieldValue(value: number): string {
+	const at = new Date(value);
+	return (
+		`${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}` +
+		`T${pad(at.getHours())}:${pad(at.getMinutes())}`
+	);
+}
+
+/**
+ * What a table renders in place of its rows. A load that failed must never
+ * answer with the empty state: "nothing here yet" is a statement about the
+ * workspace, and a failed request read nothing to make it from.
+ */
+export function tableEmpty(
+	status: ScreenStatus,
+	populated: TableEmpty,
+): TableEmpty {
+	if (status !== 'error') return populated;
+	return {
+		icon: 'alert',
+		title: t('directory.common.loadFailed'),
+		hint: t('directory.common.loadFailedHint'),
+	};
+}

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

@@ -0,0 +1,173 @@
+import type { TableSort } from '@flowdular/sdk/ui';
+import { cell, createStore } from 'segment-state';
+import type {
+	GroupSortKey,
+	ListDirection,
+	ProvisioningEvent,
+	ProvisioningOperation,
+	ProvisioningOutcome,
+	ScimGroupMapping,
+	ScimToken,
+	TokenSortKey,
+} from '../domain/types.ts';
+
+/** Rows one screen page asks for; the server bounds it too. */
+export const PAGE_SIZE = 50;
+
+/**
+ * The pages a screen has walked: `cursors[index]` is the cursor that opened
+ * page `index`, and page 0 has none. Going back reuses the stored cursor, so a
+ * page reads the rows it read before; a page never reached cannot be opened.
+ */
+export interface ListPaging {
+	readonly pageIndex: number;
+	readonly cursors: readonly (string | null)[];
+}
+
+export const FIRST_PAGE: ListPaging = { pageIndex: 0, cursors: [null] };
+
+export function pageCursor(paging: ListPaging): string | null {
+	return paging.cursors[paging.pageIndex] ?? null;
+}
+
+export function hasNextPage(paging: ListPaging): boolean {
+	return paging.cursors.length > paging.pageIndex + 1;
+}
+
+/**
+ * Records what the page on screen answered. The pages behind it were opened
+ * from a cursor this answer replaces, so they are forgotten with it.
+ */
+export function pageLoaded(
+	paging: ListPaging,
+	nextCursor: string | null,
+): ListPaging {
+	const cursors = paging.cursors.slice(0, paging.pageIndex + 1);
+	if (nextCursor !== null) cursors.push(nextCursor);
+	return { pageIndex: paging.pageIndex, cursors };
+}
+
+/** Turns to a page the screen has a cursor for; any other request is ignored. */
+export function turnTo(paging: ListPaging, pageIndex: number): ListPaging {
+	if (
+		pageIndex === paging.pageIndex ||
+		pageIndex < 0 ||
+		pageIndex >= paging.cursors.length
+	) {
+		return paging;
+	}
+	return { pageIndex, cursors: paging.cursors };
+}
+
+export interface ListSort<Key extends string> {
+	readonly sort: Key;
+	readonly direction: ListDirection;
+}
+
+/**
+ * The table's sort report as the request the server takes. The header cycles
+ * through ascending, descending and none, and none means the list's default.
+ */
+export function sortOf<Key extends string>(
+	sorts: readonly TableSort[],
+	keys: readonly Key[],
+	fallback: Key,
+): ListSort<Key> {
+	const first = sorts[0];
+	if (first && (keys as readonly string[]).includes(first.key)) {
+		return { sort: first.key as Key, direction: first.desc ? 'desc' : 'asc' };
+	}
+	return { sort: fallback, direction: 'asc' };
+}
+
+export function sortingState(sort: ListSort<string>): readonly TableSort[] {
+	return [{ key: sort.sort, desc: sort.direction === 'desc' }];
+}
+
+/**
+ * The listing loads a screen has fired. Responses land in any order, so only
+ * the load fired last may write rows; an older one is discarded on arrival,
+ * or it would show rows of a filter, sort or page the controls no longer name.
+ */
+export interface LoadSequence {
+	/** Fires a load and answers its ticket. */
+	begin(): number;
+	isLatest(ticket: number): boolean;
+}
+
+export function createLoadSequence(): LoadSequence {
+	let issued = 0;
+	return {
+		begin: () => (issued += 1),
+		isLatest: (ticket) => ticket === issued,
+	};
+}
+
+/** `denied` is a 403 the shell could not hide; `error` is everything else. */
+export type ScreenStatus =
+	| 'idle'
+	| 'loading'
+	| 'submitting'
+	| 'denied'
+	| 'error';
+
+export type TokenConfirm = 'rotate' | 'revoke';
+
+export function createScimTokensClientState() {
+	const store = createStore({
+		tokens: cell<readonly ScimToken[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		query: '',
+		/** The term the rows on screen answer, so typing it again loads nothing. */
+		appliedQuery: '',
+		statusFilter: cell<ScimToken['status'] | ''>(''),
+		sort: cell<ListSort<TokenSortKey>>({ sort: 'label', direction: 'asc' }),
+		paging: cell<ListPaging>(FIRST_PAGE),
+		filtersOpen: false,
+		editorOpen: false,
+		selectedId: '',
+		/** The expiry field's own `YYYY-MM-DDTHH:mm` reading, empty for none. */
+		expiresAt: '',
+		/* Held only until the drawer closes; the server never returns it again. */
+		revealedToken: '',
+		confirm: cell<TokenConfirm | null>(null),
+	});
+	return { store, state: store.state, loads: createLoadSequence() };
+}
+
+export function createGroupMappingsClientState() {
+	const store = createStore({
+		groups: cell<readonly ScimGroupMapping[]>([]),
+		roles: cell<readonly string[]>([]),
+		defaultRole: '',
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		query: '',
+		appliedQuery: '',
+		sort: cell<ListSort<GroupSortKey>>({
+			sort: 'precedence',
+			direction: 'asc',
+		}),
+		paging: cell<ListPaging>(FIRST_PAGE),
+		editorOpen: false,
+		selectedId: '',
+		roleKey: '',
+		precedence: '',
+	});
+	return { store, state: store.state, loads: createLoadSequence() };
+}
+
+export function createProvisioningLogClientState() {
+	const store = createStore({
+		events: cell<readonly ProvisioningEvent[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		operationFilter: cell<ProvisioningOperation | ''>(''),
+		outcomeFilter: cell<ProvisioningOutcome | ''>(''),
+		filtersOpen: false,
+		/* Null once the server stops handing one back: that is the last page. */
+		nextCursor: cell<string | null>(null),
+	});
+	return { store, state: store.state };
+}