@flowdular/sdk 0.2.3 → 0.3.0

package/modules/notifications/src/cli/commands.json

@@ -0,0 +1,17 @@
+{
+	"protocolVersion": 1,
+	"moduleId": "notifications.core",
+	"commands": [
+		{
+			"path": ["notifications", "secrets-rotate"],
+			"capability": {
+				"id": "notifications.secrets.rotate",
+				"version": 1,
+				"summary": "Re-seal stored webhook signing secrets with the current encryption key.",
+				"risk": "process",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": true
+			}
+		}
+	]
+}

package/modules/notifications/src/cli/index.ts

@@ -0,0 +1,126 @@
+import {
+	defineCliExtension,
+	type CliExtensionContext,
+} from '@flowdular/sdk/cli-protocol';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+	runDatabaseMigrations,
+	type DatabaseAdapterLease,
+} from '@flowdular/sdk/database';
+import { databaseMigrations } from '../services/migration.ts';
+import { rotateWebhookSecrets } from '../services/secret-rotation.ts';
+import { secretVaultFromEnvironment } from '../services/secret-vault.ts';
+
+const rotateCapability = {
+	id: 'notifications.secrets.rotate',
+	version: 1,
+	summary:
+		'Re-seal stored webhook signing secrets with the current encryption key.',
+	risk: 'process' as const,
+	requiresApprovedSpec: false,
+	supportsDryRun: true,
+};
+
+interface OpenDatabase {
+	readonly leases: readonly DatabaseAdapterLease[];
+	readonly runtime: DatabaseAdapterLease;
+	readonly background: DatabaseAdapterLease;
+}
+
+/* The operator commands read the same deployment database the platform does;
+   there is no module-owned file to open. The runner owns the provider and a
+   module owns no driver, so it arrives on the context.
+
+   A run that applies nothing applies no schema either: it verifies the ledger
+   and stops, so a dry run can never be what creates this module's tables. */
+async function open(context: CliExtensionContext): Promise<OpenDatabase> {
+	const databases = context.databases;
+	if (!databases) {
+		throw new Error(
+			'notifications.core CLI commands read the deployment database, and this workspace has none configured.',
+		);
+	}
+	const requirements = {
+		dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+		capabilities: [DATABASE_CAPABILITY_IDS.TRANSACTIONS],
+	};
+	const migration = await databases.acquire({
+		namespace: 'notifications.core',
+		purpose: 'migration',
+		requirements,
+	});
+	const state = await runDatabaseMigrations(
+		migration.database,
+		'notifications.core',
+		databaseMigrations,
+		{ dryRun: !context.apply },
+	);
+	if (!context.apply && state.some((entry) => entry.action === 'applied')) {
+		await migration.release();
+		throw new Error(
+			'notifications.core has no schema in this deployment yet. Start the platform, or run the command with --apply, to create it.',
+		);
+	}
+	const runtime = await databases.acquire({
+		namespace: 'notifications.core',
+		purpose: 'runtime',
+		requirements,
+	});
+	/* The inventory counts rows across the whole deployment, which only the
+	   cross-tenant read-only role may do. */
+	const background = await databases.acquire({
+		namespace: 'notifications.core',
+		purpose: 'background',
+		requirements,
+	});
+	return { leases: [migration, runtime, background], runtime, background };
+}
+
+/* The provider belongs to the runner; only the leases this command took are
+   released here. */
+async function close(open: OpenDatabase): Promise<void> {
+	for (const lease of open.leases) await lease.release();
+}
+
+export const cliExtension = defineCliExtension({
+	protocolVersion: 1,
+	moduleId: 'notifications.core',
+	commands: [
+		{
+			path: ['notifications', 'secrets-rotate'],
+			capability: rotateCapability,
+			execute: async (context) => {
+				/* The report names key ids and row counts only; a secret never
+				   reaches the command output. */
+				const vault = secretVaultFromEnvironment(
+					process.env,
+					context.workspaceRoot,
+				);
+				const opened = await open(context);
+				try {
+					const report = await rotateWebhookSecrets({
+						runtime: opened.runtime.database,
+						background: opened.background.database,
+						vault,
+						apply: context.apply,
+					});
+					return {
+						data: { moduleId: 'notifications.core', ...report },
+						evidence: ['modules/notifications/spec/module.yaml', 'docs/cli.md'],
+						warnings:
+							report.skipped > 0
+								? [
+										`${report.skipped} rows were rewritten by the application while this ran and keep their own envelope. Run the command again.`,
+									]
+								: [],
+					};
+				} finally {
+					await close(opened);
+				}
+			},
+		},
+	],
+});
+
+export default cliExtension;

