@flowdular/sdk 0.2.3 → 0.3.0

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

@@ -0,0 +1,65 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type { WorkspaceReportPage } 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 ReportsApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+
+	constructor(status: number, code: string, message: string) {
+		super(message);
+		this.name = 'ReportsApiError';
+		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 reportsErrorMessage(
+	error: unknown,
+	fallbackKey: string,
+): string {
+	if (error instanceof ReportsApiError) {
+		const key = 'reports.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);
+}
+
+/** A read, so it carries no CSRF token and no body. */
+export async function loadReport(range?: {
+	readonly from?: string;
+	readonly to?: string;
+}): Promise<WorkspaceReportPage> {
+	const parameters = new URLSearchParams();
+	if (range?.from) parameters.set('from', range.from);
+	if (range?.to) parameters.set('to', range.to);
+	const query = parameters.toString();
+	const response = await fetch('/api/reports' + (query ? '?' + query : ''), {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	const value = (await response.json()) as WorkspaceReportPage & ErrorEnvelope;
+	if (!response.ok) {
+		throw new ReportsApiError(
+			response.status,
+			value.error?.code ?? 'REQUEST_FAILED',
+			value.error?.message ?? t('reports.error.request'),
+		);
+	}
+	return value;
+}

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

@@ -0,0 +1,36 @@
+import { type ModuleClientContribution } from '@flowdular/sdk/client';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import {
+	REPORTS_SUMMARY_WIDGET,
+	REPORTS_VIEWS,
+	reportsNavigation,
+} from './navigation.ts';
+import { ReportsSummaryWidget } from './ReportsSummaryWidget.tsrx';
+import { ReportsView } from './ReportsView.tsrx';
+
+export interface ReportsClientContributionOptions {
+	readonly csrfToken: string;
+}
+
+export function createReportsClientContribution(
+	options: ReportsClientContributionOptions,
+): ModuleClientContribution {
+	return {
+		moduleId: 'reports.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: reportsNavigation,
+		views: [
+			{
+				id: REPORTS_VIEWS.reports,
+				render: () => <ReportsView csrfToken={options.csrfToken} />,
+			},
+		],
+		widgets: [
+			{
+				...REPORTS_SUMMARY_WIDGET,
+				render: () => <ReportsSummaryWidget />,
+			},
+		],
+	};
+}

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

@@ -0,0 +1,18 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createReportsClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export { createReportsClientContribution } from './contribution.tsrx';
+export type { ReportsClientContributionOptions } from './contribution.tsrx';
+export { ReportsView } from './ReportsView.tsrx';
+export { ReportsSummaryWidget } from './ReportsSummaryWidget.tsrx';
+export { REPORTS_VIEWS } from './navigation.ts';
+
+/* Canonical entry used by the generated platform composition. */
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({ csrfToken: context.csrfToken });
+}

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

@@ -0,0 +1,39 @@
+import type { NavigationContribution, WorkspaceSlot } from '@flowdular/sdk/client';
+import { t } from '@flowdular/sdk/client/i18n';
+import { REPORTS_PERMISSIONS } from '../acl/permissions.ts';
+
+/** The view ids the contribution registers and every entry points at. */
+export const REPORTS_VIEWS = {
+	reports: 'reports',
+} as const;
+
+/* Labels are read every render so a locale change reaches an entry the shell
+   built once. */
+export const reportsNavigation: readonly NavigationContribution[] = [
+	{
+		id: 'reports.navigation',
+		viewId: REPORTS_VIEWS.reports,
+		group: 'Administration',
+		get label() {
+			return t('reports.navigation.label');
+		},
+		glyph: 'activity',
+		get description() {
+			return t('reports.navigation.description');
+		},
+		scope: REPORTS_PERMISSIONS.read,
+		order: 70,
+	},
+];
+
+export const REPORTS_SUMMARY_WIDGET: {
+	readonly id: string;
+	readonly slot: WorkspaceSlot;
+	readonly scope: string;
+	readonly order: number;
+} = {
+	id: 'reports.dashboard.reports-summary',
+	slot: 'dashboard.metrics',
+	scope: REPORTS_PERMISSIONS.read,
+	order: 30,
+};

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

@@ -0,0 +1,123 @@
+import type { Translate } from '@flowdular/sdk/client/i18n';
+import type { ReportRange, ReportTile } from '../domain/providers.ts';
+import { REPORT_LIMITS, type WorkspaceReport } from '../domain/types.ts';
+import type { ScreenStatus } from './state.ts';
+
+/** Which of the five states the screen renders. */
+export type ScreenSurface = 'loading' | 'denied' | 'error' | 'empty' | 'ready';
+
+export function screenSurface(
+	status: ScreenStatus,
+	reports: readonly WorkspaceReport[],
+): ScreenSurface {
+	if (status === 'denied') return 'denied';
+	if (status === 'error') return 'error';
+	if (status === 'loading' && reports.length === 0) return 'loading';
+	/* A provider may answer lines without a single number, and that report is
+	   something to render rather than an empty screen. */
+	return reports.some(
+		(report) => report.tiles.length > 0 || report.series.length > 0,
+	)
+		? 'ready'
+		: 'empty';
+}
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Whether the picked range is wider than one request may ask for. The server
+ * refuses the same width with a stable code; the screen checks it first so a
+ * reader sees the bound without spending a request on it.
+ */
+export function rangeTooWide(from: string, to: string): boolean {
+	const start = Date.parse(from + 'T00:00:00Z');
+	const end = Date.parse(to + 'T00:00:00Z');
+	if (Number.isNaN(start) || Number.isNaN(end)) return false;
+	return end - start > (REPORT_LIMITS.rangeDays - 1) * DAY_MS;
+}
+
+/**
+ * A label as the reader should see it. A provider module names its copy with a
+ * key into its own bundle; `translate` answers the key itself when that bundle
+ * has no such entry, which is when the provider's own literal is used.
+ */
+export function resolvedLabel(
+	translate: Translate,
+	label: string,
+	key: string | undefined,
+): string {
+	if (key === undefined || key === '') return label;
+	const translated = translate(key);
+	return translated === key ? label : translated;
+}
+
+/**
+ * What one report card says under its name: the period the provider answered
+ * for when it named one, and otherwise the range the request asked for.
+ */
+export function reportCaption(
+	translate: Translate,
+	day: (value: string) => string,
+	report: WorkspaceReport,
+	range: ReportRange | null,
+): string {
+	const period = report.period ?? range;
+	if (period === null) return report.moduleId;
+	return translate('reports.report.range', {
+		module: report.moduleId,
+		from: day(period.from),
+		to: day(period.to),
+	});
+}
+
+/** One tile with the report it came from, for a view that flattens them. */
+export interface RankedTile {
+	readonly report: WorkspaceReport;
+	readonly tile: ReportTile;
+}
+
+/**
+ * The largest tiles of a whole report, biggest first. The dashboard shows a
+ * fixed few of these, so the comparison is across providers and the tie-break
+ * is the provider key and then the tile key, which keeps the order stable when
+ * two providers answer the same number.
+ */
+export function largestTiles(
+	reports: readonly WorkspaceReport[],
+	count: number,
+): readonly RankedTile[] {
+	const ranked: RankedTile[] = [];
+	for (const report of reports) {
+		for (const tile of report.tiles) ranked.push({ report, tile });
+	}
+	ranked.sort(
+		(left, right) =>
+			right.tile.value - left.tile.value ||
+			left.report.key.localeCompare(right.report.key) ||
+			left.tile.key.localeCompare(right.tile.key),
+	);
+	return ranked.slice(0, Math.max(0, count));
+}
+
+export function numberLabel(locale: string, value: number): string {
+	return new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(
+		value,
+	);
+}
+
+export function deltaLabel(locale: string, value: number): string {
+	return new Intl.NumberFormat(locale, {
+		maximumFractionDigits: 2,
+		signDisplay: 'exceptZero',
+	}).format(value);
+}
+
+export function dayLabel(locale: string, day: string): string {
+	const parsed = Date.parse(day + 'T00:00:00Z');
+	if (Number.isNaN(parsed)) return day;
+	return new Intl.DateTimeFormat(locale, {
+		month: 'numeric',
+		day: 'numeric',
+		timeZone: 'UTC',
+	}).format(new Date(parsed));
+}

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

@@ -0,0 +1,28 @@
+import { cell, createStore } from 'segment-state';
+import type { ReportRange } from '../domain/providers.ts';
+import type { WorkspaceReport } from '../domain/types.ts';
+
+/** `denied` is a 403 the shell could not hide; `error` is everything else. */
+export type ScreenStatus = 'idle' | 'loading' | 'denied' | 'error';
+
+export function createReportsClientState() {
+	const store = createStore({
+		reports: cell<readonly WorkspaceReport[]>([]),
+		/* The range the server answered for, not the one the fields hold: the
+		   two differ while a reader is editing the dates. */
+		range: cell<ReportRange | null>(null),
+		unavailable: cell<readonly string[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		from: '',
+		to: '',
+	});
+	return { store, state: store.state };
+}
+
+export function createReportsWidgetState() {
+	const store = createStore({
+		reports: cell<readonly WorkspaceReport[]>([]),
+	});
+	return { store, state: store.state };
+}

package/modules/reports/src/domain/providers.ts

@@ -0,0 +1,115 @@
+/**
+ * The public cross-module surface. A module that owns a rollup resolves it
+ * while it composes through
+ * `context.capabilities.get<ReportProviderRegistry>(REPORTS_PROVIDERS_CAPABILITY)`
+ * and continues without registering when it is absent, so a deployment without
+ * reports.core still boots. Registration closes when reports.core starts.
+ */
+export const REPORTS_PROVIDERS_CAPABILITY = 'reports.v1';
+
+/** Who is asking. The provider reads it; it never comes from the request. */
+export interface ReportPrincipal {
+	readonly accountId: string;
+	readonly tenantId: string;
+	readonly scopes: readonly string[];
+}
+
+/** Two UTC days, both inclusive, already validated and bounded by reports.core. */
+export interface ReportRange {
+	/** `YYYY-MM-DD`. */
+	readonly from: string;
+	/** `YYYY-MM-DD`, never earlier than `from`. */
+	readonly to: string;
+}
+
+export interface ReportProviderQuery {
+	readonly tenantId: string;
+	readonly principal: ReportPrincipal;
+	readonly range: ReportRange;
+	/**
+	 * Aborted when the provider's time budget expires. A provider that passes it
+	 * to its own statements stops working for an answer nobody waits for; one
+	 * that ignores it is still abandoned, it just keeps running.
+	 */
+	readonly signal?: AbortSignal;
+}
+
+/**
+ * A key in the provider module's own translation bundle, fully qualified the
+ * way `t()` takes it. reports.core renders the translation when that bundle
+ * carries the key in the reader's locale and the literal label beside it when
+ * it does not, so a provider that ships no bundle still names itself.
+ */
+export type ReportLabelKey = string;
+
+/** One number of a report. The unit carries whatever context the owner wants. */
+export interface ReportTile {
+	/** Unique inside the provider; `^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$`. */
+	readonly key: string;
+	readonly label: string;
+	readonly tileLabelKey?: ReportLabelKey;
+	readonly value: number;
+	readonly unit?: string;
+	/** Change against the provider's own comparison period, when it states one. */
+	readonly delta?: number;
+}
+
+export interface ReportSeriesPoint {
+	/** The position on the range axis; a UTC day for the shipped providers. */
+	readonly at: string;
+	readonly value: number;
+}
+
+export interface ReportSeries {
+	readonly key: string;
+	readonly label: string;
+	readonly seriesLabelKey?: ReportLabelKey;
+	readonly points: readonly ReportSeriesPoint[];
+}
+
+export interface ReportProviderAnswer {
+	readonly tiles: readonly ReportTile[];
+	readonly series?: readonly ReportSeries[];
+	/**
+	 * The period these numbers actually cover, when it is not the range that
+	 * was asked for. A provider that rolls up by its own period answers that
+	 * period here, so the screen captions the card with what it is showing
+	 * rather than with what it asked for.
+	 */
+	readonly period?: ReportRange;
+}
+
+export interface ReportProvider {
+	/** `^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$`, unique across every module. */
+	readonly key: string;
+	readonly label: string;
+	readonly labelKey?: ReportLabelKey;
+	/** The scope a reader needs before this provider is asked at all. */
+	readonly permission: string;
+	read(input: ReportProviderQuery): Promise<ReportProviderAnswer>;
+}
+
+export interface ReportProviderRegistry {
+	/**
+	 * Adds the module's providers in the order given. Provider order is the
+	 * order the screen renders in, and the order modules compose in is the order
+	 * they register in. Throws a `ReportsServiceError` with a stable code for a
+	 * malformed provider, a duplicate key, or a call made after reports.core
+	 * started.
+	 */
+	register(moduleId: string, providers: readonly ReportProvider[]): void;
+}
+
+/** Largest values the registry and the answer reader accept. */
+export const REPORT_PROVIDER_LIMITS = {
+	moduleId: 64,
+	key: 96,
+	label: 120,
+	permission: 96,
+	unit: 32,
+	at: 32,
+	providers: 64,
+	tiles: 16,
+	series: 8,
+	points: 400,
+} as const;

package/modules/reports/src/domain/types.ts

@@ -0,0 +1,44 @@
+import type {
+	ReportLabelKey,
+	ReportRange,
+	ReportSeries,
+	ReportTile,
+} from './providers.ts';
+
+/** Bounds reports.core enforces on a request, independent of any provider. */
+export const REPORT_LIMITS = {
+	tenantId: 128,
+	/**
+	 * Widest range one request may ask for. It equals the point bound, so a
+	 * daily series over the widest range still fits inside one provider answer.
+	 */
+	rangeDays: 400,
+	defaultRangeDays: 30,
+} as const;
+
+/** A provider as the reader sees it, without its read operation. */
+export interface ReportProviderSummary {
+	readonly key: string;
+	readonly moduleId: string;
+	readonly label: string;
+	readonly labelKey?: ReportLabelKey;
+	readonly permission: string;
+}
+
+/** One provider's answer, read and bounded, as the screen renders it. */
+export interface WorkspaceReport extends ReportProviderSummary {
+	readonly tiles: readonly ReportTile[];
+	readonly series: readonly ReportSeries[];
+	/** The period this provider answered for, when it is not the request range. */
+	readonly period?: ReportRange;
+}
+
+export interface WorkspaceReportPage {
+	readonly range: ReportRange;
+	readonly reports: readonly WorkspaceReport[];
+	/**
+	 * Providers that were asked and could not answer, by key. A provider whose
+	 * permission the reader lacks is never asked and never named here.
+	 */
+	readonly unavailable: readonly string[];
+}

package/modules/reports/src/index.ts

@@ -0,0 +1,47 @@
+import type { ModuleManifest, RegisteredModule } from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { REPORTS_PERMISSIONS } from './acl/permissions.ts';
+
+export const moduleDefinition = {
+	manifest: manifest as ModuleManifest,
+	navigation: [
+		{
+			id: 'reports.navigation',
+			label: 'Reports',
+			href: '/reports',
+			order: 70,
+			permission: REPORTS_PERMISSIONS.read,
+		},
+	],
+	permissions: Object.values(REPORTS_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export { REPORTS_PERMISSIONS } from './acl/permissions.ts';
+
+/* The cross-module contract. A provider module imports the identifier and the
+   types from here and resolves the registry through the capability registry;
+   nothing else in this module is meant to be imported by another one. */
+export {
+	REPORTS_PROVIDERS_CAPABILITY,
+	REPORT_PROVIDER_LIMITS,
+} from './domain/providers.ts';
+export type {
+	ReportPrincipal,
+	ReportProvider,
+	ReportProviderAnswer,
+	ReportProviderQuery,
+	ReportProviderRegistry,
+	ReportRange,
+	ReportSeries,
+	ReportSeriesPoint,
+	ReportTile,
+} from './domain/providers.ts';
+
+export { REPORT_LIMITS } from './domain/types.ts';
+export type {
+	ReportProviderSummary,
+	WorkspaceReport,
+	WorkspaceReportPage,
+} from './domain/types.ts';
+
+export { ReportsServiceError } from './services/service-error.ts';

package/modules/reports/src/platform.ts

@@ -0,0 +1,37 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import {
+	REPORTS_PROVIDERS_CAPABILITY,
+	type ReportProviderRegistry,
+} from './domain/providers.ts';
+import { createReportsRoutes, createReportsRuntime } from './server/index.ts';
+import { REPORTS_MODULE_SETTINGS, reportsBudget } from './settings.ts';
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	const runtime = createReportsRuntime({
+		budget: () => reportsBudget(context.settings),
+	});
+	/* Registered while this module composes so every provider module, which
+	   declares reports.core as a dependency and therefore composes later, finds
+	   the registry open. `start` runs once every module has composed, which is
+	   exactly when the provider list is final. */
+	context.capabilities.register<ReportProviderRegistry>(
+		REPORTS_PROVIDERS_CAPABILITY,
+		{
+			register: (moduleId, providers) =>
+				runtime.providers.register(moduleId, providers),
+		},
+	);
+	/* reports.core holds no rows: it composes what the owning modules answer
+	   and keeps nothing. The empty declaration is how a workspace sees that. */
+	context.dataClasses.declare('reports.core', []);
+	return {
+		routes: createReportsRoutes(context.auth, runtime),
+		settings: REPORTS_MODULE_SETTINGS,
+		start: () => runtime.start(),
+	};
+}

package/modules/reports/src/server/index.ts

@@ -0,0 +1,21 @@
+export { createReportsRoutes, endpoints } from '../api/endpoints.ts';
+export { createReportsRuntime } from './runtime.ts';
+export type { ReportsRuntime, ReportsRuntimeOptions } from './runtime.ts';
+export { createReportProviderRegistry } from '../services/provider-registry.ts';
+export type {
+	MutableReportProviderRegistry,
+	RegisteredReportProvider,
+} from '../services/provider-registry.ts';
+export { readReportRange, utcDay } from '../services/range.ts';
+export {
+	PROVIDER_TIMEOUT_RANGE,
+	readAnswer,
+	ReportsService,
+} from '../services/reports-service.ts';
+export type {
+	ReportsBudget,
+	ReportsQueryInput,
+	ReportsServiceOptions,
+} from '../services/reports-service.ts';
+export { ReportsServiceError } from '../services/service-error.ts';
+export { REPORTS_MODULE_SETTINGS, reportsBudget } from '../settings.ts';

package/modules/reports/src/server/runtime.ts

@@ -0,0 +1,40 @@
+import type { ReportProviderRegistry } from '../domain/providers.ts';
+import {
+	createReportProviderRegistry,
+	type MutableReportProviderRegistry,
+} from '../services/provider-registry.ts';
+import {
+	ReportsService,
+	type ReportsBudget,
+} from '../services/reports-service.ts';
+
+export interface ReportsRuntimeOptions {
+	/** Live platform setting, read again for every request. */
+	readonly budget: () => ReportsBudget;
+}
+
+export interface ReportsRuntime {
+	/** The registration half, registered as `reports.v1` while modules compose. */
+	readonly providers: ReportProviderRegistry;
+	service(): ReportsService;
+	/** Seals the registry: composition is over and nothing may register now. */
+	start(): void;
+}
+
+/**
+ * reports.core owns no rows, so there is no lease, no migration and nothing to
+ * dispose: the runtime is the provider registry plus the one service that fans
+ * out over it.
+ */
+export function createReportsRuntime(
+	options: ReportsRuntimeOptions,
+): ReportsRuntime {
+	const registry: MutableReportProviderRegistry =
+		createReportProviderRegistry();
+	const service = new ReportsService({ registry, budget: options.budget });
+	return {
+		providers: registry,
+		service: () => service,
+		start: () => registry.seal(),
+	};
+}

package/modules/reports/src/services/index.ts

@@ -0,0 +1,17 @@
+export { createReportProviderRegistry } from './provider-registry.ts';
+export type {
+	MutableReportProviderRegistry,
+	RegisteredReportProvider,
+} from './provider-registry.ts';
+export { readReportRange, utcDay } from './range.ts';
+export {
+	PROVIDER_TIMEOUT_RANGE,
+	readAnswer,
+	ReportsService,
+} from './reports-service.ts';
+export type {
+	ReportsBudget,
+	ReportsQueryInput,
+	ReportsServiceOptions,
+} from './reports-service.ts';
+export { bounded, ReportsServiceError } from './service-error.ts';