@flowdular/sdk 0.2.4 → 0.3.1

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

@@ -0,0 +1,209 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type { DocumentAttachment } from '../domain/attachments.ts';
+import type {
+	DocumentDeleteOutcome,
+	DocumentReadUrl,
+	DocumentScan,
+} 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 DocumentsApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+
+	constructor(status: number, code: string, message: string) {
+		super(message);
+		this.name = 'DocumentsApiError';
+		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 documentsErrorMessage(
+	error: unknown,
+	fallbackKey: string,
+): string {
+	if (error instanceof DocumentsApiError) {
+		const key = 'documents.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 DocumentsApiError(
+			response.status,
+			value.error?.code ?? 'REQUEST_FAILED',
+			value.error?.message ?? t('documents.error.request'),
+		);
+	}
+	return value;
+}
+
+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),
+		}),
+	);
+}
+
+export interface DocumentFilter {
+	readonly ownerModule?: string;
+	readonly recordRef?: string;
+	readonly scan?: DocumentScan | '';
+	/** Substring of the filename or the description; the server matches it. */
+	readonly search?: string;
+	/** The page to continue; null or absent asks for the first one. */
+	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 interface DocumentPage {
+	readonly items: readonly DocumentAttachment[];
+	readonly page: { readonly nextCursor: string | null };
+}
+
+/** One server-filtered, server-paged listing; the screen narrows nothing. */
+export async function loadDocuments(
+	filter: DocumentFilter = {},
+): Promise<DocumentPage> {
+	const response = await fetch(
+		'/api/documents' +
+			query({
+				ownerModule: filter.ownerModule ?? '',
+				recordRef: filter.recordRef ?? '',
+				scan: filter.scan ?? '',
+				q: filter.search ?? '',
+				cursor: filter.cursor ?? '',
+			}),
+		{
+			headers: { accept: 'application/json' },
+			credentials: 'same-origin',
+		},
+	);
+	return payload<DocumentPage>(response);
+}
+
+export interface DocumentLimits {
+	readonly maxObjectBytes: number;
+	readonly contentTypes: readonly string[];
+}
+
+export async function loadDocumentLimits(): Promise<DocumentLimits> {
+	return payload<DocumentLimits>(
+		await fetch('/api/documents/limits', {
+			headers: { accept: 'application/json' },
+			credentials: 'same-origin',
+		}),
+	);
+}
+
+export interface UploadDocumentRequest {
+	readonly file: File;
+	readonly ownerModule: string;
+	readonly recordRef: string;
+	readonly description: string;
+}
+
+/* A header is ASCII on the wire and a document name is not, so every text
+   header is percent encoded and the server decodes it once. */
+function encodedHeaders(
+	input: UploadDocumentRequest,
+	csrfToken: string,
+): Record<string, string> {
+	return {
+		'content-type': input.file.type,
+		'x-csrf-token': csrfToken,
+		'x-document-filename': encodeURIComponent(input.file.name),
+		'x-document-owner-module': encodeURIComponent(input.ownerModule),
+		'x-document-record-ref': encodeURIComponent(input.recordRef),
+		...(input.description === ''
+			? {}
+			: { 'x-document-description': encodeURIComponent(input.description) }),
+	};
+}
+
+/** The file is the whole body: there is no multipart parser on the server. */
+export async function uploadDocument(
+	input: UploadDocumentRequest,
+	csrfToken: string,
+): Promise<DocumentAttachment> {
+	const response = await fetch('/api/documents/upload', {
+		method: 'POST',
+		headers: encodedHeaders(input, csrfToken),
+		credentials: 'same-origin',
+		body: input.file,
+	});
+	return (await payload<{ readonly document: DocumentAttachment }>(response))
+		.document;
+}
+
+export async function documentReadUrl(
+	id: string,
+	csrfToken: string,
+): Promise<DocumentReadUrl> {
+	return post<DocumentReadUrl>('/api/documents/read-url', { id }, csrfToken);
+}
+
+export async function deleteDocument(
+	id: string,
+	csrfToken: string,
+): Promise<DocumentAttachment> {
+	return (
+		await post<{ readonly document: DocumentAttachment }>(
+			'/api/documents/delete',
+			{ id },
+			csrfToken,
+		)
+	).document;
+}
+
+/** One outcome per id, in the order the ids were sent. */
+export async function deleteDocuments(
+	ids: readonly string[],
+	csrfToken: string,
+): Promise<readonly DocumentDeleteOutcome[]> {
+	return (
+		await post<{ readonly outcomes: readonly DocumentDeleteOutcome[] }>(
+			'/api/documents/delete-many',
+			{ ids },
+			csrfToken,
+		)
+	).outcomes;
+}

package/modules/documents/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 { DOCUMENTS_PERMISSIONS } from '../acl/permissions.ts';
+import { DocumentsView } from './DocumentsView.tsrx';
+import { documentsNavigation, DOCUMENTS_VIEW } from './navigation.ts';
+
+export interface DocumentsClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+}
+
+export function createDocumentsClientContribution(
+	options: DocumentsClientContributionOptions,
+): ModuleClientContribution {
+	const canManage = options.scopes.includes(DOCUMENTS_PERMISSIONS.manage);
+	return {
+		moduleId: 'documents.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: documentsNavigation,
+		views: [
+			{
+				id: DOCUMENTS_VIEW,
+				render: () =>
+					<DocumentsView csrfToken={options.csrfToken} canManage={canManage} />,
+			},
+		],
+	};
+}

