@remit/web-client 0.0.325 → 0.0.326

package/dist/src/hooks/calendar/useCalendarCollectionWrites.js

@@ -0,0 +1,75 @@
+/**
+ * Creating, renaming, rezoning and deleting a calendar collection.
+ *
+ * A refusal comes back as an outcome carrying the server's own words — a url
+ * segment already taken, a zone it cannot resolve, the default calendar that
+ * cannot be removed — so the settings card states it where the reader acted.
+ * A lapsed session is not among the statuses owned here and escalates.
+ *
+ * Every write invalidates the listing, which is what the settings page, the
+ * editor's picker and the address filter all read. A delete or a rezone also
+ * moves or removes occurrences, so the event reads are invalidated with it.
+ */
+import { calendarDetailOperationsDeleteCalendarMutation, calendarDetailOperationsUpdateCalendarMutation, calendarOperationsCreateCalendarMutation, calendarOperationsListCalendarsQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { formatErrorMessage } from "@remit/ui";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+import { softErrorStatuses } from "../../lib/error-classifier";
+import { useInvalidateCalendarReads } from "./useCalendarWrites";
+const COLLECTION_WRITE_META = softErrorStatuses(400, 404);
+const WRITTEN = { kind: "written" };
+const refused = (error) => ({
+    kind: "refused",
+    message: formatErrorMessage(error),
+});
+export function useCalendarCollectionWrites() {
+    const queryClient = useQueryClient();
+    const invalidateReads = useInvalidateCalendarReads();
+    const invalidateListing = useCallback(() => queryClient.invalidateQueries({
+        queryKey: calendarOperationsListCalendarsQueryKey(),
+    }), [queryClient]);
+    const invalidateAll = useCallback(() => {
+        invalidateReads();
+        return invalidateListing();
+    }, [invalidateReads, invalidateListing]);
+    const create = useMutation({
+        ...calendarOperationsCreateCalendarMutation(),
+        meta: COLLECTION_WRITE_META,
+        onSuccess: invalidateListing,
+    });
+    const update = useMutation({
+        ...calendarDetailOperationsUpdateCalendarMutation(),
+        meta: COLLECTION_WRITE_META,
+        onSuccess: invalidateAll,
+    });
+    const remove = useMutation({
+        ...calendarDetailOperationsDeleteCalendarMutation(),
+        meta: COLLECTION_WRITE_META,
+        onSuccess: invalidateAll,
+    });
+    const createCalendar = useCallback((input) => create
+        .mutateAsync({ body: input })
+        .then(() => WRITTEN)
+        .catch(refused), [create]);
+    const updateCalendar = useCallback((calendarId, patch) => update
+        .mutateAsync({ path: { calendarId }, body: patch })
+        .then(() => WRITTEN)
+        .catch(refused), [update]);
+    const deleteCalendar = useCallback((calendarId) => remove
+        .mutateAsync({ path: { calendarId } })
+        .then(() => WRITTEN)
+        .catch(refused), [remove]);
+    return useMemo(() => ({
+        createCalendar,
+        updateCalendar,
+        deleteCalendar,
+        isWriting: create.isPending || update.isPending || remove.isPending,
+    }), [
+        createCalendar,
+        updateCalendar,
+        deleteCalendar,
+        create.isPending,
+        update.isPending,
+        remove.isPending,
+    ]);
+}

package/dist/src/hooks/calendar/useCalendarEvent.d.ts

@@ -0,0 +1,8 @@
+import type { RemitImapCalendarEventResponse } from "@remit/api-http-client/types.gen.ts";
+export interface CalendarEventResource {
+    resource: RemitImapCalendarEventResponse | undefined;
+    isLoading: boolean;
+    error: unknown;
+    refetch: () => void;
+}
+export declare function useCalendarEvent(calendarObjectId: string, calendarId: string): CalendarEventResource;

package/dist/src/hooks/calendar/useCalendarEvent.js

@@ -0,0 +1,32 @@
+/**
+ * One stored resource — the bytes behind an event, and the etag a conditional
+ * write is built on.
+ *
+ * The listing carries what a grid chip draws; this carries what an edit needs.
+ * An event opened for editing is read here first, so the `If-Match` a write
+ * sends is the version the reader actually looked at rather than whatever the
+ * grid last cached.
+ */
+import { calendarEventDetailOperationsGetCalendarEventOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { softErrorStatuses } from "../../lib/error-classifier";
+/** A resource the address names that is no longer there is an empty pane. */
+const RESOURCE_META = softErrorStatuses(404);
+export function useCalendarEvent(calendarObjectId, calendarId) {
+    const { data, isLoading, error, refetch } = useQuery({
+        ...calendarEventDetailOperationsGetCalendarEventOptions({
+            path: { calendarObjectId },
+            query: { calendarId },
+        }),
+        meta: RESOURCE_META,
+        enabled: calendarObjectId !== "" && calendarId !== "",
+    });
+    return {
+        resource: data,
+        isLoading,
+        error,
+        refetch: () => {
+            refetch();
+        },
+    };
+}

package/dist/src/hooks/calendar/useCalendarEvents.d.ts

@@ -0,0 +1,58 @@
+import type { RemitImapCalendarEventInstance } from "@remit/api-http-client/types.gen.ts";
+import type { CalendarViewId } from "@remit/ui";
+import { type CalendarWindow } from "./window";
+/**
+ * How long a window stays worth reusing.
+ *
+ * Explicit rather than inherited, because prefetching is the whole point: a
+ * warmed week that is already stale by the time the reader steps onto it is
+ * fetched twice and the step waits anyway. Nothing here goes out of date on a
+ * timer — every write invalidates the windows it touched — so this only needs
+ * to outlast the reader moving back and forth across a few weeks.
+ */
+export declare const CALENDAR_WINDOW_STALE_TIME: number;
+export interface CalendarEventWindowRequest extends CalendarWindow {
+    /** Empty asks about every calendar the account holds. */
+    calendarIds: readonly string[];
+    /** False while the tick list is still being resolved against real calendars. */
+    enabled?: boolean;
+}
+export interface CalendarEventWindowResult {
+    instances: RemitImapCalendarEventInstance[];
+    isLoading: boolean;
+    /** A refusal this surface renders inline. Null when the read succeeded. */
+    error: unknown;
+    refetch: () => void;
+}
+/** One window, asked for once however many surfaces are drawing it. */
+export declare function useCalendarEventWindow(request: CalendarEventWindowRequest): CalendarEventWindowResult;
+export interface CalendarEventWeeksResult {
+    instances: RemitImapCalendarEventInstance[];
+    /** Windows whose answer has not arrived, by their `from`. */
+    pendingWindows: Set<string>;
+    /** The first refusal any of them met. Null when they all succeeded. */
+    error: unknown;
+    refetch: () => void;
+}
+/**
+ * Several windows at once, each fetched and cached on its own.
+ *
+ * This is what lets a surface hold a range wider than a single read may ask
+ * for: the server refuses a window over a year, and one request that grows
+ * every time the reader reaches an end eventually becomes that window and
+ * replaces what is on screen with a refusal. A week per request has no such
+ * ceiling — reaching an end adds a key rather than widening one — and because
+ * the keys are the grid's own, dropping into the week grid and coming back out
+ * draws from what the strip already fetched, and vice versa.
+ *
+ * Windows already held keep their entries while a new one is in flight, so
+ * nothing on screen is given up to fetch what is beside it.
+ */
+export declare function useCalendarEventWeeks(windows: readonly CalendarWindow[], calendarIds: readonly string[], enabled: boolean): CalendarEventWeeksResult;
+/**
+ * The windows either side of the one on screen, warmed while the reader is
+ * looking at this one. A step is a navigation, and a navigation that has to
+ * wait for a request reads as the calendar being slow rather than as the week
+ * being fetched.
+ */
+export declare function usePrefetchAdjacentWindows(view: CalendarViewId, date: string, calendarIds: readonly string[], enabled: boolean): void;

package/dist/src/hooks/calendar/useCalendarEvents.js

@@ -0,0 +1,128 @@
+/**
+ * Expanded occurrences over a window.
+ *
+ * The server does the expansion, so nothing here reads an RRULE: a week grid
+ * and a day strip draw the same instances because they asked the same question,
+ * not because they each ran the same maths.
+ *
+ * The query is keyed by the window rather than by the day the address names, so
+ * every day inside a week shares one cache entry and stepping back to a week
+ * already read draws from it. The window either side is prefetched, which is
+ * what makes prev and next land on a full calendar instead of a spinner.
+ */
+import { calendarEventOperationsListCalendarEventsOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueries, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useMemo } from "react";
+import { stepCalendarDate } from "../../lib/calendar-route";
+import { softErrorStatuses } from "../../lib/error-classifier";
+import { calendarWindow } from "./window";
+/**
+ * The refusals this surface answers itself: a window the server will not read,
+ * and a calendar the address names that is no longer there. Everything else —
+ * a lapsed session above all — escalates.
+ */
+const CALENDAR_READ_META = softErrorStatuses(400, 404);
+/**
+ * How long a window stays worth reusing.
+ *
+ * Explicit rather than inherited, because prefetching is the whole point: a
+ * warmed week that is already stale by the time the reader steps onto it is
+ * fetched twice and the step waits anyway. Nothing here goes out of date on a
+ * timer — every write invalidates the windows it touched — so this only needs
+ * to outlast the reader moving back and forth across a few weeks.
+ */
+export const CALENDAR_WINDOW_STALE_TIME = 5 * 60_000;
+const requestOptions = ({ from, to, calendarIds, }) => ({
+    query: calendarIds.length === 0
+        ? { from, to }
+        : { from, to, calendarId: [...calendarIds] },
+});
+/** One window, asked for once however many surfaces are drawing it. */
+export function useCalendarEventWindow(request) {
+    const { data, isLoading, error, refetch } = useQuery({
+        ...calendarEventOperationsListCalendarEventsOptions(requestOptions(request)),
+        meta: CALENDAR_READ_META,
+        staleTime: CALENDAR_WINDOW_STALE_TIME,
+        enabled: request.enabled ?? true,
+    });
+    return {
+        instances: data?.items ?? [],
+        isLoading,
+        error,
+        refetch: () => {
+            refetch();
+        },
+    };
+}
+/**
+ * Several windows at once, each fetched and cached on its own.
+ *
+ * This is what lets a surface hold a range wider than a single read may ask
+ * for: the server refuses a window over a year, and one request that grows
+ * every time the reader reaches an end eventually becomes that window and
+ * replaces what is on screen with a refusal. A week per request has no such
+ * ceiling — reaching an end adds a key rather than widening one — and because
+ * the keys are the grid's own, dropping into the week grid and coming back out
+ * draws from what the strip already fetched, and vice versa.
+ *
+ * Windows already held keep their entries while a new one is in flight, so
+ * nothing on screen is given up to fetch what is beside it.
+ */
+export function useCalendarEventWeeks(windows, calendarIds, enabled) {
+    const results = useQueries({
+        queries: windows.map((window) => ({
+            ...calendarEventOperationsListCalendarEventsOptions(requestOptions({ ...window, calendarIds })),
+            meta: CALENDAR_READ_META,
+            staleTime: CALENDAR_WINDOW_STALE_TIME,
+            enabled,
+        })),
+    });
+    const froms = windows.map((window) => window.from).join("|");
+    const settled = results.map((result) => result.data);
+    const pendingKey = results.map((result) => result.isPending).join("|");
+    const firstError = results.find((result) => result.error)?.error ?? null;
+    // biome-ignore lint/correctness/useExhaustiveDependencies: the joined keys stand for the per-window results, which are a new array every render
+    const instances = useMemo(() => settled.flatMap((data) => data?.items ?? []), [froms, pendingKey]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: as above
+    const pendingWindows = useMemo(() => {
+        const pending = new Set();
+        windows.forEach((window, index) => {
+            if (results[index]?.isPending)
+                pending.add(window.from);
+        });
+        return pending;
+    }, [froms, pendingKey]);
+    return {
+        instances,
+        pendingWindows,
+        error: firstError,
+        refetch: () => {
+            for (const result of results) {
+                if (result.error)
+                    result.refetch();
+            }
+        },
+    };
+}
+/**
+ * The windows either side of the one on screen, warmed while the reader is
+ * looking at this one. A step is a navigation, and a navigation that has to
+ * wait for a request reads as the calendar being slow rather than as the week
+ * being fetched.
+ */
+export function usePrefetchAdjacentWindows(view, date, calendarIds, enabled) {
+    const queryClient = useQueryClient();
+    const key = [...calendarIds].join(",");
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const ids = key === "" ? [] : key.split(",");
+        for (const direction of [-1, 1]) {
+            const neighbour = calendarWindow(view, stepCalendarDate(date, view, direction));
+            void queryClient.prefetchQuery({
+                ...calendarEventOperationsListCalendarEventsOptions(requestOptions({ ...neighbour, calendarIds: ids })),
+                staleTime: CALENDAR_WINDOW_STALE_TIME,
+            });
+        }
+    }, [queryClient, view, date, key, enabled]);
+}

package/dist/src/hooks/calendar/useCalendarFeed.d.ts

@@ -0,0 +1,29 @@
+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 declare function useCalendarFeed(calendarId: string): CalendarFeedControls;

package/dist/src/hooks/calendar/useCalendarFeed.js

@@ -0,0 +1,115 @@
+/**
+ * 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 function useCalendarFeed(calendarId) {
+    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(() => { });
+    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,
+    };
+}
+function readState(query) {
+    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/dist/src/hooks/calendar/useCalendarFreeBusy.d.ts

@@ -0,0 +1,15 @@
+import type { RemitImapCalendarFreeBusySpan } from "@remit/api-http-client/types.gen.ts";
+import type { CalendarWindow } from "./window";
+export interface CalendarFreeBusyResult {
+    spans: RemitImapCalendarFreeBusySpan[];
+    /** Windows whose answer has not arrived, by their `from`. */
+    pendingWindows: Set<string>;
+    error: unknown;
+    refetch: () => void;
+}
+/**
+ * Busy time a window at a time, for the same reason the events are read that
+ * way: this endpoint refuses a window over a year too, so a range that grows
+ * as the reader scrolls cannot be one request.
+ */
+export declare function useCalendarFreeBusyWeeks(windows: readonly CalendarWindow[]): CalendarFreeBusyResult;

