@flowdular/sdk 0.2.3 → 0.3.0

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

@@ -0,0 +1,154 @@
+/** Every state a request can hold. Only `pending` accepts a decision. */
+export const APPROVAL_STATUSES = [
+	'pending',
+	'approved',
+	'rejected',
+	'expired',
+	'cancelled',
+] as const;
+
+export type ApprovalStatus = (typeof APPROVAL_STATUSES)[number];
+
+export const TERMINAL_APPROVAL_STATUSES = [
+	'approved',
+	'rejected',
+	'expired',
+	'cancelled',
+] as const;
+
+export type TerminalApprovalStatus =
+	(typeof TERMINAL_APPROVAL_STATUSES)[number];
+
+/** Every row the append-only ledger can carry. */
+export const APPROVAL_DECISIONS = [
+	'approve',
+	'reject',
+	'expire',
+	'cancel',
+] as const;
+
+export type ApprovalDecisionKind = (typeof APPROVAL_DECISIONS)[number];
+
+/**
+ * One pending or resolved question of whether an action on a record may go
+ * ahead. The eligibility snapshot is not part of it: who may decide is answered
+ * by the snapshot rows behind `decidableBy`, and re-answered against live
+ * membership when a decision arrives.
+ */
+export interface ApprovalRequest {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly subjectModule: string;
+	readonly subjectRef: string;
+	readonly permission: string;
+	readonly action: string;
+	readonly title: string;
+	readonly summary: string | null;
+	readonly requesterAccountId: string;
+	readonly requirement: ApprovalRequirementRecord;
+	readonly decisionsNeeded: number;
+	readonly status: ApprovalStatus;
+	readonly expiresAt: number;
+	readonly resolvedAt: number | null;
+	readonly createdAt: number;
+}
+
+/**
+ * The requirement as it was opened. It mirrors the kernel `ApprovalRequirement`
+ * with the two optional fields resolved, so a stored row never has to be read
+ * back through a partially specified shape.
+ */
+export interface ApprovalRequirementRecord {
+	readonly roleKey: string | null;
+	readonly scope: string | null;
+	readonly decisions: number;
+	readonly expiresInDays: number;
+}
+
+export interface ApprovalDecision {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly requestId: string;
+	/** Null for the expiry loop, which is the one decision no member makes. */
+	readonly deciderAccountId: string | null;
+	readonly decision: ApprovalDecisionKind;
+	readonly comment: string | null;
+	readonly decidedAt: number;
+}
+
+/** What an erasure writes over the comment of a decision it keeps. */
+export const ERASED_DECISION_COMMENT = '[erased]';
+
+/**
+ * Prefix of the account an erasure writes over a decision or an eligibility row
+ * it keeps. Something unique to the row follows it, because both tables are
+ * unique per request and account: one fixed value would collide the moment two
+ * erased subjects had answered, or been eligible for, the same request, and the
+ * erasure would fail instead of clearing either of them.
+ */
+export const ERASED_ACCOUNT_PREFIX = 'erased:';
+
+/** Sort keys the inbox list accepts; each is backed by a keyset index. */
+export const APPROVAL_LIST_SORTS = ['createdAt'] as const;
+
+export type ApprovalListSort = (typeof APPROVAL_LIST_SORTS)[number];
+
+export const APPROVAL_LIST_DIRECTIONS = ['asc', 'desc'] as const;
+
+export type ApprovalListDirection = (typeof APPROVAL_LIST_DIRECTIONS)[number];
+
+/** One keyset page of the inbox list. `after` is the last row of the page before it. */
+export interface ApprovalListPage {
+	readonly limit: number;
+	readonly sort: ApprovalListSort;
+	readonly direction: ApprovalListDirection;
+	readonly after: { readonly createdAt: number; readonly id: string } | null;
+}
+
+/** What one bulk decision did with one id; a refusal names the code the single decision would answer with. */
+export interface ApprovalDecideOutcome {
+	readonly id: string;
+	readonly outcome: 'decided' | 'not-found' | 'refused';
+	readonly reason?: string;
+}
+
+/** A request with its ledger, as the drawer and the read endpoints return it. */
+export interface ApprovalRequestDetail {
+	readonly request: ApprovalRequest;
+	readonly decisions: readonly ApprovalDecision[];
+}
+
+/**
+ * What the member reading a request may do with it, answered by the server so a
+ * screen never has to guess at eligibility it cannot see.
+ */
+export interface ApprovalViewerRights {
+	readonly accountId: string;
+	readonly canDecide: boolean;
+	readonly canCancel: boolean;
+}
+
+export interface ApprovalRequestView extends ApprovalRequestDetail {
+	readonly viewer: ApprovalViewerRights;
+}
+
+/** What the cross-tenant expiry poll is allowed to learn. */
+export interface ApprovalRouting {
+	readonly tenantId: string;
+	readonly id: string;
+	readonly expiresAt: number;
+	readonly status: ApprovalStatus;
+}
+
+/** A workspace member as eligibility is resolved against it. */
+export interface ApprovalMember {
+	readonly accountId: string;
+	readonly roleKey: string;
+	readonly scopes: readonly string[];
+}
+
+export function isTerminalApprovalStatus(
+	status: ApprovalStatus,
+): status is TerminalApprovalStatus {
+	return status !== 'pending';
+}

