@remit/web-client 0.0.238 → 0.0.240

package/src/hooks/calendar/useCalendarFeed.ts

@@ -0,0 +1,163 @@
+/**
+ * A calendar's secret subscription address, as the settings surface holds it
+ * (issue #1067).
+ *
+ * The plaintext token exists in exactly one place: the answer to the write that
+ * minted it. It is kept here until the reader dismisses it and is never read
+ * back — the server stores a hash, so a lost address is rotated rather than
+ * recovered.
+ *
+ * The read owns its 404 and its 403 and nothing else. "This calendar has no
+ * feed" and "this calendar is not yours" are both answers the card states where
+ * it stands — the 404 as the offer to create one, the 403 as "couldn't read
+ * whether it is shared", never as "not shared yet". A 401 is the session gone,
+ * and no banner on this card signs anyone back in, so it escalates.
+ */
+import {
+	calendarDetailOperationsGetCalendarFeedOptions,
+	calendarDetailOperationsGetCalendarFeedQueryKey,
+	calendarDetailOperationsPutCalendarFeedMutation,
+	calendarDetailOperationsRevokeCalendarFeedMutation,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+import { calendarFeedUrl } from "@/lib/calendar-feed-url";
+import {
+	isNotFound,
+	softErrorMeta,
+	softErrorStatuses,
+} from "@/lib/error-classifier";
+
+export type CalendarFeedState =
+	| { status: "loading" }
+	/** The server answered, and this calendar is not shared. */
+	| { status: "absent" }
+	| { status: "active"; createdAt: number; rotatedAt: number }
+	/** The server refused to say, which is not the same as "not shared". */
+	| { status: "unreadable"; error: unknown };
+
+export interface CalendarFeedControls {
+	state: CalendarFeedState;
+	/** The address just minted, shown once. Empty at every other moment. */
+	mintedUrl: string;
+	isBusy: boolean;
+	/** A create, rotate or revoke the server turned down. */
+	actionError: unknown;
+	mint: () => void;
+	revoke: () => void;
+	dismissMinted: () => void;
+	retry: () => void;
+}
+
+export function useCalendarFeed(calendarId: string): CalendarFeedControls {
+	const queryClient = useQueryClient();
+	const [mintedUrl, setMintedUrl] = useState("");
+
+	const queryKey = calendarDetailOperationsGetCalendarFeedQueryKey({
+		path: { calendarId },
+	});
+
+	const query = useQuery({
+		...calendarDetailOperationsGetCalendarFeedOptions({
+			path: { calendarId },
+		}),
+		meta: softErrorStatuses(404, 403),
+		retry: false,
+	});
+
+	const invalidate = () => {
+		queryClient.invalidateQueries({ queryKey });
+	};
+
+	// Each write clears the other's refusal as it starts, so the card never
+	// states a failure the reader has already written past. Only one of the two
+	// can name the other directly; the revoke is declared first and reaches
+	// forward through this ref.
+	const resetMint = useRef<() => void>(() => {});
+
+	const revokeMutation = useMutation({
+		...calendarDetailOperationsRevokeCalendarFeedMutation(),
+		meta: softErrorMeta,
+		onMutate: () => {
+			resetMint.current();
+		},
+		onSuccess: () => {
+			setMintedUrl("");
+			invalidate();
+		},
+	});
+
+	const mintMutation = useMutation({
+		...calendarDetailOperationsPutCalendarFeedMutation(),
+		meta: softErrorMeta,
+		// The answer to this write is the plaintext token. Nothing may hold it
+		// once the surface showing it lets go, so it is collected the moment the
+		// observer detaches — on dismissal, and on leaving the page — instead of
+		// sitting in the mutation cache for the default five minutes.
+		gcTime: 0,
+		onMutate: () => {
+			revokeMutation.reset();
+		},
+		onSuccess: (data) => {
+			setMintedUrl(calendarFeedUrl(window.location.host, data.feedToken));
+			invalidate();
+		},
+	});
+
+	resetMint.current = mintMutation.reset;
+
+	const { mutate: mintFeed, reset: resetMintMutation } = mintMutation;
+	const { mutate: revokeFeed } = revokeMutation;
+
+	const mint = useCallback(() => {
+		mintFeed({ path: { calendarId } });
+	}, [calendarId, mintFeed]);
+
+	const revoke = useCallback(() => {
+		revokeFeed({ path: { calendarId } });
+	}, [calendarId, revokeFeed]);
+
+	// Resetting the mutation drops the answer that carried the plaintext token,
+	// which otherwise sits in the mutation cache for its whole gcTime after the
+	// reader has said they saved it.
+	const dismissMinted = useCallback(() => {
+		setMintedUrl("");
+		resetMintMutation();
+	}, [resetMintMutation]);
+
+	const { refetch } = query;
+	const retry = useCallback(() => {
+		refetch();
+	}, [refetch]);
+
+	return {
+		state: readState(query),
+		mintedUrl,
+		isBusy: mintMutation.isPending || revokeMutation.isPending,
+		actionError: mintMutation.error ?? revokeMutation.error,
+		mint,
+		revoke,
+		dismissMinted,
+		retry,
+	};
+}
+
+interface FeedQuery {
+	data?: { createdAt: number; rotatedAt: number };
+	error: unknown;
+	isPending: boolean;
+}
+
+function readState(query: FeedQuery): CalendarFeedState {
+	if (query.error) {
+		if (isNotFound(query.error)) return { status: "absent" };
+		return { status: "unreadable", error: query.error };
+	}
+	if (query.isPending) return { status: "loading" };
+	if (!query.data) return { status: "absent" };
+	return {
+		status: "active",
+		createdAt: query.data.createdAt,
+		rotatedAt: query.data.rotatedAt,
+	};
+}

package/src/hooks/useResultFolderIndex.ts

@@ -3,6 +3,10 @@
  * and `useMailboxNameIndex` run — cached forever, react-query dedupes the
  * identical key across call sites) and reduces it to the mailboxId → folder map
  * search results resolve their provenance against. See `lib/result-folder.ts`.