package/modules/documents/src/client/download.ts

@@ -0,0 +1,70 @@
+/**
+ * The part of a browser window this module uses to hand a reader a file. Named
+ * as an interface so the behaviour can be exercised without one.
+ */
+export interface DownloadWindow {
+	open(url: string, target: string): DownloadTab | null;
+}
+
+export interface DownloadTab {
+	location: { href: string };
+	opener: unknown;
+	close(): void;
+}
+
+/** The tab a download was started in, before the URL that fills it exists. */
+export interface DownloadTarget {
+	/** Sends the waiting tab to the URL the server issued. */
+	send(url: string): void;
+	/** Closes it when no URL was issued, so no blank tab is left behind. */
+	abort(): void;
+}
+
+/**
+ * Opens the tab inside the click that asked for it. A tab opened after the
+ * await that resolves the read URL is a pop-up the browser blocks, so the tab
+ * is claimed first and sent to the URL when it arrives. `opener` is dropped as
+ * soon as the tab exists: the download route must not reach back into the app.
+ */
+export function openDownloadTarget(
+	view: DownloadWindow,
+): DownloadTarget | null {
+	const tab = view.open('', '_blank');
+	if (!tab) return null;
+	tab.opener = null;
+	return {
+		send(url) {
+			tab.location.href = url;
+		},
+		abort() {
+			tab.close();
+		},
+	};
+}
+
+/**
+ * One download from the click to the bytes. The tab is claimed before `resolve`
+ * runs and closed again when it refuses, and a window the browser would not
+ * open is reported rather than passed over in silence.
+ */
+export async function runDownload(
+	view: DownloadWindow,
+	resolve: () => Promise<string>,
+): Promise<void> {
+	const target = openDownloadTarget(view);
+	if (!target) throw new DownloadBlocked();
+	try {
+		target.send(await resolve());
+	} catch (error) {
+		target.abort();
+		throw error;
+	}
+}
+
+/** The browser refused the tab, so the reader has to allow it themselves. */
+export class DownloadBlocked extends Error {
+	constructor() {
+		super('The browser blocked the download tab.');
+		this.name = 'DownloadBlocked';
+	}
+}

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

@@ -0,0 +1,22 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createDocumentsClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export { createDocumentsClientContribution } from './contribution.tsrx';
+export type { DocumentsClientContributionOptions } from './contribution.tsrx';
+export { documentsNavigation, DOCUMENTS_VIEW } from './navigation.ts';
+export { DocumentsView } from './DocumentsView.tsrx';
+export { DocumentUploader } from './DocumentUploader.tsrx';
+export type { DocumentUploadValue } from './DocumentUploader.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/documents/src/client/navigation.ts

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

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

