feat: Add an nc link parser tool

Assisted-by: ClaudeCode:claude-opus-4-8
Signed-off-by: Marcel Klehr <mklehr@gmx.net>

Author: marcelklehr

ex_app/lib/all_tools/nextcloud_links.py

@@ -0,0 +1,216 @@
+# SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+import re
+from urllib.parse import parse_qs, unquote, urlparse
+
+from langchain_core.tools import tool
+from nc_py_api import AsyncNextcloudApp
+
+from ex_app.lib.all_tools.lib.decorator import safe_tool
+
+# Hint telling the agent which tools can act on the parsed entity.
+_TOOL_HINTS = {
+	'files': 'Use get_file_content_by_file_link / get_file_path_by_id with the file_id.',
+	'talk': 'Use the Talk tools; resolve the token via list_talk_conversations (match on token).',
+	'collectives': 'Collective pages are Markdown files; if a file_id is present use the Files tools, otherwise open the collective by name.',
+	'deck': 'Use the Deck tools with board_id / card_id.',
+	'mail': 'Use the Mail tools; mailbox_id maps to a folder_id, thread_id identifies the conversation.',
+	'calendar': 'Use the Calendar tools; the object is identified by calendar + object href/token.',
+	'bookmarks': 'Use the Bookmarks tools; filter by folder_id if present.',
+	'cookbook': 'Use get_recipe_details with recipe_id.',
+	'forms': 'Forms are identified by a share hash; call list_forms to map the hash to a form_id.',
+	'tables': 'Use the Tables tools with table_id (or list rows of the view_id).',
+}
+
+
+def _clean_path(path: str) -> str:
+	"""Strip the optional /index.php prefix from a Nextcloud path."""
+	return re.sub(r'^/index\.php', '', path or '')
+
+
+def _int(value):
+	try:
+		return int(value)
+	except (TypeError, ValueError):
+		return value
+
+
+def _first(query: dict, *keys):
+	"""Return the first value of the first present key in a parsed query string."""
+	for key in keys:
+		if key in query and query[key]:
+			return query[key][0]
+	return None
+
+
+def _parse_nextcloud_url(url: str) -> dict:
+	"""
+	Parse a Nextcloud deep-link URL into its app, entity type and identifiers.
+
+	Returns a dict with at least ``app`` and ``entity_type`` and, when found, an
+	``ids`` mapping. ``entity_type`` is ``None`` (and app may be ``unknown``) when
+	the URL does not match any known Nextcloud app route.
+	"""
+	if not isinstance(url, str) or not url.strip():
+		raise ValueError('A non-empty URL string is required')
+
+	parsed = urlparse(url.strip())
+	path = _clean_path(unquote(parsed.path or ''))
+	fragment = unquote(parsed.fragment or '')
+	query = parse_qs(parsed.query or '')
+	# Hash-router apps (deck, tables, cookbook, ...) carry the real route in the
+	# fragment, e.g. /apps/tables#/table/3 . Search path and fragment together.
+	hay = f'{path}#{fragment}'
+
+	result = {'app': 'unknown', 'entity_type': None, 'ids': {}, 'url': url}
+
+	def done(app, entity_type, ids=None, **extra):
+		result.update(app=app, entity_type=entity_type, ids={k: v for k, v in (ids or {}).items() if v is not None})
+		result.update(extra)
+		hint = _TOOL_HINTS.get(app)
+		if hint:
+			result['hint'] = hint
+		return result
+
+	# --- Files (files) ------------------------------------------------------
+	# https://host/f/123  |  /index.php/f/123  |  ?fileid=123 / ?openfile=123
+	m = re.search(r'/f/(\d+)/?$', path)
+	if m:
+		return done('files', 'file', {'file_id': _int(m.group(1))})
+	file_id = _first(query, 'fileid', 'fileId', 'openfile')
+
+	# public share of a file/folder: /s/{token}
+	m = re.search(r'/s/([A-Za-z0-9]+)/?$', path)
+	if m and not path.startswith('/apps/'):
+		return done('files', 'public_share', {'token': m.group(1)})
+
+	# --- Talk (spreed) ------------------------------------------------------
+	# /call/{token}  optionally  #message_{id}
+	m = re.search(r'/(?:apps/spreed/)?call/([A-Za-z0-9]+)', path)
+	if m:
+		msg = re.search(r'message_(\d+)', fragment)
+		return done('talk', 'conversation', {'token': m.group(1)},
+					message_id=_int(msg.group(1)) if msg else None)
+
+	# --- App-scoped routes: /apps/{app}/... --------------------------------
+	app_match = re.match(r'^/apps/([^/?#]+)(/.*)?$', path)
+	app = app_match.group(1) if app_match else None
+	app_rest = (app_match.group(2) if app_match else '') or ''
+	scope = f'{app_rest}#{fragment}'  # everything after the app name
+
+	if app == 'collectives':
+		# /apps/collectives/{Collective Name}/{Page/Sub Page}?fileId=123
+		segments = [s for s in app_rest.split('/') if s]
+		collective = segments[0] if segments else None
+		page_path = '/'.join(segments[1:]) or None
+		return done('collectives', 'page' if page_path else 'collective', {
+			'collective': collective,
+			'page_path': page_path,
+			'file_id': _int(file_id) if file_id else None,
+		})
+
+	if app == 'deck':
+		board = re.search(r'board/(\d+)', scope)
+		card = re.search(r'card/(\d+)', scope)
+		if card and board:
+			return done('deck', 'card', {'board_id': _int(board.group(1)), 'card_id': _int(card.group(1))})
+		if card:
+			return done('deck', 'card', {'card_id': _int(card.group(1))})
+		if board:
+			return done('deck', 'board', {'board_id': _int(board.group(1))})
+		return done('deck', None)
+
+	if app == 'mail':
+		box = re.search(r'box/(\d+)', scope)
+		thread = re.search(r'thread/(\d+)', scope)
+		if thread:
+			return done('mail', 'thread', {'mailbox_id': _int(box.group(1)) if box else None,
+											'thread_id': _int(thread.group(1))})
+		if box:
+			return done('mail', 'mailbox', {'mailbox_id': _int(box.group(1))})
+		return done('mail', None)
+
+	if app == 'calendar':
+		public = re.search(r'/p/([A-Za-z0-9]+)', app_rest)
+		if public:
+			return done('calendar', 'public_share', {'token': public.group(1)})
+		# .../{view}/{date}/edit/sidebar/{objectId}/{recurrenceId}
+		obj = re.search(r'/edit/[^/]+/([^/?#]+)(?:/([^/?#]+))?', scope)
+		if obj:
+			return done('calendar', 'event', {'object_id': obj.group(1), 'recurrence_id': obj.group(2)},
+						note='object_id is a base64-encoded "<calendarId>/<filename>.ics" reference')
+		date = re.search(r'/(\d{4}-\d{2}-\d{2})', app_rest)
+		view = re.match(r'^/([a-zA-Z]+)', app_rest)
+		return done('calendar', 'view', {'view': view.group(1) if view else None,
+										'date': date.group(1) if date else None})
+
+	if app == 'bookmarks':
+		folder = _first(query, 'folder') or (re.search(r'folders?/(\d+)', scope).group(1)
+											if re.search(r'folders?/(\d+)', scope) else None)
+		return done('bookmarks', 'folder' if folder else 'app', {'folder_id': _int(folder) if folder else None})
+
+	if app == 'cookbook':
+		recipe = re.search(r'recipe/(\d+)', scope)
+		if recipe:
+			return done('cookbook', 'recipe', {'recipe_id': _int(recipe.group(1))})
+		category = re.search(r'category/([^/?#]+)', scope)
+		if category:
+			return done('cookbook', 'category', {'category': category.group(1)})
+		return done('cookbook', None)
+
+	if app == 'forms':
+		# /apps/forms/{hash} (fill) | /apps/forms/{edit,results,submit,embed}/{hash}
+		m = re.match(r'^/(edit|results|submit|embed)/([^/?#]+)', app_rest)
+		if m:
+			return done('forms', m.group(1), {'hash': m.group(2)})
+		m = re.match(r'^/([^/?#]+)', app_rest)
+		if m:
+			return done('forms', 'form', {'hash': m.group(1)})
+		return done('forms', None)
+
+	if app == 'tables':
+		view = re.search(r'view/(\d+)', scope)
+		table = re.search(r'table/(\d+)', scope)
+		if table:
+			return done('tables', 'table', {'table_id': _int(table.group(1))})
+		if view:
+			return done('tables', 'view', {'view_id': _int(view.group(1))})
+		return done('tables', None)
+
+	# --- Fallbacks ----------------------------------------------------------
+	if file_id:
+		return done('files', 'file', {'file_id': _int(file_id)})
+	if app:
+		return done(app, None)
+	return result
+
+
+async def get_tools(nc: AsyncNextcloudApp):
+
+	@tool
+	@safe_tool
+	async def parse_nextcloud_url(url: str):
+		"""
+		Parse a Nextcloud deep-link URL and extract which app it belongs to, the
+		entity type it points at, and the identifiers needed to fetch that entity
+		with the matching tools. Use this to turn a link a user pasted (e.g. a Talk
+		room, a Deck card, a Collectives page, a Tables table, a recipe, ...) into
+		concrete ids before calling the relevant app tools.
+
+		Supports the Files, Talk (spreed), Collectives, Deck, Mail, Calendar,
+		Bookmarks, Cookbook, Forms and Tables apps.
+		:param url: a Nextcloud URL (with or without the /index.php prefix)
+		:return: a dict with keys `app`, `entity_type`, `ids`, and a `hint` on which
+			tools to use. `entity_type` is null when the URL is not a recognized route.
+		"""
+		return _parse_nextcloud_url(url)
+
+	return [parse_nextcloud_url]
+
+
+def get_category_name():
+	return "Nextcloud Links"
+
+
+async def is_available(nc: AsyncNextcloudApp):
+	return True