@flowdular/sdk 0.1.0

package/modules/system/src/client/ModulesView.tsrx

@@ -0,0 +1,241 @@
+import { useEffect, useMemo } from 'octane';
+import {
+	Alert,
+	Button,
+	Drawer,
+	EmptyState,
+	Icon,
+	PageHeader,
+	ScopeSummary,
+	SearchField,
+	TableCard,
+	Tag,
+} from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client';
+import { useValue } from 'segment-state';
+import { ApiError, loadModuleCatalog, type ModuleCatalogEntry } from './api.ts';
+import { moduleColumns, surfaces } from './module-columns.tsrx';
+import { ModuleSettingsSection } from './ModuleSettingsSection.tsrx';
+import { createModulesClientState } from './state.ts';
+
+export interface ModulesViewProps {
+	readonly csrfToken: string;
+	readonly canManageSettings: boolean;
+}
+
+export function ModulesView(props: ModulesViewProps) @{
+	const client = useMemo(() => createModulesClientState(), []);
+	const [modules] = useValue(client.state.modules);
+	const [commands] = useValue(client.state.commands);
+	const [status, setStatus] = useValue(client.state.status);
+	const [error, setError] = useValue(client.state.error);
+	const [query, setQuery] = useValue(client.state.query);
+	const [selectedModuleId, setSelectedModuleId] = useValue(
+		client.state.selectedModuleId,
+	);
+	const selected =
+		modules.find((module) => module.id === selectedModuleId) ?? null;
+	const term = query.trim().toLocaleLowerCase(activeLocale());
+	const visible =
+		term === ''
+			? modules
+			: modules.filter(
+					(module) =>
+						module.id.includes(term) ||
+							module.name.toLocaleLowerCase(activeLocale()).includes(term),
+				);
+	const enabled = modules.filter((module) => module.enabled);
+
+	const refresh = async () => {
+		setStatus('loading');
+		setError('');
+		try {
+			const catalog = await loadModuleCatalog();
+			client.store.act((transaction) => {
+				transaction.set(client.state.modules, catalog.modules);
+				transaction.set(client.state.commands, catalog.commands);
+				transaction.set(client.state.status, 'idle');
+			}, 'system/modules-loaded');
+		} catch (loadError) {
+			const denied = loadError instanceof ApiError && loadError.status === 403;
+			setError(
+				loadError instanceof Error
+					? loadError.message
+					: t('system.error.catalog'),
+			);
+			setStatus(denied ? 'denied' : 'error');
+		}
+	};
+
+	useEffect(() => {
+		void refresh();
+	}, []);
+
+	<div class="ui-view">
+		<PageHeader
+			eyebrow={t('system.page.eyebrow')}
+			title={t('system.page.title')}
+			description={t('system.page.description')}
+		>
+			<Button size="sm" onClick={() => void refresh()}>
+				<Icon name="refresh" size={14} />
+				{t('system.action.refresh')}
+			</Button>
+		</PageHeader>
+		@if (status === 'denied') {
+			<section class="ui-card">
+				<EmptyState icon="shield" title={t('system.denied.title')}>{t(
+					'system.denied.hint',
+				)}</EmptyState>
+			</section>
+		} @else {
+			<>
+				@if (status === 'error') {
+					<Alert>{error}</Alert>
+				}
+				<TableCard
+					title={t('system.table.title')}
+					count={t('system.table.count', {
+						enabled: enabled.length,
+						total: modules.length,
+					})}
+					search={<SearchField
+						value={query}
+						placeholder={t('system.search.placeholder')}
+						label={t('system.search.label')}
+						onInput={setQuery}
+					/>}
+					caption={t('system.table.caption')}
+					columns={moduleColumns()}
+					rows={visible}
+					rowKey={(module) => module.id}
+					status={status === 'loading' && modules.length === 0
+						? 'loading'
+						: 'idle'}
+					loadingLabel={t('system.table.loading')}
+					filtered={term !== ''}
+					empty={{
+						icon: 'modules',
+						title: t('system.table.emptyTitle'),
+						hint: t('system.table.emptyHint'),
+					}}
+					emptyFiltered={{
+						icon: 'modules',
+						title: t('system.table.emptyFilteredTitle'),
+						hint: t('system.table.emptyFilteredHint'),
+					}}
+					onSelect={(module) => setSelectedModuleId(module.id)}
+					actionsLabel={t('system.table.actions')}
+					actions={(module) => [
+						{
+							id: 'open',
+							label: t('system.action.open'),
+							icon: 'external',
+							onSelect: () => setSelectedModuleId(module.id),
+						},
+					]}
+					noteIcon="code"
+					note={<>
+						{t('system.table.cliNote')}
+						{' '}
+						<code class="ui-mono">{commands.enable ?? ''}</code>
+						{' · '}
+						<code class="ui-mono">{commands.disable ?? ''}</code>
+						{' · '}
+						<code class="ui-mono">{commands.grantScopes ?? ''}</code>
+					</>}
+				/>
+			</>
+		}
+		<Drawer
+			open={selected !== null}
+			title={selected?.name ?? t('system.drawer.module')}
+			subtitle={selected?.id ?? ''}
+			width="lg"
+			onClose={() => setSelectedModuleId(null)}
+		>
+			@if (selected) {
+				<ModuleDetail
+					module={selected}
+					csrfToken={props.csrfToken}
+					canManageSettings={props.canManageSettings}
+				/>
+			}
+		</Drawer>
+	</div>
+}
+
+function ModuleDetail(props: {
+	readonly module: ModuleCatalogEntry;
+	readonly csrfToken: string;
+	readonly canManageSettings: boolean;
+}) @{
+	<div class="ui-drawer__body">
+		<div class="ui-form">
+			<div class="ui-form__section">
+				<div class="ui-form__section-head">
+					<b>{t('system.detail.overview')}</b>
+					@if (props.module.description) {
+						<small>{props.module.description}</small>
+					}
+				</div>
+				<div class="ui-form__row ui-form__row--4">
+					<span class="ui-cell">
+						<small>{t('system.table.version')}</small>
+						<b class="ui-mono">
+							{props.module.version || t('system.value.na')}
+						</b>
+					</span>
+					<span class="ui-cell">
+						<small>{t('system.detail.specVersion')}</small>
+						<b class="ui-mono">
+							{props.module.specVersion ?? t('system.value.none')}
+						</b>
+					</span>
+					<span class="ui-cell">
+						<small>{t('system.table.platform')}</small>
+						<b>{surfaces(props.module)}</b>
+					</span>
+					<span class="ui-cell">
+						<small>{t('system.table.status')}</small>
+						<Tag tone={props.module.enabled ? 'success' : 'neutral'} dot>
+							{props.module.enabled
+								? t('system.status.enabled')
+								: t('system.status.available')}
+						</Tag>
+					</span>
+				</div>
+				<span class="ui-cell">
+					<small>{t('system.detail.capabilities')}</small>
+					<span class="ui-mono">
+						{props.module.capabilities.join(', ') || t('system.value.none')}
+					</span>
+				</span>
+				<span class="ui-cell">
+					<small>{t('system.detail.directory')}</small>
+					<span class="ui-mono">{props.module.directory}</span>
+				</span>
+			</div>
+			<div class="ui-form__section">
+				<div class="ui-form__section-head">
+					<b>{t('system.detail.permissions')}</b>
+					<small>{t('system.detail.permissionCount', {
+						count: props.module.permissions.length,
+					})}</small>
+				</div>
+				@if (props.module.permissions.length === 0) {
+					<span class="ui-help">{t('system.detail.noPermissions')}</span>
+				} @else {
+					<ScopeSummary
+						scopes={props.module.permissions.map((permission) => permission.id)}
+					/>
+				}
+			</div>
+			<ModuleSettingsSection
+				moduleId={props.module.id}
+				csrfToken={props.csrfToken}
+				canManage={props.canManageSettings}
+			/>
+		</div>
+	</div>
+}

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