@@ -0,0 +1,110 @@
+import type { TableEmpty, TagTone } from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client/i18n';
+import type { DocumentAttachment } from '../domain/attachments.ts';
+import type { DocumentScan } from '../domain/types.ts';
+import type { ScreenStatus } from './state.ts';
+
+const BYTE_UNITS = ['bytes', 'kb', 'mb', 'gb'] as const;
+
+/** 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);
+}
+
+/**
+ * A size a person reads, in the reader's locale. The unit stops at gigabytes
+ * because the object limit is 25 MB and a workspace quota is counted in GB.
+ */
+export function byteLabel(value: number): string {
+	let size = value;
+	let unit = 0;
+	while (size >= 1024 && unit < BYTE_UNITS.length - 1) {
+		size /= 1024;
+		unit += 1;
+	}
+	return t('documents.unit.' + BYTE_UNITS[unit], {
+		value: new Intl.NumberFormat(activeLocale(), {
+			maximumFractionDigits: unit === 0 ? 0 : 1,
+		}).format(size),
+	});
+}
+
+export function scanLabel(scan: DocumentScan): string {
+	return t('documents.scan.' + scan);
+}
+
+export function scanTone(scan: DocumentScan): TagTone {
+	if (scan === 'clean') return 'success';
+	return scan === 'infected' ? 'danger' : 'warning';
+}
+
+/**
+ * Why this file cannot be uploaded, or empty when it can. The storage port
+ * applies the same ceiling to the bytes it receives; checking it here spends a
+ * comparison instead of the upload. A screen that could not read the limits
+ * offers the upload and lets the server answer.
+ */
+export function uploadRefusal(
+	bytes: number,
+	maxObjectBytes: number | null,
+): string {
+	if (maxObjectBytes === null || bytes <= maxObjectBytes) return '';
+	return t('documents.upload.form.tooLarge', {
+		limit: byteLabel(maxObjectBytes),
+	});
+}
+
+/**
+ * Why a row cannot be downloaded, or empty when it can. An infected object was
+ * deleted the moment the scan found it, and a deleted one is gone.
+ */
+export function downloadRefusal(record: DocumentAttachment): string {
+	if (record.scan === 'infected')
+		return t('documents.action.downloadRefusedInfected');
+	if (record.status === 'deleted')
+		return t('documents.action.downloadRefusedDeleted');
+	return '';
+}
+
+/** 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 download action says about this row. The label is the name of the
+ * action whatever the row 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 downloadAction(record: DocumentAttachment): ActionCopy {
+	const reason = downloadRefusal(record);
+	return {
+		label: t('documents.action.download'),
+		disabled: reason !== '',
+		reason,
+	};
+}
+
+/**
+ * What the table renders in place of its rows. A load that failed must never
+ * answer with the empty state: "no documents 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('documents.loadFailed.title'),
+		hint: t('documents.loadFailed.hint'),
+	};
+}

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

@@ -0,0 +1,117 @@
+import { cell, createStore } from 'segment-state';
+import type { DocumentAttachment } from '../domain/attachments.ts';
+import type { DocumentDeleteOutcome, DocumentScan } from '../domain/types.ts';
+
+/** `denied` is a 403 the shell could not hide; `error` is everything else. */
+export type ScreenStatus =
+	| 'idle'
+	| 'loading'
+	| 'submitting'
+	| 'denied'
+	| 'error';
+
+export function createDocumentsClientState() {
+	const store = createStore({
+		documents: cell<readonly DocumentAttachment[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		query: '',
+		/* The term the rows on screen were loaded with, so a typed one is known
+		   to be pending and a cleared one still asks the server for a listing. */
+		appliedQuery: '',
+		ownerModuleFilter: '',
+		scanFilter: cell<DocumentScan | ''>(''),
+		/* Owner modules seen on any page loaded so far: the filter's options
+		   cannot come from one page without disappearing as the reader walks. */
+		ownerModulesSeen: cell<readonly string[]>([]),
+		filtersOpen: false,
+		uploaderOpen: false,
+		/* Remounts the uploader so the native file input starts empty again. */
+		formSession: 0,
+		/* Null once the server stops handing one back: that is the last page. */
+		nextCursor: cell<string | null>(null),
+		confirmDeleteId: cell<string | null>(null),
+		/* Row ids checked in the table; the screen owns it, the table never
+		   clears it. */
+		selectedIds: cell<ReadonlySet<string>>(new Set()),
+		confirmDeleteMany: false,
+	});
+	return { store, state: store.state };
+}
+
+/**
+ * Whether the typed term still has to reach the server. The search is a query
+ * filter, so what is on screen is only right once a listing was loaded with
+ * exactly this term; whitespace alone is not a term.
+ */
+export function searchPending(query: string, applied: string): boolean {
+	return query.trim() !== applied;
+}
+
+/** Owner modules present in the loaded set, for the filter's option list. */
+export function ownerModules(
+	documents: readonly DocumentAttachment[],
+): readonly string[] {
+	return [...new Set(documents.map((document) => document.ownerModule))].sort();
+}
+
+/**
+ * The rows a screen holds after a page arrives. Appending keeps what the reader
+ * already walked; a new listing replaces it, so a changed filter can never mix
+ * two result sets.
+ */
+export function mergeDocumentPage(
+	held: readonly DocumentAttachment[],
+	page: readonly DocumentAttachment[],
+	append: boolean,
+): readonly DocumentAttachment[] {
+	return append ? [...held, ...page] : page;
+}
+
+/** The owner modules the filter offers once this page has been seen. */
+export function mergeOwnerModules(
+	seen: readonly string[],
+	page: readonly DocumentAttachment[],
+): readonly string[] {
+	return [...new Set([...seen, ...ownerModules(page)])].sort();
+}
+
+/**
+ * The selection once a page arrives. A new listing is a new set of rows, so
+ * nothing checked before it is still selected; an appended page keeps it.
+ */
+export function selectionAfterPage(
+	selected: ReadonlySet<string>,
+	append: boolean,
+): ReadonlySet<string> {
+	return append ? selected : new Set();
+}
+
+/** The selected rows a bulk delete may name: the stored ones on screen. */
+export function deletableIds(
+	documents: readonly DocumentAttachment[],
+	selected: ReadonlySet<string>,
+): readonly string[] {
+	return documents
+		.filter((record) => selected.has(record.id) && record.status === 'stored')
+		.map((record) => record.id);
+}
+
+/** How many ids each outcome covered, for the notice after a bulk delete. */
+export function deleteOutcomeCounts(
+	outcomes: readonly DocumentDeleteOutcome[],
+): {
+	readonly deleted: number;
+	readonly missing: number;
+	readonly refused: number;
+} {
+	let deleted = 0;
+	let missing = 0;
+	let refused = 0;
+	for (const entry of outcomes) {
+		if (entry.outcome === 'deleted') deleted += 1;
+		else if (entry.outcome === 'not-found') missing += 1;
+		else refused += 1;
+	}
+	return { deleted, missing, refused };
+}

package/modules/documents/src/domain/attachments.ts

@@ -0,0 +1,84 @@
+import type { DocumentScan, DocumentStatus } from './types.ts';
+
+/**
+ * The public cross-module surface. A module that owns a record resolves it with
+ * `context.capabilities.get<DocumentAttachments>(DOCUMENTS_ATTACHMENTS_CAPABILITY)`
+ * and reaches its own attachments by reference: its module id plus the record
+ * reference it chose. There is no attach call, because bytes only ever enter
+ * through `POST /api/documents/upload`, where the session, the CSRF proof, the
+ * workspace quota and the storage port's limits are applied; a capability that
+ * took bytes would be a second upload path with none of them.
+ */
+export const DOCUMENTS_ATTACHMENTS_CAPABILITY = 'documents.attachments.v1';
+
+/**
+ * One document as another module sees it. The storage key is documents.core's
+ * own bookkeeping and stays out: bytes are reached through `open` or a read
+ * URL, never by addressing the object store.
+ */
+export interface DocumentAttachment {
+	readonly id: string;
+	readonly ownerModule: string;
+	readonly recordRef: string;
+	readonly filename: string;
+	readonly contentType: string;
+	readonly bytes: number;
+	readonly checksum: string | null;
+	readonly scan: DocumentScan;
+	readonly status: DocumentStatus;
+	readonly uploaderAccountId: string;
+	readonly description: string | null;
+	readonly createdAt: number;
+}
+
+/**
+ * The bytes of one document as another module reads them. The storage key is
+ * absent here too: documents.core opens the object and hands over the stream,
+ * so a caller never addresses the store.
+ */
+export interface DocumentAttachmentBody {
+	readonly contentType: string;
+	readonly bytes: number;
+	readonly filename: string;
+	readonly body: ReadableStream<Uint8Array>;
+}
+
+export interface DocumentAttachments {
+	/**
+	 * Documents of one record, newest first. The tenant id comes from the
+	 * caller's principal; a caller naming another module's id sees that module's
+	 * attachments, so the reference pair is a scope, not an authorization.
+	 */
+	list(
+		tenantId: string,
+		ownerModule: string,
+		recordRef: string,
+	): Promise<readonly DocumentAttachment[]>;
+	/**
+	 * The decrypted body of one document of that reference, streamed from the
+	 * same storage access the read URL route serves. Null is every reference
+	 * that has no readable object: an unknown id, another module's or another
+	 * record's pair, another workspace's document, a deleted row, an infected
+	 * one, or a row whose object is gone. A caller that has to tell those apart
+	 * reads `list`, which carries the scan verdict and the status of each row.
+	 *
+	 * The stream is the caller's: nothing else reads it, cancels it or closes
+	 * it, and the whole object is held in memory while it is open.
+	 */
+	open(
+		tenantId: string,
+		ownerModule: string,
+		recordRef: string,
+		id: string,
+	): Promise<DocumentAttachmentBody | null>;
+	/**
+	 * Deletes the object, then marks the row deleted. Idempotent: false means the
+	 * reference matched no stored document, including a second delete of one.
+	 */
+	delete(
+		tenantId: string,
+		ownerModule: string,
+		recordRef: string,
+		id: string,
+	): Promise<boolean>;
+}