@flowdular/sdk 0.3.1 → 0.3.2

package/.ai/references/catalog/src/client/api.ts

@@ -1,46 +1,109 @@
 import { t } from '@flowdular/sdk/client/i18n';
 import type { HistoryPage } from '@flowdular/sdk/kernel';
 import type {
+	CatalogBulkOutcome,
 	CatalogItem,
+	CatalogItemKind,
+	CatalogItemStatus,
+	CatalogListSort,
 	CreateCatalogItemInput,
 	UpdateCatalogItemInput,
 } from '../domain/types.ts';
 
 interface ErrorEnvelope {
-	readonly error?: { readonly message?: string };
+	readonly error?: { readonly code?: string; readonly message?: string };
+}
+
+export class ApiError extends Error {
+	readonly status: number;
+	/** Stable server code; '' when the response carried none. */
+	readonly code: string;
+
+	constructor(status: number, message: string, code = '') {
+		super(message);
+		this.name = 'ApiError';
+		this.status = status;
+		this.code = code;
+	}
 }
 
 async function payload<T>(response: Response): Promise<T> {
 	const value = (await response.json()) as T & ErrorEnvelope;
 	if (!response.ok) {
-		throw new Error(value.error?.message ?? t('catalog.error.request'));
+		throw new ApiError(
+			response.status,
+			value.error?.message ?? t('catalog.error.request'),
+			value.error?.code ?? '',
+		);
 	}
 	return value;
 }
 
