@flowdular/sdk 0.2.4 → 0.3.0

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

@@ -0,0 +1,203 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type {
+	ApprovalDecideOutcome,
+	ApprovalListDirection,
+	ApprovalListSort,
+	ApprovalRequest,
+	ApprovalRequestView,
+	ApprovalStatus,
+} 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 ApprovalsApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+
+	constructor(status: number, code: string, message: string) {
+		super(message);
+		this.name = 'ApprovalsApiError';
+		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 approvalsErrorMessage(
+	error: unknown,
+	fallbackKey: string,
+): string {
+	if (error instanceof ApprovalsApiError) {
+		const key = 'approvals.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 ApprovalsApiError(
+			response.status,
+			value.error?.code ?? 'REQUEST_FAILED',
+			value.error?.message ?? t('approvals.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),
+		}),
+	);
+}
+
+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 type ApprovalsListScope = 'mine' | 'decidable' | 'all';
+
+export interface ApprovalsFilter {
+	readonly scope?: ApprovalsListScope;
+	readonly status?: ApprovalStatus | '';
+	readonly sort?: ApprovalListSort;
+	readonly direction?: ApprovalListDirection;
+	readonly limit?: number;
+	/** The cursor that opens this page; none for the first page. */
+	readonly cursor?: string | null;
+}
+
+export interface ApprovalsPage {
+	readonly items: readonly ApprovalRequest[];
+	/** Null once the last page is on screen. */
+	readonly nextCursor: string | null;
+}
+
+export async function loadRequests(
+	filter: ApprovalsFilter = {},
+): Promise<ApprovalsPage> {
+	const page = await get<{
+		readonly items: readonly ApprovalRequest[];
+		readonly page: { readonly nextCursor: string | null };
+	}>(
+		'/api/approvals/requests' +
+			query({
+				scope: filter.scope ?? '',
+				status: filter.status ?? '',
+				sort: filter.sort ?? '',
+				direction: filter.direction ?? '',
+				limit: filter.limit === undefined ? '' : String(filter.limit),
+				cursor: filter.cursor ?? '',
+			}),
+	);
+	return { items: page.items, nextCursor: page.page.nextCursor };
+}
+
+export async function loadPendingCount(): Promise<number> {
+	return (
+		await get<{ readonly pending: number }>('/api/approvals/pending-count')
+	).pending;
+}
+
+export async function loadRequest(id: string): Promise<ApprovalRequestView> {
+	return get<ApprovalRequestView>(
+		'/api/approvals/requests/' + encodeURIComponent(id),
+	);
+}
+
+async function decision(
+	path: string,
+	id: string,
+	comment: string,
+	csrfToken: string,
+): Promise<ApprovalRequestView> {
+	return post<ApprovalRequestView>(
+		path,
+		comment === '' ? { id } : { id, comment },
+		csrfToken,
+	);
+}
+
+export async function approveRequest(
+	id: string,
+	comment: string,
+	csrfToken: string,
+): Promise<ApprovalRequestView> {
+	return decision('/api/approvals/requests/approve', id, comment, csrfToken);
+}
+
+export async function rejectRequest(
+	id: string,
+	comment: string,
+	csrfToken: string,
+): Promise<ApprovalRequestView> {
+	return decision('/api/approvals/requests/reject', id, comment, csrfToken);
+}
+
+export type BulkDecision = 'approve' | 'reject';
+
+export async function decideRequests(
+	ids: readonly string[],
+	decision: BulkDecision,
+	comment: string,
+	csrfToken: string,
+): Promise<readonly ApprovalDecideOutcome[]> {
+	return (
+		await post<{ readonly outcomes: readonly ApprovalDecideOutcome[] }>(
+			'/api/approvals/decide-many',
+			comment === '' ? { ids, decision } : { ids, decision, comment },
+			csrfToken,
+		)
+	).outcomes;
+}
+
+export async function cancelRequest(
+	id: string,
+	csrfToken: string,
+): Promise<ApprovalRequestView> {
+	return post<ApprovalRequestView>(
+		'/api/approvals/requests/cancel',
+		{ id },
+		csrfToken,
+	);
+}

