@conduction/nextcloud-vue 0.1.0-beta.1

package/src/types/notification.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenRegister Notification entity type.
+ *
+ * Represents a notification related to an object (e.g., status changes,
+ * assignments, deadline alerts). Typically delivered via Nextcloud's
+ * notification system.
+ */
+export interface TNotification {
+	id: string | number
+	uuid?: string
+	type: TNotificationType
+	title: string
+	message?: string
+	objectId?: string
+	objectUuid?: string
+	objectType?: string
+	userId?: string
+	priority?: TNotificationPriority
+	read?: boolean
+	actionUrl?: string | null
+	created: string
+	updated?: string
+}
+
+/** Notification type categories. */
+export type TNotificationType =
+	| 'status-change'
+	| 'assignment'
+	| 'deadline'
+	| 'mention'
+	| 'comment'
+	| 'system'
+	| string
+
+/** Notification priority levels. */
+export type TNotificationPriority = 'urgent' | 'high' | 'normal' | 'low'

package/src/types/object.d.ts

@@ -0,0 +1,40 @@
+/**
+ * OpenRegister Object entity type.
+ *
+ * An object is the core data entity stored in a register under a schema.
+ * The `@self` key contains system metadata, while other keys are schema properties.
+ */
+export interface TObject {
+	'@self': {
+		id: string
+		name: string | null
+		description: string | null
+		uuid: string
+		uri: string
+		version: string | null
+		register: string
+		schema: string
+		schemaVersion: string | null
+		relations: string | unknown[] | null
+		files: string | unknown[] | null
+		folder: string | null
+		textRepresentation: string | null
+		locked: unknown[] | null
+		owner: string | null
+		authorization: unknown[] | null
+		application: string | null
+		organisation: string | null
+		groups: unknown[] | null
+		validation: unknown[] | null
+		deleted: unknown[] | null
+		geo: unknown[] | null
+		retention: unknown[] | null
+		size: string | null
+		updated: string
+		created: string
+		published: string | null
+		depublished: string | null
+	}
+	/** Schema-defined properties (dynamic keys). */
+	[key: string]: unknown
+}

package/src/types/organisation.d.ts

@@ -0,0 +1,41 @@
+import type { TQuota, TUsage, TCrudAuthorization } from './shared'
+
+/**
+ * OpenRegister Organisation entity type.
+ *
+ * Organisations group users and control access to registers, schemas, and objects.
+ */
+export interface TOrganisation {
+	id?: number
+	uuid?: string
+	name: string
+	slug?: string
+	description?: string
+	users?: string[]
+	groups?: string[]
+	isDefault?: boolean
+	active?: boolean
+	owner?: string
+	parent?: string | null
+	children?: string[]
+	quota?: TQuota
+	usage?: TUsage
+	authorization?: TOrganisationAuthorization
+	created?: string
+	updated?: string
+}
+
+/** Organisation-level authorization with per-entity-type CRUD + special permissions. */
+export interface TOrganisationAuthorization {
+	register?: TCrudAuthorization
+	schema?: TCrudAuthorization
+	object?: TCrudAuthorization
+	view?: TCrudAuthorization
+	agent?: TCrudAuthorization
+	configuration?: TCrudAuthorization
+	application?: TCrudAuthorization
+	object_publish?: string[]
+	agent_use?: string[]
+	dashboard_view?: string[]
+	llm_use?: string[]
+}

package/src/types/register.d.ts

@@ -0,0 +1,25 @@
+import type { TQuota, TUsage, TEntityStats } from './shared'
+
+/**
+ * OpenRegister Register entity type.
+ *
+ * A register is a collection of schemas and their objects, backed by a data source.
+ */
+export interface TRegister {
+	id?: string
+	title: string
+	description: string
+	schemas: string[]
+	source: string
+	databaseId: string
+	published?: string | null
+	depublished?: string | null
+	tablePrefix?: string
+	updated?: string
+	created: string
+	slug: string
+	groups?: string[]
+	quota?: TQuota
+	usage?: TUsage
+	stats?: TEntityStats
+}

package/src/types/schema.d.ts