-export async function loadCatalogItems(): Promise<readonly CatalogItem[]> {
-	const response = await fetch('/api/catalog/items', {
+async function post<T>(
+	path: string,
+	body: unknown,
+	csrfToken: string,
+): Promise<T> {
+	const response = await fetch(path, {
+		method: 'POST',
+		headers: {
+			'content-type': 'application/json',
+			'x-csrf-token': csrfToken,
+		},
+		credentials: 'same-origin',
+		body: JSON.stringify(body),
+	});
+	return payload<T>(response);
+}
+
+export interface CatalogListRequest {
+	readonly sort: CatalogListSort;
+	readonly direction: 'asc' | 'desc';
+	readonly limit: number;
+	/** A substring of the name or the SKU; '' narrows nothing. */
+	readonly query: string;
+	readonly kind: '' | CatalogItemKind;
+	readonly status: '' | CatalogItemStatus;
+	/** The cursor that opens this page; null asks for the first one. */
+	readonly cursor: string | null;
+}
+
+export interface CatalogListPage {
+	readonly items: readonly CatalogItem[];
+	readonly page: { readonly nextCursor: string | null; readonly limit: number };
+}
+
+/** One server-sorted, server-narrowed, server-paged listing; the screen narrows nothing. */
+export async function loadCatalogItems(
+	request: CatalogListRequest,
+): Promise<CatalogListPage> {
+	const parameters = new URLSearchParams({
+		sort: request.sort,
+		direction: request.direction,
+		limit: String(request.limit),
+	});
+	if (request.query !== '') parameters.set('q', request.query);
+	if (request.kind !== '') parameters.set('kind', request.kind);
+	if (request.status !== '') parameters.set('status', request.status);
+	if (request.cursor !== null) parameters.set('cursor', request.cursor);
+	const response = await fetch('/api/catalog/items?' + parameters.toString(), {
 		headers: { accept: 'application/json' },
 		credentials: 'same-origin',
 	});
-	return (await payload<{ readonly items: readonly CatalogItem[] }>(response))
-		.items;
+	return payload<CatalogListPage>(response);
 }
 
 export async function createCatalogItem(
 	input: CreateCatalogItemInput,
 	csrfToken: string,
 ): Promise<CatalogItem> {
-	const response = await fetch('/api/catalog/items', {
-		method: 'POST',
-		headers: {
-			'content-type': 'application/json',
-			'x-csrf-token': csrfToken,
-		},
-		credentials: 'same-origin',
-		body: JSON.stringify(input),
-	});
-	return (await payload<{ readonly item: CatalogItem }>(response)).item;
+	return (
+		await post<{ readonly item: CatalogItem }>(
+			'/api/catalog/items',
+			input,
+			csrfToken,
+		)
+	).item;
 }
 
 async function mutateItem(
@@ -48,16 +111,8 @@ async function mutateItem(
 	body: unknown,
 	csrfToken: string,
 ): Promise<CatalogItem> {
-	const response = await fetch(path, {
-		method: 'POST',
-		headers: {
-			'content-type': 'application/json',
-			'x-csrf-token': csrfToken,
-		},
-		credentials: 'same-origin',
-		body: JSON.stringify(body),
-	});
-	return (await payload<{ readonly item: CatalogItem }>(response)).item;
+	return (await post<{ readonly item: CatalogItem }>(path, body, csrfToken))
+		.item;
 }
 
 export function updateCatalogItem(
@@ -81,20 +136,53 @@ export function restoreCatalogItem(
 	return mutateItem('/api/catalog/items/restore', { id }, csrfToken);
 }
 
+type OutcomesResponse = { readonly outcomes: readonly CatalogBulkOutcome[] };
+
+/* The selected rows, one outcome per id. */
+export async function archiveCatalogItems(
+	ids: readonly string[],
+	csrfToken: string,
+): Promise<readonly CatalogBulkOutcome[]> {
+	return (
+		await post<OutcomesResponse>(
+			'/api/catalog/items/archive-many',
+			{ ids },
+			csrfToken,
+		)
+	).outcomes;
+}
+
+export async function restoreCatalogItems(
+	ids: readonly string[],
+	csrfToken: string,
+): Promise<readonly CatalogBulkOutcome[]> {
+	return (
+		await post<OutcomesResponse>(
+			'/api/catalog/items/restore-many',
+			{ ids },
+			csrfToken,
+		)
+	).outcomes;
+}
+
 export async function deleteCatalogItem(
 	id: string,
 	csrfToken: string,
 ): Promise<void> {
-	const response = await fetch('/api/catalog/items/delete', {
-		method: 'POST',
-		headers: {
-			'content-type': 'application/json',
-			'x-csrf-token': csrfToken,
-		},
-		credentials: 'same-origin',
-		body: JSON.stringify({ id }),
-	});
-	await payload<{ readonly deleted: true }>(response);
+	await post<{ readonly deleted: true }>(
+		'/api/catalog/items/delete',
+		{ id },
+		csrfToken,
+	);
+}
+
+/* exports.core owns the job, its file and the screen that hands it over, so the
+   Catalog screen only starts one. */
+export async function startListExport(
+	list: string,
+	csrfToken: string,
+): Promise<void> {
+	await post<unknown>('/api/exports/start', { list }, csrfToken);
 }
 
 export async function loadCatalogItemHistory(

package/.ai/references/catalog/src/client/contribution.tsrx

@@ -13,6 +13,10 @@ export interface CatalogClientContributionOptions {
 	readonly scopes: readonly string[];
 }
 
+/* exports.core's own permission; the screen shows the export button only to a
+   principal that may start a job there. */
+const EXPORTS_MANAGE = 'exports.lists.manage';
+
 export function createCatalogClientContribution(
 	options: CatalogClientContributionOptions,
 ): ModuleClientContribution {
@@ -45,6 +49,7 @@ export function createCatalogClientContribution(
 					<CatalogView
 						csrfToken={options.csrfToken}
 						canManage={options.scopes.includes(CATALOG_PERMISSIONS.manage)}
+						canExport={options.scopes.includes(EXPORTS_MANAGE)}
 					/>,
 			},
 		],

package/.ai/references/catalog/src/client/state.ts

@@ -1,12 +1,64 @@
 import { cell, createStore } from 'segment-state';
 import type { HistoryEntry } from '@flowdular/sdk/kernel';
-import type { CatalogItem } from '../domain/types.ts';
+import type { TableSort } from '@flowdular/sdk/ui';
+import type {
+	CatalogBulkOutcome,
+	CatalogItem,
+	CatalogItemKind,
+	CatalogItemStatus,
+	CatalogListSort,
+} from '../domain/types.ts';
+import type { CatalogListPage } from './api.ts';
+
+/** `denied` is a 403 the shell could not hide; `error` is everything else. */
+export type CatalogStatus =
+	| 'idle'
+	| 'loading'
+	| 'submitting'
+	| 'denied'
+	| 'error';
+
+export type CatalogKindFilter = '' | CatalogItemKind;
+export type CatalogStatusFilter = '' | CatalogItemStatus;
+
+export const DEFAULT_CATALOG_SORTING: readonly TableSort[] = [
+	{ key: 'name', desc: false },
+];
+
+/** The screen opens on the active items; archived ones are a filter away. */
+export const DEFAULT_STATUS_FILTER: CatalogStatusFilter = 'active';
+
+/**
+ * The cursor that opened each page the reader has visited: page 0 has none,
+ * and page n holds the cursor page n - 1 answered. Going back reuses the stored
+ * cursor; a page past the stack cannot be opened.
+ */
+export type PageCursors = readonly (string | null)[];
+
+/** One listing as the server answers it: the page, its order and its filters. */
+export interface Listing {
+	readonly pageIndex: number;
+	readonly pageSize: number;
+	readonly sorting: readonly TableSort[];
+	readonly query: string;
+	readonly kind: CatalogKindFilter;
+	readonly status: CatalogStatusFilter;
+	readonly cursors: PageCursors;
+}
 
 export function createCatalogClientState() {
 	const store = createStore({
 		items: cell<readonly CatalogItem[]>([]),
 		query: '',
-		includeArchived: false,
+		/** The term the rows on screen answer; typing moves `query` ahead of it. */
+		appliedQuery: '',
+		kindFilter: cell<CatalogKindFilter>(''),
+		statusFilter: cell<CatalogStatusFilter>(DEFAULT_STATUS_FILTER),
+		sorting: cell<readonly TableSort[]>(DEFAULT_CATALOG_SORTING),
+		pageIndex: 0,
+		pageSize: 50,
+		cursors: cell<PageCursors>([null]),
+		nextCursor: cell<string | null>(null),
 		filtersOpen: false,
 		formOpen: false,
 		deleteConfirmOpen: false,
@@ -16,9 +68,123 @@ export function createCatalogClientState() {
 		historyEntries: cell<readonly HistoryEntry[]>([]),
 		historyLoading: false,
 		historyError: '',
-		status: cell<'idle' | 'loading' | 'submitting'>('idle'),
+		status: cell<CatalogStatus>('idle'),
 		error: '',
 		formSession: 0,
+		/* Row ids checked in the table; the screen owns it, the table never
+		   clears it. */
+		selectedIds: cell<ReadonlySet<string>>(new Set()),
+		confirmArchiveMany: false,
+		exportStarted: false,
 	});
 	return { store, state: store.state };
 }
+
+/** The server's sort key and direction behind the table's sorting state. */
+export function catalogSort(sorts: readonly TableSort[]): {
+	readonly sort: CatalogListSort;
+	readonly direction: 'asc' | 'desc';
+} {
+	const first = sorts[0] ?? DEFAULT_CATALOG_SORTING[0]!;
+	return {
+		sort: first.key === 'sku' || first.key === 'updatedAt' ? first.key : 'name',
+		direction: first.desc ? 'desc' : 'asc',
+	};
+}
+
+/** The cursor that opens `pageIndex`, or undefined when the reader never reached it. */
+export function pageCursor(
+	cursors: PageCursors,
+	pageIndex: number,
+): string | null | undefined {
+	return pageIndex < cursors.length ? cursors[pageIndex] : undefined;
+}
+
+/**
+ * Records what the page at `pageIndex` answered: the cursor of the page after
+ * it, or nothing when it was the last. Pages beyond the next one are dropped,
+ * since the set may have changed under them.
+ */
+export function rememberNextCursor(
+	cursors: PageCursors,
+	pageIndex: number,
+	nextCursor: string | null,
+): PageCursors {
+	const kept = cursors.slice(0, pageIndex + 1);
+	return nextCursor === null ? kept : [...kept, nextCursor];
+}
+
+export function resetPageCursors(): PageCursors {
+	return [null];
+}
+
+/**
+ * What a loaded page writes to the screen. The selection is emptied with every
+ * listing, on a page, sort or filter change as much as on a refresh, because a
+ * selected id names a row the reader saw on the page that is being replaced.
+ */
+export function loadedListing(
+	next: Listing,
+	page: CatalogListPage,
+): {
+	readonly items: readonly CatalogItem[];
+	readonly appliedQuery: string;
+	readonly pageIndex: number;
+	readonly cursors: PageCursors;
+	readonly nextCursor: string | null;
+	readonly selectedIds: ReadonlySet<string>;
+} {
+	return {
+		items: page.items,
+		appliedQuery: next.query,
+		pageIndex: next.pageIndex,
+		cursors: rememberNextCursor(
+			next.cursors,
+			next.pageIndex,
+			page.page.nextCursor,
+		),
+		nextCursor: page.page.nextCursor,
+		selectedIds: new Set(),
+	};
+}
+
+export function searchPending(query: string, applied: string): boolean {
+	return query.trim() !== applied;
+}
+
+/** The selected rows a lifecycle action may name: on screen and in the status it leaves. */
+export function bulkTargets(
+	items: readonly CatalogItem[],
+	selected: ReadonlySet<string>,
+	from: CatalogItemStatus,
+): readonly string[] {
+	return items
+		.filter((item) => selected.has(item.id) && item.status === from)
+		.map((item) => item.id);
+}
+
+/** How many ids each outcome covered, for the toast after a bulk action. */
+export function bulkOutcomeCounts(outcomes: readonly CatalogBulkOutcome[]): {
+	readonly updated: number;
+	readonly missing: number;
+	readonly refused: number;
+} {
+	let updated = 0;
+	let missing = 0;
+	let refused = 0;
+	for (const entry of outcomes) {
+		if (entry.outcome === 'updated') updated += 1;
+		else if (entry.outcome === 'not-found') missing += 1;
+		else refused += 1;
+	}
+	return { updated, missing, refused };
+}
+
+/* The server ordered the page, so a changed row keeps its place until the next
+   read; a row that is not on this page changes nothing here. */
+export function replaceItem(
+	items: readonly CatalogItem[],
+	item: CatalogItem,
+): readonly CatalogItem[] {
+	return items.map((current) => (current.id === item.id ? item : current));
+}

package/.ai/references/catalog/src/domain/lists.ts

@@ -0,0 +1,7 @@
+/**
+ * The id exports.core holds this module's items list under: the module id
+ * followed by the list key. The screen that starts a job and the server that
+ * declares the list name one string, without the client bundle importing
+ * `@flowdular/sdk/server` to read it.
+ */
+export const CATALOG_ITEMS_EXPORT_LIST_ID = 'catalog.core.items';

package/.ai/references/catalog/src/domain/types.ts

@@ -11,6 +11,26 @@ export interface CatalogItem {
 	readonly currency: string;
 	readonly status: 'active' | 'archived';
 	readonly createdAt: number;
+	readonly updatedAt: number;
+}
+
+export type CatalogItemStatus = CatalogItem['status'];
+
+/** The orders the items list answers; each one ends in the item id. */
+export const CATALOG_LIST_SORTS = ['name', 'sku', 'updatedAt'] as const;
+export type CatalogListSort = (typeof CATALOG_LIST_SORTS)[number];
+
+/** Characters a list search term may carry. */
+export const CATALOG_SEARCH_LENGTH = 120;
+
+/** Ids one bulk lifecycle call may name. */
+export const CATALOG_BULK_LIMIT = 100;
+
+export interface CatalogBulkOutcome {
+	readonly id: string;
+	readonly outcome: 'updated' | 'not-found' | 'refused';
+	/** The stable service code behind a refusal. */
+	readonly reason?: string;
 }
 
 export interface CreateCatalogItemInput {

package/.ai/references/catalog/src/platform.ts

@@ -2,9 +2,14 @@ import type {
 	PlatformServerComposition,
 	PlatformServerContext,
 } from '@flowdular/sdk/modules/auth/server';
+import {
+	EXPORT_LISTS_CAPABILITY,
+	type ExportLists,
+} from '@flowdular/sdk/modules/exports';
 import { platformVariableRegistry } from '@flowdular/sdk/kernel';
 import { registerCatalogVariableSource } from './domain/variables.ts';
 import { catalogDataClasses } from './services/data-classes.ts';
+import { createCatalogItemsListExport } from './services/item-export.ts';
 import {
 	catalogAgentTools,
 	createCatalogRoutes,
@@ -30,8 +35,23 @@ export function createServerComposition(
 		tools,
 	);
 	context.dataClasses.declare(catalogDataClasses(() => runtime.service()));
+	/* exports.core is an optional requirement, so its registry may not exist
+	   yet while this module composes; it is asked for here and again at start,
+	   and a deployment without exports.core registers nothing. */
+	let registered = false;
+	const registerLists = (): void => {
+		if (registered) return;
+		const lists = context.capabilities.get<ExportLists>(
+			EXPORT_LISTS_CAPABILITY,
+		);
+		if (!lists) return;
+		registered = true;
+		lists.register('catalog.core', [createCatalogItemsListExport(runtime)]);
+	};
+	registerLists();
 	return {
 		routes: createCatalogRoutes(context.auth, runtime),
+		start: () => registerLists(),
 		dispose: () => runtime.dispose(),
 	};
 }

package/.ai/references/catalog/src/services/catalog-service.ts

@@ -7,14 +7,22 @@ import {
 	type HistoryPage,
 	type HistoryRequest,
 } from '@flowdular/sdk/kernel';
-import type {
-	CatalogItem,
-	CatalogItemKind,
-	CreateCatalogItemInput,
-	UpdateCatalogItemInput,
+import {
+	CATALOG_BULK_LIMIT,
+	CATALOG_LIST_SORTS,
+	CATALOG_SEARCH_LENGTH,
+	type CatalogBulkOutcome,
+	type CatalogItem,
+	type CatalogItemKind,
+	type CatalogItemStatus,
+	type CatalogListSort,
+	type CreateCatalogItemInput,
+	type UpdateCatalogItemInput,
 } from '../domain/types.ts';
 import {
 	DuplicateSkuError,
+	type CatalogListPage,
+	type CatalogPageKeyset,
 	type CatalogRepository,
 	type ExportCursor,
 } from './repository.ts';
@@ -31,6 +39,32 @@ export interface CatalogIdempotencyRequest {
 /** Rows one export read carries; the whole tenant is walked page by page. */
 export const EXPORT_PAGE = 200;
 
+/** The default page of the items list, and the most a read may ask for. */
+export const LIST_PAGE_LIMIT = 50;
+export const LIST_PAGE_MAX_LIMIT = 200;
+
+/** One list page as a caller asks for it, before the service validates it. */
+export interface CatalogListInput {
+	readonly sort: CatalogListSort;
+	readonly direction: 'asc' | 'desc';
+	readonly kind: CatalogItemKind | null;
+	readonly status: CatalogItemStatus | null;
+	/** A substring of the name or the SKU; '' narrows nothing. */
+	readonly search: string;
+	readonly limit: number;
+	readonly after: CatalogPageKeyset | null;
+}
+
+export const FIRST_LIST_PAGE: CatalogListInput = {
+	sort: 'name',
+	direction: 'asc',
+	kind: null,
+	status: null,
+	search: '',
+	limit: LIST_PAGE_MAX_LIMIT,
+	after: null,
+};
+
 export class CatalogServiceError extends Error {
 	constructor(
 		readonly code: string,
@@ -68,6 +102,16 @@ function itemKind(value: CatalogItemKind): CatalogItemKind {
 	return value;
 }
 
+function itemStatus(value: CatalogItemStatus): CatalogItemStatus {
+	if (value !== 'active' && value !== 'archived') {
+		throw new CatalogServiceError(
+			'INVALID_INPUT',
+			'status must be active or archived.',
+		);
+	}
+	return value;
+}
+
 function trustedActor(actor: Actor): Actor {
 	const normalized = normalizeActor(actor);
 	if (!normalized) {
@@ -82,8 +126,52 @@ function trustedActor(actor: Actor): Actor {
 export class CatalogService {
 	constructor(private readonly repository: CatalogRepository) {}
 
-	async list(tenantId: string): Promise<readonly CatalogItem[]> {
-		return await this.repository.list(bounded(tenantId, 'tenantId', 1, 128));
+	/** One server-ordered, server-narrowed page; the only listing the module answers. */
+	async listPage(
+		tenantId: string,
+		input: CatalogListInput,
+	): Promise<CatalogListPage> {
+		if (!(CATALOG_LIST_SORTS as readonly string[]).includes(input.sort)) {
+			throw new CatalogServiceError(
+				'INVALID_INPUT',
+				`sort must be one of ${CATALOG_LIST_SORTS.join(', ')}.`,
+			);
+		}
+		if (input.direction !== 'asc' && input.direction !== 'desc') {
+			throw new CatalogServiceError(
+				'INVALID_INPUT',
+				'direction must be asc or desc.',
+			);
+		}
+		if (
+			!Number.isSafeInteger(input.limit) ||
+			input.limit < 1 ||
+			input.limit > LIST_PAGE_MAX_LIMIT
+		) {
+			throw new CatalogServiceError(
+				'INVALID_INPUT',
+				`limit must be an integer between 1 and ${LIST_PAGE_MAX_LIMIT}.`,
+			);
+		}
+		const search = bounded(input.search, 'search', 0, CATALOG_SEARCH_LENGTH);
+		return await this.repository.listPage(
+			bounded(tenantId, 'tenantId', 1, 128),
+			{
+				sort: input.sort,
+				direction: input.direction,
+				kind: input.kind === null ? null : itemKind(input.kind),
+				status: input.status === null ? null : itemStatus(input.status),
+				term: search === '' ? null : search.toLocaleLowerCase('en-US'),
+				limit: input.limit,
+				after:
+					input.after === null
+						? null
+						: {
+								sortValue: bounded(input.after.sortValue, 'cursor', 0, 512),
+								id: bounded(input.after.id, 'cursor', 1, 128),
+							},
+			},
+		);
 	}
 
 	async get(tenantId: string, id: string): Promise<CatalogItem | null> {
@@ -160,6 +248,7 @@ export class CatalogService {
 				'currency must be a three-letter ISO code.',
 			);
 		}
+		const now = Date.now();
 		return {
 			id: randomUUID(),
 			tenantId: bounded(tenantId, 'tenantId', 1, 128),
@@ -170,7 +259,8 @@ export class CatalogService {
 			basePriceMinor: input.basePriceMinor,
 			currency,
 			status: 'active',
-			createdAt: Date.now(),
+			createdAt: now,
+			updatedAt: now,
 		};
 	}
 
@@ -246,6 +336,51 @@ export class CatalogService {
 		return await this.changeStatus(tenantId, id, 'active', actor);
 	}
 
+	archiveMany(
+		tenantId: string,
+		ids: readonly string[],
+		actor: Actor,
+	): Promise<readonly CatalogBulkOutcome[]> {
+		return this.each(ids, (id) => this.archive(tenantId, id, actor));
+	}
+
+	restoreMany(
+		tenantId: string,
+		ids: readonly string[],
+		actor: Actor,
+	): Promise<readonly CatalogBulkOutcome[]> {
+		return this.each(ids, (id) => this.restore(tenantId, id, actor));
+	}
+
+	/* One outcome per id through the single-row path, so every accepted
+	   transition keeps its own history row and a refused id fails no other. */
+	private async each(
+		ids: readonly string[],
+		write: (id: string) => Promise<unknown>,
+	): Promise<readonly CatalogBulkOutcome[]> {
+		if (ids.length < 1 || ids.length > CATALOG_BULK_LIMIT) {
+			throw new CatalogServiceError(
+				'INVALID_INPUT',
+				`ids must name between 1 and ${CATALOG_BULK_LIMIT} items.`,
+			);
+		}
+		const outcomes: CatalogBulkOutcome[] = [];
+		for (const id of ids) {
+			try {
+				await write(id);
+				outcomes.push({ id, outcome: 'updated' });
+			} catch (error) {
+				if (!(error instanceof CatalogServiceError)) throw error;
+				outcomes.push(
+					error.code === 'CATALOG_ITEM_NOT_FOUND'
+						? { id, outcome: 'not-found' }
+						: { id, outcome: 'refused', reason: error.code },
+				);
+			}
+		}
+		return outcomes;
+	}
+
 	async delete(tenantId: string, id: string, actor: Actor): Promise<void> {
 		const trustedTenantId = bounded(tenantId, 'tenantId', 1, 128);
 		const trustedId = bounded(id, 'id', 1, 128);