@remit/web-client 0.0.325 → 0.0.327

package/dist/src/hooks/useTriageLayer.js

@@ -0,0 +1,99 @@
+/**
+ * The pane-level interaction layer: the bridge between a mounted list and the
+ * global keyboard dispatcher, plus next/previous adjacency.
+ *
+ * The list publishes `MessageListCommands` into `listCommandsRef` and reports
+ * its cursor and selection through `onTriageContextChange`; the keyboard hook
+ * registers the navigation and selection keys only while a list is serving
+ * them, so with no list mounted Enter, Space and ⌘A stay with the browser.
+ *
+ * This lived inside `MailboxPane`, which is why the brief and Flagged had a
+ * keyboard hint bar and no keyboard (#149). Every pane mounts it now.
+ *
+ * It is two hooks because a pane's verbs are aimed at the focused row: the
+ * context comes first, the pane builds its handlers from it, and the keyboard
+ * registration comes last.
+ *
+ * A modal open over the pane is not this layer's problem. Every overlay declares
+ * itself on the shared stack (`@remit/ui`'s `overlay-scope`) and `useTriageKeyboard`
+ * contains what the top frame does not serve, so the pane no longer reports which
+ * of its own dialogs is up and every other layer on the page suspends with it.
+ *
+ * While a thread is open, `ConversationView` binds its own window listener for
+ * the messages inside it, and both used to act on one press (#723). The split
+ * is the one `shortcut-tree` already declares: the cursor keys belong to
+ * whichever surface has a list on screen, and answering a thread belongs to
+ * the open thread — so `hasOpenThread` hands r, a and f over, and the list
+ * keeps j/k, Home/End and Enter for as long as it is mounted.
+ */
+import { useTriageKeyboard } from "@remit/ui";
+import { useCallback, useRef, useState } from "react";
+import { adjacentMessageId } from "../lib/adjacent-message";
+export const useTriageContext = () => {
+    const [focusedMessageId, setFocusedMessageId] = useState(undefined);
+    const [selectedIds, setSelectedIds] = useState([]);
+    const [orderedIds, setOrderedIds] = useState([]);
+    // Null whenever no list is mounted (reading-only phone view, drafts) — the
+    // keyboard layer then simply has nothing to drive.
+    const listCommandsRef = useRef(null);
+    const [hasList, setHasList] = useState(false);
+    const onTriageContextChange = useCallback((context) => {
+        setFocusedMessageId(context.focusedMessageId);
+        setSelectedIds(context.selectedIds);
+        if (context.orderedIds)
+            setOrderedIds(context.orderedIds);
+        setHasList(context.hasList);
+    }, []);
+    return {
+        listCommandsRef,
+        onTriageContextChange,
+        focusedMessageId,
+        selectedIds,
+        orderedIds,
+        hasList,
+    };
+};
+export const useTriageLayer = ({ context, orderedIds, selectedMessageId, enabled = true, onClose, handlers, hasOpenThread = false, }) => {
+    const { listCommandsRef, hasList } = context;
+    const goBack = useCallback(() => {
+        if (listCommandsRef.current?.clearSelection())
+            return;
+        if (selectedMessageId)
+            onClose();
+    }, [listCommandsRef, selectedMessageId, onClose]);
+    // Dropped rather than kept and guarded: an unregistered action is never
+    // preventDefault-ed (see useTriageKeyboard), so the keystroke falls through
+    // to ConversationView's own listener instead of two handlers racing on one
+    // keypress.
+    const { reply, replyAll, forward, ...restHandlers } = handlers;
+    useTriageKeyboard({
+        enabled,
+        handlers: {
+            // Registered only while a list is mounted to serve them. An unregistered
+            // action is never preventDefault-ed, so with no list the browser keeps
+            // Enter, Space and ⌘A — select-all-text in the reading pane still works.
+            ...(hasList
+                ? {
+                    focusNext: () => listCommandsRef.current?.focusNext(),
+                    focusPrevious: () => listCommandsRef.current?.focusPrevious(),
+                    focusFirst: () => listCommandsRef.current?.focusFirst(),
+                    focusLast: () => listCommandsRef.current?.focusLast(),
+                    openFocused: () => listCommandsRef.current?.openFocused(),
+                    toggleSelect: () => listCommandsRef.current?.toggleSelect(),
+                    extendSelectDown: () => listCommandsRef.current?.extendSelectDown(),
+                    extendSelectUp: () => listCommandsRef.current?.extendSelectUp(),
+                    selectAll: () => listCommandsRef.current?.selectAll(),
+                    toggleDensity: () => listCommandsRef.current?.toggleDensity(),
+                }
+                : {}),
+            back: goBack,
+            ...restHandlers,
+            ...(hasOpenThread ? {} : { reply, replyAll, forward }),
+        },
+    });
+    return {
+        goBack,
+        nextMessageId: adjacentMessageId(orderedIds, selectedMessageId, "next") ?? undefined,
+        previousMessageId: adjacentMessageId(orderedIds, selectedMessageId, "previous") ?? undefined,
+    };
+};