package/modules/approvals/src/client/approvals.css

@@ -0,0 +1,51 @@
+/* Approvals module: composites specific to this module. Primitives (buttons,
+   fields, tags, cards) come from @flowdular/sdk/ui and are not restyled here. */
+
+.approvals-summary {
+	margin: 0;
+	color: var(--ink-2);
+	line-height: 1.5;
+}
+
+.approvals-facts {
+	display: grid;
+	grid-template-columns: minmax(9rem, auto) 1fr;
+	gap: 8px 16px;
+	margin: 0;
+}
+
+.approvals-facts dt {
+	font-size: var(--text-sm);
+	color: var(--ink-3);
+}
+
+.approvals-facts dd {
+	margin: 0;
+	overflow-wrap: anywhere;
+}
+
+.approvals-ledger__list {
+	display: grid;
+	gap: 8px;
+	padding: 0;
+	margin: 0;
+	list-style: none;
+}
+
+/* One decision per row: what was decided, by whom, when. The comment is its own
+   full-width line so a long one does not squeeze the three columns above it. */
+.approvals-ledger__list li {
+	display: grid;
+	grid-template-columns: auto 1fr auto;
+	gap: 8px;
+	align-items: baseline;
+	padding-block: 8px;
+	border-top: 1px solid var(--line);
+}
+
+.approvals-ledger__comment {
+	grid-column: 1 / -1;
+	margin: 0;
+	font-size: var(--text-sm);
+	color: var(--ink-3);
+}

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

@@ -0,0 +1,44 @@
+import { type ModuleClientContribution } from '@flowdular/sdk/client';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import { APPROVALS_PERMISSIONS } from '../acl/permissions.ts';
+import { ApprovalsView } from './ApprovalsView.tsrx';
+import {
+	APPROVALS_PENDING_WIDGET,
+	APPROVALS_VIEWS,
+	approvalsNavigation,
+} from './navigation.ts';
+import { PendingCountWidget } from './PendingCountWidget.tsrx';
+import './approvals.css';
+
+export interface ApprovalsClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+}
+
+export function createApprovalsClientContribution(
+	options: ApprovalsClientContributionOptions,
+): ModuleClientContribution {
+	return {
+		moduleId: 'approvals.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: approvalsNavigation,
+		views: [
+			{
+				id: APPROVALS_VIEWS.inbox,
+				render: () =>
+					<ApprovalsView
+						csrfToken={options.csrfToken}
+						canManage={options.scopes.includes(APPROVALS_PERMISSIONS.manage)}
+						canDecide={options.scopes.includes(APPROVALS_PERMISSIONS.decide)}
+					/>,
+			},
+		],
+		widgets: [
+			{
+				...APPROVALS_PENDING_WIDGET,
+				render: () => <PendingCountWidget />,
+			},
+		],
+	};
+}

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

@@ -0,0 +1,26 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createApprovalsClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export { createApprovalsClientContribution } from './contribution.tsrx';
+export type { ApprovalsClientContributionOptions } from './contribution.tsrx';
+export { ApprovalRequestDrawer } from './ApprovalRequestDrawer.tsrx';
+export { ApprovalsView } from './ApprovalsView.tsrx';
+export { PendingCountWidget } from './PendingCountWidget.tsrx';
+export {
+	APPROVALS_PENDING_WIDGET,
+	APPROVALS_VIEWS,
+	approvalsNavigation,
+} from './navigation.ts';
+
+/* Canonical entry used by the generated platform composition. */
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({
+		csrfToken: context.csrfToken,
+		scopes: context.scopes,
+	});
+}

package/modules/approvals/src/client/navigation.ts

