@flowdular/sdk 0.3.0 → 0.3.2

package/.ai/references/catalog/src/services/database-repository.ts

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import type {
 	DatabaseHandle,
+	DatabaseParameter,
+	DatabaseStatement,
 	DatabaseTransaction,
 } from '@flowdular/sdk/database';
 import {
@@ -18,10 +20,12 @@ import {
 	type TrackedFields,
 	type UserActor,
 } from '@flowdular/sdk/kernel';
-import type { CatalogItem } from '../domain/types.ts';
+import type { CatalogItem, CatalogListSort } from '../domain/types.ts';
 import { databaseMigrations } from './migration.ts';
 import {
 	DuplicateSkuError,
+	type CatalogListPage,
+	type CatalogListRead,
 	type CatalogRepository,
 	type ExportCursor,
 } from './repository.ts';
@@ -36,12 +40,24 @@ import {
 const HISTORY_TABLE = 'catalog_items_history_v2';
 
 const COLUMNS = `id, tenant_id, sku, name, kind, unit, base_price_minor,
-	currency, status, created_at`;
+	currency, status, created_at, updated_at`;
 
 /* Queries stay explicit. Catalog data never passes through a SQL rewriter, and
    values always use the adapter's parameter channel. */
-const LIST = `SELECT ${COLUMNS} FROM catalog_items
-			 WHERE tenant_id = $1 ORDER BY sku_normalized, id`;
+
+/* The expression each list order sorts by, and the type the cursor value is
+   cast back to. Every expression is the second column of an index after
+   tenant_id, so a page is one index range scan. */
+const LIST_SORTS: Readonly<
+	Record<
+		CatalogListSort,
+		{ readonly expression: string; readonly cast: string }
+	>
+> = {
+	name: { expression: 'lower(name)', cast: 'text' },
+	sku: { expression: 'sku_normalized', cast: 'text' },
+	updatedAt: { expression: 'updated_at', cast: 'bigint' },
+};
 
 const LIST_FOR_EXPORT = `SELECT ${COLUMNS} FROM catalog_items
 			 WHERE tenant_id = $1
@@ -59,15 +75,16 @@ const FIND = `SELECT ${COLUMNS} FROM catalog_items WHERE tenant_id = $1 AND id =
 
 const INSERT = `INSERT INTO catalog_items
 			 (id, tenant_id, sku, sku_normalized, name, kind, unit,
-			  base_price_minor, currency, status, created_at)
-			 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`;
+			  base_price_minor, currency, status, created_at, updated_at)
+			 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)`;
 
 const UPDATE = `UPDATE catalog_items
-			 SET name = $1, kind = $2, unit = $3, base_price_minor = $4, currency = $5
-			 WHERE tenant_id = $6 AND id = $7 RETURNING ${COLUMNS}`;
+			 SET name = $1, kind = $2, unit = $3, base_price_minor = $4, currency = $5,
+			     updated_at = $6
+			 WHERE tenant_id = $7 AND id = $8 RETURNING ${COLUMNS}`;
 
-const SET_STATUS = `UPDATE catalog_items SET status = $1 WHERE tenant_id = $2 AND id = $3
-			 RETURNING ${COLUMNS}`;
+const SET_STATUS = `UPDATE catalog_items SET status = $1, updated_at = $2
+			 WHERE tenant_id = $3 AND id = $4 RETURNING ${COLUMNS}`;
 
 const DELETE = 'DELETE FROM catalog_items WHERE tenant_id = $1 AND id = $2';
 
@@ -91,6 +108,11 @@ interface CatalogItemRow {
 	currency: string;
 	status: CatalogItem['status'];
 	created_at: number | bigint | string;
+	updated_at: number | bigint | string;
+}
+
+interface CatalogListRow extends CatalogItemRow {
+	sort_value: string | number | bigint;
 }
 
 interface HistoryRow {
@@ -149,6 +171,61 @@ function fromRow(row: CatalogItemRow): CatalogItem {
 		currency: row.currency,
 		status: row.status,
 		createdAt: integer(row.created_at, 'timestamp'),
+		updatedAt: integer(row.updated_at, 'timestamp'),
+	};
+}
+
+/* The term is matched as a substring, so the three characters LIKE reads as
+   syntax are escaped; the statement declares a backslash as ESCAPE. */
+function likePattern(term: string): string {
+	return '%' + term.replace(/[\\%_]/g, (character) => '\\' + character) + '%';
+}
+
+/**
+ * One list page: the tenant predicate and the filters narrow, the keyset
+ * predicate over (sort expression, id) opens the page after the cursor, and
+ * ORDER BY names the same expression, so the read is one index range in one
+ * direction. The sort value is projected so the next cursor carries exactly
+ * what the database compared, never a JavaScript re-computation of it.
+ */
+export function listStatement(
+	tenantId: string,
+	read: CatalogListRead,
+): DatabaseStatement {
+	const parameters: DatabaseParameter[] = [tenantId];
+	const filters = ['tenant_id = $1'];
+	if (read.kind !== null) {
+		parameters.push(read.kind);
+		filters.push(`kind = $${parameters.length}`);
+	}
+	if (read.status !== null) {
+		parameters.push(read.status);
+		filters.push(`status = $${parameters.length}`);
+	}
+	if (read.term !== null) {
+		parameters.push(likePattern(read.term));
+		filters.push(
+			`(lower(name) LIKE $${parameters.length} ESCAPE '\\'
+	          OR sku_normalized LIKE $${parameters.length} ESCAPE '\\')`,
+		);
+	}
+	const sort = LIST_SORTS[read.sort];
+	if (read.after !== null) {
+		parameters.push(read.after.sortValue, read.after.id);
+		filters.push(
+			`(${sort.expression}, id) ${read.direction === 'asc' ? '>' : '<'}
+	          ($${parameters.length - 1}::${sort.cast}, $${parameters.length}::text)`,
+		);
+	}
+	parameters.push(read.limit);
+	const order = read.direction === 'asc' ? 'ASC' : 'DESC';
+	return {
+		text: `SELECT ${COLUMNS}, ${sort.expression} AS sort_value
+	       FROM catalog_items
+	       WHERE ${filters.join(' AND ')}
+	       ORDER BY ${sort.expression} ${order}, id ${order}
+	       LIMIT $${parameters.length}`,
+		parameters,
 	};
 }
 
@@ -209,17 +286,24 @@ export class DatabaseCatalogRepository implements CatalogRepository {
 		private readonly readyPromise: Promise<void> = Promise.resolve(),
 	) {}
 
-	async list(tenantId: string): Promise<readonly CatalogItem[]> {
+	async listPage(
+		tenantId: string,
+		read: CatalogListRead,
+	): Promise<CatalogListPage> {
 		await this.readyPromise;
 		const result = await this.database.transaction(
 			(transaction) =>
-				transaction.query<CatalogItemRow>({
-					text: LIST,
-					parameters: [tenantId],
-				}),
+				transaction.query<CatalogListRow>(listStatement(tenantId, read)),
 			{ access: 'read', tenantId },
 		);
-		return result.rows.map(fromRow);
+		const last = result.rows.at(-1);
+		return {
+			items: result.rows.map(fromRow),
+			next:
+				last && result.rows.length === read.limit
+					? { sortValue: String(last.sort_value), id: last.id }
+					: null,
+		};
 	}
 
 	async listItemsForExport(
@@ -355,6 +439,7 @@ export class DatabaseCatalogRepository implements CatalogRepository {
 						item.unit,
 						item.basePriceMinor,
 						item.currency,
+						Date.now(),
 						item.tenantId,
 						item.id,
 					],
@@ -390,9 +475,10 @@ export class DatabaseCatalogRepository implements CatalogRepository {
 			async (transaction) => {
 				const before = await this.#find(transaction, tenantId, id);
 				if (!before) return null;
+				if (before.status === status) return before;
 				const result = await transaction.query<CatalogItemRow>({
 					text: SET_STATUS,
-					parameters: [status, tenantId, id],
+					parameters: [status, Date.now(), tenantId, id],
 				});
 				const row = result.rows[0];
 				if (!row) return null;
@@ -486,6 +572,7 @@ export class DatabaseCatalogRepository implements CatalogRepository {
 				item.currency,
 				item.status,
 				item.createdAt,
+				item.updatedAt,
 			],
 		});
 		await appendRecordHistory(transaction, HISTORY_TABLE, {

package/.ai/references/catalog/src/services/item-export.ts

@@ -0,0 +1,81 @@
+import { randomBytes } from 'node:crypto';
+import {
+	defineListExport,
+	type DefinedListExport,
+} from '@flowdular/sdk/server';
+import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
+import { CATALOG_ITEMS_EXPORT_LIST_ID } from '../domain/lists.ts';
+import type { CatalogItem } from '../domain/types.ts';
+import type { CatalogRuntime } from '../server/runtime.ts';
+import {
+	decodeListCursor,
+	encodeListCursor,
+	type CatalogListQuery,
+} from '../api/list-cursor.ts';
+
+/* The export walks the whole workspace in SKU order, the keyset the unique
+   (tenant_id, sku_normalized) index already carries, without a filter. */
+const EXPORT_QUERY: CatalogListQuery = {
+	sort: 'sku',
+	direction: 'asc',
+	kind: null,
+	status: null,
+	search: '',
+};
+
+/**
+ * The workspace's catalog items as a CSV export. Every page is the same read
+ * the items list endpoint answers, under the tenant of the principal the job
+ * was started by and behind the permission the Catalog screen itself needs.
+ */
+export function createCatalogItemsListExport(
+	runtime: CatalogRuntime,
+): DefinedListExport {
+	const cursorSecret = randomBytes(32);
+	return defineListExport<CatalogItem>({
+		id: CATALOG_ITEMS_EXPORT_LIST_ID,
+		label: 'Catalog items',
+		permission: CATALOG_PERMISSIONS.read,
+		columns: [
+			{ key: 'sku', header: 'SKU', value: (row) => row.sku },
+			{ key: 'name', header: 'Name', value: (row) => row.name },
+			{ key: 'kind', header: 'Kind', value: (row) => row.kind },
+			{ key: 'unit', header: 'Unit', value: (row) => row.unit },
+			{
+				key: 'basePriceMinor',
+				header: 'Base price (minor units)',
+				value: (row) => row.basePriceMinor,
+			},
+			{ key: 'currency', header: 'Currency', value: (row) => row.currency },
+			{ key: 'status', header: 'Status', value: (row) => row.status },
+		],
+		page: async (principal, cursor, limit) => {
+			const page = await (
+				await runtime.service()
+			).listPage(principal.tenantId, {
+				...EXPORT_QUERY,
+				limit,
+				after:
+					cursor === null
+						? null
+						: decodeListCursor(
+								cursorSecret,
+								cursor,
+								principal.tenantId,
+								EXPORT_QUERY,
+							),
+			});
+			return {
+				rows: page.items,
+				nextCursor: page.next
+					? encodeListCursor(
+							cursorSecret,
+							principal.tenantId,
+							EXPORT_QUERY,
+							page.next,
+						)
+					: null,
+			};
+		},
+	});
+}

package/.ai/references/catalog/src/services/migration.ts

@@ -1,5 +1,8 @@
 import type { DatabaseMigration } from '@flowdular/sdk/database';
-import { postgresTenantTableState } from '@flowdular/sdk/database';
+import {
+	migrationObjectState,
+	postgresTenantTableState,
+} from '@flowdular/sdk/database';
 
 /* Every constant mirrors its migrations/<id>.up.sql file byte for byte;
    tests/migrations.test.ts fails on drift. */
@@ -108,6 +111,19 @@ CREATE POLICY catalog_idempotency_ledger_tenant_policy ON catalog_idempotency_le
   WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
 `;
 
+export const CATALOG_MIGRATION_005_LIST_INDEXES = `ALTER TABLE catalog_items ADD COLUMN IF NOT EXISTS updated_at BIGINT NOT NULL DEFAULT 0;
+-- The backfill runs as the migrator, which forced row security keeps out of
+-- every row without a tenant setting; lift the flag for the statement only.
+ALTER TABLE catalog_items NO FORCE ROW LEVEL SECURITY;
+UPDATE catalog_items SET updated_at = created_at WHERE updated_at = 0;
+ALTER TABLE catalog_items FORCE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items ALTER COLUMN updated_at DROP DEFAULT;
+CREATE INDEX IF NOT EXISTS catalog_items_tenant_name_idx
+  ON catalog_items (tenant_id, lower(name), id);
+CREATE INDEX IF NOT EXISTS catalog_items_tenant_updated_idx
+  ON catalog_items (tenant_id, updated_at, id);
+`;
+
 export const databaseMigrations: readonly DatabaseMigration[] = [
 	{
 		id: '0001_catalog_core',
@@ -168,4 +184,14 @@ export const databaseMigrations: readonly DatabaseMigration[] = [
 				],
 			),
 	},
+	{
+		id: '0005_catalog_list_indexes',
+		sql: { postgresql: CATALOG_MIGRATION_005_LIST_INDEXES },
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() => database.schema.hasColumn('catalog_items', 'updated_at'),
+				() => database.schema.hasIndex('catalog_items_tenant_name_idx'),
+				() => database.schema.hasIndex('catalog_items_tenant_updated_idx'),
+			]),
+	},
 ];

