@flowdular/sdk 0.2.4 → 0.3.0

package/modules/search/src/client/api.ts

@@ -0,0 +1,157 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type {
+	RecentQuery,
+	SearchProviderSummary,
+	SearchResultHit,
+} from '../domain/types.ts';
+
+interface ErrorEnvelope {
+	readonly error?: {
+		readonly code?: string;
+		readonly message?: string;
+	};
+}
+
+/** A failed request with the server's stable code, so a screen can translate it. */
+export class SearchApiError extends Error {
+	readonly status: number;
+	readonly code: string;
+
+	constructor(status: number, code: string, message: string) {
+		super(message);
+		this.name = 'SearchApiError';
+		this.status = status;
+		this.code = code;
+	}
+}
+
+/**
+ * The server message is English and written for an operator. A code this module
+ * knows becomes translated copy; anything else keeps the server's own sentence
+ * rather than hiding what went wrong behind a generic line.
+ */
+export function searchErrorMessage(
+	error: unknown,
+	fallbackKey: string,
+): string {
+	if (error instanceof SearchApiError) {
+		const key = 'search.error.code.' + error.code;
+		const translated = t(key);
+		if (translated !== key) return translated;
+		return error.message;
+	}
+	if (error instanceof Error && error.message !== '') return error.message;
+	return t(fallbackKey);
+}
+
+async function payload<T>(response: Response): Promise<T> {
+	const value = (await response.json()) as T & ErrorEnvelope;
+	if (!response.ok) {
+		throw new SearchApiError(
+			response.status,
+			value.error?.code ?? 'REQUEST_FAILED',
+			value.error?.message ?? t('search.error.request'),
+		);
+	}
+	return value;
+}
+
+export interface SearchPage {
+	readonly hits: readonly SearchResultHit[];
+	readonly nextCursor: string | null;
+	readonly providers: readonly SearchProviderSummary[];
+	readonly unavailable: readonly string[];
+}
+
+export interface SearchRequest {
+	readonly query: string;
+	readonly provider?: string;
+	readonly cursor?: string | null;
+	readonly limit?: number;
+	/** Keeps the query in recall. Sent only for a submit the member meant. */
+	readonly remember?: boolean;
+	/** Aborted by the palette when the member types on. */
+	readonly signal?: AbortSignal;
+}
+
+interface SearchResponse {
+	readonly items: readonly SearchResultHit[];
+	readonly page: { readonly nextCursor: string | null };
+	readonly providers: readonly SearchProviderSummary[];
+	readonly unavailable: readonly string[];
+}
+
+export async function searchRecords(input: SearchRequest): Promise<SearchPage> {
+	const parameters = new URLSearchParams({ q: input.query });
+	if (input.provider) parameters.set('provider', input.provider);
+	if (input.cursor) parameters.set('cursor', input.cursor);
+	if (input.limit) parameters.set('limit', String(input.limit));
+	if (input.remember) parameters.set('remember', '1');
+	const response = await payload<SearchResponse>(
+		await fetch('/api/search?' + parameters.toString(), {
+			headers: { accept: 'application/json' },
+			credentials: 'same-origin',
+			...(input.signal ? { signal: input.signal } : {}),
+		}),
+	);
+	return {
+		hits: response.items,
+		nextCursor: response.page.nextCursor,
+		providers: response.providers,
+		unavailable: response.unavailable,
+	};
+}
+
+export async function loadRecentQueries(): Promise<readonly RecentQuery[]> {
+	return (
+		await payload<{ readonly items: readonly RecentQuery[] }>(
+			await fetch('/api/search/recent', {
+				headers: { accept: 'application/json' },
+				credentials: 'same-origin',
+			}),
+		)
+	).items;
+}
+
+/**
+ * Keeps a query in recall without searching again. It is sent while the screen
+ * is already navigating to the record the member opened, so `keepalive` is what
+ * makes the browser finish the request after the view is gone.
+ */
+export async function rememberQuery(
+	query: string,
+	csrfToken: string,
+): Promise<boolean> {
+	return (
+		await payload<{ readonly recorded: boolean }>(
+			await fetch('/api/search/recent', {
+				method: 'POST',
+				headers: {
+					accept: 'application/json',
+					'content-type': 'application/json',
+					'x-csrf-token': csrfToken,
+				},
+				credentials: 'same-origin',
+				keepalive: true,
+				body: JSON.stringify({ q: query }),
+			}),
+		)
+	).recorded;
+}
+
+export async function clearRecentQueries(csrfToken: string): Promise<number> {
+	return (
+		await payload<{ readonly cleared: number }>(
+			await fetch('/api/search/recent/clear', {
+				method: 'POST',
+				headers: {
+					accept: 'application/json',
+					'content-type': 'application/json',
+					'x-csrf-token': csrfToken,
+				},
+				credentials: 'same-origin',
+				body: '{}',
+			}),
+		)
+	).cleared;
+}