@@ -0,0 +1,36 @@
+import type { ModuleCatalogEntry } from '../server/module-catalog.ts';
+import { t } from '@flowdular/sdk/client/i18n';
+
+export type { ModuleCatalogEntry };
+
+export interface ModuleCatalog {
+	readonly modules: readonly ModuleCatalogEntry[];
+	readonly commands: Readonly<Record<string, string>>;
+}
+
+export class ApiError extends Error {
+	readonly status: number;
+
+	constructor(status: number, message: string) {
+		super(message);
+		this.name = 'ApiError';
+		this.status = status;
+	}
+}
+
+export async function loadModuleCatalog(): Promise<ModuleCatalog> {
+	const response = await fetch('/api/system/modules', {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	const value = (await response.json()) as ModuleCatalog & {
+		readonly error?: { readonly message?: string };
+	};
+	if (!response.ok) {
+		throw new ApiError(
+			response.status,
+			value.error?.message ?? t('system.error.catalog'),
+		);
+	}
+	return value;
+}

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

@@ -0,0 +1,48 @@
+import { t, type ModuleClientContribution } from '@flowdular/sdk/client';
+import { SYSTEM_PERMISSIONS } from '../acl/permissions.ts';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import { ModulesView } from './ModulesView.tsrx';
+
+export interface SystemClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes?: readonly string[];
+}
+
+export function createSystemClientContribution(
+	options: SystemClientContributionOptions,
+): ModuleClientContribution {
+	const scopes = options.scopes ?? [];
+	return {
+		moduleId: 'system.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: [
+			{
+				id: 'system.navigation.modules',
+				viewId: 'modules',
+				group: 'Administration',
+				get label() {
+					return t('system.navigation.modules');
+				},
+				glyph: 'modules',
+				get description() {
+					return t('system.navigation.modulesDescription');
+				},
+				scope: SYSTEM_PERMISSIONS.modulesRead,
+				order: 60,
+			},
+		],
+		views: [
+			{
+				id: 'modules',
+				render: () =>
+					<ModulesView
+						csrfToken={options.csrfToken}
+						canManageSettings={scopes.includes(
+							SYSTEM_PERMISSIONS.settingsManage,
+						)}
+					/>,
+			},
+		],
+	};
+}

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