package/dist/src/hooks/useTriggerSync.d.ts

@@ -0,0 +1,30 @@
+interface UseTriggerSyncResult {
+    trigger: () => void;
+    triggerAsync: () => Promise<unknown>;
+    isPending: boolean;
+    error: unknown;
+    reset: () => void;
+}
+/**
+ * Build the TanStack query key for the mailbox-list query owned by the
+ * given account. Extracted from the hook so the staleness/invalidation
+ * contract can be unit-tested without rendering React.
+ */
+export declare const buildMailboxListKey: (accountId: string) => [Pick<import("@remit/api-http-client").Options<import("@remit/api-http-client").MailboxOperationsListMailboxesData>, "query" | "body" | "headers" | "path" | "baseUrl"> & {
+    _id: string;
+    _infinite?: boolean;
+    tags?: ReadonlyArray<string>;
+}];
+/**
+ * Trigger a server-side mailbox-list sync for an account.
+ *
+ * Wraps the generated `syncOperationsTriggerSync` mutation. The backend
+ * enqueues a SYNC_MAILBOXES SQS event and the worker picks it up; the
+ * mutation resolves as soon as the enqueue ack returns, not when the
+ * sync itself finishes. We invalidate the account's mailboxes query on
+ * success so the freshly-synced rows are re-fetched once the worker
+ * writes them — TanStack will pick the new data up via its background
+ * refetch on the next render.
+ */
+export declare const useTriggerSync: (accountId: string) => UseTriggerSyncResult;
+export {};

package/dist/src/hooks/useTriggerSync.js

@@ -0,0 +1,42 @@
+import { mailboxOperationsListMailboxesQueryKey, syncOperationsTriggerSyncMutation, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useTelemetry } from "../lib/telemetry-context";
+/**
+ * Build the TanStack query key for the mailbox-list query owned by the
+ * given account. Extracted from the hook so the staleness/invalidation
+ * contract can be unit-tested without rendering React.
+ */
+export const buildMailboxListKey = (accountId) => mailboxOperationsListMailboxesQueryKey({ path: { accountId } });
+/**
+ * Trigger a server-side mailbox-list sync for an account.
+ *
+ * Wraps the generated `syncOperationsTriggerSync` mutation. The backend
+ * enqueues a SYNC_MAILBOXES SQS event and the worker picks it up; the
+ * mutation resolves as soon as the enqueue ack returns, not when the
+ * sync itself finishes. We invalidate the account's mailboxes query on
+ * success so the freshly-synced rows are re-fetched once the worker
+ * writes them — TanStack will pick the new data up via its background
+ * refetch on the next render.
+ */
+export const useTriggerSync = (accountId) => {
+    const queryClient = useQueryClient();
+    const telemetry = useTelemetry();
+    const mutation = useMutation({
+        ...syncOperationsTriggerSyncMutation(),
+        onSuccess: () => {
+            telemetry.recordEvent("sync.triggered");
+            queryClient.invalidateQueries({
+                queryKey: buildMailboxListKey(accountId),
+            });
+        },
+    });
+    return {
+        trigger: () => {
+            mutation.mutate({ path: { accountId } });
+        },
+        triggerAsync: () => mutation.mutateAsync({ path: { accountId } }),
+        isPending: mutation.isPending,
+        error: mutation.error,
+        reset: mutation.reset,
+    };
+};