package/modules/search/src/client/contribution.tsrx

@@ -0,0 +1,31 @@
+import { type ModuleClientContribution } from '@flowdular/sdk/client';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import {
+	createSearchCommandContribution,
+	searchNavigation,
+	SEARCH_VIEWS,
+} from './navigation.ts';
+import { SearchView } from './SearchView.tsrx';
+import './search.css';
+
+export interface SearchClientContributionOptions {
+	readonly csrfToken: string;
+}
+
+export function createSearchClientContribution(
+	options: SearchClientContributionOptions,
+): ModuleClientContribution {
+	return {
+		moduleId: 'search.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: searchNavigation,
+		views: [
+			{
+				id: SEARCH_VIEWS.search,
+				render: () => <SearchView csrfToken={options.csrfToken} />,
+			},
+		],
+		commandSearch: createSearchCommandContribution(options.csrfToken),
+	};
+}

package/modules/search/src/client/index.ts

@@ -0,0 +1,17 @@
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createSearchClientContribution as canonicalContribution } from './contribution.tsrx';
+
+export { createSearchClientContribution } from './contribution.tsrx';
+export type { SearchClientContributionOptions } from './contribution.tsrx';
+export { SearchView } from './SearchView.tsrx';
+export { SEARCH_VIEWS, workspaceRouteHref } from './navigation.ts';
+
+/* Canonical entry used by the generated platform composition. */
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({ csrfToken: context.csrfToken });
+}

package/modules/search/src/client/navigation.ts

