Public API to get a publicly shared calendar by its token (OCP\Calendar\IManager) #65325

Is your feature request related to a problem? Please describe.

There's no public API for apps to resolve a public calendar share token to a calendar. In nextcloud/calendar#9051 (Open Graph tags for public calendar links) I need the calendar's display name and owner for a token. Right now that's only possible through OCA\DAV\CalDAV\CalDavBackend::getPublicCalendar(), which is internal to the DAV app. @GVodyanov suggested agreeing on a public API here first: nextcloud/calendar#9051 (review)

Describe the solution you'd like

Add a lookup to OCP\Calendar\IManager:

/**
 * Returns the publicly shared calendar for the given share token, or null if there is none.
 *
 * @since 36.0.0
 */
public function getCalendarByPublicToken(string $token): ?ICalendar;

• Implemented in DAV (CalendarProvider / CalendarImpl) on top of CalDavBackend::getPublicCalendar(), returning null when the token is unknown instead of throwing NotFound.
• getDisplayName() returns the plain calendar name. getPublicCalendar() appends (uid) for DAV clients, which isn't wanted here.
• The returned calendar should expose only what the public link already exposes (read-only permissions).

Open question: how to expose the owner. ICalendar doesn't have it today, but CalendarImpl already has a public getOwnerPrincipalUri() that isn't part of OCP. Options I see:

1. New small interface next to ICalendarIsPublic / ICalendarIsShared, e.g. ICalendarHasOwner::getOwnerPrincipalUri(): string, implemented by CalendarImpl. Callers use IUserManager for the display name. Small and reusable beyond public calendars.
2. Same interface, but getOwner(): ?IUser. More convenient for callers, but ties the calendar API to users.
3. Dedicated return type instead of ICalendar, e.g. IPublicCalendar with getCalendar(): ICalendar, getOwnerPrincipalUri() and getOwnerDisplayName(). Scoped to this use case, but adds another type.

I'd lean towards 1, but I'm happy to go with whatever fits the calendar API best. Naming is open too (getCalendarByPublicToken() vs getPublicCalendar(string $token)).

Describe alternatives you've considered

• Keep using CalDavBackend from the calendar app: internal class, can break without notice, needs psalm ignores.
• Fetch the public calendar via the public DAV endpoint over HTTP from the calendar app: wasteful for a page render and still doesn't give a clean owner.

Additional context

• Consumer: feat(public): add Open Graph metadata for public share links calendar#9051. It would use this when available and fall back to a generic title/description on Nextcloud 34.
• I can open the server PR once the shape is agreed.

AI disclosure: this proposal was drafted with help from AI coding assistants (Cursor agents / LLM-based tools).