@flowdular/sdk 0.2.4 → 0.3.0

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

@@ -0,0 +1,63 @@
+import type { TagTone } from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client/i18n';
+import type { MeterKind, MeterUsage } from '../domain/types.ts';
+import type { ScreenStatus } from './state.ts';
+
+/**
+ * What a screen puts under its header. A failed load answers `error` and
+ * nothing else: the table's own empty copy would otherwise sit under the alert
+ * and tell the reader this workspace has no meters, which is not what happened.
+ */
+export function screenSurface(
+	status: ScreenStatus,
+): 'denied' | 'error' | 'records' {
+	if (status === 'denied') return 'denied';
+	return status === 'error' ? 'error' : 'records';
+}
+
+export function numberLabel(value: number): string {
+	return new Intl.NumberFormat(activeLocale()).format(value);
+}
+
+/** Epoch milliseconds as the reader's local date and time. */
+export function timestampLabel(value: number | null): string {
+	if (value === null) return t('metering.common.notYet');
+	return new Intl.DateTimeFormat(activeLocale(), {
+		dateStyle: 'medium',
+		timeStyle: 'short',
+	}).format(value);
+}
+
+export function kindLabel(kind: MeterKind): string {
+	return t('metering.kind.' + kind);
+}
+
+/** Whole percent of the limit a month's usage has reached, or null. */
+export function usageShare(entry: MeterUsage): number | null {
+	if (entry.limit === null) return null;
+	/* A limit of zero allows nothing, so it is reached whatever the usage is.
+	   Reading it as "no share" would paint a meter the workspace cannot use at
+	   all in the same neutral tone as an unlimited one. */
+	if (entry.limit === 0) return 100;
+	return Math.floor((entry.used / entry.limit) * 100);
+}
+
+export function usageLabel(entry: MeterUsage): string {
+	if (entry.limit === null) {
+		return t('metering.usage.unlimited', { used: numberLabel(entry.used) });
+	}
+	return t('metering.usage.ofLimit', {
+		used: numberLabel(entry.used),
+		limit: numberLabel(entry.limit),
+	});
+}
+
+/* The warning share comes from the server with the meters, so the colour on
+   the screen and the notification in the inbox never disagree about what a
+   workspace has reached. */
+export function usageTone(entry: MeterUsage, warningPercent: number): TagTone {
+	const share = usageShare(entry);
+	if (share === null) return 'neutral';
+	if (share >= 100) return 'danger';
+	return share >= warningPercent ? 'warning' : 'success';
+}

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