@@ -0,0 +1,97 @@
+import type {
+	CommandSearchContribution,
+	CommandSearchHit,
+	NavigationContribution,
+} from '@flowdular/sdk/client';
+import { t } from '@flowdular/sdk/client/i18n';
+import { SEARCH_PERMISSIONS } from '../acl/permissions.ts';
+import { SEARCH_LIMITS } from '../domain/types.ts';
+import { rememberQuery, searchRecords } from './api.ts';
+
+export const SEARCH_VIEWS = { search: 'search' } as const;
+
+/**
+ * A workspace-relative route as a shell href. The shell owns the slug, so it is
+ * read back from the address bar rather than threaded through every component.
+ */
+export function workspaceRouteHref(
+	route: string,
+	pathname: string,
+	basePath: string,
+): string {
+	const segments = pathname.split('/').filter(Boolean);
+	const inWorkspace =
+		segments[0] === basePath.slice(1) ? segments.slice(1) : [];
+	const workspaceSlug = inWorkspace.length > 1 ? inWorkspace[0] : null;
+	const safe = route.startsWith('/') && !route.startsWith('//') ? route : '/';
+	return workspaceSlug === null
+		? basePath + safe
+		: basePath + '/' + workspaceSlug + safe;
+}
+
+/* Labels are read every render so a locale change reaches an entry the shell
+   built once. */
+export const searchNavigation: readonly NavigationContribution[] = [
+	{
+		id: 'search.navigation',
+		viewId: SEARCH_VIEWS.search,
+		group: 'Workspace',
+		get label() {
+			return t('search.navigation.label');
+		},
+		glyph: 'search',
+		get description() {
+			return t('search.navigation.description');
+		},
+		scope: SEARCH_PERMISSIONS.read,
+		order: 15,
+	},
+];
+
+/** Hits the palette asks for in one pass; it groups and caps them per provider. */
+const PALETTE_LIMIT = 20;
+
+/**
+ * The palette's record hits. The shell debounces and aborts, so the search stays
+ * a plain request: one page, mapped into the shell's own hit shape.
+ *
+ * Opening one of them is the member saying the query was the right one, exactly
+ * as on the search screen, so it is kept in recall by the same keepalive write
+ * the browser finishes while the shell is already navigating. The query is read
+ * back from the answer the opened hit belongs to, not from whatever the palette
+ * box holds by then, and an answer the palette replaced takes its queries with
+ * it, so recall never keeps a term that found nothing.
+ */
+export function createSearchCommandContribution(
+	csrfToken: string,
+): CommandSearchContribution {
+	let answered = new Map<string, string>();
+	return {
+		id: 'search.core.records',
+		scope: SEARCH_PERMISSIONS.read,
+		order: 10,
+		search: async ({ query, signal }): Promise<readonly CommandSearchHit[]> => {
+			const page = await searchRecords({ query, limit: PALETTE_LIMIT, signal });
+			const labels = new Map(
+				page.providers.map((provider) => [provider.key, provider.label]),
+			);
+			const hits = page.hits.map((hit) => ({
+				id: hit.provider + ':' + hit.ref,
+				provider: hit.provider,
+				providerLabel: labels.get(hit.provider) ?? hit.provider,
+				title: hit.title,
+				snippet: hit.snippet,
+				viewId: hit.viewId,
+				route: hit.route,
+			}));
+			answered = new Map(hits.map((hit) => [hit.id, query.trim()]));
+			return hits;
+		},
+		onOpen: async (hit): Promise<void> => {
+			const term = answered.get(hit.id);
+			if (term === undefined || term.length < SEARCH_LIMITS.queryMinimum)
+				return;
+			await rememberQuery(term, csrfToken);
+		},
+	};
+}

package/modules/search/src/client/search.css

@@ -0,0 +1,56 @@
+/* Search module: composites specific to this module. Primitives (buttons,
+   fields, tags, cards) come from @flowdular/sdk/ui and are not restyled here. */
+
+.search-recent__list {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 8px;
+	padding: 12px 20px 16px;
+}
+
+/* A recall entry is a whole query, not a label, so it is a button sized by its
+   text. Promotion candidate: a shared chip once a second module needs one. */
+.search-recent__item {
+	max-width: 100%;
+	overflow: hidden;
+	padding: 4px 10px;
+	font-size: var(--text-xs);
+	color: var(--ink-2);
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	cursor: pointer;
+	background: var(--surface);
+	border: 1px solid var(--line);
+	border-radius: 999px;
+}
+
+.search-recent__item:hover {
+	color: var(--primary);
+	border-color: var(--primary);
+}
+
+/* The hit cell is the whole record: the title and its snippet share one link so
+   the entire row target is reachable with one tab stop. */
+.search-hit {
+	display: flex;
+	flex-direction: column;
+	gap: 2px;
+	color: inherit;
+	text-decoration: none;
+}
+
+.search-hit:hover b {
+	color: var(--primary);
+}
+
+/* The search field submits on Enter, which is what records the query; the form
+   is a wrapper only and must not change the field's own layout. */
+.search-submit {
+	display: contents;
+}
+
+.search-more {
+	display: flex;
+	justify-content: flex-end;
+	padding: 12px 14px;
+}

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

