@flowdular/sdk 0.2.3 → 0.3.0

package/modules/exports/src/client/ExportsView.tsrx

@@ -0,0 +1,327 @@
+import { useEffect, useMemo } from 'octane';
+import { t } from '@flowdular/sdk/client/i18n';
+import {
+	Alert,
+	Button,
+	EmptyState,
+	Icon,
+	PageHeader,
+	Select,
+	Tag,
+	TableCard,
+	type TableColumn,
+} from '@flowdular/sdk/ui';
+import { useValue } from 'segment-state';
+import {
+	EXPORT_JOB_STATUSES,
+	type ExportJobStatus,
+	type ExportJobView,
+} from '../domain/types.ts';
+import {
+	exportErrorMessage,
+	exportReadUrl,
+	ExportApiError,
+	loadExportJobs,
+	loadExportLists,
+	startExport,
+} from './api.ts';
+import {
+	byteLabel,
+	countLabel,
+	failureLabel,
+	statusLabel,
+	statusTone,
+	timestampLabel,
+} from './presentation.ts';
+import {
+	createExportsClientState,
+	startableLists,
+	startState,
+} from './state.ts';
+
+export interface ExportsViewProps {
+	readonly csrfToken: string;
+	/** Whether the reader holds exports.lists.manage; the server decides again. */
+	readonly canManage: boolean;
+}
+
+export function ExportsView(props: ExportsViewProps) @{
+	const client = useMemo(() => createExportsClientState(), []);
+	const [jobs] = useValue(client.state.jobs);
+	const [status, setStatus] = useValue(client.state.status);
+	const [error, setError] = useValue(client.state.error);
+	const [statusFilter, setStatusFilter] = useValue(client.state.statusFilter);
+	const [openingId] = useValue(client.state.openingId);
+	const [lists, setLists] = useValue(client.state.lists);
+	const [listsStatus, setListsStatus] = useValue(client.state.listsStatus);
+	const [listsError, setListsError] = useValue(client.state.listsError);
+	const [selectedListId, setSelectedListId] = useValue(
+		client.state.selectedListId,
+	);
+	const [starting, setStarting] = useValue(client.state.starting);
+
+	const refresh = async (filter: ExportJobStatus | '') => {
+		setStatus('loading');
+		setError('');
+		try {
+			const page = await loadExportJobs({ status: filter });
+			client.store.act((transaction) => {
+				transaction.set(client.state.jobs, page.items);
+				transaction.set(client.state.nextCursor, page.nextCursor);
+			}, 'exports/loaded');
+			setStatus('idle');
+		} catch (loadError) {
+			setError(exportErrorMessage(loadError, 'exports.error.load'));
+			setStatus(
+				loadError instanceof ExportApiError && loadError.status === 403
+					? 'denied'
+					: 'error',
+			);
+		}
+	};
+
+	/* The catalogue is sealed at boot, so it is read once and not per refresh. */
+	const loadLists = async () => {
+		setListsStatus('loading');
+		setListsError('');
+		try {
+			setLists(await loadExportLists());
+			setListsStatus('idle');
+		} catch (catalogueError) {
+			setListsError(
+				exportErrorMessage(catalogueError, 'exports.error.catalogue'),
+			);
+			setListsStatus(
+				catalogueError instanceof ExportApiError &&
+				catalogueError.status === 403
+					? 'denied'
+					: 'error',
+			);
+		}
+	};
+
+	useEffect(() => {
+		void refresh('');
+		if (props.canManage) void loadLists();
+	}, []);
+
+	/* The job appears in the table the moment it is recorded, so the reader sees
+   the work queued rather than an acknowledgement they have to trust. */
+	const begin = async () => {
+		if (selectedListId === '') return;
+		setStarting(true);
+		setError('');
+		try {
+			await startExport(props.csrfToken, selectedListId);
+			await refresh(statusFilter);
+		} catch (startError) {
+			setError(exportErrorMessage(startError, 'exports.error.start'));
+		} finally {
+			setStarting(false);
+		}
+	};
+
+	/* The signed route is minted on the click and used at once, so the screen
+   never holds a credential it could re-render or log. */
+	const open = async (job: ExportJobView) => {
+		client.store.act(
+			(transaction) => transaction.set(client.state.openingId, job.id),
+			'exports/opening',
+		);
+		setError('');
+		try {
+			const url = await exportReadUrl(props.csrfToken, job.id);
+			globalThis.location.assign(url);
+		} catch (openError) {
+			setError(exportErrorMessage(openError, 'exports.error.open'));
+		} finally {
+			client.store.act(
+				(transaction) => transaction.set(client.state.openingId, null),
+				'exports/opened',
+			);
+		}
+	};
+
+	const start = startState(listsStatus, lists);
+
+	const columns = (): readonly TableColumn<ExportJobView>[] => [
+		{
+			key: 'listId',
+			header: t('exports.table.column.listId'),
+			width: '30%',
+			value: (job) => job.listId,
+			cell: (job) => <b>{job.listId}</b>,
+		},
+		{
+			key: 'status',
+			header: t('exports.table.column.status'),
+			width: '16%',
+			value: (job) => statusLabel(job.status),
+			cell: (job) =>
+				<Tag tone={statusTone(job.status)}>{statusLabel(job.status)}</Tag>,
+		},
+		{
+			key: 'rowCount',
+			header: t('exports.table.column.rowCount'),
+			width: '12%',
+			numeric: true,
+			value: (job) => job.rowCount,
+			cell: (job) => countLabel(job.rowCount),
+		},
+		{
+			key: 'byteCount',
+			header: t('exports.table.column.byteCount'),
+			width: '12%',
+			numeric: true,
+			value: (job) => job.byteCount,
+			cell: (job) => byteLabel(job.byteCount),
+		},
+		{
+			key: 'startedAt',
+			header: t('exports.table.column.startedAt'),
+			width: '18%',
+			value: (job) => job.startedAt,
+			cell: (job) => timestampLabel(job.startedAt),
+		},
+		{
+			key: 'file',
+			header: t('exports.table.column.file'),
+			width: '12%',
+			cell: (job) => job.downloadable
+				? <Button
+						size="sm"
+						disabled={openingId !== null}
+						onClick={() => void open(job)}
+					>
+						<Icon name="download" size={14} />
+						{t('exports.action.open')}
+					</Button>
+				: <span class="ui-cell__muted">{failureLabel(job.failureCode)}</span>,
+		},
+	];
+
+	<div class="ui-view">
+		<PageHeader
+			eyebrow={t('exports.page.eyebrow')}
+			title={t('exports.page.title')}
+			description={t('exports.page.description')}
+		>
+			<Button
+				size="sm"
+				disabled={status === 'denied'}
+				onClick={() => void refresh(statusFilter)}
+			>
+				<Icon name="refresh" size={14} />
+				{status === 'loading'
+					? t('exports.action.refreshing')
+					: t('exports.action.refresh')}
+			</Button>
+		</PageHeader>
+		@if (status === 'denied') {
+			<section class="ui-card">
+				<EmptyState icon="shield" title={t('exports.denied.title')}>{t(
+					'exports.denied.hint',
+				)}</EmptyState>
+			</section>
+		} @else {
+			<>
+				@if (props.canManage) {
+					<section class="ui-card">
+						<div class="ui-card__head">
+							<span class="ui-card__title">
+								{t('exports.start.title')}
+								<small>{t('exports.start.description')}</small>
+							</span>
+						</div>
+						<div class="ui-form">
+							@if (start === 'denied') {
+								<EmptyState
+									icon="shield"
+									title={t('exports.start.deniedTitle')}
+								>{t('exports.start.deniedHint')}</EmptyState>
+							} @else if (start === 'error') {
+								<Alert>{listsError}</Alert>
+							} @else if (start === 'loading') {
+								<p class="ui-note">
+									<Icon name="refresh" size={14} />
+									<span>{t('exports.start.loading')}</span>
+								</p>
+							} @else if (start === 'empty') {
+								<EmptyState
+									icon="download"
+									title={t('exports.start.emptyTitle')}
+								>{t('exports.start.emptyHint')}</EmptyState>
+							} @else {
+								<>
+									<Select
+										id="exports-start-list"
+										label={t('exports.start.list')}
+										placeholder={t('exports.start.placeholder')}
+										value={selectedListId}
+										disabled={starting}
+										onChange={(value) => setSelectedListId(value)}
+										options={startableLists(lists).map(
+											(entry) => ({
+												value: entry.id,
+												label: entry.label + ' (' + entry.moduleId + ')',
+											}),
+										)}
+									/>
+									<div class="ui-form__actions">
+										<Button
+											disabled={starting || selectedListId === ''}
+											onClick={() => void begin()}
+										>
+											<Icon name="play" size={14} />
+											{starting
+												? t('exports.action.starting')
+												: t('exports.action.start')}
+										</Button>
+									</div>
+								</>
+							}
+						</div>
+					</section>
+				}
+				@if (error) {
+					<Alert>{error}</Alert>
+				}
+				<TableCard
+					title={t('exports.table.title')}
+					count={t('exports.table.count', { count: jobs.length })}
+					caption={t('exports.table.caption')}
+					columns={columns()}
+					rows={jobs}
+					rowKey={(job) => job.id}
+					status={status === 'loading' && jobs.length === 0
+						? 'loading'
+						: 'idle'}
+					loadingLabel={t('exports.table.loading')}
+					empty={{
+						icon: 'download',
+						title: t('exports.table.emptyTitle'),
+						hint: t('exports.table.emptyHint'),
+					}}
+					filters={<Select
+						id="exports-status-filter"
+						label={t('exports.filter.status')}
+						value={statusFilter}
+						onChange={(value) => {
+							setStatusFilter(value as ExportJobStatus | '');
+							void refresh(value as ExportJobStatus | '');
+						}}
+						options={[
+							{ value: '', label: t('exports.filter.any') },
+							...EXPORT_JOB_STATUSES.map(
+								(value) => ({
+									value,
+									label: statusLabel(value),
+								}),
+							),
+						]}
+					/>}
+				/>
+			</>
+		}
+	</div>
+}

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

