@conduction/nextcloud-vue 2.119.0 → 2.121.0

package/src/components/CnTimelineWidget/CnTimelineWidget.vue

@@ -1,7 +1,16 @@
 <!-- SPDX-License-Identifier: EUPL-1.2 -->
 <!-- SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl> -->
 <template>
-	<section class="cn-timeline-widget" data-testid="cn-timeline-widget" :aria-busy="loading ? 'true' : 'false'">
+	<CnTimelineManage v-if="manage"
+		:register="resolvedRegister"
+		:schema="resolvedSchema"
+		:objectId="resolvedObjectId"
+		:apiBase="apiBase"
+		:content="content" />
+	<section v-else
+		class="cn-timeline-widget"
+		data-testid="cn-timeline-widget"
+		:aria-busy="loading ? 'true' : 'false'">
 		<h3 v-if="resolvedTitle" class="cn-timeline-widget__title">
 			{{ resolvedTitle }}
 		</h3>
@@ -53,6 +62,7 @@
 <script>
 import { getLanguage, translate as t } from '@nextcloud/l10n'
 import { NcLoadingIcon, NcNoteCard } from '@nextcloud/vue'
+import CnTimelineManage from './CnTimelineManage.vue'
 import { auditEvents, fieldEvents, listEvents, relatedEvents, sortEvents, timelineEntryEvents } from '../../utils/timelineEvents.js'
 import { userLocale } from '../../utils/userLocale.js'
 
@@ -74,6 +84,12 @@ import { userLocale } from '../../utils/userLocale.js'
  * Oldest first by default (`order: 'desc'` flips it). A moment after now is
  * marked upcoming, in words as well as style.
  *