@@ -0,0 +1,31 @@
+import { cell, createStore } from 'segment-state';
+import type { MeterLimit, MeterUsage } 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 createUsageClientState() {
+	const store = createStore({
+		meters: cell<readonly MeterUsage[]>([]),
+		/* The server's own warning share, so the screen colours what the inbox
+		   notifies on rather than a second copy of the rule. */
+		warningPercent: cell<number>(80),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		query: '',
+		moduleFilter: '',
+		filtersOpen: false,
+	});
+	return { store, state: store.state };
+}
+
+export function createLimitsClientState() {
+	const store = createStore({
+		limits: cell<readonly MeterLimit[]>([]),
+		meters: cell<readonly MeterUsage[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		query: '',
+	});
+	return { store, state: store.state };
+}

package/modules/metering/src/domain/meters.ts

@@ -0,0 +1,100 @@
+import type { MeterKind } from './types.ts';
+
+/**
+ * The public cross-module surface. A metering module resolves it through
+ * `context.capabilities.get<MeterRegistry>(METERING_METERS_CAPABILITY)` during
+ * its own composition, declares what it counts, and reports facts at run time.
+ */
+export const METERING_METERS_CAPABILITY = 'metering.meters.v1';
+
+/** The stable code a caller records when `check` refuses. */
+export const METER_LIMIT_EXCEEDED = 'METER_LIMIT_EXCEEDED';
+
+export interface MeterDeclaration {
+	/** `^[a-z][a-z0-9-]*$`; the meter key is `${moduleId}.${key}`. */
+	readonly key: string;
+	readonly label: string;
+	readonly unit: string;
+	readonly kind: MeterKind;
+}
+
+export interface MeterRecordInput {
+	readonly tenantId: string;
+	/** The full key, `<moduleId>.<key>`, as `declare` composed it. */
+	readonly meter: string;
+	/** Whole units of the meter. Never negative. */
+	readonly amount: number;
+	/** Epoch milliseconds the fact happened at; the caller's clock by default. */
+	readonly at?: number;
+	/** Makes the fact idempotent. Without it every call counts again. */
+	readonly sourceRef?: string;
+}
+
+export interface MeterRecordResult {
+	/** False when this source reference was already counted. */
+	readonly recorded: boolean;
+	/** The UTC day bucket the fact landed in, `YYYY-MM-DD`. */
+	readonly day: string;
+}
+
+export interface MeterCheckInput {
+	readonly tenantId: string;
+	readonly meter: string;
+	readonly amount: number;
+}
+
+/**
+ * `refused` once this month's usage plus the amount would pass the limit,
+ * `warning` when the amount is what carries the month past the warning share
+ * of the limit, `allowed` otherwise. A workspace with no limit is always
+ * allowed.
+ */
+export type MeterVerdict = 'allowed' | 'warning' | 'refused';
+
+export interface MeterCheckResult {
+	readonly verdict: MeterVerdict;
+	/** This calendar month's usage in UTC, before the amount asked about. */
+	readonly used: number;
+	/** The operator's ceiling, or null when this workspace is unlimited. */
+	readonly limit: number | null;
+}
+
+export interface MeterRegistry {
+	/**
+	 * Accepted only while the platform composes. Declaring after the platform
+	 * started throws, so the meters a request reads are the ones every module
+	 * agreed on at boot.
+	 */
+	declare(moduleId: string, meters: readonly MeterDeclaration[]): void;
+	/**
+	 * Counts one fact in metering.core's own tenant-scoped write transaction,
+	 * not in the caller's: no database handle crosses this boundary. The fact
+	 * therefore commits independently of whatever the caller is doing, and a
+	 * caller that wants exactly-once semantics names a `sourceRef`, which makes
+	 * a repeat a no-op.
+	 */
+	record(input: MeterRecordInput): Promise<MeterRecordResult>;
+	/** Reads this month's usage against the limit. Writes nothing. */
+	check(input: MeterCheckInput): Promise<MeterCheckResult>;
+}
+
+/** Longest values and largest amounts the capability accepts. */
+export const METER_LIMITS = {
+	moduleId: 64,
+	/** The declared key, before the module id is prefixed. */
+	key: 96,
+	label: 120,
+	unit: 32,
+	sourceRef: 200,
+	tenantId: 128,
+	metersPerModule: 64,
+	/**
+	 * One fact. The month sum is a BIGINT sum of these, so it leaves the safe
+	 * integer range after roughly 9007 facts at this amount; past that the sum
+	 * is read as `Number.MAX_SAFE_INTEGER` rather than failing the fact that
+	 * crossed the line (`DatabaseMeteringRepository`).
+	 */
+	amount: 1_000_000_000_000,
+	monthlyLimit: 1_000_000_000_000,
+	setBy: 128,
+} as const;

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

@@ -0,0 +1,71 @@
+/** How a meter counts. Declared once by the owning module, never by a reader. */
+export const METER_KINDS = ['cumulative', 'gauge'] as const;
+export type MeterKind = (typeof METER_KINDS)[number];
+
+/** Which share of a limit a notification was sent for. */
+export const METER_THRESHOLDS = ['warning', 'exhausted'] as const;
+export type MeterThreshold = (typeof METER_THRESHOLDS)[number];
+
+/** A meter as one workspace recorded it. `key` is `<moduleId>.<meter key>`. */
+export interface Meter {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly key: string;
+	readonly moduleId: string;
+	readonly label: string;
+	readonly unit: string;
+	readonly kind: MeterKind;
+	readonly createdAt: number;
+}
+
+/** The usage of one meter on one UTC day. */
+export interface UsageBucket {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly meter: string;
+	readonly day: string;
+	readonly amount: number;
+	readonly events: number;
+	readonly updatedAt: number;
+}
+
+/** The operator's ceiling for one meter in one workspace, per calendar month. */
+export interface MeterLimit {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly meter: string;
+	readonly monthlyLimit: number;
+	readonly setBy: string;
+	readonly updatedAt: number;
+}
+
+/** A limit change as the CLI recorded it. Written once, never rewritten. */
+export interface MeterLimitEvent {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly meter: string;
+	readonly monthlyLimit: number;
+	readonly previousLimit: number | null;
+	readonly setBy: string;
+	readonly occurredAt: number;
+}
+
+/** Evidence that a threshold notification was published for a month. */
+export interface MeterThresholdNotice {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly meter: string;
+	readonly month: string;
+	readonly threshold: MeterThreshold;
+	readonly sentAt: number;
+}
+
+/** One row of the usage screen and of the dashboard widget. */
+export interface MeterUsage {
+	readonly meter: Meter;
+	/** UTC `YYYY-MM` the usage below was summed over. */
+	readonly month: string;
+	readonly used: number;
+	/** The operator's ceiling, or null when this workspace is unlimited. */
+	readonly limit: number | null;
+}

package/modules/metering/src/index.ts

@@ -0,0 +1,51 @@
+import type { ModuleManifest, RegisteredModule } from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { METERING_PERMISSIONS } from './acl/permissions.ts';
+
+export const moduleDefinition = {
+	manifest: manifest as ModuleManifest,
+	navigation: [
+		{
+			id: 'metering.navigation',
+			label: 'Usage',
+			href: '/metering-usage',
+			order: 68,
+			permission: METERING_PERMISSIONS.read,
+		},
+	],
+	permissions: Object.values(METERING_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export { METERING_PERMISSIONS } from './acl/permissions.ts';
+
+/* The cross-module contract. A reporting module imports the identifier and the
+   types from here and resolves the implementation through the capability
+   registry; nothing else in this module is meant to be imported by another. */
+export {
+	METERING_METERS_CAPABILITY,
+	METER_LIMIT_EXCEEDED,
+	METER_LIMITS,
+} from './domain/meters.ts';
+export type {
+	MeterCheckInput,
+	MeterCheckResult,
+	MeterDeclaration,
+	MeterRecordInput,
+	MeterRecordResult,
+	MeterRegistry,
+	MeterVerdict,
+} from './domain/meters.ts';
+
+export { METER_KINDS, METER_THRESHOLDS } from './domain/types.ts';
+export type {
+	Meter,
+	MeterKind,
+	MeterLimit,
+	MeterLimitEvent,
+	MeterThreshold,
+	MeterThresholdNotice,
+	MeterUsage,
+	UsageBucket,
+} from './domain/types.ts';
+
+export { MeteringServiceError } from './services/service-error.ts';

package/modules/metering/src/platform.ts

@@ -0,0 +1,84 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import {
+	REPORTS_PROVIDERS_CAPABILITY,
+	type ReportProviderRegistry,
+} from '@flowdular/sdk/modules/reports';
+import {
+	METERING_METERS_CAPABILITY,
+	type MeterRegistry,
+} from './domain/meters.ts';
+import { createMeteringRoutes, createMeteringRuntime } from './server/index.ts';
+import { meteringDataClasses } from './services/data-classes.ts';
+import { createUsageReportProvider } from './services/reports.ts';
+import {
+	NOTIFICATIONS_PUBLISH_CAPABILITY,
+	type NotificationPublisher,
+} from './services/notifications.ts';
+import {
+	METERING_MODULE_SETTINGS,
+	meteringWarningPercent,
+} from './settings.ts';
+
+/* A threshold reaches the people who answer for the workspace's spending, and
+   auth.core owns that answer. It is asked when a threshold is crossed, never
+   cached, so a change of owner reaches the next notification. */
+function workspaceOwners(
+	context: PlatformServerContext,
+): (tenantId: string) => Promise<readonly string[]> {
+	return async (tenantId) =>
+		(await (await context.auth.service()).listTenantMembers(tenantId))
+			.filter((member) => member.status === 'active' && member.role === 'owner')
+			.map((member) => member.accountId);
+}
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	const runtime = createMeteringRuntime({
+		databases: context.databases,
+		purpose:
+			context.environment.NODE_ENV === 'test'
+				? 'test'
+				: context.environment.NODE_ENV === 'production'
+					? 'runtime'
+					: 'preview',
+		warningPercent: () => meteringWarningPercent(context.settings),
+		owners: workspaceOwners(context),
+		/* notifications.core is optional and is not a package dependency. The
+		   lookup happens when a threshold is crossed, so a module composed after
+		   this one is found and an absent one is a no-op. */
+		notifications: () =>
+			context.capabilities.get<NotificationPublisher>(
+				NOTIFICATIONS_PUBLISH_CAPABILITY,
+			),
+	});
+	/* Registered before any module composes so every declaring module resolves
+	   it during its own composition; start() seals it once they all have. */
+	context.capabilities.register<MeterRegistry>(
+		METERING_METERS_CAPABILITY,
+		runtime.meters,
+	);
+	/* reports.core is a declared dependency, so it has composed and its registry
+	   is still open. The capability stays optional all the same: a deployment
+	   that leaves reports out still composes this module. */
+	context.capabilities
+		.get<ReportProviderRegistry>(REPORTS_PROVIDERS_CAPABILITY)
+		?.register('metering.core', [
+			createUsageReportProvider(() => runtime.service()),
+		]);
+	/* The sweep and the export run here, on this module's own leases and under
+	   its own tenant transaction; the platform only holds the declaration. */
+	context.dataClasses.declare(
+		'metering.core',
+		meteringDataClasses(() => runtime.service()),
+	);
+	return {
+		routes: createMeteringRoutes(context.auth, runtime),
+		settings: METERING_MODULE_SETTINGS,
+		start: () => runtime.start(),
+		dispose: () => runtime.dispose(),
+	};
+}

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

@@ -0,0 +1,40 @@
+export { createMeteringRoutes, endpoints } from '../api/endpoints.ts';
+export {
+	DatabaseMeteringRepository,
+	migrateMeteringDatabase,
+	monthRange,
+} from '../services/database-repository.ts';
+export { createMeteringRuntime } from './runtime.ts';
+export type { MeteringRuntime, MeteringRuntimeOptions } from './runtime.ts';
+export {
+	METERING_METERS_CAPABILITY,
+	METER_LIMIT_EXCEEDED,
+	METER_LIMITS,
+} from '../domain/meters.ts';
+export type {
+	MeterCheckInput,
+	MeterCheckResult,
+	MeterDeclaration,
+	MeterRecordInput,
+	MeterRecordResult,
+	MeterRegistry,
+	MeterVerdict,
+} from '../domain/meters.ts';
+export {
+	BUCKET_RETENTION_DAYS,
+	meteringDataClasses,
+} from '../services/data-classes.ts';
+export { MeterDeclarationRegistry } from '../services/meter-registry.ts';
+export type { DeclaredMeter } from '../services/meter-registry.ts';
+export {
+	EXPORT_PAGE,
+	MAX_BUCKET_WINDOW_DAYS,
+	MeteringService,
+	thresholdPoint,
+	utcDay,
+	utcMonth,
+	WARNING_PERCENT_RANGE,
+} from '../services/metering-service.ts';
+export type { MeteringServiceOptions } from '../services/metering-service.ts';
+export type { MeteringRepository } from '../services/repository.ts';
+export { MeteringServiceError } from '../services/service-error.ts';

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

@@ -0,0 +1,165 @@
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+	DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+} from '@flowdular/sdk/database';
+import type {
+	MeterCheckInput,
+	MeterCheckResult,
+	MeterDeclaration,
+	MeterRecordInput,
+	MeterRecordResult,
+	MeterRegistry,
+} from '../domain/meters.ts';
+import {
+	DatabaseMeteringRepository,
+	migrateMeteringDatabase,
+} from '../services/database-repository.ts';
+import { MeterDeclarationRegistry } from '../services/meter-registry.ts';
+import { MeteringService } from '../services/metering-service.ts';
+import type { NotificationPublisherResolver } from '../services/notifications.ts';
+import { MeteringServiceError } from '../services/service-error.ts';
+import type { MeteringRepository } from '../services/repository.ts';
+
+export interface MeteringRuntimeOptions {
+	/** Platform-owned provider. Modules never receive a DSN or a pool. */
+	readonly databases: DatabaseProvider;
+	readonly purpose?:
+		| Exclude<DatabaseProviderRequest['purpose'], 'migration'>
+		| undefined;
+	/** Live platform setting, read again for every fact. */
+	readonly warningPercent: () => number;
+	/** Account ids of the workspace owners, resolved through auth.core. */
+	readonly owners?: (tenantId: string) => Promise<readonly string[]>;
+	readonly notifications?: NotificationPublisherResolver;
+	readonly now?: () => number;
+	/** Supplied by tests that own the leases themselves. */
+	readonly repository?: MeteringRepository;
+	/**
+	 * `verify` reads the ledger and applies no DDL, for a caller that is not
+	 * applying anything (a read command, a dry run). It refuses a schema the
+	 * deployment has not migrated yet instead of creating one.
+	 */
+	readonly migrations?: 'apply' | 'verify';
+}
+
+export interface MeteringRuntime {
+	/** The declaration half, available before any database is open. */
+	readonly registry: MeterDeclarationRegistry;
+	/** The object registered as `metering.meters.v1`. */
+	readonly meters: MeterRegistry;
+	service(): Promise<MeteringService>;
+	/** Seals the registry: composition is over and nothing may declare now. */
+	start(): void;
+	dispose(): Promise<void>;
+}
+
+export function createMeteringRuntime(
+	options: MeteringRuntimeOptions,
+): MeteringRuntime {
+	const registry = new MeterDeclarationRegistry();
+	let disposed = false;
+	let runtimeLeasePromise: Promise<DatabaseAdapterLease> | undefined;
+	let servicePromise: Promise<MeteringService> | undefined;
+
+	const build = (repository: MeteringRepository): MeteringService =>
+		new MeteringService({
+			repository,
+			registry,
+			warningPercent: options.warningPercent,
+			...(options.owners ? { owners: options.owners } : {}),
+			...(options.notifications
+				? { notifications: options.notifications }
+				: {}),
+			...(options.now ? { now: options.now } : {}),
+		});
+
+	/* Schema work runs on the migrator role and that lease is released before
+	   the runtime one is taken, so request handling never holds a schema owner. */
+	const initialize = async (): Promise<MeteringService> => {
+		if (options.repository) return build(options.repository);
+		const migrationLease = await options.databases.acquire({
+			namespace: 'metering.core',
+			purpose: 'migration',
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+					DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+					DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+				],
+			},
+		});
+		const verifyOnly = options.migrations === 'verify';
+		try {
+			const state = await migrateMeteringDatabase(migrationLease.database, {
+				dryRun: verifyOnly,
+			});
+			if (verifyOnly && state.some((entry) => entry.action === 'applied')) {
+				throw new MeteringServiceError(
+					'SCHEMA_NOT_MIGRATED',
+					'metering.core has no schema in this deployment yet. Start the platform, or run the command with --apply, to create it.',
+					503,
+				);
+			}
+		} finally {
+			await migrationLease.release();
+		}
+		runtimeLeasePromise = options.databases.acquire({
+			namespace: 'metering.core',
+			purpose: options.purpose ?? 'runtime',
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.TRANSACTIONS,
+					DATABASE_CAPABILITY_IDS.TENANT_CONTEXT,
+				],
+			},
+		});
+		const lease = await runtimeLeasePromise;
+		return build(new DatabaseMeteringRepository(lease.database));
+	};
+
+	const service = (): Promise<MeteringService> => {
+		if (disposed) {
+			return Promise.reject(new Error('Metering runtime is disposed.'));
+		}
+		servicePromise ??= initialize();
+		return servicePromise;
+	};
+
+	/* The capability object is handed out at composition, before any database is
+	   open. `declare` is answered in process; a fact opens the database on its
+	   first call and every later one reuses the same lease. */
+	const meters: MeterRegistry = {
+		declare: (moduleId: string, declarations: readonly MeterDeclaration[]) =>
+			registry.declare(moduleId, declarations),
+		record: async (input: MeterRecordInput): Promise<MeterRecordResult> =>
+			(await service()).record(input),
+		check: async (input: MeterCheckInput): Promise<MeterCheckResult> =>
+			(await service()).check(input),
+	};
+
+	return {
+		registry,
+		meters,
+		service,
+		start: () => registry.seal(),
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (!runtimeLeasePromise) {
+				await servicePromise?.catch(() => undefined);
+			}
+			if (!runtimeLeasePromise) return;
+			const lease = await runtimeLeasePromise;
+			await lease.release();
+			runtimeLeasePromise = undefined;
+			servicePromise = undefined;
+		},
+	};
+}

package/modules/metering/src/services/data-classes.ts

@@ -0,0 +1,34 @@
+import type { DataClassDeclaration } from '@flowdular/sdk/kernel';
+import type { MeteringService } from './metering-service.ts';
+
+/** Days a bucket is kept unless the workspace shortens the period. */
+export const BUCKET_RETENTION_DAYS = 400;
+
+/**
+ * The classes metering.core owns. Day buckets are the only rows kept by age:
+ * limits and threshold records stay until the operator removes them, and the
+ * idempotency claims travel with the buckets they belong to.
+ *
+ * The service arrives as a thunk because declaring happens while the platform
+ * composes, before anything has opened a database.
+ */
+export function meteringDataClasses(
+	service: () => Promise<MeteringService>,
+): readonly DataClassDeclaration[] {
+	return [
+		{
+			key: 'buckets',
+			label: 'Usage buckets',
+			defaultRetentionDays: BUCKET_RETENTION_DAYS,
+			exportable: true,
+			sweep: async (input) =>
+				(await service()).sweepBuckets(
+					input.tenantId,
+					input.cutoff,
+					input.limit,
+				),
+			export: async (input) =>
+				(await service()).exportBuckets(input.tenantId, input.sink),
+		},
+	];
+}