@flowdular/sdk 0.2.3 → 0.3.0

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

@@ -0,0 +1,159 @@
+import type { ModuleSettingValue } from '@flowdular/sdk/kernel';
+import { t } from '@flowdular/sdk/client/i18n';
+import { cell, createStore } from 'segment-state';
+import type { FlagGroup } from './flags.ts';
+import { updateSetting, type SettingsEntryPayload } from './settings-api.ts';
+
+export interface RowResult {
+	readonly ok: boolean;
+	readonly message: string;
+}
+
+export type SettingsStatus = 'loading' | 'idle' | 'denied' | 'error';
+
+/** Row identity across modules; a key alone repeats between them. */
+export function rowKey(moduleId: string, key: string): string {
+	return moduleId + '.' + key;
+}
+
+export function createFlagsState() {
+	const store = createStore({
+		groups: cell<readonly FlagGroup[]>([]),
+		status: cell<SettingsStatus>('loading'),
+		error: '',
+		busyKey: cell<string | null>(null),
+		results: cell<ReadonlyMap<string, RowResult>>(new Map()),
+	});
+	return { store, state: store.state };
+}
+
+export function createSectionState() {
+	const store = createStore({
+		settings: cell<readonly SettingsEntryPayload[]>([]),
+		status: cell<SettingsStatus>('loading'),
+		error: '',
+		busyKey: cell<string | null>(null),
+		results: cell<ReadonlyMap<string, RowResult>>(new Map()),
+	});
+	return { store, state: store.state };
+}
+
+export type FlagsState = ReturnType<typeof createFlagsState>;
+export type SectionState = ReturnType<typeof createSectionState>;
+
+interface SaveOutcome {
+	/** The row the server answered with, or null when nothing was written. */
+	readonly saved: SettingsEntryPayload | null;
+	readonly result: RowResult;
+}
+
+async function settingSaved(
+	moduleId: string,
+	key: string,
+	value: ModuleSettingValue | null,
+	csrfToken: string,
+): Promise<SaveOutcome> {
+	try {
+		return {
+			saved: await updateSetting(moduleId, key, value, csrfToken),
+			result: {
+				ok: true,
+				message:
+					value === null
+						? t('system.settings.resetDone')
+						: t('system.settings.saved'),
+			},
+		};
+	} catch (error) {
+		return {
+			saved: null,
+			result: {
+				ok: false,
+				message:
+					error instanceof Error
+						? error.message
+						: t('system.settings.errorSave'),
+			},
+		};
+	}
+}
+
+/**
+ * One row of a workspace's feature flags, written back when its request
+ * answers. A second row can be saved while this one is still in flight, so
+ * every cell is read inside the transaction: the values the render captured are
+ * already behind by the time the answer arrives, and writing them back would
+ * undo the save that landed first.
+ */
+export async function saveFlag(
+	client: FlagsState,
+	moduleId: string,
+	key: string,
+	value: ModuleSettingValue | null,
+	csrfToken: string,
+): Promise<void> {
+	const identity = rowKey(moduleId, key);
+	client.store.act((transaction) => {
+		transaction.set(client.state.busyKey, identity);
+	}, 'system/flag-saving');
+	const { saved, result } = await settingSaved(moduleId, key, value, csrfToken);
+	client.store.act(
+		(transaction) => {
+			if (saved) {
+				transaction.update(client.state.groups, (current) =>
+					current.map((group) =>
+						group.moduleId !== moduleId
+							? group
+							: {
+									...group,
+									flags: group.flags.map((flag) =>
+										flag.key === key ? saved : flag,
+									),
+								},
+					),
+				);
+			}
+			transaction.update(client.state.results, (current) =>
+				new Map(current).set(identity, result),
+			);
+			/* A row still saving owns the indicator; only the row that finished
+		   clears it. */
+			transaction.update(client.state.busyKey, (current) =>
+				current === identity ? null : current,
+			);
+		},
+		result.ok ? 'system/flag-saved' : 'system/flag-save-failed',
+	);
+}
+
+/** One row of a module's settings. Same in-flight rules as `saveFlag`. */
+export async function saveSetting(
+	client: SectionState,
+	moduleId: string,
+	key: string,
+	value: ModuleSettingValue | null,
+	csrfToken: string,
+): Promise<void> {
+	client.store.act((transaction) => {
+		transaction.set(client.state.busyKey, key);
+	}, 'system/module-setting-saving');
+	const { saved, result } = await settingSaved(moduleId, key, value, csrfToken);
+	client.store.act(
+		(transaction) => {
+			if (saved) {
+				transaction.update(client.state.settings, (current) =>
+					current.map((setting) => (setting.key === key ? saved : setting)),
+				);
+			}
+			transaction.update(client.state.results, (current) =>
+				new Map(current).set(key, result),
+			);
+			transaction.update(client.state.busyKey, (current) =>
+				current === key ? null : current,
+			);
+		},
+		result.ok
+			? 'system/module-setting-saved'
+			: 'system/module-setting-save-failed',
+	);
+}

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

