@flowdular/sdk 0.2.4 → 0.3.0

package/modules/import/src/client/NewImportForm.tsrx

@@ -0,0 +1,274 @@
+import { useMemo } from 'octane';
+import { Alert, Button, FormField, Switch } from '@flowdular/sdk/ui';
+import { t } from '@flowdular/sdk/client/i18n';
+import { cell, createStore, useValue } from 'segment-state';
+import { parseCsv } from '../domain/csv.ts';
+import { IMPORT_MODES, type ImportMode } from '../domain/ports.ts';
+import { IMPORT_MAX_CSV_BYTES } from '../domain/types.ts';
+import type { ImportTargetView } from '../services/import-service.ts';
+import { modeLabel } from './presentation.ts';
+
+export interface NewImportValue {
+	readonly file: File;
+	readonly target: string;
+	readonly mode: ImportMode;
+	readonly dryRun: boolean;
+	readonly columns: Readonly<Record<string, string>>;
+	readonly saveMapping: boolean;
+}
+
+export interface NewImportFormProps {
+	readonly targets: readonly ImportTargetView[];
+	readonly busy: boolean;
+	readonly error: string;
+	/** The saved template for a target, offered as the starting mapping. */
+	readonly loadMapping: (target: string) => Promise<
+		Readonly<Record<string, string>>
+	>;
+	readonly onCancel: () => void;
+	readonly onSubmit: (value: NewImportValue) => void;
+}
+
+/* Enough of the file to hold a header row; a header longer than this is a file
+   this screen cannot offer column names for, and the reader types them. */
+const HEADER_SLICE_BYTES = 64 * 1024;
+
+async function detectHeader(file: File): Promise<readonly string[]> {
+	try {
+		const text = await file.slice(0, HEADER_SLICE_BYTES).text();
+		/* The slice can cut a record in half, so only the header is trusted. */
+		return parseCsv(text, {
+			maxBytes: HEADER_SLICE_BYTES,
+			maxRows: Number.MAX_SAFE_INTEGER,
+		}).header;
+	} catch {
+		return [];
+	}
+}
+
+export function NewImportForm(props: NewImportFormProps) @{
+	const formState = useMemo(
+		() => createStore({
+			target: props.targets.find((entry) => entry.permitted)?.target ?? '',
+			mode: cell<ImportMode>('create-only'),
+			dryRun: true,
+			saveMapping: true,
+			fileName: '',
+			file: cell<File | null>(null),
+			header: cell<readonly string[]>([]),
+			columns: cell<Readonly<Record<string, string>>>({}),
+			localError: '',
+		}),
+		[],
+	);
+	const [target, setTarget] = useValue(formState.state.target);
+	const [mode, setMode] = useValue(formState.state.mode);
+	const [dryRun, setDryRun] = useValue(formState.state.dryRun);
+	const [saveMapping, setSaveMapping] = useValue(formState.state.saveMapping);
+	const [fileName, setFileName] = useValue(formState.state.fileName);
+	const [file, setFile] = useValue(formState.state.file);
+	const [header, setHeader] = useValue(formState.state.header);
+	const [columns, setColumns] = useValue(formState.state.columns);
+	const [localError, setLocalError] = useValue(formState.state.localError);
+
+	const selected =
+		props.targets.find((entry) => entry.target === target) ?? null;
+
+	const chooseTarget = async (value: string) => {
+		setTarget(value);
+		setColumns(value === '' ? {} : await props.loadMapping(value));
+	};
+
+	const chooseFile = async (chosen: File | null) => {
+		setLocalError('');
+		setFile(chosen);
+		setFileName(chosen?.name ?? '');
+		if (!chosen) {
+			setHeader([]);
+			return;
+		}
+		if (chosen.size > IMPORT_MAX_CSV_BYTES) {
+			setLocalError(t('import.form.error.tooLarge'));
+			setHeader([]);
+			return;
+		}
+		setHeader(await detectHeader(chosen));
+	};
+
+	const setColumn = (field: string, value: string) => {
+		const next = { ...columns };
+		if (value === '') delete next[field];
+		else next[field] = value;
+		setColumns(next);
+	};
+
+	const submit = (event: SubmitEvent) => {
+		event.preventDefault();
+		if (!file || !selected) return;
+		const missing = selected.fields.find(
+			(field) => field.required && !columns[field.id],
+		);
+		if (missing) {
+			setLocalError(t('import.form.error.mapping', { field: missing.label }));
+			return;
+		}
+		setLocalError('');
+		props.onSubmit({
+			file,
+			target: selected.target,
+			mode,
+			dryRun,
+			columns,
+			saveMapping,
+		});
+	};
+
+	<form class="ui-drawer__form" onSubmit={submit}>
+		<div class="ui-drawer__body">
+			<div class="ui-form">
+				<div class="ui-form__row">
+					<FormField label={t('import.form.target')} required>
+						<select
+							class="ui-select"
+							name="target"
+							value={target}
+							onInput={(event) => void chooseTarget(event.currentTarget.value)}
+							required
+						>
+							<option value="">{t('import.form.targetPlaceholder')}</option>
+							@for (const entry of props.targets; key entry.target) {
+								<option value={entry.target} disabled={!entry.permitted}>
+									{entry.permitted
+										? entry.label
+										: t('import.form.targetDenied', { label: entry.label })}
+								</option>
+							}
+						</select>
+					</FormField>
+					<FormField label={t('import.form.mode')} required>
+						<select
+							class="ui-select"
+							name="mode"
+							value={mode}
+							onInput={(event) => setMode(
+								event.currentTarget.value as ImportMode,
+							)}
+						>
+							@for (const value of IMPORT_MODES; key value) {
+								<option value={value}>{modeLabel(value)}</option>
+							}
+						</select>
+					</FormField>
+				</div>
+				<div class="ui-form__row">
+					<FormField
+						label={t('import.form.file')}
+						help={t('import.form.fileHelp')}
+						required
+					>
+						<input
+							class="ui-input"
+							type="file"
+							name="file"
+							accept=".csv,text/csv"
+							onChange={(event) => void chooseFile(
+								event.currentTarget.files?.[0] ?? null,
+							)}
+							required
+						/>
+					</FormField>
+				</div>
+				@if (selected && file) {
+					<div class="ui-form__section">
+						<div class="ui-form__section-head">
+							<b>{t('import.form.mapping')}</b>
+							<small>
+								{header.length > 0
+									? t('import.form.mappingHelp', { file: fileName })
+									: t('import.form.mappingManual')}
+							</small>
+						</div>
+						@for (const field of selected.fields; key field.id) {
+							<FormField
+								label={field.label}
+								help={t('import.form.fieldType', {
+									type: t('import.type.' + field.type),
+								})}
+								required={field.required}
+							>
+								@if (header.length > 0) {
+									<select
+										class="ui-select"
+										name={'column-' + field.id}
+										value={columns[field.id] ?? ''}
+										onInput={(event) => setColumn(
+											field.id,
+											event.currentTarget.value,
+										)}
+									>
+										<option value="">{t('import.form.columnNone')}</option>
+										@for (const name of header; key name) {
+											<option value={name}>{name}</option>
+										}
+									</select>
+								} @else {
+									<input
+										class="ui-input ui-mono"
+										name={'column-' + field.id}
+										value={columns[field.id] ?? ''}
+										maxlength={200}
+										onInput={(event) => setColumn(
+											field.id,
+											event.currentTarget.value,
+										)}
+									/>
+								}
+							</FormField>
+						}
+					</div>
+				}
+				<div class="ui-form__row">
+					<FormField
+						label={t('import.form.dryRun')}
+						help={t('import.form.dryRunHelp')}
+					>
+						<Switch
+							label={t('import.form.dryRun')}
+							checked={dryRun}
+							onChange={(value) => setDryRun(value)}
+						/>
+					</FormField>
+					<FormField
+						label={t('import.form.saveMapping')}
+						help={t('import.form.saveMappingHelp')}
+					>
+						<Switch
+							label={t('import.form.saveMapping')}
+							checked={saveMapping}
+							onChange={(value) => setSaveMapping(value)}
+						/>
+					</FormField>
+				</div>
+				@if (localError) {
+					<Alert>{localError}</Alert>
+				}
+				@if (props.error) {
+					<Alert>{props.error}</Alert>
+				}
+			</div>
+		</div>
+		<div class="ui-drawer__foot">
+			<small>{t('import.form.note')}</small>
+			<div class="ui-form__actions">
+				<Button onClick={props.onCancel}>{t('import.form.cancel')}</Button>
+				<Button
+					variant="primary"
+					type="submit"
+					disabled={props.busy || !file || !selected}
+				>
+					{props.busy ? t('import.form.submitting') : t('import.form.submit')}
+				</Button>
+			</div>
+		</div>
+	</form>
+}

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