@@ -0,0 +1,39 @@
+import type { NavigationContribution, WorkspaceSlot } from '@flowdular/sdk/client';
+import { t } from '@flowdular/sdk/client/i18n';
+import { APPROVALS_PERMISSIONS } from '../acl/permissions.ts';
+
+/** The view ids the contribution registers and every entry points at. */
+export const APPROVALS_VIEWS = {
+	inbox: 'approvals',
+} as const;
+
+/* Labels are read every render so a locale change reaches an entry the shell
+   built once. */
+export const approvalsNavigation: readonly NavigationContribution[] = [
+	{
+		id: 'approvals.navigation.inbox',
+		viewId: APPROVALS_VIEWS.inbox,
+		group: 'Workspace',
+		get label() {
+			return t('approvals.navigation.inbox');
+		},
+		glyph: 'check',
+		get description() {
+			return t('approvals.navigation.inboxDescription');
+		},
+		scope: APPROVALS_PERMISSIONS.read,
+		order: 25,
+	},
+];
+
+export const APPROVALS_PENDING_WIDGET: {
+	readonly id: string;
+	readonly slot: WorkspaceSlot;
+	readonly scope: string;
+	readonly order: number;
+} = {
+	id: 'approvals.dashboard.pending-count',
+	slot: 'dashboard.metrics',
+	scope: APPROVALS_PERMISSIONS.read,
+	order: 25,
+};

package/modules/approvals/src/client/pending-count.ts

@@ -0,0 +1,26 @@
+import { cell, createStore } from 'segment-state';
+import { loadPendingCount } from './api.ts';
+
+/* One count behind the dashboard tile and the Approvals screen. The screen
+   reports what it just decided, so the tile follows a real event instead of
+   polling for one. */
+const store = createStore({ pending: cell(0) });
+
+export const pendingCount = store.state.pending;
+
+export function clearPendingCount(): void {
+	store.set(store.state.pending, 0, 'approvals/pending-cleared');
+}
+
+export async function refreshPendingCount(): Promise<void> {
+	try {
+		store.set(
+			store.state.pending,
+			await loadPendingCount(),
+			'approvals/pending-loaded',
+		);
+	} catch {
+		/* The tile is an accessory. A failed count keeps the last one rather than
+		   raising an error across the whole workspace. */
+	}
+}

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

@@ -0,0 +1,52 @@
+import { activeLocale, t } from '@flowdular/sdk/client';
+import type {
+	ApprovalDecisionKind,
+	ApprovalRequirementRecord,
+	ApprovalStatus,
+} from '../domain/types.ts';
+
+export function statusLabel(status: ApprovalStatus): string {
+	return t('approvals.status.' + status);
+}
+
+export function statusTone(
+	status: ApprovalStatus,
+): 'info' | 'success' | 'danger' | 'neutral' {
+	if (status === 'pending') return 'info';
+	if (status === 'approved') return 'success';
+	if (status === 'rejected' || status === 'expired') return 'danger';
+	return 'neutral';
+}
+
+export function decisionLabel(decision: ApprovalDecisionKind): string {
+	return t('approvals.decision.' + decision);
+}
+
+/** Epoch milliseconds as the reader's locale writes them; empty stays empty. */
+export function timestampLabel(value: number | null): string {
+	if (value === null) return t('approvals.common.notYet');
+	return new Intl.DateTimeFormat(activeLocale(), {
+		dateStyle: 'medium',
+		timeStyle: 'short',
+	}).format(new Date(value));
+}
+
+/** The requirement as one line: who has to answer, how many of them, how long. */
+export function requirementLabel(
+	requirement: ApprovalRequirementRecord,
+): string {
+	const who =
+		requirement.roleKey !== null && requirement.scope !== null
+			? t('approvals.requirement.roleAndScope', {
+					role: requirement.roleKey,
+					scope: requirement.scope,
+				})
+			: requirement.roleKey !== null
+				? t('approvals.requirement.role', { role: requirement.roleKey })
+				: t('approvals.requirement.scope', { scope: requirement.scope ?? '' });
+	return t('approvals.requirement.summary', {
+		who,
+		decisions: requirement.decisions,
+		days: requirement.expiresInDays,
+	});
+}

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

