create-flowdular 0.3.1 → 0.4.0

package/agent-template/.ai/references/catalog/src/api/endpoints.ts

@@ -1,9 +1,12 @@
+import { randomBytes } from 'node:crypto';
 import {
 	defineEndpoint,
 	HttpProblem,
 	jsonResponse,
+	pageResponse,
 	problemResponse,
 	readJsonObject,
+	readPageQuery,
 	requiredInteger,
 	requiredString,
 } from '@flowdular/sdk/server';
@@ -16,13 +19,26 @@ import {
 	sessionMutationDenial,
 } from '@flowdular/sdk/modules/auth/server';
 import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
-import type {
-	CatalogItemKind,
-	CreateCatalogItemInput,
-	UpdateCatalogItemInput,
+import {
+	CATALOG_BULK_LIMIT,
+	CATALOG_LIST_SORTS,
+	CATALOG_SEARCH_LENGTH,
+	type CatalogItemKind,
+	type CatalogListSort,
+	type CreateCatalogItemInput,
+	type UpdateCatalogItemInput,
 } from '../domain/types.ts';
-import { CatalogServiceError } from '../services/catalog-service.ts';
+import {
+	CatalogServiceError,
+	LIST_PAGE_LIMIT,
+	LIST_PAGE_MAX_LIMIT,
+} from '../services/catalog-service.ts';
 import type { CatalogRuntime } from '../server/runtime.ts';
+import {
+	decodeListCursor,
+	encodeListCursor,
+	type CatalogListQuery,
+} from './list-cursor.ts';
 
 function failure(error: unknown): Response {
 	if (error instanceof CatalogServiceError) {
@@ -34,6 +50,59 @@ function failure(error: unknown): Response {
 	return problemResponse(error, 'The catalog operation failed.');
 }
 
+function invalid(message: string): HttpProblem {
+	return new HttpProblem('INVALID_INPUT', message, 400);
+}
+
+function listQuery(url: URL): CatalogListQuery {
+	const sort = url.searchParams.get('sort') ?? 'name';
+	if (!(CATALOG_LIST_SORTS as readonly string[]).includes(sort)) {
+		throw invalid(`sort must be one of ${CATALOG_LIST_SORTS.join(', ')}.`);
+	}
+	const direction = url.searchParams.get('direction') ?? 'asc';
+	if (direction !== 'asc' && direction !== 'desc') {
+		throw invalid('direction must be asc or desc.');
+	}
+	const kind = url.searchParams.get('kind') ?? '';
+	if (kind !== '' && kind !== 'product' && kind !== 'service') {
+		throw invalid('kind must be product or service.');
+	}
+	const status = url.searchParams.get('status') ?? '';
+	if (status !== '' && status !== 'active' && status !== 'archived') {
+		throw invalid('status must be active or archived.');
+	}
+	const search = (url.searchParams.get('q') ?? '').trim();
+	if (search.length > CATALOG_SEARCH_LENGTH) {
+		throw invalid(
+			`q must contain at most ${CATALOG_SEARCH_LENGTH} characters.`,
+		);
+	}
+	return {
+		sort: sort as CatalogListSort,
+		direction,
+		kind: kind === '' ? null : kind,
+		status: status === '' ? null : status,
+		search,
+	};
+}
+
+/* One outcome answers one row, so an id is named once; the count and each id
+   are bounded like the single route's. */
+function requiredIds(value: Record<string, unknown>): readonly string[] {
+	const raw = value.ids;
+	if (!Array.isArray(raw)) throw invalid('ids must be an array.');
+	if (raw.length < 1 || raw.length > CATALOG_BULK_LIMIT) {
+		throw invalid(`ids must name between 1 and ${CATALOG_BULK_LIMIT} items.`);
+	}
+	const ids = raw.map((entry) =>
+		requiredString({ id: entry }, 'id', { max: 128 }),
+	);
+	if (new Set(ids).size !== ids.length) {
+		throw invalid('ids must not repeat an id.');
+	}
+	return ids;
+}
+
 function mutableInput(
 	value: Record<string, unknown>,
 ): Omit<UpdateCatalogItemInput, 'id'> {
@@ -58,18 +127,45 @@ export function createCatalogRoutes(
 	auth: AuthRuntime,
 	runtime: CatalogRuntime,
 ) {
+	/* Module-owned and never stored: a cursor names a position in one
+	   workspace's own list, so a restart invalidating one costs a client the
+	   first page. */
+	const cursorSecret = randomBytes(32);
 	const list = defineEndpoint({
 		id: 'catalog.items.list',
 		path: '/api/catalog/items',
 		methods: ['GET'],
 		access: { kind: 'permission', permission: CATALOG_PERMISSIONS.read },
 		resolveIdentity: endpointIdentityFromContext,
-		handler: async ({ octane }) =>
-			jsonResponse({
-				items: await (
+		handler: async ({ octane }) => {
+			try {
+				const tenantId = principalFromContext(octane)!.tenantId;
+				const url = new URL(octane.request.url);
+				const page = readPageQuery(url, {
+					maxLimit: LIST_PAGE_MAX_LIMIT,
+					defaultLimit: LIST_PAGE_LIMIT,
+				});
+				const query = listQuery(url);
+				const result = await (
 					await runtime.service()
-				).list(principalFromContext(octane)!.tenantId),
-			}),
+				).listPage(tenantId, {
+					...query,
+					limit: page.limit,
+					after: page.cursor
+						? decodeListCursor(cursorSecret, page.cursor, tenantId, query)
+						: null,
+				});
+				return pageResponse({
+					items: result.items,
+					limit: page.limit,
+					nextCursor: result.next
+						? encodeListCursor(cursorSecret, tenantId, query, result.next)
+						: null,
+				});
+			} catch (error) {
+				return failure(error);
+			}
+		},
 	});
 	const create = defineEndpoint({
 		id: 'catalog.items.create',
@@ -164,6 +260,46 @@ export function createCatalogRoutes(
 		'/api/catalog/items/restore',
 		'catalog.items.restore',
 	);
+	/* The bulk sibling of a lifecycle route: same permission and CSRF rule,
+	   one outcome per id through the same service path. */
+	const lifecycleMany = (
+		action: 'archiveMany' | 'restoreMany',
+		path: string,
+		id: string,
+	) =>
+		defineEndpoint({
+			id,
+			path,
+			methods: ['POST'],
+			access: { kind: 'permission', permission: CATALOG_PERMISSIONS.manage },
+			resolveIdentity: endpointIdentityFromContext,
+			handler: async ({ octane }) => {
+				const denial = sessionMutationDenial(octane, auth);
+				if (denial) return denial;
+				try {
+					const value = await readJsonObject(octane.request);
+					const service = await runtime.service();
+					const outcomes = await service[action](
+						principalFromContext(octane)!.tenantId,
+						requiredIds(value),
+						actorFromContext(octane)!,
+					);
+					return jsonResponse({ outcomes });
+				} catch (error) {
+					return failure(error);
+				}
+			},
+		});
+	const archiveMany = lifecycleMany(
+		'archiveMany',
+		'/api/catalog/items/archive-many',
+		'catalog.items.archive-many',
+	);
+	const restoreMany = lifecycleMany(
+		'restoreMany',
+		'/api/catalog/items/restore-many',
+		'catalog.items.restore-many',
+	);
 	const remove = defineEndpoint({
 		id: 'catalog.items.delete',
 		path: '/api/catalog/items/delete',
@@ -227,6 +363,8 @@ export function createCatalogRoutes(
 		update.serverRoute,
 		archive.serverRoute,
 		restore.serverRoute,
+		archiveMany.serverRoute,
+		restoreMany.serverRoute,
 		remove.serverRoute,
 		history.serverRoute,
 	] as const;
@@ -238,6 +376,8 @@ export const endpoints = [
 	'catalog.items.update',
 	'catalog.items.archive',
 	'catalog.items.restore',
+	'catalog.items.archive-many',
+	'catalog.items.restore-many',
 	'catalog.items.delete',
 	'catalog.items.history',
 ] as const;

package/agent-template/.ai/references/catalog/src/api/list-cursor.ts

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import { decodeCursor, encodeCursor, HttpProblem } from '@flowdular/sdk/server';
+import type {
+	CatalogItemKind,
+	CatalogItemStatus,
+	CatalogListSort,
+} from '../domain/types.ts';
+import type { CatalogPageKeyset } from '../services/repository.ts';
+
+/** The listing a cursor belongs to: its order and its filters. */
+export interface CatalogListQuery {
+	readonly sort: CatalogListSort;
+	readonly direction: 'asc' | 'desc';
+	readonly kind: CatalogItemKind | null;
+	readonly status: CatalogItemStatus | null;
+	readonly search: string;
+}
+
+function cursorInvalid(): HttpProblem {
+	return new HttpProblem(
+		'CURSOR_INVALID',
+		'The page cursor is not valid.',
+		400,
+	);
+}
+
+/* The filters travel as a digest so a long term cannot push the signed cursor
+   past its length bound. */
+function filtersDigest(query: CatalogListQuery): string {
+	return createHash('sha256')
+		.update(
+			JSON.stringify([query.kind ?? '', query.status ?? '', query.search]),
+		)
+		.digest('hex')
+		.slice(0, 32);
+}
+
+/* The cursor names the position and the listing it belongs to: the workspace,
+   the sort, the direction and the filters. A cursor presented with any of them
+   changed would splice two listings, so it is refused rather than reused. */
+function cursorPayload(
+	tenantId: string,
+	query: CatalogListQuery,
+	keyset: CatalogPageKeyset,
+): Record<string, string> {
+	return {
+		t: tenantId,
+		s: query.sort,
+		d: query.direction,
+		f: filtersDigest(query),
+		v: keyset.sortValue,
+		id: keyset.id,
+	};
+}
+
+export function encodeListCursor(
+	secret: Uint8Array,
+	tenantId: string,
+	query: CatalogListQuery,
+	keyset: CatalogPageKeyset,
+): string {
+	return encodeCursor(cursorPayload(tenantId, query, keyset), secret);
+}
+
+/** Throws `HttpProblem` `CURSOR_INVALID` (400) for a cursor of another listing. */
+export function decodeListCursor(
+	secret: Uint8Array,
+	cursor: string,
+	tenantId: string,
+	query: CatalogListQuery,
+): CatalogPageKeyset {
+	const payload = decodeCursor(cursor, secret);
+	const expected = cursorPayload(tenantId, query, { sortValue: '', id: '' });
+	for (const key of ['t', 's', 'd', 'f'] as const) {
+		if (payload[key] !== expected[key]) throw cursorInvalid();
+	}
+	const sortValue = payload.v;
+	const id = payload.id;
+	if (typeof sortValue !== 'string' || typeof id !== 'string') {
+		throw cursorInvalid();
+	}
+	return { sortValue, id };
+}