@@ -0,0 +1,243 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type { ImportMode } from '../domain/ports.ts';
+import { IMPORT_CSV_CONTENT_TYPE } from '../domain/types.ts';
+import type {
+	ImportJobView,
+	ImportJobRow,
+	ImportJobStatus,
+	ImportMapping,
+} from '../domain/types.ts';
+import type { ImportTargetView } from '../services/import-service.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 ImportApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+
+	constructor(status: number, code: string, message: string) {
+		super(message);
+		this.name = 'ImportApiError';
+		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 importErrorMessage(
+	error: unknown,
+	fallbackKey: string,
+): string {
+	if (error instanceof ImportApiError) {
+		const key = 'import.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 ImportApiError(
+			response.status,
+			value.error?.code ?? 'REQUEST_FAILED',
+			value.error?.message ?? t('import.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),
+		}),
+	);
+}
+
+interface Page<T> {
+	readonly items: readonly T[];
+	readonly page: { readonly nextCursor: string | null };
+}
+
+export async function loadTargets(): Promise<readonly ImportTargetView[]> {
+	return (
+		await get<{ targets: readonly ImportTargetView[] }>('/api/import/targets')
+	).targets;
+}
+
+export interface JobFilter {
+	readonly status?: ImportJobStatus | '';
+	readonly target?: string;
+	readonly cursor?: string | null;
+}
+
+function query(entries: Readonly<Record<string, string>>): string {
+	const parameters = new URLSearchParams();
+	for (const [key, value] of Object.entries(entries)) {
+		if (value !== '') parameters.set(key, value);
+	}
+	const text = parameters.toString();
+	return text === '' ? '' : '?' + text;
+}
+
+export async function loadJobs(
+	filter: JobFilter = {},
+): Promise<Page<ImportJobView>> {
+	return get<Page<ImportJobView>>(
+		'/api/import/jobs' +
+			query({
+				status: filter.status ?? '',
+				target: filter.target ?? '',
+				cursor: filter.cursor ?? '',
+			}),
+	);
+}
+
+export async function loadJob(id: string): Promise<ImportJobView> {
+	return (
+		await get<{ job: ImportJobView }>(
+			`/api/import/jobs/${encodeURIComponent(id)}`,
+		)
+	).job;
+}
+
+export async function loadJobRows(
+	id: string,
+	cursor: string | null = null,
+): Promise<Page<ImportJobRow>> {
+	return get<Page<ImportJobRow>>(
+		`/api/import/jobs/${encodeURIComponent(id)}/rows` +
+			query({ cursor: cursor ?? '' }),
+	);
+}
+
+export async function loadMapping(
+	target: string,
+): Promise<ImportMapping | null> {
+	return (
+		await get<{ mapping: ImportMapping | null }>(
+			'/api/import/mappings' + query({ target }),
+		)
+	).mapping;
+}
+
+export async function saveMapping(
+	target: string,
+	columns: Readonly<Record<string, string>>,
+	csrfToken: string,
+): Promise<ImportMapping> {
+	return (
+		await post<{ mapping: ImportMapping }>(
+			'/api/import/mappings/save',
+			{ target, columns },
+			csrfToken,
+		)
+	).mapping;
+}
+
+export interface StartImportRequest {
+	readonly target: string;
+	readonly documentId: string;
+	readonly documentRef: string;
+	readonly mode: ImportMode;
+	readonly dryRun: boolean;
+	readonly columns: Readonly<Record<string, string>>;
+}
+
+export async function startImport(
+	input: StartImportRequest,
+	csrfToken: string,
+): Promise<ImportJobView> {
+	return (
+		await post<{ job: ImportJobView }>(
+			'/api/import/jobs/start',
+			input,
+			csrfToken,
+		)
+	).job;
+}
+
+export async function continueImport(
+	id: string,
+	validOnly: boolean,
+	csrfToken: string,
+): Promise<ImportJobView> {
+	return (
+		await post<{ job: ImportJobView }>(
+			'/api/import/jobs/continue',
+			{ id, validOnly },
+			csrfToken,
+		)
+	).job;
+}
+
+export async function cancelImport(
+	id: string,
+	csrfToken: string,
+): Promise<ImportJobView> {
+	return (
+		await post<{ job: ImportJobView }>(
+			'/api/import/jobs/cancel',
+			{ id },
+			csrfToken,
+		)
+	).job;
+}
+
+/**
+ * The CSV enters through documents.core, where the session, the CSRF proof, the
+ * workspace quota and the storage limits are applied. import.core stores no
+ * bytes of its own, so this is the only upload path.
+ */
+export async function uploadSourceCsv(
+	file: File,
+	documentRef: string,
+	csrfToken: string,
+): Promise<{ readonly id: string }> {
+	const response = await fetch('/api/documents/upload', {
+		method: 'POST',
+		headers: {
+			'content-type': IMPORT_CSV_CONTENT_TYPE,
+			'x-csrf-token': csrfToken,
+			'x-document-filename': encodeURIComponent(file.name),
+			'x-document-owner-module': encodeURIComponent('import.core'),
+			'x-document-record-ref': encodeURIComponent(documentRef),
+		},
+		credentials: 'same-origin',
+		body: file,
+	});
+	return (await payload<{ document: { id: string } }>(response)).document;
+}

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