@@ -0,0 +1,113 @@
+import { cell, createStore } from 'segment-state';
+import {
+	SEARCH_LIMITS,
+	type RecentQuery,
+	type SearchProviderSummary,
+	type SearchResultHit,
+} from '../domain/types.ts';
+import type { SearchPage } from './api.ts';
+
+/** `denied` is a 403 the shell could not hide; `error` is everything else. */
+export type ScreenStatus =
+	| 'idle'
+	| 'loading'
+	| 'submitting'
+	| 'denied'
+	| 'error';
+
+export function createSearchClientState() {
+	const store = createStore({
+		hits: cell<readonly SearchResultHit[]>([]),
+		providers: cell<readonly SearchProviderSummary[]>([]),
+		unavailable: cell<readonly string[]>([]),
+		recent: cell<readonly RecentQuery[]>([]),
+		status: cell<ScreenStatus>('idle'),
+		error: '',
+		query: '',
+		/* '' searches every provider the member may see. */
+		providerFilter: '',
+		filtersOpen: false,
+		nextCursor: cell<string | null>(null),
+		/** True once a query has been run, so "no hits" is not shown before one. */
+		searched: false,
+	});
+	return { store, state: store.state };
+}
+
+export type SearchClientState = ReturnType<typeof createSearchClientState>;
+
+/**
+ * One answered page on the screen. `append` is the load-more path: the hits
+ * that arrived under a cursor extend the list instead of replacing it, and the
+ * new cursor is what a further page resumes from.
+ */
+export function applyPage(
+	client: SearchClientState,
+	page: SearchPage,
+	options: { readonly term: string; readonly append: boolean },
+): void {
+	client.store.act((transaction) => {
+		transaction.set(
+			client.state.hits,
+			options.append
+				? [...transaction.get(client.state.hits), ...page.hits]
+				: page.hits,
+		);
+		transaction.set(client.state.providers, page.providers);
+		transaction.set(client.state.unavailable, page.unavailable);
+		transaction.set(client.state.nextCursor, page.nextCursor);
+		transaction.set(client.state.status, 'idle');
+		/* The first load asks with an empty query to get the provider list, and
+		   that must not turn the empty table into "nothing matched". */
+		transaction.set(
+			client.state.searched,
+			options.term.length >= SEARCH_LIMITS.queryMinimum,
+		);
+	}, 'search/loaded');
+}
+
+/**
+ * Whether an answer that has just arrived may still be written. Two things move
+ * while a request is in flight and each one alone invalidates it: a newer
+ * request was dispatched, and only the newest may write; and the member changed
+ * the term, which no answer to the old term describes, including back under the
+ * minimum where the screen shows nothing at all.
+ *
+ * The term is compared against the box rather than counted out by a ticket
+ * because the screen's one provider-list load asks with no term: retiring every
+ * request on a term under the minimum would retire that load at mount, before
+ * the member has typed anything, and leave the provider filter empty for good.
+ */
+export function answerIsCurrent(
+	client: SearchClientState,
+	term: string,
+	ticket: number,
+	requests: { readonly current: number },
+): boolean {
+	return (
+		requests.current === ticket &&
+		client.store.get(client.state.query).trim() === term
+	);
+}
+
+/**
+ * Back below the minimum query length. The hits of the longer term are gone,
+ * so they are dropped with the page position rather than left on screen under
+ * a term that never produced them.
+ */
+export function clearResults(client: SearchClientState): void {
+	client.store.act((transaction) => {
+		transaction.set(client.state.hits, []);
+		transaction.set(client.state.unavailable, []);
+		transaction.set(client.state.nextCursor, null);
+		transaction.set(client.state.searched, false);
+		transaction.set(client.state.status, 'idle');
+	}, 'search/cleared');
+}
+
+/** The provider label behind a hit, or its key when the provider is unknown. */
+export function providerLabels(
+	providers: readonly SearchProviderSummary[],
+): ReadonlyMap<string, string> {
+	return new Map(providers.map((provider) => [provider.key, provider.label]));
+}

package/modules/search/src/domain/data-classes.ts