@@ -2,6 +2,7 @@ import { cell, createStore } from 'segment-state';
 import type { ModuleCatalogEntry } from './api.ts';
 
 export type ModulesStatus = 'loading' | 'idle' | 'denied' | 'error';
+export type ModulesTab = 'catalog' | 'flags';
 
 export function createModulesClientState() {
 	const store = createStore({
@@ -11,6 +12,7 @@ export function createModulesClientState() {
 		error: '',
 		query: '',
 		selectedModuleId: cell<string | null>(null),
+		tab: cell<ModulesTab>('catalog'),
 	});
 	return { store, state: store.state };
 }

package/modules/system/src/domain/time-zone.ts

@@ -0,0 +1,105 @@
+import { TENANT_TIME_ZONE_SETTING } from '@flowdular/sdk/contracts';
+import {
+	ModuleSettingsError,
+	type ModuleSettingsRuntime,
+} from '@flowdular/sdk/kernel';
+
+/* This module declares the setting; the shared contract names it, so a reader
+   in another module addresses the same id, key and fallback. */
+export const SYSTEM_MODULE_ID = TENANT_TIME_ZONE_SETTING.moduleId;
+export const TENANT_TIME_ZONE_KEY = TENANT_TIME_ZONE_SETTING.key;
+export const DEFAULT_TIME_ZONE = TENANT_TIME_ZONE_SETTING.defaultValue;
+export const MAX_TIME_ZONE_LENGTH = 64;
+
+/* A cheap shape filter in front of the Intl probe, so a hostile value never
+   reaches the formatter and never enters the accepted set below. */
+export const TIME_ZONE_PATTERN =
+	'[A-Za-z][A-Za-z0-9_+-]*(?:/[A-Za-z0-9_+-]+){0,2}';
+
+const SHAPE = new RegExp(`^(?:${TIME_ZONE_PATTERN})$`);
+
+export class InvalidTimeZoneError extends Error {
+	readonly code = 'INVALID_TIME_ZONE';
+
+	constructor() {
+		super(
+			`Time zone must be an IANA zone name such as Europe/Warsaw, at most ${MAX_TIME_ZONE_LENGTH} characters.`,
+		);
+		this.name = 'InvalidTimeZoneError';
+	}
+}
+
+/* Canonical names the runtime accepted, keyed by the lower-cased candidate so
+   every spelling of a zone shares one entry. Capped like the formatter cache in
+   automations: a deployment works in a handful of zones, and the cap keeps a
+   long-lived process from carrying every spelling it was ever sent. */
+const MAX_ACCEPTED_ZONES = 32;
+const accepted = new Map<string, string>();
+
+function probe(value: string): string | null {
+	try {
+		return new Intl.DateTimeFormat('en-US', {
+			timeZone: value,
+		}).resolvedOptions().timeZone;
+	} catch {
+		return null;
+	}
+}
+
+/** The canonical IANA name, or null when this runtime does not know the zone. */
+export function resolveTimeZone(value: string): string | null {
+	const candidate = value.trim();
+	if (candidate.length === 0 || candidate.length > MAX_TIME_ZONE_LENGTH) {
+		return null;
+	}
+	if (!SHAPE.test(candidate)) return null;
+	const spelling = candidate.toLowerCase();
+	const cached = accepted.get(spelling);
+	if (cached !== undefined) return cached;
+	const canonical = probe(candidate);
+	if (canonical === null) return null;
+	if (accepted.size >= MAX_ACCEPTED_ZONES) accepted.clear();
+	accepted.set(spelling, canonical);
+	return canonical;
+}
+
+export function isSupportedTimeZone(value: string): boolean {
+	return resolveTimeZone(value) !== null;
+}
+
+/** The canonical name to store, or `InvalidTimeZoneError` for anything else. */
+export function normalizeTimeZone(value: string): string {
+	const canonical = resolveTimeZone(value);
+	if (canonical === null) throw new InvalidTimeZoneError();
+	return canonical;
+}
+
+/**
+ * The workspace time zone any module may read. A stored value this runtime no
+ * longer knows falls back to UTC rather than failing the caller, because the
+ * readers are schedulers and formatters that must keep working.
+ */
+export function tenantTimeZone(
+	settings: ModuleSettingsRuntime,
+	tenantId: string,
+): string {
+	let stored: string;
+	try {
+		stored = settings.get<string>(
+			tenantId,
+			SYSTEM_MODULE_ID,
+			TENANT_TIME_ZONE_KEY,
+		);
+	} catch (error) {
+		/* system.core is not composed in this deployment. A workspace that was
+		   not primed is the caller's defect and stays loud. */
+		if (
+			error instanceof ModuleSettingsError &&
+			error.code === 'SETTINGS_NOT_DECLARED'
+		) {
+			return DEFAULT_TIME_ZONE;
+		}
+		throw error;
+	}
+	return resolveTimeZone(stored) ?? DEFAULT_TIME_ZONE;
+}

package/modules/system/src/index.ts

@@ -9,3 +9,15 @@ export const systemModule = {
 } satisfies RegisteredModule;
 
 export { SYSTEM_PERMISSIONS } from './acl/permissions.ts';
+export { SYSTEM_MODULE_SETTINGS } from './settings.ts';
+export {
+	DEFAULT_TIME_ZONE,
+	InvalidTimeZoneError,
+	isSupportedTimeZone,
+	MAX_TIME_ZONE_LENGTH,
+	normalizeTimeZone,
+	resolveTimeZone,
+	SYSTEM_MODULE_ID,
+	TENANT_TIME_ZONE_KEY,
+	tenantTimeZone,
+} from './domain/time-zone.ts';

package/modules/system/src/platform.ts

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

package/modules/system/src/server/endpoints.ts

@@ -15,9 +15,17 @@ import {
 import {
 	ModuleSettingsError,
 	type ModuleSettingEntry,
+	type ModuleSettingKind,
 	type ModuleSettingsRuntime,
+	type ModuleSettingValue,
 } from '@flowdular/sdk/kernel';
 import { SYSTEM_PERMISSIONS } from '../acl/permissions.ts';
+import {
+	InvalidTimeZoneError,
+	normalizeTimeZone,
+	SYSTEM_MODULE_ID,
+	TENANT_TIME_ZONE_KEY,
+} from '../domain/time-zone.ts';
 import { readModuleCatalog } from './module-catalog.ts';
 
 export interface SystemRouteOptions {
@@ -29,9 +37,14 @@ export interface SystemRouteOptions {
 const MAIL_TRANSPORT_REQUIRED =
 	'Email confirmation needs a composed mail transport; none is available in this deployment.';
 
+const MFA_KEY_REQUIRED =
+	'Required multi-factor authentication needs a deployment MFA encryption key; none is configured.';
+
 export interface SettingsEntryPayload {
 	readonly key: string;
 	readonly type: ModuleSettingEntry['definition']['type'];
+	/** Present only on a feature flag; the Flags screen selects on it. */
+	readonly kind?: ModuleSettingKind;
 	readonly scope: 'platform' | 'tenant';
 	readonly label: string;
 	readonly labelKey?: string;
@@ -58,22 +71,45 @@ export interface SettingsModulePayload {
 	readonly settings: readonly SettingsEntryPayload[];
 }
 
+/** What the deployment composed; both gate an auth.core setting. */
+interface SettingsDeployment {
+	readonly mailTransport: boolean;
+	readonly mfaKeyConfigured: boolean;
+}
+
+/* auth.core refuses these two writes while the deployment configuration they
+   need is missing. The row stays visible but locked, so the screen never offers
+   a control whose write the runtime will answer with a 409. */
+function lockReason(
+	entry: ModuleSettingEntry,
+	deployment: SettingsDeployment,
+): { readonly locked: string; readonly lockedKey: string } | undefined {
+	if (entry.moduleId !== 'auth.core') return undefined;
+	if (entry.key === 'emailConfirmation' && !deployment.mailTransport) {
+		return {
+			locked: MAIL_TRANSPORT_REQUIRED,
+			lockedKey: 'system.settings.mailTransportRequired',
+		};
+	}
+	if (entry.key === 'requireMfa' && !deployment.mfaKeyConfigured) {
+		return {
+			locked: MFA_KEY_REQUIRED,
+			lockedKey: 'system.settings.mfaKeyRequired',
+		};
+	}
+	return undefined;
+}
+
 function entryPayload(
 	entry: ModuleSettingEntry,
-	mailTransport: boolean,
+	deployment: SettingsDeployment,
 ): SettingsEntryPayload {
 	const definition = entry.definition;
-	/* auth.core cannot honor email confirmation without a composed mail
-	   transport; the row stays visible but locked until one exists. */
-	const locked =
-		entry.moduleId === 'auth.core' &&
-		entry.key === 'emailConfirmation' &&
-		!mailTransport
-			? MAIL_TRANSPORT_REQUIRED
-			: undefined;
+	const lock = lockReason(entry, deployment);
 	return {
 		key: entry.key,
 		type: definition.type,
+		...(definition.kind ? { kind: definition.kind } : {}),
 		scope: definition.scope ?? 'tenant',
 		label: definition.label ?? entry.key,
 		...(definition.labelKey ? { labelKey: definition.labelKey } : {}),
@@ -89,15 +125,32 @@ function entryPayload(
 		...(definition.min !== undefined ? { min: definition.min } : {}),
 		...(definition.max !== undefined ? { max: definition.max } : {}),
 		...(definition.multiline ? { multiline: true } : {}),
-		...(locked
-			? {
-					locked,
-					lockedKey: 'system.settings.mailTransportRequired',
-				}
-			: {}),
+		...(lock ?? {}),
 	};
 }
 
+/* The declared pattern bounds the shape only, so the write surface canonicalizes
+   the workspace zone against the runtime zone database. A name this deployment
+   does not know never reaches storage, where every reader would fall back. */
+function timeZoneValue(
+	moduleId: string,
+	key: string,
+	value: ModuleSettingValue | null,
+): ModuleSettingValue | null {
+	if (moduleId !== SYSTEM_MODULE_ID || key !== TENANT_TIME_ZONE_KEY) {
+		return value;
+	}
+	if (typeof value !== 'string') return value;
+	try {
+		return normalizeTimeZone(value);
+	} catch (error) {
+		if (error instanceof InvalidTimeZoneError) {
+			throw new HttpProblem(error.code, error.message, 400);
+		}
+		throw error;
+	}
+}
+
 function settingsProblem(error: unknown): Response {
 	if (error instanceof ModuleSettingsError) {
 		return jsonResponse(
@@ -276,7 +329,7 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 				const grouped = new Map<string, SettingsEntryPayload[]>();
 				for (const entry of options.settings.list(principal.tenantId)) {
 					const group = grouped.get(entry.moduleId) ?? [];
-					group.push(entryPayload(entry, options.auth.mailTransport));
+					group.push(entryPayload(entry, options.auth));
 					grouped.set(entry.moduleId, group);
 				}
 				const payload: SettingsModulePayload[] = [...grouped].map(
@@ -335,20 +388,18 @@ export function createSystemRoutes(options: SystemRouteOptions) {
 						409,
 					);
 				}
-				options.settings.set(
+				await options.settings.set(
 					principal.tenantId,
 					moduleId,
 					key,
-					value ?? null,
+					timeZoneValue(moduleId, key, value) ?? null,
 					principal.accountId,
 				);
 				const entry = options.settings
 					.list(principal.tenantId)
 					.find((item) => item.moduleId === moduleId && item.key === key);
 				return jsonResponse({
-					setting: entry
-						? entryPayload(entry, options.auth.mailTransport)
-						: null,
+					setting: entry ? entryPayload(entry, options.auth) : null,
 				});
 			} catch (error) {
 				return settingsProblem(error);

package/modules/system/src/settings.ts

@@ -0,0 +1,28 @@
+import { defineModuleSettings } from '@flowdular/sdk/kernel';
+import {
+	DEFAULT_TIME_ZONE,
+	MAX_TIME_ZONE_LENGTH,
+	SYSTEM_MODULE_ID,
+	TIME_ZONE_PATTERN,
+} from './domain/time-zone.ts';
+
+export const SYSTEM_MODULE_SETTINGS = defineModuleSettings({
+	moduleId: SYSTEM_MODULE_ID,
+	settings: {
+		timeZone: {
+			type: 'string',
+			defaultValue: DEFAULT_TIME_ZONE,
+			visibility: 'shared',
+			client: false,
+			scope: 'tenant',
+			min: 1,
+			max: MAX_TIME_ZONE_LENGTH,
+			pattern: TIME_ZONE_PATTERN,
+			labelKey: 'system.settings.timeZone.label',
+			label: 'Workspace time zone',
+			descriptionKey: 'system.settings.timeZone.description',
+			description:
+				'IANA zone name such as Europe/Warsaw. Modules that show or schedule local times read it; the default is UTC.',
+		},
+	},
+});

package/modules/system/translations/en.json

@@ -14,6 +14,20 @@
 	"action.reset": "Reset",
 	"denied.title": "Access denied",
 	"denied.hint": "Reading the module catalog needs the system.modules.read scope.",
+	"tab.label": "Administration views",
+	"tab.catalog": "Modules",
+	"tab.flags": "Flags",
+	"flags.title": "Feature flags",
+	"flags.count": "{count} in {modules} modules",
+	"flags.loading": "Loading flags…",
+	"flags.loadingHint": "Reading the flags every enabled module declares.",
+	"flags.emptyTitle": "No feature flags",
+	"flags.emptyHint": "No enabled module declares a feature flag in this workspace.",
+	"flags.deniedTitle": "Access denied",
+	"flags.deniedHint": "Reading feature flags needs the system.settings.read scope.",
+	"flags.deniedManage": "Changing a flag needs the system.settings.manage scope.",
+	"flags.auditNote": "Every change is recorded as {action} for this workspace.",
+	"flags.auditLink": "Open the audit trail",
 	"search.placeholder": "Filter by id or name",
 	"search.label": "Filter modules",
 	"table.title": "Module catalog",
@@ -60,5 +74,8 @@
 	"settings.configured": "Configured",
 	"settings.emptyValue": "Empty",
 	"settings.mailTransportRequired": "Email confirmation needs a configured mail transport.",
+	"settings.mfaKeyRequired": "Required multi-factor authentication needs a deployment MFA encryption key.",
+	"settings.timeZone.label": "Workspace time zone",
+	"settings.timeZone.description": "IANA zone name such as Europe/Warsaw. Modules that show or schedule local times read it; the default is UTC.",
 	"error.catalog": "Could not load the module catalog."
 }

package/modules/system/translations/pl.json

@@ -14,6 +14,20 @@
 	"action.reset": "Przywróć domyślne",
 	"denied.title": "Brak dostępu",
 	"denied.hint": "Odczyt katalogu modułów wymaga uprawnienia system.modules.read.",
+	"tab.label": "Widoki administracyjne",
+	"tab.catalog": "Moduły",
+	"tab.flags": "Flagi",
+	"flags.title": "Flagi funkcji",
+	"flags.count": "{count} w {modules} modułach",
+	"flags.loading": "Wczytywanie flag…",
+	"flags.loadingHint": "Trwa odczyt flag deklarowanych przez włączone moduły.",
+	"flags.emptyTitle": "Brak flag funkcji",
+	"flags.emptyHint": "Żaden włączony moduł nie deklaruje flagi funkcji w tej przestrzeni roboczej.",
+	"flags.deniedTitle": "Brak dostępu",
+	"flags.deniedHint": "Odczyt flag funkcji wymaga uprawnienia system.settings.read.",
+	"flags.deniedManage": "Zmiana flagi wymaga uprawnienia system.settings.manage.",
+	"flags.auditNote": "Każda zmiana jest zapisywana jako {action} dla tej przestrzeni roboczej.",
+	"flags.auditLink": "Otwórz dziennik audytu",
 	"search.placeholder": "Filtruj po identyfikatorze lub nazwie",
 	"search.label": "Filtruj moduły",
 	"table.title": "Katalog modułów",
@@ -60,5 +74,8 @@
 	"settings.configured": "Skonfigurowano",
 	"settings.emptyValue": "Puste",
 	"settings.mailTransportRequired": "Potwierdzanie adresu e-mail wymaga skonfigurowanej usługi wysyłki wiadomości.",
+	"settings.mfaKeyRequired": "Wymagane uwierzytelnianie dwuskładnikowe potrzebuje klucza szyfrującego MFA skonfigurowanego we wdrożeniu.",
+	"settings.timeZone.label": "Strefa czasowa obszaru roboczego",
+	"settings.timeZone.description": "Nazwa strefy IANA, na przykład Europe/Warsaw. Moduły, które pokazują lub planują czas lokalny, odczytują tę wartość; domyślnie UTC.",
 	"error.catalog": "Nie udało się wczytać katalogu modułów."
 }

package/modules/users/module.json

@@ -3,7 +3,7 @@
 	"schemaVersion": 1,
 	"id": "users.core",
 	"package": "@flowdular/module-users",
-	"version": "0.6.0",
+	"version": "0.9.8",
 	"profile": "full",
 	"capabilities": ["api", "client", "translations"],
 	"platform": {
@@ -13,15 +13,41 @@
 	"dependencies": [
 		{
 			"id": "system.core",
-			"range": "0.5.0"
+			"range": "^0.7.0"
 		},
 		{
 			"id": "auth.core",
-			"range": "0.10.0"
+			"range": "^0.13.0"
+		},
+		{
+			"id": "search.core",
+			"range": "^0.1.0"
+		},
+		{
+			"id": "import.core",
+			"range": "^0.1.0"
+		},
+		{
+			"id": "exports.core",
+			"range": "^0.2.0"
+		}
+	],
+	"requires": [
+		{
+			"id": "search.providers.v1",
+			"optional": true
+		},
+		{
+			"id": "import.ports.v1",
+			"optional": true
+		},
+		{
+			"id": "exports.lists.v1",
+			"optional": true
 		}
 	],
 	"tenancy": "required",
 	"locales": ["en", "pl"],
 	"stability": "experimental",
-	"platformApi": "0.1.0"
+	"platformApi": "^0.1.2"
 }

package/modules/users/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/module-users",
-	"version": "0.6.0",
+	"version": "0.9.8",
 	"type": "module",
 	"exports": {
 		".": "./src/index.ts",
@@ -17,10 +17,13 @@
 		"@flowdular/client": "workspace:*",
 		"@flowdular/contracts": "workspace:*",
 		"@flowdular/module-auth": "workspace:*",
+		"@flowdular/module-exports": "workspace:*",
+		"@flowdular/module-import": "workspace:*",
+		"@flowdular/module-search": "workspace:*",
 		"@flowdular/server": "workspace:*",
 		"@flowdular/ui": "workspace:*",
 		"octane": "0.1.51",
-		"segment-state": "0.2.0"
+		"segment-state": "0.2.1"
 	},
 	"devDependencies": {
 		"@flowdular/database": "workspace:*",