@@ -0,0 +1,39 @@
+import type { TEntityStats } from './shared'
+
+/**
+ * OpenRegister Schema entity type.
+ *
+ * Defines the structure and validation rules for objects in a register.
+ */
+export interface TSchema {
+	id?: string
+	title: string
+	version: string
+	description: string
+	summary: string
+	required: string[]
+	properties: Record<string, unknown>
+	archive: Record<string, unknown>
+	updated: string
+	created: string
+	slug: string
+	configuration?: TSchemaConfiguration
+	hardValidation: boolean
+	maxDepth: number
+	authorization?: Record<string, string[]>
+	extend?: string
+	stats?: TEntityStats
+}
+
+/** Schema configuration options. */
+export interface TSchemaConfiguration {
+	objectNameField?: string
+	objectDescriptionField?: string
+	objectSummaryField?: string
+	objectImageField?: string
+	allowFiles?: boolean
+	allowedTags?: string[]
+	unique?: boolean
+	facetCacheTtl?: number
+	autoPublish?: boolean
+}

package/src/types/shared.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared utility types used across OpenRegister entities.
+ */
+
+/** Standard paginated API response shape. */
+export interface TPaginated<T = unknown> {
+	results: T[]
+	total: number
+	page: number
+	pages: number
+	limit: number
+	offset: number
+}
+
+/** Empty paginated response (used as initial state). */
+export type TEmptyPaginated = TPaginated<never>
+
+/** Resource quota limits. Used by registers, organisations, views, applications. */
+export interface TQuota {
+	storage?: number | null
+	bandwidth?: number | null
+	requests?: number | null
+	users?: number | null
+	groups?: number | null
+}
+
+/** Resource usage tracking. Mirrors TQuota but values are always numbers. */
+export interface TUsage {
+	storage?: number
+	bandwidth?: number
+	requests?: number
+	users?: number
+	groups?: number
+}
+
+/** Aggregate statistics for objects, logs, and files. Used by schemas and registers. */
+export interface TEntityStats {
+	objects: {
+		total: number
+		size: number
+		invalid: number
+		deleted: number
+		locked: number
+		published: number
+	}
+	logs: {
+		total: number
+		size: number
+	}
+	files: {
+		total: number
+		size: number
+	}
+}
+
+/** CRUD authorization configuration per entity type. */
+export interface TCrudAuthorization {
+	create?: string[]
+	read?: string[]
+	update?: string[]
+	delete?: string[]
+}
+
+/** Unified API error shape returned by all store actions. */
+export interface TApiError {
+	status: number | null
+	message: string
+	details: unknown | null
+	isValidation: boolean
+	fields: Record<string, string> | null
+	toString(): string
+}
+
+/** Object path reference for routing. */
+export interface TObjectPath {
+	register: string
+	schema: string
+	objectId?: string
+}

package/src/types/source.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenRegister Source entity type.
+ *
+ * A data source backing a register (database connection).
+ */
+export interface TSource {
+	id?: string | number
+	title: string
+	description: string
+	databaseUrl: string
+	type: 'internal' | 'mongodb'
+	updated: string
+	created: string
+}

package/src/types/task.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenRegister Task entity type.
+ *
+ * Tasks are CalDAV-based (iCalendar VTODO) and linked to objects.
+ * Fetched via the /tasks sub-resource endpoint and normalized from
+ * iCal format to this frontend-friendly shape.
+ */
+export interface TTask {
+	id: string
+	uid?: string
+	calendarId?: string
+	taskUri?: string
+	title: string
+	description?: string
+	reference?: string
+	objectUuid?: string
+	deadline?: string | null
+	daysText?: string
+	isOverdue?: boolean
+	isCompleted?: boolean
+	priority: TTaskPriority
+	status: TTaskStatus
+	created?: string
+	updated?: string
+}
+
+/** CalDAV task priority levels (mapped from iCal 0-9 range). */
+export type TTaskPriority = 'urgent' | 'high' | 'normal' | 'low'
+
+/** CalDAV task status values. */
+export type TTaskStatus = 'needs-action' | 'in-process' | 'completed' | 'cancelled'

package/src/utils/errors.js