@@ -0,0 +1,73 @@
+import type {
+	DataClassDeclaration,
+	DataClassExportSummary,
+} from '@flowdular/sdk/kernel';
+import type { SearchRepository } from '../services/repository.ts';
+
+/** Matches the spec entity and the class the spec names, search.core.recent-queries. */
+export const SEARCH_RECENT_QUERY_CLASS = 'recent-queries';
+export const SEARCH_RECENT_RETENTION_DAYS = 90;
+
+/** Rows read per page while exporting, so a large workspace stays bounded. */
+const EXPORT_PAGE = 500;
+
+/** Rows one sweep pass may remove, whatever the registry asks for. */
+export const SEARCH_MAX_SWEEP_BATCH = 10_000;
+
+/**
+ * The only data search.core holds. Provider records belong to the modules that
+ * own them and are declared by those modules, so nothing here reaches another
+ * module's table.
+ */
+export function searchDataClasses(
+	repository: () => Promise<SearchRepository>,
+): readonly DataClassDeclaration[] {
+	return [
+		{
+			key: SEARCH_RECENT_QUERY_CLASS,
+			label: 'Recent searches',
+			defaultRetentionDays: SEARCH_RECENT_RETENTION_DAYS,
+			exportable: true,
+			sweep: async ({ tenantId, cutoff, limit }) => ({
+				removed: await (
+					await repository()
+				).sweepRecent(
+					tenantId,
+					cutoff.getTime(),
+					Math.min(Math.max(Math.trunc(limit), 1), SEARCH_MAX_SWEEP_BATCH),
+				),
+			}),
+			/* Paged by id alone: a row's `ran_at` is rewritten when the member runs
+			   the same query again, so a keyset on it would hand the walk the same
+			   row twice. The range is tracked instead of read off the order. */
+			export: async ({ tenantId, sink }): Promise<DataClassExportSummary> => {
+				const store = await repository();
+				let afterId = '';
+				let rows = 0;
+				let from: number | null = null;
+				let to: number | null = null;
+				for (;;) {
+					const page = await store.exportRecent(tenantId, afterId, EXPORT_PAGE);
+					for (const row of page) {
+						await sink.write({
+							accountId: row.accountId,
+							query: row.query,
+							ranAt: new Date(row.ranAt).toISOString(),
+						});
+						if (from === null || row.ranAt < from) from = row.ranAt;
+						if (to === null || row.ranAt > to) to = row.ranAt;
+						rows += 1;
+					}
+					const last = page.at(-1);
+					if (!last || page.length < EXPORT_PAGE) break;
+					afterId = last.id;
+				}
+				return {
+					rows,
+					from: from === null ? null : new Date(from),
+					to: to === null ? null : new Date(to),
+				};
+			},
+		},
+	];
+}

package/modules/search/src/domain/providers.ts