+ *
+ * The read state travels with the index: a folder label cut on a delimiter that
+ * has not arrived is wrong rather than late, so a surface that names folders can
+ * wait for this, and say so when it fails.
  */
 import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import type {
@@ -18,37 +22,63 @@ import {
 
 type MailboxItems = RemitImapMailboxResponse[];
 
+interface MailboxListsState {
+	items: MailboxItems[];
+	isPending: boolean;
+	error: Error | null;
+}
+
+export interface ResultFolderIndexState {
+	index: ResultFolderIndex;
+	isPending: boolean;
+	error: Error | null;
+}
+
 /**
  * Hoisted, not inline: `useQueries` skips re-running `combine` when it is given
  * the same function, so a stable reference is what makes this a memo rather than
  * a per-render reduce. Without it the index — and every search-result memo keyed
  * on it — rebuilds on every render.
  */
-const combineMailboxItems = (
-	results: { data?: { items: MailboxItems } }[],
-): MailboxItems[] => results.map((result) => result.data?.items ?? []);
+const combineMailboxLists = (
+	results: {
+		data?: { items: MailboxItems };
+		isPending: boolean;
+		error: Error | null;
+	}[],
+): MailboxListsState => ({
+	items: results.map((result) => result.data?.items ?? []),
+	isPending: results.some((result) => result.isPending),
+	error: results.find((result) => result.error)?.error ?? null,
+});
 
 export function useResultFolderIndex(
 	accounts: RemitImapAccountResponse[],
-): ResultFolderIndex {
-	const mailboxItems = useQueries({
+): ResultFolderIndexState {
+	const mailboxLists = useQueries({
 		queries: accounts.map((account) => ({
 			...mailboxOperationsListMailboxesOptions({
 				path: { accountId: account.accountId },
 			}),
 			staleTime: Infinity,
 		})),
-		combine: combineMailboxItems,
+		combine: combineMailboxLists,
 	});
 
-	return useMemo(
+	const index = useMemo(
 		() =>
 			buildResultFolderIndex(
 				accounts.map((account, i) => ({
 					folderAppointments: account.folderAppointments,
-					mailboxes: mailboxItems[i] ?? [],
+					mailboxes: mailboxLists.items[i] ?? [],
 				})),
 			),
-		[accounts, mailboxItems],
+		[accounts, mailboxLists],
 	);
+
+	return {
+		index,
+		isPending: mailboxLists.isPending,
+		error: mailboxLists.error,
+	};
 }

package/src/lib/calendar-feed-copy.ts

@@ -0,0 +1,29 @@
+/**
+ * What the two destructive feed actions say before they are taken.
+ *
+ * Both take a working subscription away from whoever holds the address, and
+ * neither can be undone by re-minting — the new address is a different secret.
+ * The copy names the calendar, so a confirmation opened from the wrong row is
+ * visibly the wrong one.
+ */
+
+export interface FeedConfirmCopy {
+	title: string;
+	description: string;
+}
+
+export const rotateFeedConfirmCopy = (
+	calendarName: string,
+): FeedConfirmCopy => ({
+	title: `Replace the address for ${calendarName}?`,
+	description:
+		"Every client already subscribed to the current address stops updating and has to be pointed at the new one. The new address is shown once.",
+});
+
+export const revokeFeedConfirmCopy = (
+	calendarName: string,
+): FeedConfirmCopy => ({
+	title: `Stop sharing ${calendarName}?`,
+	description:
+		"The address stops working immediately and every client subscribed to it stops updating. Sharing again mints a different address.",
+});

package/src/lib/calendar-feed-url.ts

@@ -0,0 +1,14 @@
+/**
+ * The address a subscriber points its calendar client at (issue #1067).
+ *
+ * `webcal://` rather than `https://`: Apple Calendar, Outlook and Thunderbird
+ * hand a `webcal:` link straight to their subscription dialog, where an https
+ * one downloads a file that never refreshes. The host carries its port, so a
+ * deployment that is not on 443 is subscribable on the same terms.
+ */
+
+const FEED_PATH_PREFIX = "/feeds/calendar/";
+const FEED_PATH_SUFFIX = ".ics";
+
+export const calendarFeedUrl = (host: string, feedToken: string): string =>
+	`webcal://${host}${FEED_PATH_PREFIX}${feedToken}${FEED_PATH_SUFFIX}`;

package/src/lib/quarantine-entries.ts

@@ -8,9 +8,11 @@ import { CANONICAL_TO_NAV_ROLE } from "./folder-roles";
  * canonical PascalCase the API uses everywhere. Both differences are resolved
  * here rather than by widening the kit's entry type.
  *
- * The record carries no hierarchy delimiter either, so the caller resolves the
- * account's own from its mailbox list and hands it in — the row shows a folder
- * name, and a path cannot be cut into one without it.
+ * The record carries no hierarchy delimiter either, so the caller joins the
+ * mailbox id against the account's own mailbox list and hands the delimiter in
+ * — the row shows a folder name, and a path cannot be cut into one without it.
+ * An empty delimiter means no account lists that mailbox, and the row keeps its
+ * whole path rather than being cut on a guess.
  */
 export function toQuarantineEntry(
 	wire: RemitImapQuarantineResponse,

package/src/routeTree.gen.ts

@@ -25,6 +25,7 @@ import { Route as SettingsIndexRouteImport } from './routes/settings/index'
 import { Route as SettingsAccountsRouteImport } from './routes/settings/accounts'
 import { Route as SettingsAdvancedRouteImport } from './routes/settings/advanced'
 import { Route as SettingsAppearanceRouteImport } from './routes/settings/appearance'
+import { Route as SettingsCalendarsRouteImport } from './routes/settings/calendars'
 import { Route as SettingsFiltersRouteImport } from './routes/settings/filters'
 import { Route as SettingsFoldersRouteImport } from './routes/settings/folders'
 import { Route as SettingsLabelsRouteImport } from './routes/settings/labels'
@@ -138,6 +139,11 @@ const SettingsAppearanceRoute = SettingsAppearanceRouteImport.update({
   path: '/appearance',
   getParentRoute: () => SettingsRoute,
 } as any)
+const SettingsCalendarsRoute = SettingsCalendarsRouteImport.update({
+  id: '/calendars',
+  path: '/calendars',
+  getParentRoute: () => SettingsRoute,
+} as any)
 const SettingsFiltersRoute = SettingsFiltersRouteImport.update({
   id: '/filters',
   path: '/filters',
@@ -335,6 +341,7 @@ export interface FileRoutesByFullPath {
   '/settings/accounts': typeof SettingsAccountsRoute
   '/settings/advanced': typeof SettingsAdvancedRoute
   '/settings/appearance': typeof SettingsAppearanceRoute
+  '/settings/calendars': typeof SettingsCalendarsRoute
   '/settings/filters': typeof SettingsFiltersRoute
   '/settings/folders': typeof SettingsFoldersRoute
   '/settings/labels': typeof SettingsLabelsRoute
@@ -378,6 +385,7 @@ export interface FileRoutesByTo {
   '/settings/accounts': typeof SettingsAccountsRoute
   '/settings/advanced': typeof SettingsAdvancedRoute
   '/settings/appearance': typeof SettingsAppearanceRoute
+  '/settings/calendars': typeof SettingsCalendarsRoute
   '/settings/filters': typeof SettingsFiltersRoute
   '/settings/folders': typeof SettingsFoldersRoute
   '/settings/labels': typeof SettingsLabelsRoute
@@ -424,6 +432,7 @@ export interface FileRoutesById {
   '/settings/accounts': typeof SettingsAccountsRoute
   '/settings/advanced': typeof SettingsAdvancedRoute
   '/settings/appearance': typeof SettingsAppearanceRoute
+  '/settings/calendars': typeof SettingsCalendarsRoute
   '/settings/filters': typeof SettingsFiltersRoute
   '/settings/folders': typeof SettingsFoldersRoute
   '/settings/labels': typeof SettingsLabelsRoute
@@ -476,6 +485,7 @@ export interface FileRouteTypes {
     | '/settings/accounts'
     | '/settings/advanced'
     | '/settings/appearance'
+    | '/settings/calendars'
     | '/settings/filters'
     | '/settings/folders'
     | '/settings/labels'
@@ -519,6 +529,7 @@ export interface FileRouteTypes {
     | '/settings/accounts'
     | '/settings/advanced'
     | '/settings/appearance'
+    | '/settings/calendars'
     | '/settings/filters'
     | '/settings/folders'
     | '/settings/labels'
@@ -564,6 +575,7 @@ export interface FileRouteTypes {
     | '/settings/accounts'
     | '/settings/advanced'
     | '/settings/appearance'
+    | '/settings/calendars'
     | '/settings/filters'
     | '/settings/folders'
     | '/settings/labels'
@@ -724,6 +736,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof SettingsAppearanceRouteImport
       parentRoute: typeof SettingsRoute
     }
+    '/settings/calendars': {
+      id: '/settings/calendars'
+      path: '/calendars'
+      fullPath: '/settings/calendars'
+      preLoaderRoute: typeof SettingsCalendarsRouteImport
+      parentRoute: typeof SettingsRoute
+    }
     '/settings/filters': {
       id: '/settings/filters'
       path: '/filters'
@@ -1177,6 +1196,7 @@ interface SettingsRouteChildren {
   SettingsAccountsRoute: typeof SettingsAccountsRoute
   SettingsAdvancedRoute: typeof SettingsAdvancedRoute
   SettingsAppearanceRoute: typeof SettingsAppearanceRoute
+  SettingsCalendarsRoute: typeof SettingsCalendarsRoute
   SettingsFiltersRoute: typeof SettingsFiltersRoute
   SettingsFoldersRoute: typeof SettingsFoldersRoute
   SettingsLabelsRoute: typeof SettingsLabelsRoute
@@ -1189,6 +1209,7 @@ const SettingsRouteChildren: SettingsRouteChildren = {
   SettingsAccountsRoute: SettingsAccountsRoute,
   SettingsAdvancedRoute: SettingsAdvancedRoute,
   SettingsAppearanceRoute: SettingsAppearanceRoute,
+  SettingsCalendarsRoute: SettingsCalendarsRoute,
   SettingsFiltersRoute: SettingsFiltersRoute,
   SettingsFoldersRoute: SettingsFoldersRoute,
   SettingsLabelsRoute: SettingsLabelsRoute,

package/src/routes/mail.tsx

@@ -173,7 +173,7 @@ function MailLayout() {
 		[accounts],
 	);
 	const mailboxNameIndex = useMailboxNameIndex(accounts);
-	const resultFolderIndex = useResultFolderIndex(accounts);
+	const resultFolderIndex = useResultFolderIndex(accounts).index;
 	const accountNameIndex = useMemo(
 		() => buildAccountNameIndex(accounts),
 		[accounts],

package/src/routes/settings/calendars.tsx

@@ -0,0 +1,73 @@
+import { SettingsShell } from "@remit/ui";
+import { createFileRoute, useNavigate } from "@tanstack/react-router";
+import { useState } from "react";
+import { CalendarFeedPanel } from "@/components/settings/CalendarFeedPanel";
+import { useCalendars } from "@/hooks/calendar/useCalendars";
+import { SETTINGS_ID_TO_PATH, SETTINGS_NAV_ITEMS } from "@/routes/settings";
+
+export const Route = createFileRoute("/settings/calendars")({
+	component: CalendarsSettings,
+});
+
+const calendarsHelp = (
+	<div className="space-y-3">
+		<p>
+			A subscription address lets Apple Calendar, Google Calendar, Outlook and
+			Thunderbird show a calendar from here, read-only and kept up to date.
+		</p>
+		<p>
+			Those clients never sign in, so the address itself is the credential.
+			Anyone who has it can read the calendar; nobody who has it can change
+			anything.
+		</p>
+		<p>
+			Only a hash of the address is stored, so it is shown once and cannot be
+			looked up later. Replacing it breaks every subscription built on the old
+			one, which is how a shared address is taken back.
+		</p>
+	</div>
+);
+
+function CalendarsSettings() {
+	const navigate = useNavigate();
+	const [helpOpen, setHelpOpen] = useState(true);
+	const { calendars, isLoading } = useCalendars();
+
+	return (
+		<SettingsShell
+			items={SETTINGS_NAV_ITEMS}
+			activeId="calendars"
+			title="Calendars"
+			description="Share a calendar with any client that can subscribe to a URL."
+			help={calendarsHelp}
+			helpOpen={helpOpen}
+			onToggleHelp={() => setHelpOpen((open) => !open)}
+			onSelect={(id) => {
+				const path = SETTINGS_ID_TO_PATH[id];
+				if (path) void navigate({ to: path });
+			}}
+			onBackToMail={() => void navigate({ to: "/mail" })}
+		>
+			{isLoading ? (
+				// biome-ignore lint/a11y/useAriaPropsSupportedByRole: aria-label on a loading skeleton is what assistive tech has to go on
+				<div
+					className="h-24 animate-pulse rounded-sm border border-line bg-surface"
+					aria-busy="true"
+					aria-label="Loading calendars"
+				/>
+			) : calendars.length === 0 ? (
+				<p className="py-12 text-sm text-fg-muted">No calendars yet.</p>
+			) : (
+				<div className="space-y-4">
+					{calendars.map((calendar) => (
+						<CalendarFeedPanel
+							key={calendar.id}
+							calendarId={calendar.id}
+							calendarName={calendar.name}
+						/>
+					))}
+				</div>
+			)}
+		</SettingsShell>
+	);
+}

package/src/routes/settings.tsx

@@ -10,7 +10,15 @@
  */
 import type { SettingsNavItem } from "@remit/ui";
 import { createFileRoute, Outlet } from "@tanstack/react-router";
-import { Filter, FolderTree, Inbox, Palette, Tag, Users } from "lucide-react";
+import {
+	CalendarDays,
+	Filter,
+	FolderTree,
+	Inbox,
+	Palette,
+	Tag,
+	Users,
+} from "lucide-react";
 import { AdvancedNavIcon } from "@/components/settings/AdvancedNavIcon";
 
 /* ------------------------------------------------------------------ */
@@ -39,6 +47,11 @@ export const SETTINGS_NAV_ITEMS: SettingsNavItem[] = [
 		label: "Labels",
 		icon: <Tag className="size-4" />,
 	},
+	{
+		id: "calendars",
+		label: "Calendars",
+		icon: <CalendarDays className="size-4" />,
+	},
 	{
 		id: "appearance",
 		label: "Appearance",
@@ -53,6 +66,7 @@ export const SETTINGS_ID_TO_PATH: Record<string, string> = {
 	folders: "/settings/folders",
 	filters: "/settings/filters",
 	labels: "/settings/labels",
+	calendars: "/settings/calendars",
 	appearance: "/settings/appearance",
 	advanced: "/settings/advanced",
 };

package/src/hooks/useAccountDelimiters.ts

@@ -1,41 +0,0 @@
-/**
- * The hierarchy separator each account's own server reports, for surfaces that
- * hold a provider path but not the mailbox row it came from — quarantine, so
- * far. Fans out the same per-account mailbox-list query as
- * `useResultFolderIndex` (cached forever, react-query dedupes the identical key
- * across call sites) and keeps only the delimiter.
- */
-import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapMailboxResponse } from "@remit/api-http-client/types.gen.ts";
-import { useQueries } from "@tanstack/react-query";
-import { useMemo } from "react";
-import { folderDelimiter } from "@/lib/move-options";
-
-/**
- * Hoisted so `useQueries` treats this as a memo rather than a per-render
- * reduce — see `useResultFolderIndex`.
- */
-const combineDelimiters = (
-	results: { data?: { items: RemitImapMailboxResponse[] } }[],
-): string[] =>
-	results.map((result) => folderDelimiter(result.data?.items ?? []));
-
-export function useAccountDelimiters(
-	accountIds: readonly string[],
-): ReadonlyMap<string, string> {
-	const delimiters = useQueries({
-		queries: accountIds.map((accountId) => ({
-			...mailboxOperationsListMailboxesOptions({ path: { accountId } }),
-			staleTime: Infinity,
-		})),
-		combine: combineDelimiters,
-	});
-
-	return useMemo(
-		() =>
-			new Map(
-				accountIds.map((accountId, i) => [accountId, delimiters[i] ?? "/"]),
-			),
-		[accountIds, delimiters],
-	);
-}