@@ -0,0 +1,29 @@
+import { type ModuleClientContribution } from '@flowdular/sdk/client';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import { IMPORT_PERMISSIONS } from '../acl/permissions.ts';
+import { ImportsView } from './ImportsView.tsrx';
+import { importNavigation, IMPORTS_VIEW } from './navigation.ts';
+
+export interface ImportClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+}
+
+export function createImportClientContribution(
+	options: ImportClientContributionOptions,
+): ModuleClientContribution {
+	const canManage = options.scopes.includes(IMPORT_PERMISSIONS.manage);
+	return {
+		moduleId: 'import.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: importNavigation,
+		views: [
+			{
+				id: IMPORTS_VIEW,
+				render: () =>
+					<ImportsView csrfToken={options.csrfToken} canManage={canManage} />,
+			},
+		],
+	};
+}

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

@@ -0,0 +1,23 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createImportClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export { createImportClientContribution } from './contribution.tsrx';
+export type { ImportClientContributionOptions } from './contribution.tsrx';
+export { importNavigation, IMPORTS_VIEW } from './navigation.ts';
+export { ImportsView } from './ImportsView.tsrx';
+export { ImportJobDrawer } from './ImportJobDrawer.tsrx';
+export { NewImportForm } from './NewImportForm.tsrx';
+export type { NewImportValue } from './NewImportForm.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/import/src/client/navigation.ts

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

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