@@ -0,0 +1,96 @@
+/**
+ * Unified error shape returned by all store actions.
+ *
+ * @typedef {object} ApiError
+ * @property {number} status HTTP status code (0 for network errors)
+ * @property {string} message Human-readable error message
+ * @property {object|null} details Validation errors or additional details
+ * @property {boolean} isValidation Whether this is a validation error (400/422)
+ * @property {object|null} fields Per-field validation errors
+ */
+
+/**
+ * Parse an HTTP error response into a unified ApiError shape.
+ *
+ * Merges the best of Pipelinq's _parseResponseError (field extraction)
+ * and Procest's _parseError (status-specific messages, isValidation flag).
+ *
+ * @param {Response} response The fetch Response object
+ * @param {string} type The object type slug (used in error messages)
+ * @return {Promise<ApiError>} Parsed error object
+ */
+export async function parseResponseError(response, type) {
+	const status = response.status
+	let details = null
+	let fields = null
+	let message = ''
+
+	try {
+		const body = await response.json()
+		details = body.errors || body.error || body.message || null
+		fields = body.validationErrors || body.errors || null
+	} catch {
+		// Response body is not JSON
+	}
+
+	switch (true) {
+	case status === 400 || status === 422:
+		message = details && typeof details === 'string'
+			? details
+			: `Validation failed for ${type}`
+		return { status, message, details, isValidation: true, fields, toString() { return this.message } }
+	case status === 401:
+		message = 'Session expired, please log in again'
+		break
+	case status === 403:
+		message = 'You do not have permission to perform this action'
+		break
+	case status === 404:
+		message = `The requested ${type} could not be found`
+		break
+	case status === 409:
+		message = `This ${type} was modified by another user. Please reload.`
+		break
+	case status >= 500:
+		message = 'An unexpected server error occurred. Please try again.'
+		break
+	default:
+		message = response.statusText || 'An unexpected error occurred'
+	}
+
+	return { status, message, details, isValidation: false, fields, toString() { return this.message } }
+}
+
+/**
+ * Create a network error object for fetch failures (no response).
+ *
+ * @param {Error} error The caught error
+ * @return {ApiError} Network error object
+ */
+export function networkError(error) {
+	return {
+		status: 0,
+		message: error.message || 'A network error occurred. Check your connection and try again.',
+		details: null,
+		isValidation: false,
+		fields: null,
+		toString() { return this.message },
+	}
+}
+
+/**
+ * Create a generic error object from a caught exception.
+ *
+ * @param {Error} error The caught error
+ * @return {ApiError} Generic error object
+ */
+export function genericError(error) {
+	return {
+		status: null,
+		message: error.message,
+		details: null,
+		isValidation: false,
+		fields: null,
+		toString() { return this.message },
+	}
+}

package/src/utils/headers.js

@@ -0,0 +1,44 @@
+/**
+ * Build standard Nextcloud request headers for API calls.
+ *
+ * Includes the CSRF request token and OCS API request header
+ * required by Nextcloud's API layer.
+ *
+ * @param {string} [contentType='application/json'] Content-Type header value
+ * @return {object} Headers object for use with fetch()
+ */
+export function buildHeaders(contentType = 'application/json') {
+	const headers = {
+		requesttoken: OC.requestToken,
+		'OCS-APIREQUEST': 'true',
+	}
+	if (contentType) {
+		headers['Content-Type'] = contentType
+	}
+	return headers
+}
+
+/**
+ * Build a query string from a params object.
+ *
+ * Handles _order serialization (JSON.stringify for objects) and skips
+ * null/undefined/empty values.
+ *
+ * @param {object} params Key-value pairs for query parameters
+ * @return {string} Query string including leading '?' or empty string
+ */
+export function buildQueryString(params = {}) {
+	const queryParams = new URLSearchParams()
+
+	for (const [key, value] of Object.entries(params)) {
+		if (value === undefined || value === null || value === '') continue
+		if (key === '_order' && typeof value === 'object') {
+			queryParams.set(key, JSON.stringify(value))
+		} else {
+			queryParams.set(key, String(value))
+		}
+	}
+
+	const str = queryParams.toString()
+	return str ? '?' + str : ''
+}

package/src/utils/index.js

@@ -0,0 +1,3 @@
+export { buildHeaders, buildQueryString } from './headers.js'
+export { parseResponseError, networkError, genericError } from './errors.js'
+export { columnsFromSchema, formatValue, filtersFromSchema } from './schema.js'