package/modules/approvals/src/index.ts

@@ -0,0 +1,52 @@
+import type { ModuleManifest, RegisteredModule } from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { APPROVALS_PERMISSIONS } from './acl/permissions.ts';
+
+export const moduleDefinition = {
+	manifest: manifest as ModuleManifest,
+	navigation: [
+		{
+			id: 'approvals.navigation',
+			label: 'Approvals',
+			href: '/approvals',
+			order: 50,
+			permission: APPROVALS_PERMISSIONS.read,
+		},
+	],
+	permissions: Object.values(APPROVALS_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export { APPROVALS_PERMISSIONS } from './acl/permissions.ts';
+
+/* The cross-module contract. A subject 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 one. */
+export {
+	APPROVALS_REQUESTS_CAPABILITY,
+	APPROVAL_LIMITS,
+} from './domain/capability.ts';
+export type {
+	ApprovalRequestFilter,
+	ApprovalsRequests,
+	OpenApprovalInput,
+} from './domain/capability.ts';
+
+export {
+	APPROVAL_DECISIONS,
+	APPROVAL_STATUSES,
+	TERMINAL_APPROVAL_STATUSES,
+	isTerminalApprovalStatus,
+} from './domain/types.ts';
+export type {
+	ApprovalDecision,
+	ApprovalDecisionKind,
+	ApprovalMember,
+	ApprovalRequest,
+	ApprovalRequestDetail,
+	ApprovalRequirementRecord,
+	ApprovalRouting,
+	ApprovalStatus,
+	TerminalApprovalStatus,
+} from './domain/types.ts';
+
+export { ApprovalsServiceError } from './services/service-error.ts';

package/modules/approvals/src/platform.ts

@@ -0,0 +1,128 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import {
+	APPROVALS_REQUESTS_CAPABILITY,
+	type ApprovalsRequests,
+} from './domain/capability.ts';
+import type { ApprovalMember } from './domain/types.ts';
+import {
+	createApprovalsRoutes,
+	createApprovalsRuntime,
+} from './server/index.ts';
+import { approvalsDataClasses } from './services/data-classes.ts';
+import {
+	NOTIFICATIONS_PUBLISH_CAPABILITY,
+	type NotificationPublisher,
+} from './services/notifications.ts';
+import {
+	APPROVALS_MODULE_SETTINGS,
+	approvalsPrimedDefaultExpiryDays,
+	approvalsPrimedExpiryIntervalMs,
+} from './settings.ts';
+
+interface AuthMemberRecord {
+	readonly accountId: string;
+	readonly role: string;
+	readonly status: string;
+	readonly membershipStatus: string;
+	readonly scopes: readonly string[];
+}
+
+/* A disabled account or a suspended membership decides nothing, so the two
+   reads apply the same filter and answer the same shape. */
+function activeMember(member: AuthMemberRecord): ApprovalMember | null {
+	if (member.status !== 'active' || member.membershipStatus !== 'active') {
+		return null;
+	}
+	return {
+		accountId: member.accountId,
+		roleKey: member.role,
+		scopes: member.scopes,
+	};
+}
+
+/* Who may decide is auth.core's answer, and it is asked at the moment a request
+   opens and again at the moment a decision arrives, never cached, so a revoked
+   role stops producing decisions immediately. */
+function tenantMembers(
+	context: PlatformServerContext,
+): (tenantId: string) => Promise<readonly ApprovalMember[]> {
+	return async (tenantId) =>
+		(await (await context.auth.service()).listTenantMembers(tenantId)).flatMap(
+			(member) => {
+				const active = activeMember(member);
+				return active ? [active] : [];
+			},
+		);
+}
+
+/* Judging one account reads one membership: the whole roll is auth.core's
+   answer only when the eligibility snapshot has to be resolved. */
+function tenantMember(
+	context: PlatformServerContext,
+): (tenantId: string, accountId: string) => Promise<ApprovalMember | null> {
+	return async (tenantId, accountId) => {
+		const member = await (
+			await context.auth.service()
+		).findTenantMember(tenantId, accountId);
+		return member ? activeMember(member) : null;
+	};
+}
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	const runtime = createApprovalsRuntime({
+		databases: context.databases,
+		purpose:
+			context.environment.NODE_ENV === 'test'
+				? 'test'
+				: context.environment.NODE_ENV === 'production'
+					? 'runtime'
+					: 'preview',
+		members: tenantMembers(context),
+		member: tenantMember(context),
+		/* The open capability runs from the workflows worker and the loop from
+		   the job runner, where no request middleware primed the workspace. */
+		defaultExpiryDays: (tenantId) =>
+			approvalsPrimedDefaultExpiryDays(context.settings, tenantId),
+		expiryIntervalMs: () => approvalsPrimedExpiryIntervalMs(context.settings),
+		/* notifications.core is optional. The lookup happens when an event is
+		   published, 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,
+			),
+	});
+	/* The runtime opens its database leases lazily, so the capability is a
+	   forwarder rather than a resolved object: registration must not force a
+	   connection at composition time. */
+	context.capabilities.register<ApprovalsRequests>(
+		APPROVALS_REQUESTS_CAPABILITY,
+		{
+			open: async (input) => (await runtime.service()).capability().open(input),
+			get: async (tenantId, id) =>
+				(await runtime.service()).capability().get(tenantId, id),
+			list: async (tenantId, filter) =>
+				(await runtime.service()).capability().list(tenantId, filter),
+			cancel: async (tenantId, id, actorAccountId) =>
+				(await runtime.service())
+					.capability()
+					.cancel(tenantId, id, actorAccountId),
+		},
+	);
+	/* The sweep, the export, the count and the erasure run here, on this
+	   module's own lease and under its own tenant transaction; the platform only
+	   holds the declaration. */
+	context.dataClasses.declare(approvalsDataClasses(() => runtime.repository()));
+	return {
+		routes: createApprovalsRoutes(context.auth, runtime),
+		settings: APPROVALS_MODULE_SETTINGS,
+		start: () => runtime.start(),
+		stop: () => runtime.quiesce(),
+		dispose: () => runtime.dispose(),
+	};
+}

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

@@ -0,0 +1,42 @@
+export { createApprovalsRoutes, endpoints } from '../api/endpoints.ts';
+export {
+	DatabaseApprovalsRepository,
+	migrateApprovalsDatabase,
+} from '../services/database-repository.ts';
+export type { ApprovalsDatabaseHandles } from '../services/database-repository.ts';
+export { createApprovalsRuntime } from './runtime.ts';
+export type { ApprovalsRuntime, ApprovalsRuntimeOptions } from './runtime.ts';
+export {
+	ApprovalsService,
+	APPROVALS_PAGE_LIMIT,
+} from '../services/approvals-service.ts';
+export type { ApprovalsServiceOptions } from '../services/approvals-service.ts';
+export {
+	createApprovalsExpiryRunner,
+	EXPIRY_BATCH,
+} from '../services/expiry-runner.ts';
+export type { ApprovalsExpiryRunnerOptions } from '../services/expiry-runner.ts';
+export { createApprovalCallbackRegistry } from '../services/callbacks.ts';
+export type {
+	ApprovalCallbackRegistry,
+	ApprovalResolvedCallback,
+} from '../services/callbacks.ts';
+export {
+	memberSatisfies,
+	normalizeRequirement,
+	resolveEligible,
+} from '../services/eligibility.ts';
+export type {
+	ApprovalRequestFilters,
+	ApprovalsRepository,
+	CreateApprovalResult,
+	DecideApprovalInput,
+	DecideApprovalResult,
+} from '../services/repository.ts';
+export { ApprovalsServiceError } from '../services/service-error.ts';
+export {
+	APPROVALS_MODULE_ID,
+	APPROVALS_MODULE_SETTINGS,
+	approvalsDefaultExpiryDays,
+	approvalsExpiryIntervalMs,
+} from '../settings.ts';

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

@@ -0,0 +1,181 @@
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+	DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+} from '@flowdular/sdk/database';
+import type { JobRunner } from '@flowdular/sdk/server';
+import type { ApprovalMember } from '../domain/types.ts';
+import {
+	createApprovalCallbackRegistry,
+	type ApprovalCallbackRegistry,
+} from '../services/callbacks.ts';
+import {
+	DatabaseApprovalsRepository,
+	migrateApprovalsDatabase,
+} from '../services/database-repository.ts';
+import { createApprovalsExpiryRunner } from '../services/expiry-runner.ts';
+import type { NotificationPublisherResolver } from '../services/notifications.ts';
+import type { ApprovalsRepository } from '../services/repository.ts';
+import { ApprovalsService } from '../services/approvals-service.ts';
+
+export interface ApprovalsRuntimeOptions {
+	/** Platform-owned provider. Modules never receive a DSN or a pool. */
+	readonly databases: DatabaseProvider;
+	readonly purpose?:
+		| Exclude<DatabaseProviderRequest['purpose'], 'migration'>
+		| undefined;
+	/** Members and their current role and scopes, resolved through auth.core. */
+	readonly members: (tenantId: string) => Promise<readonly ApprovalMember[]>;
+	/** One member's current role and scopes, resolved through auth.core. */
+	readonly member: (
+		tenantId: string,
+		accountId: string,
+	) => Promise<ApprovalMember | null>;
+	/** Live tenant setting, read again for every request that needs it. */
+	readonly defaultExpiryDays: (tenantId: string) => number | Promise<number>;
+	/** Live platform setting, read when the loop starts. */
+	readonly expiryIntervalMs: () => number | Promise<number>;
+	readonly notifications?: NotificationPublisherResolver;
+	readonly callbacks?: ApprovalCallbackRegistry;
+	readonly repository?: ApprovalsRepository;
+	readonly now?: () => number;
+}
+
+export interface ApprovalsRuntime {
+	service(): Promise<ApprovalsService>;
+	/** The open repository, for the operations behind the declared data class. */
+	repository(): Promise<ApprovalsRepository>;
+	start(): void;
+	stop(): void;
+	quiesce(): Promise<void>;
+	dispose(): Promise<void>;
+}
+
+export function createApprovalsRuntime(
+	options: ApprovalsRuntimeOptions,
+): ApprovalsRuntime {
+	const callbacks = options.callbacks ?? createApprovalCallbackRegistry();
+	let repositoryPromise: Promise<ApprovalsRepository> | undefined;
+	let leases: readonly DatabaseAdapterLease[] = [];
+	let service: ApprovalsService | undefined;
+	let jobs: JobRunner | undefined;
+	let jobsPromise: Promise<JobRunner> | undefined;
+	let starting: Promise<void> | undefined;
+	let disposed = false;
+
+	const acquire = (purpose: DatabaseProviderRequest['purpose']) =>
+		options.databases.acquire({
+			namespace: 'approvals.core',
+			purpose,
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [DATABASE_CAPABILITY_IDS.TRANSACTIONS],
+			},
+		});
+
+	const openRepository = async (): Promise<ApprovalsRepository> => {
+		if (options.repository) return options.repository;
+		/* 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 migration = await options.databases.acquire({
+			namespace: 'approvals.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,
+				],
+			},
+		});
+		try {
+			await migrateApprovalsDatabase(migration.database);
+		} finally {
+			await migration.release();
+		}
+		const runtimeLease = await acquire(options.purpose ?? 'runtime');
+		/* The expiry poll reads across tenants; every write that follows uses the
+		   tenant carried by the routing row it returned. */
+		const backgroundLease = await acquire('background');
+		leases = [runtimeLease, backgroundLease];
+		return new DatabaseApprovalsRepository({
+			runtime: runtimeLease.database,
+			background: backgroundLease.database,
+		});
+	};
+
+	const repositoryInstance = (): Promise<ApprovalsRepository> =>
+		(repositoryPromise ??= openRepository());
+
+	const resolved = async (): Promise<ApprovalsService> =>
+		(service ??= new ApprovalsService({
+			repository: await repositoryInstance(),
+			members: options.members,
+			member: options.member,
+			defaultExpiryDays: options.defaultExpiryDays,
+			callbacks,
+			...(options.notifications
+				? { notifications: options.notifications }
+				: {}),
+			...(options.now ? { now: options.now } : {}),
+		}));
+
+	/* The platform runner owns the loop: the interval and its unref, the guard
+	   against overlapping passes, the bound on claims, the isolation of one
+	   request from the next, and the drain. This module keeps its routing read
+	   and its transition. The interval is the platform setting as it reads when
+	   the loop starts, so the runner is built there rather than while the
+	   platform composes, before the setting is declared. */
+	const runner = (): Promise<JobRunner> =>
+		(jobsPromise ??= (async () =>
+			(jobs = createApprovalsExpiryRunner({
+				repository: repositoryInstance,
+				service: resolved,
+				intervalMs: await options.expiryIntervalMs(),
+				...(options.now ? { now: options.now } : {}),
+			})))());
+
+	return {
+		service: resolved,
+		repository: repositoryInstance,
+		start() {
+			if (disposed) return;
+			/* The interval is a settings read that may have to prime the platform
+			   tenant first, so the loop starts once that read settles. */
+			starting ??= runner().then(
+				(loop) => {
+					if (!disposed) loop.start();
+				},
+				(error: unknown) => {
+					jobsPromise = undefined;
+					starting = undefined;
+					console.warn('approvals.core: the expiry loop did not start.', error);
+				},
+			);
+		},
+		stop: () => jobs?.stop(),
+		async quiesce() {
+			await starting;
+			await jobs?.quiesce();
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			await starting;
+			await jobs?.dispose();
+			/* An open still in flight would assign its leases after this read, so
+			   settle it first; a failed open must not surface as an unhandled
+			   rejection during teardown. */
+			await repositoryPromise?.catch(() => undefined);
+			for (const lease of leases) await lease.release();
+			leases = [];
+			repositoryPromise = undefined;
+			service = undefined;
+		},
+	};
+}