@@ -0,0 +1,26 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createSystemClientContribution } from './contribution.tsrx';
+
+export { createSystemClientContribution } from './contribution.tsrx';
+export type { SystemClientContributionOptions } from './contribution.tsrx';
+export { loadSystemOverview } from './overview-api.ts';
+export type {
+	OverviewActivityPoint,
+	OverviewModulePoint,
+	SystemOverviewPayload,
+} from './overview-api.ts';
+export { ModulesView } from './ModulesView.tsrx';
+export { ModuleSettingsSection } from './ModuleSettingsSection.tsrx';
+
+/* Canonical entry used by the generated platform composition. */
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return createSystemClientContribution({
+		csrfToken: context.csrfToken,
+		scopes: context.scopes,
+	});
+}

package/modules/system/src/client/module-columns.tsrx

@@ -0,0 +1,66 @@
+import { Tag, type TableColumn } from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client';
+import type { ModuleCatalogEntry } from './api.ts';
+
+export function surfaces(module: ModuleCatalogEntry): string {
+	const parts = [
+		module.platform.server && 'server',
+		module.platform.client && 'client',
+	].filter(Boolean);
+	return parts.length > 0 ? parts.join(' + ') : t('system.value.none');
+}
+
+export function moduleColumns(): readonly TableColumn<ModuleCatalogEntry>[] {
+	return [
+		{
+			key: 'module',
+			header: t('system.table.module'),
+			width: '23%',
+			cell: (module) => <span class="ui-cell">
+				<b>{module.name}</b>
+				<small class="ui-mono">{module.id}</small>
+			</span>,
+		},
+		{
+			key: 'version',
+			header: t('system.table.version'),
+			width: '13%',
+			cell: (module) => <span class="ui-cell">
+				<span class="ui-mono">{module.version || t('system.value.na')}</span>
+				{module.specVersion
+					? <small>{t('system.table.specVersion', {
+							version: module.specVersion,
+						})}</small>
+					: null}
+			</span>,
+		},
+		{
+			key: 'platform',
+			header: t('system.table.platform'),
+			width: '30%',
+			cell: (module) => <span class="ui-cell">
+				<span>{surfaces(module)}</span>
+				<small>{module.capabilities.join(', ')}</small>
+			</span>,
+		},
+		{
+			key: 'permissions',
+			header: t('system.table.permissions'),
+			width: '10%',
+			numeric: true,
+			cell: (module) => new Intl.NumberFormat(activeLocale()).format(
+				module.permissions.length,
+			),
+		},
+		{
+			key: 'status',
+			header: t('system.table.status'),
+			width: '14%',
+			cell: (module) => <Tag tone={module.enabled ? 'success' : 'neutral'} dot>
+				{module.enabled
+					? t('system.status.enabled')
+					: t('system.status.available')}
+			</Tag>,
+		},
+	];
+}

package/modules/system/src/client/overview-api.ts