@@ -0,0 +1,141 @@
+import { cell, createStore } from 'segment-state';
+import type {
+	ApprovalDecideOutcome,
+	ApprovalListDirection,
+	ApprovalRequest,
+	ApprovalRequestView,
+	ApprovalStatus,
+} from '../domain/types.ts';
+import type { ApprovalsListScope, BulkDecision } from './api.ts';
+
+/** `denied` is a 403 the shell could not hide; `error` is everything else. */
+export type ScreenStatus =
+	| 'idle'
+	| 'loading'
+	| 'submitting'
+	| 'denied'
+	| 'error';
+
+/**
+ * The cursors of the pages the member has walked: `stack[pageIndex]` is the
+ * cursor that opened that page, page 0 has none, and going back reuses the
+ * stored cursor rather than asking the server for a position it never named.
+ */
+export type CursorStack = readonly (string | null)[];
+
+export const FIRST_PAGE: CursorStack = [null];
+
+export function pageCursor(
+	stack: CursorStack,
+	pageIndex: number,
+): string | null {
+	return stack[pageIndex] ?? null;
+}
+
+/** Whether the stack knows how to open this page. */
+export function canOpenPage(stack: CursorStack, pageIndex: number): boolean {
+	return pageIndex >= 0 && pageIndex < stack.length;
+}
+
+/**
+ * The stack after `pageIndex` loaded and answered `nextCursor`. Pages past the
+ * one that loaded are forgotten: the set may have moved under them.
+ */
+export function recordNextCursor(
+	stack: CursorStack,
+	pageIndex: number,
+	nextCursor: string | null,
+): CursorStack {
+	const kept = stack.slice(0, pageIndex + 1);
+	return nextCursor === null ? kept : [...kept, nextCursor];
+}
+
+export const DEFAULT_PAGE_SIZE = 25;
+
+export function createApprovalsClientState() {
+	const store = createStore({
+		requests: cell<readonly ApprovalRequest[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		/* The inbox opens on what the member can act on, not on everything. */
+		scope: cell<ApprovalsListScope>('decidable'),
+		statusFilter: cell<ApprovalStatus | ''>(''),
+		/* Newest first; the one sort key the list offers is createdAt. */
+		direction: cell<ApprovalListDirection>('desc'),
+		pageIndex: 0,
+		pageSize: DEFAULT_PAGE_SIZE,
+		cursors: cell<CursorStack>(FIRST_PAGE),
+		filtersOpen: false,
+		selectedId: cell<string | null>(null),
+		selected: cell<ApprovalRequestView | null>(null),
+		comment: '',
+		/* Row ids checked in the table; the screen owns it and empties it with
+		   every new listing, the table never clears it. */
+		selectedIds: cell<ReadonlySet<string>>(new Set()),
+		confirmDecision: cell<BulkDecision | null>(null),
+		bulkComment: '',
+	});
+	return { store, state: store.state };
+}
+
+/** The selected rows a bulk decision may name: the pending ones on screen. */
+export function decidableIds(
+	requests: readonly ApprovalRequest[],
+	selected: ReadonlySet<string>,
+): readonly string[] {
+	return requests
+		.filter(
+			(request) => selected.has(request.id) && request.status === 'pending',
+		)
+		.map((request) => request.id);
+}
+
+/** How many ids each outcome covered, for the notice after a bulk decision. */
+export function decideOutcomeCounts(
+	outcomes: readonly ApprovalDecideOutcome[],
+): {
+	readonly decided: number;
+	readonly missing: number;
+	readonly refused: number;
+} {
+	let decided = 0;
+	let missing = 0;
+	let refused = 0;
+	for (const entry of outcomes) {
+		if (entry.outcome === 'decided') decided += 1;
+		else if (entry.outcome === 'not-found') missing += 1;
+		else refused += 1;
+	}
+	return { decided, missing, refused };
+}
+
+/** Which of the five states the inbox renders. */
+export type ApprovalsScreen = 'denied' | 'error' | 'table';
+
+export interface ApprovalsListing {
+	readonly visible: readonly ApprovalRequest[];
+	readonly filtered: boolean;
+	readonly activeFilters: number;
+	readonly screen: ApprovalsScreen;
+}
+
+/* The server already filtered by scope and status; this only reports what the
+   table has to say about an empty result. A load that failed answers with the
+   error state: the table would report an empty inbox instead, which is the one
+   answer a failed load must never give. */
+export function approvalsListing(
+	requests: readonly ApprovalRequest[],
+	scope: ApprovalsListScope,
+	statusFilter: ApprovalStatus | '',
+	status: ScreenStatus = 'idle',
+): ApprovalsListing {
+	const activeFilters =
+		(scope === 'decidable' ? 0 : 1) + (statusFilter === '' ? 0 : 1);
+	return {
+		visible: requests,
+		filtered: activeFilters > 0,
+		activeFilters,
+		screen:
+			status === 'denied' ? 'denied' : status === 'error' ? 'error' : 'table',
+	};
+}

package/modules/approvals/src/domain/capability.ts

@@ -0,0 +1,95 @@
+import type { ApprovalRequirement } from '@flowdular/sdk/kernel';
+import type { ApprovalRequest, ApprovalStatus } from './types.ts';
+
+/**
+ * The public cross-module surface. A subject module resolves it through
+ * `context.capabilities.get<ApprovalsRequests>(APPROVALS_REQUESTS_CAPABILITY)`
+ * and continues without an approval step when it is absent.
+ */
+export const APPROVALS_REQUESTS_CAPABILITY = 'approvals.requests.v1';
+
+export interface OpenApprovalInput {
+	readonly tenantId: string;
+	/** The module that owns the record, for example `workflows.core`. */
+	readonly subjectModule: string;
+	/** Stable reference to that module's record, for example a run and node id. */
+	readonly subjectRef: string;
+	/** The permission the denied action needed. */
+	readonly permission: string;
+	/** The domain operation, when one permission covers several. */
+	readonly action: string;
+	readonly title: string;
+	readonly summary?: string;
+	readonly requesterAccountId: string;
+	readonly requirement: ApprovalRequirement;
+	/**
+	 * Run once when the request reaches a terminal state, outside the deciding
+	 * transaction. It is in-process only: a restart loses it, so a subject
+	 * module that must not miss an outcome reads the request back as well.
+	 * A callback that throws is logged and never changes the recorded decision.
+	 */
+	readonly onResolved?: (request: ApprovalRequest) => Promise<void>;
+}
+
+export interface ApprovalRequestFilter {
+	readonly status?: ApprovalStatus | undefined;
+	readonly subjectModule?: string | undefined;
+	readonly subjectRef?: string | undefined;
+	/** Requests this account opened. */
+	readonly requesterAccountId?: string | undefined;
+	/** Requests whose eligibility snapshot names this account. */
+	readonly decidableBy?: string | undefined;
+	readonly limit?: number | undefined;
+}
+
+export interface ApprovalsRequests {
+	/**
+	 * Idempotent on (tenantId, subjectModule, subjectRef) while a request for
+	 * that subject is pending: a repeat returns the open request and registers
+	 * the new callback against it rather than asking the same question twice.
+	 */
+	open(input: OpenApprovalInput): Promise<ApprovalRequest>;
+	get(tenantId: string, id: string): Promise<ApprovalRequest | null>;
+	/**
+	 * The first `limit` matches, newest first; two requests opened at the same
+	 * millisecond come in descending id order.
+	 */
+	list(
+		tenantId: string,
+		filter: ApprovalRequestFilter,
+	): Promise<readonly ApprovalRequest[]>;
+	/**
+	 * Cancels a pending request opened by `actorAccountId`. A member cancelling
+	 * somebody else's request goes through the endpoint, which is where
+	 * `approvals.requests.manage` is checked.
+	 */
+	cancel(
+		tenantId: string,
+		id: string,
+		actorAccountId: string,
+	): Promise<ApprovalRequest>;
+}
+
+/** Longest values the capability accepts; over any of them is a rejection. */
+export const APPROVAL_LIMITS = {
+	subjectModule: 64,
+	subjectRef: 200,
+	permission: 96,
+	action: 64,
+	title: 200,
+	summary: 2_000,
+	comment: 2_000,
+	accountId: 128,
+	roleKey: 64,
+	scope: 96,
+	/** Deciders held in one eligibility snapshot. */
+	eligible: 200,
+	/** Approvals one requirement may ask for. */
+	decisions: 16,
+	expiryDays: 90,
+	listLimit: 200,
+	/** Requests one bulk decision may name. */
+	decideMany: 100,
+	/** Pending callbacks one process holds before the oldest is dropped. */
+	callbacks: 4_096,
+} as const;