package/.ai/references/catalog/src/services/repository.ts

@@ -4,7 +4,12 @@ import type {
 	HistoryPage,
 	HistoryQuery,
 } from '@flowdular/sdk/kernel';
-import type { CatalogItem } from '../domain/types.ts';
+import type {
+	CatalogItem,
+	CatalogItemKind,
+	CatalogItemStatus,
+	CatalogListSort,
+} from '../domain/types.ts';
 import type { TargetIdempotencyRequest } from './target-idempotency.ts';
 
 export class DuplicateSkuError extends Error {
@@ -20,9 +25,33 @@ export interface ExportCursor {
 	readonly id: string;
 }
 
+/** Keyset position of a list page: the projected sort value and id of its last row. */
+export interface CatalogPageKeyset {
+	readonly sortValue: string;
+	readonly id: string;
+}
+
+/** One list page read, already validated by the service. */
+export interface CatalogListRead {
+	readonly sort: CatalogListSort;
+	readonly direction: 'asc' | 'desc';
+	readonly kind: CatalogItemKind | null;
+	readonly status: CatalogItemStatus | null;
+	/** Lower-cased substring of the name or the SKU; null narrows nothing. */
+	readonly term: string | null;
+	readonly limit: number;
+	readonly after: CatalogPageKeyset | null;
+}
+
+export interface CatalogListPage {
+	readonly items: readonly CatalogItem[];
+	/** The keyset after the last row, only when the page was full. */
+	readonly next: CatalogPageKeyset | null;
+}
+
 /** The database-agnostic business port. No driver type crosses it. */
 export interface CatalogRepository {
-	list(tenantId: string): Promise<readonly CatalogItem[]>;
+	listPage(tenantId: string, read: CatalogListRead): Promise<CatalogListPage>;
 	listItemsForExport(
 		tenantId: string,
 		after: ExportCursor | null,

package/.ai/references/catalog/tests/agent-tools.test.ts

@@ -15,6 +15,7 @@ import {
 import { CATALOG_PERMISSIONS } from '../src/acl/permissions.ts';
 import { registerCatalogVariableSource } from '../src/domain/variables.ts';
 import {
+	allItems,
 	catalogTestProvider,
 	closeCatalogTestDatabases,
 } from './support/database.ts';
@@ -161,10 +162,10 @@ describe('catalog agent tools', () => {
 		)) as CatalogItem;
 		expect(created.tenantId).toBe('tenant-a');
 		await expect(
-			(await runtime.service()).list('tenant-a'),
+			allItems(await runtime.service(), 'tenant-a'),
 		).resolves.toHaveLength(1);
 		await expect(
-			(await runtime.service()).list('tenant-b'),
+			allItems(await runtime.service(), 'tenant-b'),
 		).resolves.toHaveLength(0);
 	});
 
@@ -200,9 +201,9 @@ describe('catalog agent tools', () => {
 				})
 			).entries[0]?.actor,
 		).toEqual(actor);