@@ -0,0 +1,133 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type {
+	ExportJobStatus,
+	ExportJobView,
+	ExportListView,
+} 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 ExportApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+
+	constructor(status: number, code: string, message: string) {
+		super(message);
+		this.name = 'ExportApiError';
+		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 exportErrorMessage(
+	error: unknown,
+	fallbackKey: string,
+): string {
+	if (error instanceof ExportApiError) {
+		const key = 'exports.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 ExportApiError(
+			response.status,
+			value.error?.code ?? 'REQUEST_FAILED',
+			value.error?.message ?? t('exports.error.request'),
+		);
+	}
+	return value;
+}
+
+export interface ExportJobPageView {
+	readonly items: readonly ExportJobView[];
+	readonly nextCursor: string | null;
+}
+
+export async function loadExportJobs(
+	options: {
+		readonly status?: ExportJobStatus | '';
+		readonly cursor?: string | null;
+	} = {},
+): Promise<ExportJobPageView> {
+	const query = new URLSearchParams();
+	if (options.status) query.set('status', options.status);
+	if (options.cursor) query.set('cursor', options.cursor);
+	const search = query.toString();
+	const response = await fetch(
+		'/api/exports/jobs' + (search === '' ? '' : `?${search}`),
+		{
+			headers: { accept: 'application/json' },
+			credentials: 'same-origin',
+		},
+	);
+	const page = await payload<{
+		readonly items: readonly ExportJobView[];
+		readonly page: { readonly nextCursor: string | null };
+	}>(response);
+	return { items: page.items, nextCursor: page.page.nextCursor };
+}
+
+/** The lists this workspace offers, each marked with whether the reader may export it. */
+export async function loadExportLists(): Promise<readonly ExportListView[]> {
+	const response = await fetch('/api/exports/lists', {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	return (
+		await payload<{ readonly lists: readonly ExportListView[] }>(response)
+	).lists;
+}
+
+/** Starts one export. The server decides the permission on the live principal. */
+export async function startExport(
+	csrfToken: string,
+	listId: string,
+): Promise<ExportJobView> {
+	const response = await fetch('/api/exports/start', {
+		method: 'POST',
+		headers: {
+			accept: 'application/json',
+			'content-type': 'application/json',
+			'x-csrf-token': csrfToken,
+		},
+		credentials: 'same-origin',
+		body: JSON.stringify({ list: listId }),
+	});
+	return (await payload<{ readonly job: ExportJobView }>(response)).job;
+}
+
+/** The signed route is minted per click and never kept by the screen. */
+export async function exportReadUrl(
+	csrfToken: string,
+	id: string,
+): Promise<string> {
+	const response = await fetch('/api/exports/jobs/read-url', {
+		method: 'POST',
+		headers: {
+			accept: 'application/json',
+			'content-type': 'application/json',
+			'x-csrf-token': csrfToken,
+		},
+		credentials: 'same-origin',
+		body: JSON.stringify({ id }),
+	});
+	return (await payload<{ readonly url: string }>(response)).url;
+}

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

@@ -0,0 +1,31 @@
+import { type ModuleClientContribution } from '@flowdular/sdk/client';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import { EXPORTS_PERMISSIONS } from '../acl/permissions.ts';
+import { ExportsView } from './ExportsView.tsrx';
+import { exportsNavigation, EXPORTS_VIEW } from './navigation.ts';
+
+export interface ExportsClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+}
+
+export function createExportsClientContribution(
+	options: ExportsClientContributionOptions,
+): ModuleClientContribution {
+	/* The control is hidden without the scope; the server refuses a start either
+   way, so this is presentation and never the authorization. */
+	const canManage = options.scopes.includes(EXPORTS_PERMISSIONS.manage);
+	return {
+		moduleId: 'exports.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: exportsNavigation,
+		views: [
+			{
+				id: EXPORTS_VIEW,
+				render: () =>
+					<ExportsView csrfToken={options.csrfToken} canManage={canManage} />,
+			},
+		],
+	};
+}

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

@@ -0,0 +1,20 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createExportsClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export { createExportsClientContribution } from './contribution.tsrx';
+export type { ExportsClientContributionOptions } from './contribution.tsrx';
+export { exportsNavigation, EXPORTS_VIEW } from './navigation.ts';
+export { ExportsView } from './ExportsView.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/exports/src/client/navigation.ts

@@ -0,0 +1,25 @@
+import type { NavigationContribution } from '@flowdular/sdk/client';
+import { t } from '@flowdular/sdk/client/i18n';
+import { EXPORTS_PERMISSIONS } from '../acl/permissions.ts';
+
+/** The view id the navigation entry points at; it equals the URL slug. */
+export const EXPORTS_VIEW = 'exports';
+
+/* Labels are read every render, so a locale change reaches an entry the shell
+   built once. */
+export const exportsNavigation: readonly NavigationContribution[] = [
+	{
+		id: 'exports.navigation',
+		viewId: EXPORTS_VIEW,
+		group: 'Operations',
+		get label() {
+			return t('exports.navigation.label');
+		},
+		glyph: 'download',
+		get description() {
+			return t('exports.navigation.description');
+		},
+		scope: EXPORTS_PERMISSIONS.read,
+		order: 45,
+	},
+];

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

@@ -0,0 +1,53 @@
+import type { TagTone } from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client/i18n';
+import type { ExportJobStatus } from '../domain/types.ts';
+
+/** Epoch milliseconds as the reader's local date and time. */
+export function timestampLabel(value: number): string {
+	return new Intl.DateTimeFormat(activeLocale(), {
+		dateStyle: 'medium',
+		timeStyle: 'short',
+	}).format(value);
+}
+
+export function countLabel(value: number): string {
+	return new Intl.NumberFormat(activeLocale()).format(value);
+}
+
+const BYTE_UNITS = ['B', 'kB', 'MB', 'GB'] as const;
+
+/** Decimal units, the way a file manager shows a download. */
+export function byteLabel(value: number): string {
+	let size = value;
+	let unit = 0;
+	while (size >= 1000 && unit < BYTE_UNITS.length - 1) {
+		size /= 1000;
+		unit += 1;
+	}
+	const formatted = new Intl.NumberFormat(activeLocale(), {
+		maximumFractionDigits: unit === 0 ? 0 : 1,
+	}).format(size);
+	return `${formatted} ${BYTE_UNITS[unit]}`;
+}
+
+export function statusLabel(status: ExportJobStatus): string {
+	return t('exports.status.' + status);
+}
+
+export function statusTone(status: ExportJobStatus): TagTone {
+	if (status === 'completed') return 'success';
+	if (status === 'failed') return 'danger';
+	return status === 'running' ? 'warning' : 'info';
+}
+
+/**
+ * A job's failure code is a stable code this module or a registered list
+ * produced. A code with a sentence of its own reads that; anything else is
+ * shown as it was recorded rather than hidden behind a generic line.
+ */
+export function failureLabel(code: string | null): string {
+	if (!code) return '';
+	const key = 'exports.error.code.' + code;
+	const translated = t(key);
+	return translated === key ? code : translated;
+}

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

@@ -0,0 +1,56 @@
+import { cell, createStore } from 'segment-state';
+import type {
+	ExportJobStatus,
+	ExportJobView,
+	ExportListView,
+} from '../domain/types.ts';
+
+/** `denied` is a 403 the shell could not hide; `error` is everything else. */
+export type ScreenStatus = 'idle' | 'loading' | 'denied' | 'error';
+
+/** What the start control renders once the catalogue answered, or did not. */
+export type StartState = 'loading' | 'denied' | 'error' | 'empty' | 'ready';
+
+export function createExportsClientState() {
+	const store = createStore({
+		jobs: cell<readonly ExportJobView[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		statusFilter: cell<ExportJobStatus | ''>(''),
+		nextCursor: cell<string | null>(null),
+		/** The job whose file is being opened, so one click cannot queue two. */
+		openingId: cell<string | null>(null),
+		lists: cell<readonly ExportListView[]>([]),
+		listsStatus: cell<ScreenStatus>('loading'),
+		listsError: '',
+		selectedListId: '',
+		/** True while a start is in flight, so one click cannot queue two. */
+		starting: false,
+	});
+	return { store, state: store.state };
+}
+
+/**
+ * The lists the control offers. A list the reader does not hold the permission
+ * for is left out rather than offered and refused: the server decides the same
+ * way on the live principal, so offering it could only produce a 403.
+ */
+export function startableLists(
+	lists: readonly ExportListView[],
+): readonly ExportListView[] {
+	return lists.filter((entry) => entry.permitted);
+}
+
+/**
+ * One of the five states the control renders. The catalogue is read once, so
+ * `loading` is the first read alone and a refresh keeps what is on screen.
+ */
+export function startState(
+	status: ScreenStatus,
+	lists: readonly ExportListView[],
+): StartState {
+	if (status === 'denied') return 'denied';
+	if (status === 'error') return 'error';
+	if (status === 'loading' && lists.length === 0) return 'loading';
+	return startableLists(lists).length === 0 ? 'empty' : 'ready';
+}

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

@@ -0,0 +1,29 @@
+import type { DefinedListExport } from '@flowdular/sdk/server';
+
+/**
+ * The public cross-module surface. A module that owns a list registers it while
+ * it composes:
+ * `context.capabilities.get<ExportLists>(EXPORT_LISTS_CAPABILITY)?.register('users.core', [members])`.
+ *
+ * exports.core never reads another module's database. It walks the list through
+ * the `page` the list endpoint already implements, under the requester the job
+ * was started by, and writes what comes back.
+ */
+export const EXPORT_LISTS_CAPABILITY = 'exports.lists.v1';
+
+export interface ExportLists {
+	/**
+	 * Registers the lists one module owns. Every id must be that module id
+	 * followed by the list key, so a module can only declare its own exports.
+	 * Open while the platform composes and sealed before the first request.
+	 */
+	register(moduleId: string, exports: readonly DefinedListExport[]): void;
+}
+
+export const EXPORT_LIST_LIMITS = {
+	moduleId: 64,
+	/** Lists one module may register. */
+	listsPerModule: 32,
+	/** Lists the catalogue may hold at all. */
+	lists: 256,
+} as const;