package/modules/notifications/src/client/DeliveriesView.tsrx

@@ -0,0 +1,483 @@
+import { useEffect, useMemo } from 'octane';
+import {
+	Alert,
+	Button,
+	ConfirmDialog,
+	EmptyState,
+	Filters,
+	Icon,
+	PageHeader,
+	Pagination,
+	SearchField,
+	Select,
+	TableCard,
+	Tag,
+	ToastHost,
+	toasts,
+	type TableAction,
+	type TableColumn,
+	type TableSort,
+} from '@flowdular/sdk/ui';
+import { t } from '@flowdular/sdk/client';
+import { useValue } from 'segment-state';
+import {
+	DELIVERY_STATUSES,
+	type DeliveryAttempt,
+	type DeliveryStatus,
+} from '../domain/types.ts';
+import {
+	LIST_PAGE_MAX,
+	loadDeliveries,
+	loadWebhooks,
+	NotificationsApiError,
+	notificationsErrorMessage,
+	replayDelivery,
+} from './api.ts';
+import {
+	deliveryCompletedLabel,
+	deliveryStatusLabel,
+	deliveryStatusTone,
+	errorClassLabel,
+	kindLabel,
+	timestampLabel,
+} from './presentation.ts';
+import {
+	createDeliveriesClientState,
+	FIRST_PAGE,
+	pageCursor,
+	pageLoaded,
+	searchPending,
+	subscriptionNames,
+	subscriptionOptions,
+	type CursorStack,
+	type SortDirection,
+} from './state.ts';
+
+export interface DeliveriesViewProps {
+	readonly csrfToken: string;
+	/** Names come from the webhooks list; without the scope the id is shown. */
+	readonly canReadWebhooks: boolean;
+}
+
+const PAGE_SIZES = [10, 25, 50, 100];
+const SEARCH_DEBOUNCE_MS = 300;
+
+/** One page request: the filters, the order, the page and the cursors that reach it. */
+interface DeliveriesRequest {
+	readonly status: DeliveryStatus | '';
+	readonly subscriptionId: string;
+	readonly search: string;
+	readonly direction: SortDirection;
+	readonly pageIndex: number;
+	readonly pageSize: number;
+	readonly pages: CursorStack;
+}
+
+/* The ledger carries nine values per attempt, and nine columns beside the
+   160 px action column leave none of them a readable share of a 1140 px row.
+   The two timestamps share one cell and so do the two halves of the outcome,
+   which buys every header and the longest status tag the width it needs. */
+function columns(
+	names: ReadonlyMap<string, string>,
+): readonly TableColumn<DeliveryAttempt>[] {
+	return [
+		{
+			key: 'subscription',
+			header: t('notifications.deliveries.column.subscription'),
+			width: '14%',
+			cell: (delivery) => {
+				/* An e-mail attempt is addressed to a member, not to a subscription,
+   so the column names the channel rather than an empty cell. */
+				if (delivery.channel === 'email') {
+					return t('notifications.deliveries.channel.email');
+				}
+				const id = delivery.subscriptionId ?? '';
+				return names.get(id) ?? <span class="ui-mono">{id}</span>;
+			},
+		},
+		{
+			key: 'kind',
+			header: t('notifications.deliveries.column.kind'),
+			width: '11%',
+			cell: (delivery) => kindLabel(delivery.kind),
+		},
+		{
+			key: 'sourceRef',
+			header: t('notifications.deliveries.column.sourceRef'),
+			width: '12%',
+			cell: (delivery) => <span class="ui-cell">
+				<span
+					class="ui-mono notifications-truncate"
+					title={delivery.sourceRef}
+				>{delivery.sourceRef}</span>
+				<small class="ui-cell__muted">{delivery.sourceModule}</small>
+			</span>,
+		},
+		{
+			key: 'attemptNumber',
+			header: t('notifications.deliveries.column.attempt'),
+			width: '10%',
+			numeric: true,
+			cell: (delivery) => delivery.attemptNumber,
+		},
+		{
+			key: 'status',
+			header: t('notifications.deliveries.column.status'),
+			width: '12%',
+			cell: (delivery) =>
+				<Tag
+					tone={deliveryStatusTone(delivery.status)}
+					dot
+				>{deliveryStatusLabel(delivery.status)}</Tag>,
+		},
+		{
+			key: 'scheduledFor',
+			header: t('notifications.deliveries.column.timing'),
+			width: '15%',
+			value: (delivery) => delivery.scheduledFor,
+			cell: (delivery) => <span class="ui-cell">
+				<b>{timestampLabel(delivery.scheduledFor)}</b>
+				<small class="ui-cell__muted">{deliveryCompletedLabel(
+					delivery.completedAt,
+				)}</small>
+			</span>,
+		},
+		{
+			key: 'outcome',
+			header: t('notifications.deliveries.column.outcome'),
+			width: '11%',
+			cell: (delivery) => {
+				const failure = errorClassLabel(delivery.errorClass);
+				if (delivery.responseStatus === null) return failure;
+				return <span class="ui-cell">
+					<b>{delivery.responseStatus}</b>
+					{failure === ''
+						? ''
+						: <small class="ui-cell__muted">{failure}</small>}
+				</span>;
+			},
+		},
+	];
+}
+
+export function DeliveriesView(props: DeliveriesViewProps) @{
+	const client = useMemo(() => createDeliveriesClientState(), []);
+	/* Requests answer out of order; only the latest one may write the screen. */
+	const requests = useMemo(() => ({ sequence: 0 }), []);
+	const [deliveries] = useValue(client.state.deliveries);
+	const [subscriptions] = useValue(client.state.subscriptions);
+	const [status, setStatus] = useValue(client.state.status);
+	const [error, setError] = useValue(client.state.error);
+	const [query, setQuery] = useValue(client.state.query);
+	const [appliedQuery] = useValue(client.state.appliedQuery);
+	const [statusFilter] = useValue(client.state.statusFilter);
+	const [subscriptionFilter] = useValue(client.state.subscriptionFilter);
+	const [direction] = useValue(client.state.direction);
+	const [pageIndex] = useValue(client.state.pageIndex);
+	const [pageSize] = useValue(client.state.pageSize);
+	const [pages] = useValue(client.state.pages);
+	const [filtersOpen, setFiltersOpen] = useValue(client.state.filtersOpen);
+	const [replayId, setReplayId] = useValue(client.state.replayId);
+	const names = subscriptionNames(subscriptions);
+	const filterCount =
+		(statusFilter === '' ? 0 : 1) + (subscriptionFilter === '' ? 0 : 1);
+	const filtered = filterCount > 0 || appliedQuery !== '';
+	const filterOptions = subscriptionOptions(subscriptions, deliveries);
+	const sorting: readonly TableSort[] = [
+		{ key: 'scheduledFor', desc: direction === 'desc' },
+	];
+	const current: DeliveriesRequest = {
+		status: statusFilter,
+		subscriptionId: subscriptionFilter,
+		search: appliedQuery,
+		direction,
+		pageIndex,
+		pageSize,
+		pages,
+	};
+
+	/* The server sorts, narrows and cuts the page: every request names its
+   filters, its order, its page and the cursor that opens it, and the
+   response records the cursor of the page after it. */
+	const load = async (request: DeliveriesRequest) => {
+		const cursor = pageCursor(request.pages, request.pageIndex);
+		if (cursor === null) return;
+		const sequence = requests.sequence += 1;
+		client.store.act((transaction) => {
+			transaction.set(client.state.statusFilter, request.status);
+			transaction.set(client.state.subscriptionFilter, request.subscriptionId);
+			transaction.set(client.state.appliedQuery, request.search);
+			transaction.set(client.state.direction, request.direction);
+			transaction.set(client.state.pageIndex, request.pageIndex);
+			transaction.set(client.state.pageSize, request.pageSize);
+			transaction.set(client.state.pages, request.pages);
+			transaction.set(client.state.status, 'loading');
+			transaction.set(client.state.error, '');
+		}, 'notifications/deliveries-request');
+		try {
+			const page = await loadDeliveries({
+				status: request.status,
+				subscriptionId: request.subscriptionId,
+				search: request.search,
+				direction: request.direction,
+				limit: request.pageSize,
+				cursor,
+			});
+			if (sequence !== requests.sequence) return;
+			client.store.act((transaction) => {
+				transaction.set(client.state.deliveries, page.items);
+				transaction.set(
+					client.state.pages,
+					pageLoaded(request.pages, request.pageIndex, page.page.nextCursor),
+				);
+				transaction.set(client.state.status, 'idle');
+			}, 'notifications/deliveries-loaded');
+		} catch (loadError) {
+			if (sequence !== requests.sequence) return;
+			setError(
+				notificationsErrorMessage(
+					loadError,
+					'notifications.deliveries.error.load',
+				),
+			);
+			setStatus(
+				loadError instanceof NotificationsApiError && loadError.status === 403
+					? 'denied'
+					: 'error',
+			);
+		}
+	};
+
+	/* A filter, a term or an order starts a new listing from its first page. */
+	const restart = (change: Partial<DeliveriesRequest>) => load({
+		...current,
+		...change,
+		pageIndex: 0,
+		pages: FIRST_PAGE,
+	});
+
+	/* The names behind the subscription column and filter: the largest page
+   the list serves, which is every subscription of any workspace this screen
+   is built for. */
+	const loadSubscriptionNames = async () => {
+		try {
+			client.store.set(
+				client.state.subscriptions,
+				(await loadWebhooks({ limit: LIST_PAGE_MAX })).items,
+				'notifications/deliveries-subscriptions',
+			);
+		} catch {
+			/* Names are a convenience: the ledger reads fine with the ids alone, so
+   a refused or failed subscription list never blocks this screen. */
+		}
+	};
+
+	useEffect(() => {
+		void load(current);
+		if (props.canReadWebhooks) void loadSubscriptionNames();
+	}, []);
+
+	/* The term is the server's filter, so typing it starts a new listing rather
+   than narrowing the page on screen. One listing per pause in the typing, and
+   none at all while the rows already answer this term. */
+	useEffect(() => {
+		if (!searchPending(query, appliedQuery)) return;
+		const timer = setTimeout(
+			() => void restart({ search: query.trim() }),
+			SEARCH_DEBOUNCE_MS,
+		);
+		return () => clearTimeout(timer);
+	}, [query]);
+
+	const replay = async () => {
+		const id = replayId;
+		if (id === null) return;
+		setReplayId(null);
+		setStatus('submitting');
+		setError('');
+		try {
+			await replayDelivery(id, props.csrfToken);
+			await load(current);
+			toasts.success(t('notifications.deliveries.notice.replayed'));
+		} catch (replayError) {
+			setError(
+				notificationsErrorMessage(
+					replayError,
+					'notifications.deliveries.error.replay',
+				),
+			);
+			setStatus('idle');
+		}
+	};
+
+	const rowActions = (delivery: DeliveryAttempt): readonly TableAction[] =>
+		delivery.status === 'dead-letter'
+			? [
+					{
+						id: 'replay',
+						label: t('notifications.deliveries.action.replay'),
+						icon: 'refresh',
+						onSelect: () => setReplayId(delivery.id),
+					},
+				]
+			: [];
+
+	<div class="ui-view">
+		<PageHeader
+			eyebrow={t('notifications.common.administration')}
+			title={t('notifications.deliveries.title')}
+			description={t('notifications.deliveries.description')}
+		>
+			<Button
+				size="sm"
+				disabled={status === 'denied'}
+				onClick={() => void load(current)}
+			>
+				<Icon name="refresh" size={14} />
+				{status === 'loading'
+					? t('notifications.common.refreshing')
+					: t('notifications.common.refresh')}
+			</Button>
+		</PageHeader>
+		@if (status === 'denied') {
+			<section class="ui-card">
+				<EmptyState
+					icon="shield"
+					title={t('notifications.common.accessDenied')}
+				>{t('notifications.deliveries.denied')}</EmptyState>
+			</section>
+		} @else {
+			<>
+				@if (error) {
+					<Alert>{error}</Alert>
+				}
+				<TableCard
+					title={t('notifications.deliveries.table.title')}
+					count={pages.hasMore
+						? t('notifications.deliveries.table.countMore', {
+								count: deliveries.length,
+							})
+						: t('notifications.deliveries.table.count', {
+								count: deliveries.length,
+							})}
+					search={<SearchField
+						value={query}
+						placeholder={t('notifications.deliveries.search.placeholder')}
+						label={t('notifications.deliveries.search.label')}
+						onInput={setQuery}
+					/>}
+					filters={<Filters
+						open={filtersOpen}
+						onToggle={() => setFiltersOpen(!filtersOpen)}
+						activeCount={filterCount}
+						label={t('notifications.common.filters')}
+					>
+						<Select
+							id="notifications-deliveries-status"
+							label={t('notifications.deliveries.filter.status')}
+							value={statusFilter}
+							options={[
+								{
+									value: '',
+									label: t('notifications.deliveries.filter.allStatuses'),
+								},
+								...DELIVERY_STATUSES.map(
+									(entry) => ({
+										value: entry,
+										label: deliveryStatusLabel(entry),
+									}),
+								),
+							]}
+							onChange={(value) => void restart({
+								status: value as DeliveryStatus | '',
+							})}
+						/>
+						<Select
+							id="notifications-deliveries-subscription"
+							label={t('notifications.deliveries.filter.subscription')}
+							value={subscriptionFilter}
+							options={[
+								{
+									value: '',
+									label: t('notifications.deliveries.filter.allSubscriptions'),
+								},
+								...filterOptions,
+							]}
+							onChange={(value) => void restart({ subscriptionId: value })}
+						/>
+					</Filters>}
+					caption={t('notifications.deliveries.table.caption')}
+					columns={columns(names)}
+					rows={deliveries}
+					rowKey={(delivery) => delivery.id}
+					mode="server"
+					sorting
+					sortingState={sorting}
+					onSortingChange={(sorts) => void restart({
+						direction: sorts[0]?.desc === true ? 'desc' : 'asc',
+					})}
+					pagination={{
+						pageIndex,
+						pageSize,
+						hasMore: pages.hasMore,
+						onPageChange: (index) => void load({
+							...current,
+							pageIndex: index,
+						}),
+					}}
+					after={<Pagination
+						pageIndex={pageIndex}
+						pageSize={pageSize}
+						hasMore={pages.hasMore}
+						pageSizes={PAGE_SIZES}
+						onPageChange={(index) => void load({
+							...current,
+							pageIndex: index,
+						})}
+						onPageSizeChange={(size) => void restart({ pageSize: size })}
+						label={t('notifications.pagination.label')}
+						previousLabel={t('notifications.pagination.previous')}
+						nextLabel={t('notifications.pagination.next')}
+						pageSizeLabel={t('notifications.pagination.size')}
+						summary={(page) => t('notifications.pagination.keysetSummary', {
+							page: page.pageIndex + 1,
+							from: page.from,
+						})}
+					/>}
+					status={status === 'loading' && deliveries.length === 0
+						? 'loading'
+						: 'idle'}
+					loadingLabel={t('notifications.deliveries.table.loading')}
+					filtered={filtered}
+					empty={{
+						icon: 'activity',
+						title: t('notifications.deliveries.empty.title'),
+						hint: t('notifications.deliveries.empty.hint'),
+					}}
+					emptyFiltered={{
+						icon: 'search',
+						title: t('notifications.deliveries.emptyFiltered.title'),
+						hint: t('notifications.deliveries.emptyFiltered.hint'),
+					}}
+					actions={rowActions}
+					actionsLabel={t('notifications.common.actions')}
+					noteIcon="shield"
+					note={t('notifications.deliveries.note')}
+				/>
+			</>
+		}
+		<ConfirmDialog
+			open={replayId !== null}
+			title={t('notifications.deliveries.replay.title')}
+			confirmLabel={t('notifications.deliveries.action.replay')}
+			tone="primary"
+			busy={status === 'submitting'}
+			onConfirm={() => void replay()}
+			onCancel={() => setReplayId(null)}
+		>{t('notifications.deliveries.replay.description')}</ConfirmDialog>
+		<ToastHost
+			label={t('notifications.common.messages')}
+			closeLabel={t('notifications.common.close')}
+		/>
+	</div>
+}

package/modules/notifications/src/client/FactList.tsrx

@@ -0,0 +1,24 @@
+import type { OctaneNode } from 'octane';
+
+export interface Fact {
+	readonly key: string;
+	readonly label: string;
+	readonly value: OctaneNode;
+}
+
+export interface FactListProps {
+	readonly facts: readonly Fact[];
+}
+
+/* The read side of a record inside a drawer: label over value, two per row.
+   A promotion candidate for @flowdular/sdk/ui once a second module needs it. */
+export function FactList(props: FactListProps) @{
+	<dl class="notifications-facts">
+		@for (const fact of props.facts; key fact.key) {
+			<div class="notifications-facts__item">
+				<dt class="ui-label">{fact.label}</dt>
+				<dd>{fact.value}</dd>
+			</div>
+		}
+	</dl>
+}