@@ -0,0 +1,88 @@
+/**
+ * The public cross-module surface. A module that owns searchable records
+ * resolves it while it composes through
+ * `context.capabilities.get<SearchProviderRegistry>(SEARCH_PROVIDERS_CAPABILITY)`
+ * and continues without registering when it is absent, so a deployment without
+ * search.core still boots. Registration closes when search.core starts.
+ */
+export const SEARCH_PROVIDERS_CAPABILITY = 'search.providers.v1';
+
+/** Who is asking. The provider reads it; it never comes from the request. */
+export interface SearchPrincipal {
+	readonly accountId: string;
+	readonly tenantId: string;
+	readonly scopes: readonly string[];
+}
+
+export interface SearchProviderQuery {
+	readonly tenantId: string;
+	readonly principal: SearchPrincipal;
+	/** Normalized and bounded by search.core: 2 to 200 characters, no NUL. */
+	readonly query: string;
+	/** Most hits this call may answer with; a longer page is refused. */
+	readonly limit: number;
+	/** The provider's own opaque cursor, exactly as it last returned it. */
+	readonly cursor?: string;
+	/**
+	 * Aborted when the provider's time budget expires. A provider that passes it
+	 * to its own statements stops working for an answer nobody waits for; one
+	 * that ignores it is still abandoned, it just keeps running.
+	 */
+	readonly signal?: AbortSignal;
+}
+
+export interface SearchHit {
+	/** Stable reference to the provider's record, unique inside the provider. */
+	readonly ref: string;
+	readonly title: string;
+	readonly snippet: string;
+	/** The client view the hit opens: a navigation contribution's view id. */
+	readonly viewId: string;
+	/** Workspace-relative path starting with "/", such as `/users?member=a1`. */
+	readonly route: string;
+	/**
+	 * Orders hits inside one provider. search.core never compares it across
+	 * providers, so a provider is free to score in whatever space it likes.
+	 */
+	readonly score: number;
+}
+
+export interface SearchProviderPage {
+	readonly hits: readonly SearchHit[];
+	/** Null when the provider has nothing further for this query. */
+	readonly nextCursor: string | null;
+}
+
+export interface SearchProvider {
+	/** `^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$`, unique across every module. */
+	readonly key: string;
+	readonly label: string;
+	/** The scope a member needs before this provider is asked at all. */
+	readonly permission: string;
+	search(input: SearchProviderQuery): Promise<SearchProviderPage>;
+}
+
+export interface SearchProviderRegistry {
+	/**
+	 * Adds the module's providers in the order given. Provider order is merge
+	 * order, and the order modules compose in is the order they register in.
+	 * Throws a `SearchServiceError` with a stable code for a malformed provider,
+	 * a duplicate key, or a call made after search.core started.
+	 */
+	register(moduleId: string, providers: readonly SearchProvider[]): void;
+}
+
+/** Longest values the registry and the hit reader accept. */
+export const SEARCH_PROVIDER_LIMITS = {
+	moduleId: 64,
+	key: 96,
+	label: 120,
+	permission: 96,
+	ref: 200,
+	title: 200,
+	snippet: 400,
+	viewId: 64,
+	route: 512,
+	cursor: 256,
+	providers: 64,
+} as const;

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

@@ -0,0 +1,56 @@
+/** A registered provider as the workspace sees it. */
+export interface SearchProviderSummary {
+	readonly key: string;
+	readonly moduleId: string;
+	readonly label: string;
+	readonly permission: string;
+}
+
+/** A hit as the API answers with it: what the provider returned, plus its key. */
+export interface SearchResultHit {
+	readonly provider: string;
+	readonly ref: string;
+	readonly title: string;
+	readonly snippet: string;
+	readonly viewId: string;
+	readonly route: string;
+	readonly score: number;
+}
+
+/**
+ * Where the next page resumes. The merge is provider-major, so one provider
+ * key, that provider's own cursor and an offset inside its current batch are
+ * the whole position: the cursor never grows with the number of providers.
+ */
+export interface SearchCursor {
+	readonly provider: string;
+	readonly cursor: string;
+	readonly skip: number;
+}
+
+export interface SearchResultPage {
+	readonly hits: readonly SearchResultHit[];
+	readonly nextCursor: SearchCursor | null;
+	/** The providers this principal may see, in merge order. */
+	readonly providers: readonly SearchProviderSummary[];
+	/** Keys of providers that failed or ran out of time on this request. */
+	readonly unavailable: readonly string[];
+}
+
+export interface RecentQuery {
+	readonly query: string;
+	readonly ranAt: number;
+}
+
+/** Bounds search.core enforces on its own data and input. */
+export const SEARCH_LIMITS = {
+	/** Shorter than this answers navigation entries only, and asks no provider. */
+	queryMinimum: 2,
+	queryMaximum: 200,
+	/** Recent queries kept per member and workspace. */
+	recentPerMember: 50,
+	accountId: 128,
+	tenantId: 128,
+	pageLimit: 50,
+	pageMaximum: 100,
+} as const;