@@ -0,0 +1,59 @@
+import type { TagTone } from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client/i18n';
+import type { ImportJobStatus, ImportRowOutcome } 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);
+}
+
+export function statusLabel(status: ImportJobStatus): string {
+	return t('import.status.' + status);
+}
+
+export function statusTone(status: ImportJobStatus): TagTone {
+	if (status === 'completed') return 'success';
+	if (status === 'failed') return 'danger';
+	if (status === 'cancelled') return 'neutral';
+	return status === 'validated' ? 'info' : 'warning';
+}
+
+export function outcomeLabel(outcome: ImportRowOutcome): string {
+	return t('import.outcome.' + outcome);
+}
+
+export function outcomeTone(outcome: ImportRowOutcome): TagTone {
+	if (outcome === 'created' || outcome === 'updated') return 'success';
+	if (outcome === 'invalid' || outcome === 'failed') return 'danger';
+	return outcome === 'valid' ? 'info' : 'neutral';
+}
+
+export function modeLabel(mode: string): string {
+	return t('import.mode.' + mode);
+}
+
+/**
+ * A row reason and a job's failure code are stable codes the port or this module
+ * produced. A code with a reason of its own reads that; a code this module also
+ * refuses requests with falls back to that one sentence rather than carrying a
+ * second copy of it; anything else is shown as the port wrote it rather than
+ * hidden behind a generic line.
+ */
+export function reasonLabel(reason: string | null): string {
+	if (!reason) return '';
+	for (const key of [
+		'import.reason.' + reason,
+		'import.error.code.' + reason,
+	]) {
+		const translated = t(key);
+		if (translated !== key) return translated;
+	}
+	return reason;
+}

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

@@ -0,0 +1,43 @@
+import { cell, createStore } from 'segment-state';
+import type {
+	ImportJobView,
+	ImportJobRow,
+	ImportJobStatus,
+} from '../domain/types.ts';
+import type { ImportTargetView } from '../services/import-service.ts';
+
+/** `denied` is a 403 the shell could not hide; `error` is everything else. */
+export type ScreenStatus =
+	| 'idle'
+	| 'loading'
+	| 'submitting'
+	| 'denied'
+	| 'error';
+
+export function createImportClientState() {
+	const store = createStore({
+		jobs: cell<readonly ImportJobView[]>([]),
+		targets: cell<readonly ImportTargetView[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		query: '',
+		statusFilter: cell<ImportJobStatus | ''>(''),
+		targetFilter: '',
+		filtersOpen: false,
+		formOpen: false,
+		/* Remounts the form so the native file input starts empty again. */
+		formSession: 0,
+		openJobId: cell<string | null>(null),
+		openJob: cell<ImportJobView | null>(null),
+		openJobRows: cell<readonly ImportJobRow[]>([]),
+		openJobCursor: cell<string | null>(null),
+		drawerError: '',
+		confirmCancelId: cell<string | null>(null),
+	});
+	return { store, state: store.state };
+}
+
+/** Targets present in the loaded set, for the filter's option list. */
+export function jobTargets(jobs: readonly ImportJobView[]): readonly string[] {
+	return [...new Set(jobs.map((job) => job.target))].sort();
+}