+ * `manage: true` swaps the read view for the manage view (CnTimelineManage)
+ * over OpenRegister's timeline alone: kind chips, a visibility filter, pin,
+ * follow-up, a note composer with standard text blocks, CSV export, and
+ * `entryActions` that open a registry modal on an entry. The manage controls
+ * are drawn only when the timeline read answers `canManage: true`.
+ *
  * ```json
  * { "type": "timeline", "content": {
  *   "title": "Timeline",
@@ -95,6 +111,7 @@ export default {
 	name: 'CnTimelineWidget',
 
 	components: {
+		CnTimelineManage,
 		NcLoadingIcon,
 		NcNoteCard,
 	},
@@ -123,7 +140,7 @@ export default {
 		object: { type: Object, default: null },
 		/** Card title override. */
 		title: { type: String, default: '' },
-		/** Stored widget content: `{ title, fields, related, auditTrail, timeline, order }`. */
+		/** Stored widget content: `{ title, fields, related, auditTrail, timeline, order, manage, entryActions, ... }`. */
 		content: { type: Object, default: () => ({}) },
 		/** OpenRegister API base. */
 		apiBase: { type: String, default: '/apps/openregister/api' },
@@ -172,6 +189,15 @@ export default {
 			return this.object || this.ctx.object || this.ctx.objectData || this.fetchedObject || null
 		},
 
+		/**
+		 * Whether the manage view renders instead of the read view.
+		 *
+		 * @return {boolean}
+		 */
+		manage() {
+			return this.content.manage === true
+		},
+
 		resolvedTitle() {
 			const raw = this.title || this.content.title || ''
 			return raw ? this.translate(raw) : ''
@@ -313,7 +339,7 @@ export default {
 			const register = this.resolvedRegister
 			const schema = this.resolvedSchema
 			const seq = ++this.loadSeq
-			if (!id || !register || !schema) {
+			if (!id || !register || !schema || this.manage) {
 				return
 			}
 			const [{ default: axios }, { generateUrl }] = await Promise.all([

package/src/components/CnWidgetGrid/builtInWidgets.js

@@ -26,6 +26,7 @@ import CnNoticeWidget from '../CnNoticeWidget/CnNoticeWidget.vue'
 import CnObjectDataWidget from '../CnObjectDataWidget/CnObjectDataWidget.vue'
 import CnObjectGeoWidget from '../CnObjectGeoWidget/CnObjectGeoWidget.vue'
 import CnObjectMetadataWidget from '../CnObjectMetadataWidget/CnObjectMetadataWidget.vue'
+import CnObjectTranslationsWidget from '../CnObjectTranslationsWidget/CnObjectTranslationsWidget.vue'
 import CnRelatedObjectsWidget from '../CnRelatedObjectsWidget/CnRelatedObjectsWidget.vue'
 import CnSavedViewAlertWidget from '../CnSavedViewAlertWidget/CnSavedViewAlertWidget.vue'
 import CnTextWidget from '../CnTextWidget/CnTextWidget.vue'
@@ -74,6 +75,10 @@ import CnWidgetObjectTable from '../CnWidgetObjectTable/CnWidgetObjectTable.vue'
  * data — the intended remedy for a deep menu group collapsed into one
  * top-level entry via `menu-layout.json` relocations.
  *
+ * The `object-translations` key places CnObjectTranslationsWidget: the
+ * object's translatable properties per register language, with completeness
+ * chips and one save (register / schema / objectId via the detail-context merge).
+ *
  * @type {Record<string, import('vue').Component>}
  */
 export const BUILT_IN_WIDGETS = {
@@ -97,4 +102,5 @@ export const BUILT_IN_WIDGETS = {
 	divider: CnDividerWidget,
 	'saved-view-alert': CnSavedViewAlertWidget,
 	exports: CnExportsWidget,
+	'object-translations': CnObjectTranslationsWidget,
 }

package/src/components/CnWidgetGrid/registerDashboardWidgets.js

@@ -37,6 +37,7 @@ import CnRelatedObjectsWidgetForm from '../CnRelatedObjectsWidgetForm/CnRelatedO
 import CnRetentionWidget from '../CnRetentionWidget/CnRetentionWidget.vue'
 import CnSavedViewWidget2 from '../CnSavedViewWidget/CnSavedViewWidget.vue'
 import CnSavedViewWidgetForm2 from '../CnSavedViewWidgetForm/CnSavedViewWidgetForm.vue'
+import CnSchemaRulesWidget from '../CnSchemaRulesWidget/CnSchemaRulesWidget.vue'
 import CnStackedBarWidget from '../CnStackedBarWidget/CnStackedBarWidget.vue'
 import CnStackedBarWidgetForm from '../CnStackedBarWidgetForm/CnStackedBarWidgetForm.vue'
 import CnStagesWidget from '../CnStagesWidget/CnStagesWidget.vue'
@@ -311,6 +312,15 @@ registerDashboardWidget('retention', {
 	ownsTitle: true,
 })
 
+registerDashboardWidget('schema-rules', {
+	renderer: CnSchemaRulesWidget,
+	form: null,
+	defaultContent: { register: '', schema: '', objectId: '' },
+	displayName: 'Schema rules',
+	icon: 'ScaleBalance',
+	surfaces: ['detail-page'],
+})
+
 registerDashboardWidget('plan', {
 	renderer: CnPlanWidget,
 	form: null,

package/src/components/index.js

@@ -77,6 +77,7 @@ export { CnRegisterSchemaSelect } from './CnRegisterSchemaSelect/index.js'
 export { CnThemePreview } from './CnThemePreview/index.js'
 export { CnRelationshipGraph } from './CnRelationshipGraph/index.js'
 export { CnGraphCanvas } from './CnGraphCanvas/index.js'
+export { CnStateMachineEditor } from './CnStateMachineEditor/index.js'
 export { CnFlowDetail, CnFlowIndexPage, CnFlowSidebar } from './CnFlowDetail/index.js'
 export { CnIcon, ICON_MAP, registerIcons } from './CnIcon/index.js'
 export {
@@ -167,7 +168,10 @@ export { CnJourneyDialog } from './CnJourneyDialog/index.js'
 export { CnProcessSteps } from './CnProcessSteps/index.js'
 export { CnSubObjectsField } from './CnSubObjectsField/index.js'
 export { CnIntegrationTab } from './CnIntegrationTab/index.js'
+export { CnAiFeaturesWidget } from './CnAiFeaturesWidget/index.js'
 export { CnObjectAccessTab } from './CnObjectAccessTab/index.js'
+export { CnObjectPermissionsTab } from './CnObjectPermissionsTab/index.js'
+export { CnObjectTranslationsWidget } from './CnObjectTranslationsWidget/index.js'
 export { CnIntegrationCard } from './CnIntegrationCard/index.js'
 export { CnIntegrationWidgetGrid } from './CnIntegrationWidgetGrid/index.js'
 export { CnIntegrationWidget } from './CnIntegrationWidget/index.js'
@@ -460,3 +464,7 @@ export { CnBrandStripe } from './CnBrandStripe/index.js'
 export { CnDuplicateWarning } from './CnDuplicateWarning/index.js'
 export { CnEndpointNotice } from './CnEndpointNotice/index.js'
 export { CnCountTablesReport } from './CnCountTablesReport/index.js'
+export { CnShippedConfigurationSection } from './CnShippedConfigurationSection/index.js'
+export { CnSearchIndexStatus } from './CnSearchIndexStatus/index.js'
+export { CnSchemaRulesWidget } from './CnSchemaRulesWidget/index.js'
+export { CnReadinessChecklist } from './CnReadinessChecklist/index.js'

package/src/composables/indexSources.js

@@ -737,6 +737,14 @@ function readRowsPath(body, path) {
 	return String(path).split('.').reduce((value, key) => (value && typeof value === 'object' ? value[key] : undefined), body)
 }
 
+/**
+ * The `sourceConfig` keys the endpoint source reads itself; every other key
+ * goes along as a query parameter.
+ *
+ * @type {Array<string>}
+ */
+const ENDPOINT_SOURCE_KEYS = ['url', 'rowsPath', 'totalPath', 'searchParam', 'searchFields', 'notePath', 'noteText', 'refusedText']
+
 /**
  * The endpoint source: rows from an app's own endpoint
  * (`entitySource: "endpoint"`), for a list that is not OpenRegister objects,
@@ -759,25 +767,46 @@ function readRowsPath(body, path) {
  * request with that tab's filter, its total read at `sourceConfig.totalPath`
  * (`total` by default), else the number of rows the answer holds.
  *
+ * Three more keys shape what the page says around the rows:
+ * - `searchParam`: the page's search box sends its term as this parameter
+ *   (`sender`), so the endpoint does the searching.
+ * - `notePath` and `noteText`: a value read off the answer (`filterOrder`) and
+ *   the sentence it is said in ("Filters run in this order: {order}", its one
+ *   placeholder taking the value); a list
+ *   is joined with commas. Shown above the rows.
+ * - `refusedText`: what a refused load (403) says when the endpoint gave no
+ *   `message` of its own. A refusal is not an empty list, so the page shows it
+ *   instead of the rows, and a failed load is not one either.
+ * - `searchFields`: the filters the endpoint takes, in the same shape a
+ *   registered source declares them (`{ status: { param: 'status', single:
+ *   true } }`), so a filter strip or sidebar on the page narrows the
+ *   endpoint's query.
+ *
+ * @param {object} [declared] The page's `sourceConfig`, for `searchParam` and `searchFields`.
+ * @param {object} [context] The page's helpers; `translate` is the app's catalogue.
  * @return {object} The source adapter.
  * @spec openspec/changes/index-endpoint-source/specs/index-page/spec.md#requirement-an-index-page-can-list-rows-from-an-app-endpoint
  */
-function endpointSource() {
-	const state = reactive({ rows: [], loading: false })
+function endpointSource(declared = {}, context = {}) {
+	const state = reactive({ rows: [], loading: false, refusal: '', failed: false, note: '' })
+	const translate = typeof context.translate === 'function' ? context.translate : (text) => text
+	const searchParam = typeof declared.searchParam === 'string' && declared.searchParam !== '' ? declared.searchParam : null
+	const searchFields = declared.searchFields && typeof declared.searchFields === 'object' && !Array.isArray(declared.searchFields) ? declared.searchFields : null
 	let seq = 0
 	let warned = false
 
 	/**
-	 * The query parameters for a config: every key but the url and the paths,
-	 * empty values left out, a list joined by commas.
+	 * The query parameters for a config: every key but the source's own
+	 * (`url`, the paths, the texts), empty values left out, a list joined by
+	 * commas.
 	 *
-	 * @param {object} rest The config without `url`, `rowsPath` and `totalPath`.
+	 * @param {object} config The config.
 	 * @return {object} The parameters.
 	 */
-	const paramsOf = (rest) => {
+	const paramsOf = (config) => {
 		const params = {}
-		for (const [key, value] of Object.entries(rest)) {
-			if (value === undefined || value === null || value === '') {
+		for (const [key, value] of Object.entries(config)) {
+			if (ENDPOINT_SOURCE_KEYS.includes(key) || value === undefined || value === null || value === '') {
 				continue
 			}
 			params[key] = Array.isArray(value) ? value.join(',') : (typeof value === 'object' ? JSON.stringify(value) : value)
@@ -797,15 +826,61 @@ function endpointSource() {
 		return typeof url === 'string' && url !== '' && !Object.hasOwn(config, 'entitySource')
 	}
 
+	/**
+	 * The note read off an answer, in the page's sentence.
+	 *
+	 * @param {object} body The response body.
+	 * @param {string} [path] Where the value sits.
+	 * @param {string} [text] The sentence, with one `{placeholder}` where the value goes.
+	 * @return {string} The note, or '' when there is nothing to say.
+	 */
+	const noteOf = (body, path, text) => {
+		if (!path || !body || typeof body !== 'object' || Array.isArray(body)) {
+			return ''
+		}
+		const raw = readRowsPath(body, path)
+		const value = Array.isArray(raw) ? raw.filter((v) => v !== null && v !== undefined && v !== '').join(', ') : (raw === null || raw === undefined ? '' : String(raw))
+		if (value === '') {
+			return ''
+		}
+		return text ? translate(text).replace(/\{\w+\}/, value) : value
+	}
+
+	/**
+	 * The sentence a refused load is said in: the endpoint's own, else the
+	 * page's, else the library's.
+	 *
+	 * @param {object} body The refusal's body.
+	 * @param {string} [text] The page's `refusedText`.
+	 * @return {string} The sentence.
+	 */
+	const refusalOf = (body, text) => {
+		if (body && typeof body.message === 'string' && body.message.trim() !== '') {
+			return body.message
+		}
+		return text ? translate(text) : t('nextcloud-vue', 'You may not read this list.')
+	}
+
 	return {
+		/**
+		 * The parameter the page's search term is sent as, or null when this
+		 * endpoint takes no search.
+		 */
+		searchParam,
+
+		/**
+		 * The page filters this endpoint takes, and the parameter each becomes.
+		 */
+		searchFields,
+
 		/**
 		 * Fetch the rows.
 		 *
 		 * @param {object} config The page's source config with the tab filter merged in.
-		 * @return {Promise<void>} Resolves when loaded; a failed request leaves no rows and rethrows.
+		 * @return {Promise<void>} Resolves when loaded or refused; a failed request leaves no rows and rethrows.
 		 */
 		load: async (config) => {
-			const { url, rowsPath, totalPath, ...rest } = config || {}
+			const { url, rowsPath, notePath, noteText, refusedText } = config || {}
 			const mine = ++seq
 			if (!requestable(config)) {
 				state.rows = []
@@ -817,7 +892,7 @@ function endpointSource() {
 				}
 				return
 			}
-			const params = paramsOf(rest)
+			const params = paramsOf(config)
 			state.loading = true
 			try {
 				const { default: axios } = await import('@nextcloud/axios')
@@ -826,12 +901,22 @@ function endpointSource() {
 				const rows = Array.isArray(body) ? body : readRowsPath(body, rowsPath || 'results')
 				if (mine === seq) {
 					state.rows = Array.isArray(rows) ? rows : []
+					state.refusal = ''
+					state.failed = false
+					state.note = noteOf(body, notePath, noteText)
 				}
 			} catch (error) {
-				if (mine === seq) {
-					state.rows = []
+				if (mine !== seq) {
+					return
+				}
+				state.rows = []
+				state.note = ''
+				const refused = error && error.response && error.response.status === 403
+				state.refusal = refused ? refusalOf(error.response.data, refusedText) : ''
+				state.failed = !refused
+				if (!refused) {
+					throw error
 				}
-				throw error
 			} finally {
 				if (mine === seq) {
 					state.loading = false
@@ -850,9 +935,9 @@ function endpointSource() {
 			if (!requestable(config)) {
 				return Number.NaN
 			}
-			const { url, rowsPath, totalPath, ...rest } = config
+			const { url, rowsPath, totalPath } = config
 			const { default: axios } = await import('@nextcloud/axios')
-			const res = await axios.get(generateUrl(url), { params: paramsOf(rest) })
+			const res = await axios.get(generateUrl(url), { params: paramsOf(config) })
 			const body = res ? res.data : null
 			const total = body && typeof body === 'object' && !Array.isArray(body) ? readRowsPath(body, totalPath || 'total') : undefined
 			if (typeof total === 'number' && Number.isFinite(total)) {
@@ -871,6 +956,21 @@ function endpointSource() {
 		 * @return {boolean} Whether a load is in flight.
 		 */
 		loading: () => state.loading,
+
+		/**
+		 * @return {string} The sentence the last load was refused with, or ''.
+		 */
+		refusal: () => state.refusal,
+
+		/**
+		 * @return {boolean} Whether the last load failed for another reason than a refusal.
+		 */
+		failed: () => state.failed,
+
+		/**
+		 * @return {string} The note read off the last answer, or ''.
+		 */
+		note: () => state.note,
 	}
 }
 

package/src/css/index-page.css

@@ -222,6 +222,13 @@
 	color: var(--color-text-maxcontrast);
 }
 
+/* A note the named source read off its answer, above the rows. */
+.cn-index-page__source-note {
+	margin: 0 0 8px;
+	color: var(--color-text-maxcontrast);
+	font-size: 0.9em;
+}
+
 .cn-index-page__scope-heading {
 	display: flex;
 	flex-direction: column;

package/src/index.js

@@ -40,6 +40,7 @@ export {
 	CnAdminActionCard,
 	CnAdminSettingsShell,
 	CnAdvancedFormDialog,
+	CnAiFeaturesWidget,
 	CnApiReference,
 	CnAppLoading,
 	CnAppNav,
@@ -249,9 +250,11 @@ export {
 	CnObjectMetadataModal,
 	CnObjectMetadataWidget,
 	CnObjectPartiesWidget,
+	CnObjectPermissionsTab,
 	CnObjectPresenceWidget,
 	CnObjectRow,
 	CnObjectSidebar,
+	CnObjectTranslationsWidget,
 	CnOfflineQueue,
 	CnOrderedListField,
 	CnPageHeader,
@@ -272,6 +275,7 @@ export {
 	CnQuicklinksWidget,
 	CnQuicklinksWidgetForm,
 	CnRadioCardsWidget,
+	CnReadinessChecklist,
 	CnRecordListWidget,
 	CnRedactionEditor,
 	CnReferencePreview,
@@ -301,6 +305,8 @@ export {
 	CnSavedViewWidgetForm,
 	CnSaveViewDialog,
 	CnSchemaFormDialog,
+	CnSchemaRulesWidget,
+	CnSearchIndexStatus,
 	CnSearchPage,
 	CnSearchSelect,
 	CnSectionsWidget,
@@ -312,11 +318,13 @@ export {
 	CnSettingsPage,
 	CnSettingsSection,
 	CnSetupWizard,
+	CnShippedConfigurationSection,
 	CnSignatureCapture,
 	CnSpendAnalyticsWidget,
 	CnSpendAnalyticsWidgetForm,
 	CnStagesWidget,
 	CnStagesWidgetForm,
+	CnStateMachineEditor,
 	CnStatsBlock,
 	CnStatsBlockWidget,
 	CnStatsBlockWidgetForm,
@@ -618,6 +626,7 @@ export { DYNAMIC_KEY_PREFIX, EXTENDS_FORM_KEY, PREFILL_KEY, splitDynamicFormData
 // drift on what a 409 means (breaking change / schema still has objects).
 export { deleteSchema, describeSchemaChange, saveSchema, SchemaBreakingChangeError, SchemaHasObjectsError } from './utils/index.js'
 export { validateManifest, validateManifestV2 } from './utils/validateManifest.js'
+export { validateStateMachine } from './utils/stateMachineValidation.js'
 export { clearResolveCache, resolveManifestSentinels } from './utils/resolveManifestSentinels.js'
 export { clearRouteSentinelWarnings, resolveRouteSentinels } from './utils/resolveRouteSentinels.js'
 export {

package/src/utils/aiFeatures.js

@@ -0,0 +1,241 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * The reads and the run behind CnAiFeaturesWidget: the AI features a record's
+ * TYPE object places on a surface, where hermiq runs each one, a run on one of
+ * the record's documents, and the sentence a refusal is shown as.
+ *
+ * An undeclared type asks nobody: the declaration is read first and the
+ * features endpoint is called only when something is placed on the surface.
+ * Every read answers null when it failed, so the widget can say it is
+ * incomplete instead of drawing an empty list.
+ *
+ * The run goes to hermiq in the reader's own session, so their own access
+ * decides which document can be read. A request without a usable document
+ * reference is refused before it is sent: hermiq's redaction gate sits on the
+ * document, and a request without one would run unchecked.
+ */
+import axios from '@nextcloud/axios'
+import { translate as t } from '@nextcloud/l10n'
+import { prefixUrl } from './headers.js'
+
+/** The gate name for a run refused before it was sent. */
+export const MISSING_REFERENCE = 'missing-reference'
+
+/** The hermiq endpoint a feature runs on a document through; `{slug}` is filled in. */
+export const DEFAULT_RUN_ENDPOINT = '/apps/hermiq/api/ai-features/{slug}/run-on-document'
+
+/**
+ * A run that was refused, before sending or by one of hermiq's gates.
+ */
+export class AiFeatureRefusal extends Error {
+	/**
+	 * @param {string}      feature The feature slug.
+	 * @param {string}      reason  The refusing side's own sentence.
+	 * @param {string|null} gate    The gate that refused, when named.
+	 */
+	constructor(feature, reason, gate) {
+		super(reason)
+		this.name = 'AiFeatureRefusal'
+		this.feature = feature
+		this.reason = reason
+		this.gate = gate
+	}
+}
+
+/**
+ * The id inside a reference that may be a plain id or an object carrying one.
+ *
+ * @param {string|object|null|undefined} value The reference.
+ * @return {string} The id, or ''.
+ */
+export function referenceId(value) {
+	if (value !== null && typeof value === 'object') {
+		return String(value.id ?? value.uuid ?? '').trim()
+	}
+	return String(value ?? '').trim()
+}
+
+/**
+ * The slugs a type object places on one surface. The declaration is a map of
+ * feature slug to surface name.
+ *
+ * @param {object} typeObject The type object.
+ * @param {string} field      The declaration field.
+ * @param {string} surface    The surface.
+ * @return {Array<string>} The slugs, in declaration order.
+ */
+export function surfaceSlugs(typeObject, field, surface) {
+	const declared = typeObject?.[field]
+	if (declared === null || typeof declared !== 'object' || Array.isArray(declared)) {
+		return []
+	}
+	return Object.keys(declared).filter((slug) => declared[slug] === surface)
+}
+
+/**
+ * Read one OpenRegister object.
+ *
+ * @param {string} apiBase  API root.
+ * @param {string} register Register.
+ * @param {string} schema   Schema.
+ * @param {string} id       Object id.
+ * @return {Promise<object>} The object.
+ */
+async function readObject(apiBase, register, schema, id) {
+	const { data } = await axios.get(prefixUrl(`${apiBase}/objects/${register}/${schema}/${encodeURIComponent(id)}`))
+	return data?.object ?? data ?? {}
+}
+
+/**
+ * The AI features the record's type places on the surface, each with where it
+ * runs as the features endpoint answers it.
+ *
+ * @param {object} options                         The options.
+ * @param {string} options.apiBase                 OpenRegister API root.
+ * @param {string} options.register                Register.
+ * @param {string} options.schema                  Schema of the record.
+ * @param {string} options.objectId                The record id.
+ * @param {object} options.declaration             `{typeField, typeSchema, field, surface}`.
+ * @param {string} options.featuresEndpoint        The endpoint that asks hermiq.
+ * @param {string} options.featuresQueryKey        Query key the slugs are sent under.
+ * @return {Promise<Array<object>|null>} The features, or null when they could not be read.
+ */
+export async function fetchFeatures({ apiBase, register, schema, objectId, declaration, featuresEndpoint, featuresQueryKey }) {
+	try {
+		const record = await readObject(apiBase, register, schema, objectId)
+		const typeId = referenceId(record[declaration.typeField])
+		if (typeId === '') {
+			return []
+		}
+		const typeObject = await readObject(apiBase, register, declaration.typeSchema, typeId)
+		const slugs = surfaceSlugs(typeObject, declaration.field || 'aiFeatures', declaration.surface)
+		if (slugs.length === 0) {
+			return []
+		}
+
+		const query = new URLSearchParams({ surface: declaration.surface })
+		for (const slug of slugs) {
+			query.append(`${featuresQueryKey}[${slug}]`, declaration.surface)
+		}
+		const { data } = await axios.get(`${prefixUrl(featuresEndpoint)}?${query.toString()}`)
+		return Array.isArray(data?.features) ? data.features : []
+	} catch {
+		return null
+	}
+}
+
+/**
+ * The record's documents a feature can be run on.
+ *
+ * @param {string} url The files endpoint.
+ * @return {Promise<Array<{id: string, title: string}>|null>} The documents, or null.
+ */
+export async function fetchDocuments(url) {
+	try {
+		const { data } = await axios.get(prefixUrl(url))
+		const rows = Array.isArray(data?.results) ? data.results : (Array.isArray(data) ? data : [])
+		return rows
+			.filter((row) => row && row.id !== undefined && row.id !== null)
+			.map((row) => ({ id: String(row.id), title: String(row.title ?? row.name ?? row.id) }))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * The prompts offered on the record, as the endpoint holds them.
+ *
+ * @param {string} url The prompts endpoint.
+ * @return {Promise<Array<{id: string, label: string, prompt: string}>|null>} The prompts, or null.
+ */
+export async function fetchPrompts(url) {
+	try {
+		const { data } = await axios.get(prefixUrl(url))
+		return Array.isArray(data?.prompts) ? data.prompts : []
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Ask one prompt about the record.
+ *
+ * @param {string} url       The ask endpoint.
+ * @param {string} objectKey Body key naming the record.
+ * @param {string} objectId  The record id.
+ * @param {string} message   The prompt.
+ * @return {Promise<object>} `{reply, model?}`.
+ */
+export async function askAbout(url, objectKey, objectId, message) {
+	const { data } = await axios.post(prefixUrl(url), { [objectKey]: objectId, message })
+	return data
+}
+
+/**
+ * Where a feature runs, in words. A feature hermiq does not offer reads
+ * unavailable, never local.
+ *
+ * @param {object} feature One feature row.
+ * @return {string} The sentence.
+ */
+export function whereItRuns(feature) {
+	if (feature?.available !== true) {
+		return t('nextcloud-vue', 'Unavailable: hermiq does not offer this feature here.')
+	}
+	const provider = String(feature.provider ?? '').trim()
+	const residency = String(feature.residency ?? '').trim()
+	if (provider === '' || residency === '') {
+		return t('nextcloud-vue', 'hermiq did not say which provider runs this, or where.')
+	}
+	return t('nextcloud-vue', '{provider}, runs in {residency}', { provider, residency })
+}
+
+/**
+ * Run one AI feature on one document, through hermiq.
+ *
+ * @param {object}        request                   The run.
+ * @param {string}        request.feature           The feature slug.
+ * @param {string|number} request.documentReference The document's file id.
+ * @param {string}        request.instruction       What to do with it.
+ * @param {string}        [request.runEndpoint]     Endpoint template with `{slug}`.
+ * @return {Promise<object>} hermiq's answer.
+ * @throws {AiFeatureRefusal} When the reference is missing, or hermiq refuses.
+ */
+export async function runFeatureOnDocument({ feature, documentReference, instruction, runEndpoint = DEFAULT_RUN_ENDPOINT }) {
+	const reference = String(documentReference ?? '').trim()
+	if (/^\d+$/.test(reference) === false) {
+		throw new AiFeatureRefusal(feature, t('nextcloud-vue', 'No document was chosen.'), MISSING_REFERENCE)
+	}
+
+	const url = prefixUrl(runEndpoint.replace('{slug}', encodeURIComponent(feature)))
+	try {
+		const response = await axios.post(url, { documentReference: reference, instruction })
+		return response.data
+	} catch (error) {
+		const status = error?.response?.status
+		const data = error?.response?.data ?? {}
+		if ([400, 403, 404, 422].includes(status) === true) {
+			throw new AiFeatureRefusal(feature, String(data.error ?? ''), data.gate ?? null)
+		}
+		throw error
+	}
+}
+
+/**
+ * The sentence a reader sees for a refusal, naming the feature and the reason.
+ *
+ * @param {AiFeatureRefusal} refusal      The refusal.
+ * @param {string}           featureLabel The feature's name.
+ * @return {string} The sentence.
+ */
+export function refusalSentence(refusal, featureLabel) {
+	if (refusal.gate === MISSING_REFERENCE) {
+		return t('nextcloud-vue', '{feature} reads a document, and no document was chosen.', { feature: featureLabel })
+	}
+	if (refusal.gate === 'redaction') {
+		return t('nextcloud-vue', '{feature} will not read a document that has not been redacted.', { feature: featureLabel })
+	}
+	return t('nextcloud-vue', '{feature} did not run: {reason}', { feature: featureLabel, reason: refusal.reason })
+}