package/dist/src/hooks/useUpdateAddressFlags.d.ts

@@ -0,0 +1,18 @@
+import type { RemitImapAddressFlagKey, RemitImapUpdateAddressFlagsInput } from "@remit/api-http-client/types.gen.ts";
+interface UseUpdateAddressFlagsOptions {
+    addressId: string | undefined;
+    /** The normalizedEmail of the sender — used to key the address search cache. */
+    senderEmail: string | undefined;
+}
+/**
+ * Optimistic PATCH for per-sender flags (VIP / Mute / Block).
+ * Mirrors the `useToggleTrusted` pattern: patch the cached
+ * address-search response so the toggle flips instantly, roll back on error,
+ * and invalidate on settle to reconcile with the server.
+ */
+export declare function useUpdateAddressFlags({ addressId, senderEmail, }: UseUpdateAddressFlagsOptions): {
+    updateFlags: (flags: RemitImapUpdateAddressFlagsInput) => void;
+    clearFlags: (keys: RemitImapAddressFlagKey[]) => void;
+    isPending: boolean;
+};
+export {};

package/dist/src/hooks/useUpdateAddressFlags.js

@@ -0,0 +1,93 @@
+import { addressDetailOperationsUpdateAddressMutation, addressOperationsSearchAddressesQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { useErrorBanners } from "../components/ui/ErrorBannerProvider";
+import { formatErrorDetail } from "../components/ui/error-banners";
+import { reportFatalError } from "../lib/fatal-error";
+import { senderAddressSearchQuery } from "../lib/sender-address";
+/**
+ * Apply a flag update onto an existing AddressFlags object. Each key in
+ * `patch` is a flag update object; each key in `clear` is removed outright,
+ * after the patch, matching the server's ordering. Mirrors the server-side
+ * merge semantics so the optimistic cache matches what the API returns. Typed
+ * loosely (the per-key flag value types differ — boolean for most, a category
+ * enum for `category`) and re-narrowed at the return.
+ */
+function applyFlagPatch(current, patch, clear = []) {
+    const next = { ...(current ?? {}) };
+    for (const [key, update] of Object.entries(patch)) {
+        if (update == null) {
+            delete next[key];
+        }
+        else {
+            // Each flag is `{ value, setAt? }`. Stamp setAt so the optimistic
+            // shape matches what the server writes back.
+            next[key] = { ...update, setAt: update.setAt ?? Date.now() };
+        }
+    }
+    for (const key of clear) {
+        delete next[key];
+    }
+    return next;
+}
+/**
+ * Optimistic PATCH for per-sender flags (VIP / Mute / Block).
+ * Mirrors the `useToggleTrusted` pattern: patch the cached
+ * address-search response so the toggle flips instantly, roll back on error,
+ * and invalidate on settle to reconcile with the server.
+ */
+export function useUpdateAddressFlags({ addressId, senderEmail, }) {
+    const queryClient = useQueryClient();
+    const { pushError } = useErrorBanners();
+    const addressCacheKey = addressOperationsSearchAddressesQueryKey({
+        query: senderAddressSearchQuery(senderEmail),
+    });
+    const { mutate, isPending } = useMutation({
+        ...addressDetailOperationsUpdateAddressMutation(),
+        onMutate: async (vars) => {
+            const patch = vars.body.flags ?? {};
+            const clear = vars.body.clearFlags ?? [];
+            await queryClient.cancelQueries({ queryKey: addressCacheKey });
+            const previous = queryClient.getQueryData(addressCacheKey);
+            queryClient.setQueryData(addressCacheKey, (old) => {
+                if (!old)
+                    return old;
+                return {
+                    ...old,
+                    items: old.items.map((addr) => addr.addressId === vars.path.addressId
+                        ? { ...addr, flags: applyFlagPatch(addr.flags, patch, clear) }
+                        : addr),
+                };
+            });
+            return { previous };
+        },
+        onError: (err, _vars, context) => {
+            if (context?.previous !== undefined) {
+                queryClient.setQueryData(addressCacheKey, context.previous);
+            }
+            pushError({
+                title: "Couldn't update sender preference",
+                detail: formatErrorDetail(err),
+                error: err,
+            });
+        },
+        onSettled: () => {
+            queryClient.invalidateQueries({ queryKey: addressCacheKey });
+        },
+    });
+    const submit = useCallback((body) => {
+        if (!addressId) {
+            reportFatalError(new Error(`Quick action fired but the sender's address record did not resolve (sender: ${senderEmail ?? "unknown"}). This should never happen — the address row exists.`));
+            return;
+        }
+        mutate({ path: { addressId }, body });
+    }, [addressId, mutate, senderEmail]);
+    const updateFlags = useCallback((flags) => submit({ flags }), [submit]);
+    /**
+     * Remove flags outright. This is the removal form for every flag whatever
+     * its value type: `category` holds an enum with no false-equivalent member,
+     * so `{ value: false }` cannot express "no override" for it.
+     */
+    const clearFlags = useCallback((keys) => submit({ clearFlags: keys }), [submit]);
+    return { updateFlags, clearFlags, isPending };
+}

package/dist/src/hooks/useUpdateFilter.d.ts

@@ -0,0 +1,16 @@
+import type { RemitImapUpdateFilterInput } from "@remit/api-http-client/types.gen.ts";
+/**
+ * Patch an existing filter (RFC 038 D6). The server bumps `ruleChangedAt` only
+ * when the body touches a predicate or action field, never on a name-only
+ * rename (RFC 034 Decision 3.2) — the caller decides which fields to send. On
+ * success both the account's filter list and this filter's detail are
+ * invalidated so the settings page and any open editor read the saved rule.
+ */
+export declare const useUpdateFilter: (accountId: string | undefined, filterId: string | undefined) => {
+    updateFilter: (body: RemitImapUpdateFilterInput) => void;
+    isPending: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    error: import("@remit/api-http-client").ApiError | null;
+    reset: () => void;
+};

package/dist/src/hooks/useUpdateFilter.js

@@ -0,0 +1,45 @@
+import { filterDetailOperationsGetFilterQueryKey, filterDetailOperationsUpdateFilterMutation, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { buildFilterListKey } from "./useFilters";
+/**
+ * Patch an existing filter (RFC 038 D6). The server bumps `ruleChangedAt` only
+ * when the body touches a predicate or action field, never on a name-only
+ * rename (RFC 034 Decision 3.2) — the caller decides which fields to send. On
+ * success both the account's filter list and this filter's detail are
+ * invalidated so the settings page and any open editor read the saved rule.
+ */
+export const useUpdateFilter = (accountId, filterId) => {
+    const queryClient = useQueryClient();
+    const mutation = useMutation({
+        ...filterDetailOperationsUpdateFilterMutation(),
+        onSuccess: () => {
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({
+                queryKey: buildFilterListKey(accountId),
+            });
+            if (filterId) {
+                queryClient.invalidateQueries({
+                    queryKey: filterDetailOperationsGetFilterQueryKey({
+                        path: { accountId, filterId },
+                    }),
+                });
+            }
+        },
+    });
+    const { mutate } = mutation;
+    const updateFilter = useCallback((body) => {
+        if (!accountId || !filterId)
+            return;
+        mutate({ path: { accountId, filterId }, body });
+    }, [accountId, filterId, mutate]);
+    return {
+        updateFilter,
+        isPending: mutation.isPending,
+        isSuccess: mutation.isSuccess,
+        isError: mutation.isError,
+        error: mutation.error,
+        reset: mutation.reset,
+    };
+};

package/dist/src/hooks/useVisualViewport.d.ts

@@ -0,0 +1,13 @@
+interface VisualViewportState {
+    /** Current visual viewport height in pixels. */
+    viewportHeight: number;
+    /** True when the viewport has shrunk significantly (e.g. software keyboard open). */
+    isKeyboardOpen: boolean;
+}
+/**
+ * Tracks `window.visualViewport` resize events and reports whether the
+ * software keyboard is likely open. SSR-safe — returns safe defaults
+ * when `window` or `visualViewport` are unavailable.
+ */
+export declare const useVisualViewport: () => VisualViewportState;
+export {};

package/dist/src/hooks/useVisualViewport.js

@@ -0,0 +1,37 @@
+import { useEffect, useState } from "react";
+/** Minimum shrinkage (px) from window.innerHeight to consider the keyboard open. */
+const KEYBOARD_THRESHOLD = 150;
+/**
+ * Tracks `window.visualViewport` resize events and reports whether the
+ * software keyboard is likely open. SSR-safe — returns safe defaults
+ * when `window` or `visualViewport` are unavailable.
+ */
+export const useVisualViewport = () => {
+    const [state, setState] = useState(() => {
+        if (typeof window === "undefined" || !window.visualViewport) {
+            return { viewportHeight: 0, isKeyboardOpen: false };
+        }
+        const h = window.visualViewport.height;
+        return {
+            viewportHeight: h,
+            isKeyboardOpen: window.innerHeight - h > KEYBOARD_THRESHOLD,
+        };
+    });
+    useEffect(() => {
+        if (typeof window === "undefined" || !window.visualViewport)
+            return;
+        const vv = window.visualViewport;
+        const update = () => {
+            const h = vv.height;
+            setState({
+                viewportHeight: h,
+                isKeyboardOpen: window.innerHeight - h > KEYBOARD_THRESHOLD,
+            });
+        };
+        // Sync on mount
+        update();
+        vv.addEventListener("resize", update);
+        return () => vv.removeEventListener("resize", update);
+    }, []);
+    return state;
+};

package/dist/src/hooks/useWarningsAttention.d.ts

@@ -0,0 +1,9 @@
+import type { RemitImapQuarantineListResponse } from "@remit/api-http-client/types.gen.ts";
+export declare function useWarningsList(): import("@tanstack/react-query").UseQueryResult<NoInfer<RemitImapQuarantineListResponse>, import("@remit/api-http-client").ApiError>;
+export declare const WARNINGS_ATTENTION: {
+    readonly listed: "Sync warnings";
+    readonly unread: "Warnings could not be read";
+    readonly signedOut: "Session ended";
+};
+export declare function warningsAttentionOf(data: RemitImapQuarantineListResponse | undefined, error: unknown): string | undefined;
+export declare function useWarningsAttention(): string | undefined;

package/dist/src/hooks/useWarningsAttention.js

@@ -0,0 +1,31 @@
+import { meOperationsListQuarantineOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { isUnauthenticated, softErrorStatuses } from "../lib/error-classifier";
+const WARNINGS_LIST_META = softErrorStatuses(401);
+export function useWarningsList() {
+    return useQuery({
+        ...meOperationsListQuarantineOptions(),
+        meta: WARNINGS_LIST_META,
+    });
+}
+export const WARNINGS_ATTENTION = {
+    listed: "Sync warnings",
+    unread: "Warnings could not be read",
+    signedOut: "Session ended",
+};
+export function warningsAttentionOf(data, error) {
+    if (isUnauthenticated(error))
+        return WARNINGS_ATTENTION.signedOut;
+    if (error)
+        return WARNINGS_ATTENTION.unread;
+    if (!data)
+        return undefined;
+    if ((data.entries?.length ?? 0) > 0 || (data.warnings?.length ?? 0) > 0) {
+        return WARNINGS_ATTENTION.listed;
+    }
+    return undefined;
+}
+export function useWarningsAttention() {
+    const list = useWarningsList();
+    return warningsAttentionOf(list.data, list.error);
+}

package/dist/src/index.css

@@ -0,0 +1,27 @@
+/* remit-ui owns @import "tailwindcss", the @theme token block, :root and
+   .dark — importing its token sheet gives the web client the full design
+   system. The @custom-variant dark declaration inside tokens.css covers
+   the .dark ancestor scope used everywhere in this app. */
+@import "@remit/ui/tokens.css";
+
+/* Tailwind v4 content scanning: name every source Tailwind must inspect for
+   utility class usage. Automatic detection is rooted at the Vite root, which
+   for the distributor harness build is a throwaway directory holding only the
+   entry — so nothing here may rely on it. This package's own components are
+   declared here; @remit/ui declares its own in tokens.css.
+
+   Tests are excluded: they assert on class strings, and a scanned assertion
+   emits the utility it names into the shipped stylesheet. */
+@source "./**/*.{js,ts,tsx}";
+@source not "./**/*.test.{ts,tsx}";
+@source not "./**/*.d.ts";
+
+/* Hide scrollbars while maintaining scroll functionality */
+.overflow-y-auto {
+  scrollbar-width: none; /* Firefox */
+  -ms-overflow-style: none; /* IE/Edge */
+}
+
+.overflow-y-auto::-webkit-scrollbar {
+  display: none; /* Chrome, Safari, Opera */
+}

package/dist/src/lib/account-order.d.ts

@@ -0,0 +1,3 @@
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+export declare const compareAccounts: (a: RemitImapAccountResponse, b: RemitImapAccountResponse) => number;
+export declare const sortAccountsByCreatedAt: <T extends RemitImapAccountResponse>(accounts: readonly T[]) => T[];

package/dist/src/lib/account-order.js

@@ -0,0 +1,6 @@
+export const compareAccounts = (a, b) => {
+    if (a.createdAt !== b.createdAt)
+        return a.createdAt - b.createdAt;
+    return a.accountId.localeCompare(b.accountId);
+};
+export const sortAccountsByCreatedAt = (accounts) => [...accounts].sort(compareAccounts);

package/dist/src/lib/adjacent-message.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves the message id adjacent to `currentId` in `orderedIds`.
+ *
+ * The list is in display order (newest first). "next" walks down the list
+ * (older), "previous" walks up (newer) — matching the j/k keyboard navigation
+ * and the visual top-to-bottom order. Returns `null` at the ends of the list
+ * (no wrap) and when the current id is not present.
+ */
+export declare const adjacentMessageId: (orderedIds: string[], currentId: string | undefined, direction: "next" | "previous") => string | null;

package/dist/src/lib/adjacent-message.js

@@ -0,0 +1,19 @@
+/**
+ * Resolves the message id adjacent to `currentId` in `orderedIds`.
+ *
+ * The list is in display order (newest first). "next" walks down the list
+ * (older), "previous" walks up (newer) — matching the j/k keyboard navigation
+ * and the visual top-to-bottom order. Returns `null` at the ends of the list
+ * (no wrap) and when the current id is not present.
+ */
+export const adjacentMessageId = (orderedIds, currentId, direction) => {
+    if (!currentId)
+        return null;
+    const index = orderedIds.indexOf(currentId);
+    if (index === -1)
+        return null;
+    const target = direction === "next" ? index + 1 : index - 1;
+    if (target < 0 || target >= orderedIds.length)
+        return null;
+    return orderedIds[target];
+};

package/dist/src/lib/api.d.ts

@@ -0,0 +1,35 @@
+import type { ApiError as ApiErrorWireBody } from "@remit/api-http-client/types.gen.ts";
+export declare class ApiError extends Error {
+    status: number;
+    body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+/**
+ * The wire body's coded half, re-checked at runtime. `ApiErrorWireBody` is the
+ * generated flat shape the API sends; `ApiError` is the class every HTTP
+ * failure arrives in, carrying that body at `.body`. Reading `code` off the
+ * class is the bug #1004 is about, so nothing outside this module reaches for
+ * either shape directly.
+ */
+export interface CodedApiErrorBody {
+    code: ApiErrorWireBody["code"];
+    details: Record<string, unknown> | undefined;
+}
+export declare const codedApiErrorBody: (error: unknown) => CodedApiErrorBody | undefined;
+/**
+ * The one place an HTTP failure becomes an `ApiError`, so a test can hand a
+ * consumer the exact value the error interceptor produces.
+ */
+export declare const wrapHttpFailure: (body: unknown, status: number) => ApiError;
+interface RequestOptions extends Omit<RequestInit, "body"> {
+    params?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+}
+export declare const api: {
+    get: <T>(path: string, options?: RequestOptions) => Promise<T>;
+    post: <T>(path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+    put: <T>(path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+    patch: <T>(path: string, body?: unknown, options?: RequestOptions) => Promise<T>;
+    delete: <T>(path: string, options?: RequestOptions) => Promise<T>;
+};
+export {};

package/dist/src/lib/api.js

@@ -0,0 +1,73 @@
+import { taggedFetch } from "./network-error";
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const codedApiErrorBody = (error) => {
+    const body = error instanceof ApiError ? error.body : error;
+    if (!isRecord(body))
+        return undefined;
+    const { code, details } = body;
+    if (typeof code !== "string")
+        return undefined;
+    return { code, details: isRecord(details) ? details : undefined };
+};
+const failureMessage = (body, status) => {
+    if (isRecord(body) && body.message !== undefined && body.message !== null) {
+        const message = String(body.message);
+        if (message)
+            return message;
+    }
+    return `Request failed with status ${status}`;
+};
+/**
+ * The one place an HTTP failure becomes an `ApiError`, so a test can hand a
+ * consumer the exact value the error interceptor produces.
+ */
+export const wrapHttpFailure = (body, status) => new ApiError(failureMessage(body, status), status, body);
+const buildUrl = (path, params) => {
+    const url = new URL(path, window.location.origin);
+    if (params) {
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined) {
+                url.searchParams.set(key, String(value));
+            }
+        });
+    }
+    return url.toString();
+};
+const request = async (method, path, options = {}) => {
+    const { params, body, headers, ...rest } = options;
+    const url = buildUrl(path, params);
+    const response = await taggedFetch(url, {
+        method,
+        headers: {
+            "Content-Type": "application/json",
+            ...headers,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        ...rest,
+    });
+    if (!response.ok) {
+        const errorBody = await response.json().catch(() => undefined);
+        throw wrapHttpFailure(errorBody, response.status);
+    }
+    if (response.status === 204) {
+        return undefined;
+    }
+    return response.json();
+};
+export const api = {
+    get: (path, options) => request("GET", path, options),
+    post: (path, body, options) => request("POST", path, { ...options, body }),
+    put: (path, body, options) => request("PUT", path, { ...options, body }),
+    patch: (path, body, options) => request("PATCH", path, { ...options, body }),
+    delete: (path, options) => request("DELETE", path, options),
+};

package/dist/src/lib/app-info.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Build-time constants injected by vite.config.ts via `define`.
+ * __APP_SHA__ is the full git SHA (or "dev" in local builds without git).
+ * __APP_BUILD_TIME__ is an ISO timestamp.
+ *
+ * Read through `typeof` because not every host that renders this app's
+ * components applies the `define` — Storybook's test runner mounts them
+ * without it — and a bare reference is a ReferenceError at module scope that
+ * takes the importing story down with it. An unknown build is the same
+ * "dev" the git-less local build already resolves to.
+ */
+export declare const APP_SHA: string;
+export declare const APP_BUILD_TIME: string;
+/** First 7 characters of the SHA, matching git's default short form. */
+export declare const APP_SHORT_SHA: string;
+/**
+ * True when `APP_SHA` is a real git commit — a build that was given the commit
+ * (via `GITHUB_SHA` at build time). A local build with no git resolves to the
+ * literal "dev", which is not a commit and must not be linked (a
+ * `/commit/dev` URL is a dead link).
+ */
+export declare const APP_SHA_IS_COMMIT: boolean;
+/** Commit URL for the build, or undefined when the build has no real SHA. */
+export declare const GITHUB_COMMIT_URL: string | undefined;