package/dist/src/hooks/calendar/useCalendarFreeBusy.js

@@ -0,0 +1,61 @@
+/**
+ * Busy time over a window, merged across every calendar the account holds.
+ *
+ * Not the same question as "what is on the strip". A calendar the reader has
+ * unticked still takes their Thursday afternoon, so "am I free" is answered off
+ * this and never off the rows on screen. The server does the merging, so two
+ * overlapping meetings in two calendars are one span here, and an event marked
+ * transparent or cancelled is not one at all.
+ *
+ * The endpoint takes no calendar filter, on purpose: narrowing it would answer
+ * a question nobody asked. It carries the same refusals as the window read — a
+ * window the server will not accept is stated in place, and a lapsed session
+ * escalates rather than being drawn as a clear diary.
+ */
+import { calendarFreeBusyOperationsListCalendarFreeBusyOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { softErrorStatuses } from "../../lib/error-classifier";
+import { CALENDAR_WINDOW_STALE_TIME } from "./useCalendarEvents";
+const CALENDAR_READ_META = softErrorStatuses(400, 404);
+/**
+ * Busy time a window at a time, for the same reason the events are read that
+ * way: this endpoint refuses a window over a year too, so a range that grows
+ * as the reader scrolls cannot be one request.
+ */
+export function useCalendarFreeBusyWeeks(windows) {
+    const results = useQueries({
+        queries: windows.map((window) => ({
+            ...calendarFreeBusyOperationsListCalendarFreeBusyOptions({
+                query: { from: window.from, to: window.to },
+            }),
+            meta: CALENDAR_READ_META,
+            staleTime: CALENDAR_WINDOW_STALE_TIME,
+        })),
+    });
+    const froms = windows.map((window) => window.from).join("|");
+    const settled = results.map((result) => result.data);
+    const pendingKey = results.map((result) => result.isPending).join("|");
+    // biome-ignore lint/correctness/useExhaustiveDependencies: the joined keys stand for the per-window results, which are a new array every render
+    const spans = useMemo(() => settled.flatMap((data) => data?.items ?? []), [froms, pendingKey]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: as above
+    const pendingWindows = useMemo(() => {
+        const pending = new Set();
+        windows.forEach((window, index) => {
+            if (results[index]?.isPending)
+                pending.add(window.from);
+        });
+        return pending;
+    }, [froms, pendingKey]);
+    return {
+        spans,
+        pendingWindows,
+        error: results.find((result) => result.error)?.error ?? null,
+        refetch: () => {
+            for (const result of results) {
+                if (result.error)
+                    result.refetch();
+            }
+        },
+    };
+}

package/dist/src/hooks/calendar/useCalendarJump.d.ts

@@ -0,0 +1,24 @@
+import { type CalendarJump } from "./instance";
+export type CalendarJumpSearch = {
+    kind: "Idle";
+} | {
+    kind: "Searching";
+} | {
+    kind: "Found";
+    jump: CalendarJump;
+} | {
+    kind: "Deleted";
+} | {
+    kind: "NoOccurrenceFound";
+} | {
+    kind: "SignedOut";
+} | {
+    kind: "Failed";
+    reason: string;
+};
+/**
+ * Finds the day an event falls on when the view on screen does not hold it:
+ * its occurrences in the coming year first, and failing those, the year from
+ * the resource's own start — so an event that has ended opens at its first.
+ */
+export declare function useCalendarJump(calendarObjectId: string, enabled: boolean): CalendarJumpSearch;

package/dist/src/hooks/calendar/useCalendarJump.js

@@ -0,0 +1,95 @@
+import { calendarEventDetailOperationsGetCalendarEventOptions, calendarEventOperationsListCalendarEventsOptions, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+import { getErrorStatus, softErrorStatuses } from "../../lib/error-classifier";
+import { calendarJumpOf, deviceTimeZone } from "./instance";
+const WINDOW_MS = 365 * 24 * 60 * 60_000;
+const DAY_MS = 24 * 60 * 60_000;
+const LISTING_META = softErrorStatuses(401);
+const RESOURCE_META = softErrorStatuses(401, 404);
+const instant = (ms) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, "+00:00");
+const reasonOf = (error) => {
+    const message = error instanceof Error && error.message !== ""
+        ? error.message
+        : "no reason given";
+    const status = getErrorStatus(error);
+    return status === undefined ? message : `${message} (HTTP ${status})`;
+};
+/**
+ * Finds the day an event falls on when the view on screen does not hold it:
+ * its occurrences in the coming year first, and failing those, the year from
+ * the resource's own start — so an event that has ended opens at its first.
+ */
+export function useCalendarJump(calendarObjectId, enabled) {
+    const [now] = useState(() => Date.now());
+    const clock = deviceTimeZone();
+    const nowIso = new Date(now).toISOString();
+    const ahead = useQuery({
+        ...calendarEventOperationsListCalendarEventsOptions({
+            query: {
+                from: instant(now),
+                to: instant(now + WINDOW_MS),
+                calendarObjectId,
+            },
+        }),
+        meta: LISTING_META,
+        retry: false,
+        enabled,
+    });
+    const upcoming = ahead.data
+        ? calendarJumpOf(ahead.data.items, calendarObjectId, nowIso, clock)
+        : undefined;
+    const lookup = useQuery({
+        ...calendarEventDetailOperationsGetCalendarEventOptions({
+            path: { calendarObjectId },
+        }),
+        meta: RESOURCE_META,
+        retry: false,
+        enabled: enabled && ahead.data !== undefined && upcoming === undefined,
+    });
+    const started = Date.parse(lookup.data?.dtStart ?? "");
+    const unreadableStart = lookup.data !== undefined && Number.isNaN(started);
+    const firstFrom = Number.isNaN(started) ? 0 : started - DAY_MS;
+    const first = useQuery({
+        ...calendarEventOperationsListCalendarEventsOptions({
+            query: {
+                from: instant(firstFrom),
+                to: instant(firstFrom + WINDOW_MS),
+                calendarObjectId,
+            },
+        }),
+        meta: LISTING_META,
+        retry: false,
+        enabled: enabled && lookup.data !== undefined && !unreadableStart,
+    });
+    const earliest = first.data
+        ? calendarJumpOf(first.data.items, calendarObjectId, nowIso, clock)
+        : undefined;
+    if (!enabled)
+        return { kind: "Idle" };
+    if (upcoming)
+        return { kind: "Found", jump: upcoming };
+    if (earliest)
+        return { kind: "Found", jump: earliest };
+    const deleted = getErrorStatus(lookup.error) === 404;
+    const failure = [
+        ahead.error,
+        deleted ? null : lookup.error,
+        first.error,
+    ].find((error) => error !== null);
+    if (failure !== undefined) {
+        return getErrorStatus(failure) === 401
+            ? { kind: "SignedOut" }
+            : { kind: "Failed", reason: reasonOf(failure) };
+    }
+    if (deleted)
+        return { kind: "Deleted" };
+    if (unreadableStart)
+        return {
+            kind: "Failed",
+            reason: `the stored event names no readable start (${lookup.data?.dtStart ?? ""})`,
+        };
+    if (first.data !== undefined)
+        return { kind: "NoOccurrenceFound" };
+    return { kind: "Searching" };
+}

package/dist/src/hooks/calendar/useCalendarSubscriptions.d.ts

@@ -0,0 +1,17 @@
+export interface CalendarSubscribeRequest {
+    displayName: string;
+    url: string;
+}
+export interface CalendarSubscriptionControls {
+    subscribe: (request: CalendarSubscribeRequest, onDone: () => void) => void;
+    isSubscribing: boolean;
+    subscribeError: unknown;
+    setEnabled: (calendarId: string, enabled: boolean) => void;
+    togglingCalendarId: string;
+    /** The last pause or resume the server turned down, and whose it was. */
+    toggleFailure: {
+        calendarId: string;
+        error: unknown;
+    };
+}
+export declare function useCalendarSubscriptions(): CalendarSubscriptionControls;