@@ -0,0 +1,30 @@
+import type {
+	OverviewActivityPoint,
+	OverviewModulePoint,
+	SystemOverviewPayload,
+} from '../server/endpoints.ts';
+import { t } from '@flowdular/sdk/client/i18n';
+import { ApiError } from './api.ts';
+
+export type {
+	OverviewActivityPoint,
+	OverviewModulePoint,
+	SystemOverviewPayload,
+};
+
+export async function loadSystemOverview(): Promise<SystemOverviewPayload> {
+	const response = await fetch('/api/system/overview', {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	const value = (await response.json()) as SystemOverviewPayload & {
+		readonly error?: { readonly message?: string };
+	};
+	if (!response.ok) {
+		throw new ApiError(
+			response.status,
+			value.error?.message ?? t('shell.overview.error'),
+		);
+	}
+	return value;
+}

package/modules/system/src/client/setting-copy.ts

@@ -0,0 +1,30 @@
+import { t, type Translate } from '@flowdular/sdk/client/i18n';
+import type { SettingsEntryPayload } from './settings-api.ts';
+
+export interface LocalizedSettingCopy {
+	readonly label: string;
+	readonly description: string;
+	readonly locked: string | undefined;
+}
+
+/* Setting declarations cross the API before the active locale is known. The
+   client resolves their optional keys and keeps server literals as a safe
+   fallback for older or temporarily incomplete module bundles. */
+export function translateSettingCopy(
+	setting: SettingsEntryPayload,
+	translate: Translate = t,
+): LocalizedSettingCopy {
+	const resolve = (key: string | undefined, fallback: string): string => {
+		if (key === undefined) return fallback;
+		const translated = translate(key);
+		return translated === key ? fallback : translated;
+	};
+	return {
+		label: resolve(setting.labelKey, setting.label),
+		description: resolve(setting.descriptionKey, setting.description),
+		locked:
+			setting.locked === undefined
+				? undefined
+				: resolve(setting.lockedKey, setting.locked),
+	};
+}

package/modules/system/src/client/settings-api.ts

@@ -0,0 +1,57 @@
+import type { ModuleSettingValue } from '@flowdular/sdk/kernel';
+import { t } from '@flowdular/sdk/client/i18n';
+import type {
+	SettingsEntryPayload,
+	SettingsModulePayload,
+} from '../server/endpoints.ts';
+import { ApiError } from './api.ts';
+
+export type { SettingsEntryPayload, SettingsModulePayload };
+
+async function payload<T>(response: Response, fallback: string): Promise<T> {
+	const value = (await response.json()) as T & {
+		readonly error?: { readonly message?: string };
+	};
+	if (!response.ok) {
+		throw new ApiError(response.status, value.error?.message ?? fallback);
+	}
+	return value;
+}
+
+export async function loadSettings(): Promise<
+	readonly SettingsModulePayload[]
+> {
+	const response = await fetch('/api/settings', {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	return (
+		await payload<{ readonly modules: readonly SettingsModulePayload[] }>(
+			response,
+			t('system.settings.errorLoad'),
+		)
+	).modules;
+}
+
+export async function updateSetting(
+	moduleId: string,
+	key: string,
+	value: ModuleSettingValue | null,
+	csrfToken: string,
+): Promise<SettingsEntryPayload | null> {
+	const response = await fetch('/api/settings/update', {
+		method: 'POST',
+		headers: {
+			'content-type': 'application/json',
+			'x-csrf-token': csrfToken,
+		},
+		credentials: 'same-origin',
+		body: JSON.stringify({ moduleId, key, value }),
+	});
+	return (
+		await payload<{ readonly setting: SettingsEntryPayload | null }>(
+			response,
+			t('system.settings.errorSave'),
+		)
+	).setting;
+}

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

@@ -0,0 +1,16 @@
+import { cell, createStore } from 'segment-state';
+import type { ModuleCatalogEntry } from './api.ts';
+
+export type ModulesStatus = 'loading' | 'idle' | 'denied' | 'error';
+
+export function createModulesClientState() {
+	const store = createStore({
+		modules: cell<readonly ModuleCatalogEntry[]>([]),
+		commands: cell<Readonly<Record<string, string>>>({}),
+		status: cell<ModulesStatus>('loading'),
+		error: '',
+		query: '',
+		selectedModuleId: cell<string | null>(null),
+	});
+	return { store, state: store.state };
+}

package/modules/system/src/index.ts

@@ -0,0 +1,11 @@
+import type { ModuleManifest, RegisteredModule } from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { SYSTEM_PERMISSIONS } from './acl/permissions.ts';
+
+export const systemModule = {
+	manifest: manifest as ModuleManifest,
+	navigation: [],
+	permissions: Object.values(SYSTEM_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export { SYSTEM_PERMISSIONS } from './acl/permissions.ts';

package/modules/system/src/platform.ts

@@ -0,0 +1,11 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import { createSystemRoutes } from './server/endpoints.ts';
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	return { routes: createSystemRoutes(context) };
+}