-		await expect((await runtime.service()).list('tenant-b')).resolves.toEqual(
-			[],
-		);
+		await expect(
+			allItems(await runtime.service(), 'tenant-b'),
+		).resolves.toEqual([]);
 	});
 
 	it('reuses the service validation so a tool cannot persist a bad currency', async () => {

package/.ai/references/catalog/tests/client-state.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import type { CatalogItem } from '../src/domain/types.ts';
+import {
+	bulkOutcomeCounts,
+	bulkTargets,
+	catalogSort,
+	loadedListing,
+	pageCursor,
+	rememberNextCursor,
+	resetPageCursors,
+	searchPending,
+	type Listing,
+} from '../src/client/state.ts';
+
+function item(id: string, status: CatalogItem['status']): CatalogItem {
+	return {
+		id,
+		tenantId: 'tenant-a',
+		sku: id.toUpperCase(),
+		name: 'Item ' + id,
+		kind: 'product',
+		unit: 'pcs',
+		basePriceMinor: 100,
+		currency: 'EUR',
+		status,
+		createdAt: 1,
+		updatedAt: 1,
+	};
+}
+
+function listing(changes: Partial<Listing> = {}): Listing {
+	return {
+		pageIndex: 0,
+		pageSize: 50,
+		sorting: [{ key: 'name', desc: false }],
+		query: '',
+		kind: '',
+		status: 'active',
+		cursors: resetPageCursors(),
+		...changes,
+	};
+}
+
+describe('catalog client listing state', () => {
+	it('walks the cursor stack forward, back, and resets it on a new listing', () => {
+		let cursors = resetPageCursors();
+		expect(pageCursor(cursors, 0)).toBeNull();
+		expect(pageCursor(cursors, 1)).toBeUndefined();
+
+		cursors = rememberNextCursor(cursors, 0, 'c1');
+		expect(pageCursor(cursors, 1)).toBe('c1');
+		cursors = rememberNextCursor(cursors, 1, 'c2');
+		expect(cursors).toEqual([null, 'c1', 'c2']);
+
+		/* Going back reuses the stored cursor and drops what lay beyond. */
+		cursors = rememberNextCursor(cursors, 0, 'c1-again');
+		expect(cursors).toEqual([null, 'c1-again']);
+		expect(pageCursor(cursors, 2)).toBeUndefined();
+
+		/* The last page answers no cursor, so nothing follows it. */
+		cursors = rememberNextCursor(cursors, 1, null);
+		expect(cursors).toEqual([null, 'c1-again']);
+
+		expect(resetPageCursors()).toEqual([null]);
+	});
+
+	it('writes a loaded page with an empty selection', () => {
+		const loaded = loadedListing(
+			listing({ pageIndex: 1, cursors: [null, 'c1'], query: 'bolt' }),
+			{
+				items: [item('a', 'active')],
+				page: { nextCursor: 'c2', limit: 50 },
+			},
+		);
+		expect(loaded).toEqual({
+			items: [item('a', 'active')],
+			appliedQuery: 'bolt',
+			pageIndex: 1,
+			cursors: [null, 'c1', 'c2'],
+			nextCursor: 'c2',
+			selectedIds: new Set(),
+		});
+	});
+
+	it('maps the table sort to the server keys', () => {
+		expect(catalogSort([])).toEqual({ sort: 'name', direction: 'asc' });
+		expect(catalogSort([{ key: 'sku', desc: true }])).toEqual({
+			sort: 'sku',
+			direction: 'desc',
+		});
+		expect(catalogSort([{ key: 'updatedAt', desc: false }])).toEqual({
+			sort: 'updatedAt',
+			direction: 'asc',
+		});
+		expect(catalogSort([{ key: 'price', desc: false }])).toEqual({
+			sort: 'name',
+			direction: 'asc',
+		});
+	});
+
+	it('names only the selected rows in the status the action leaves', () => {
+		const items = [
+			item('a', 'active'),
+			item('b', 'archived'),
+			item('c', 'active'),
+		];
+		const selected = new Set(['a', 'b', 'missing']);
+		expect(bulkTargets(items, selected, 'active')).toEqual(['a']);
+		expect(bulkTargets(items, selected, 'archived')).toEqual(['b']);
+	});
+
+	it('counts bulk outcomes and detects a pending search', () => {
+		expect(
+			bulkOutcomeCounts([
+				{ id: 'a', outcome: 'updated' },
+				{ id: 'b', outcome: 'not-found' },
+				{ id: 'c', outcome: 'refused', reason: 'X' },
+				{ id: 'd', outcome: 'updated' },
+			]),
+		).toEqual({ updated: 2, missing: 1, refused: 1 });
+		expect(searchPending(' bolt ', 'bolt')).toBe(false);
+		expect(searchPending('bolt', '')).toBe(true);
+	});
+});