@agent-native/dispatch 0.17.3 → 0.18.0

package/src/components/transactional-email-metrics.tsx

@@ -0,0 +1,127 @@
+import { useT } from "@agent-native/core/client/i18n";
+
+import { Skeleton } from "./ui/skeleton";
+import { Tooltip, TooltipContent, TooltipTrigger } from "./ui/tooltip";
+
+/**
+ * Shared between the transactional email list and detail pages so both
+ * render the same "unknown vs. zero" and provider-availability rules.
+ */
+
+export interface EmailEngagement {
+  templateId: string;
+  delivered: number;
+  uniqueOpens: number;
+  uniqueClicks: number;
+  /** null when nothing was delivered in the window, so there is no rate yet. */
+  openRate: number | null;
+}
+
+export type ProviderMetricsResult<T> =
+  | { available: true; data: T }
+  | { available: false; reason: string };
+
+/**
+ * Renders a metric the backend could not read. "Unknown" and "zero" must stay
+ * visibly different — a dash with a reason is the only honest rendering.
+ */
+export function UnknownMetric({ reason }: { reason: string }) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span className="cursor-help text-muted-foreground underline decoration-dotted underline-offset-2">
+          —
+        </span>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-64">{reason}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+export function SendsCell({
+  sent,
+  failed,
+}: {
+  sent: number | null;
+  failed: number | null;
+}) {
+  const t = useT();
+  if (sent === null) {
+    return (
+      <UnknownMetric reason={t("dispatch.transactionalEmail.sendLogUnread")} />
+    );
+  }
+  return (
+    <span className="tabular-nums">
+      {sent}
+      {failed !== null && failed > 0 ? (
+        <span className="ml-2 text-xs text-destructive">
+          {t("dispatch.transactionalEmail.failedCount", { count: failed })}
+        </span>
+      ) : null}
+      {failed === null ? (
+        <span className="ml-2 text-xs text-muted-foreground">
+          {t("dispatch.transactionalEmail.failuresUnknown")}
+        </span>
+      ) : null}
+    </span>
+  );
+}
+
+export function OpenRateCell({
+  engagement,
+  unavailableReason,
+  loading,
+}: {
+  engagement: EmailEngagement | undefined;
+  unavailableReason: string | null;
+  loading: boolean;
+}) {
+  const t = useT();
+  if (unavailableReason) {
+    return <UnknownMetric reason={unavailableReason} />;
+  }
+  if (loading) return <Skeleton className="h-4 w-10" />;
+  if (!engagement) {
+    return (
+      <UnknownMetric
+        reason={t("dispatch.transactionalEmail.noProviderRecord")}
+      />
+    );
+  }
+  if (engagement.openRate === null) {
+    return (
+      <span className="text-xs text-muted-foreground">
+        {t("dispatch.transactionalEmail.noDeliveredMail")}
+      </span>
+    );
+  }
+  return (
+    <span className="tabular-nums">
+      {`${(engagement.openRate * 100).toFixed(1)}%`}
+    </span>
+  );
+}
+
+export function LastSentCell({
+  lastSentAt,
+  sent,
+}: {
+  lastSentAt: number | null;
+  sent: number | null;
+}) {
+  const t = useT();
+  if (lastSentAt !== null) {
+    return <>{new Date(lastSentAt).toLocaleString()}</>;
+  }
+  if (sent === 0) {
+    return (
+      <span className="text-xs text-muted-foreground">
+        {t("dispatch.transactionalEmail.neverSent")}
+      </span>
+    );
+  }
+  return (
+    <UnknownMetric reason={t("dispatch.transactionalEmail.lastSentUnknown")} />
+  );
+}

package/src/components/transactional-email-preview.tsx

@@ -0,0 +1,88 @@
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+import { IconAlertTriangle } from "@tabler/icons-react";
+import { useQuery } from "@tanstack/react-query";
+
+import {
+  fetchEmailPreview,
+  type EmailPreview,
+} from "../client/transactional-emails";
+import { Alert, AlertDescription, AlertTitle } from "./ui/alert";
+import { Skeleton } from "./ui/skeleton";
+
+/**
+ * The "core" app id means the email was read from Dispatch's own local
+ * catalog (see transactional-email.tsx), not a cross-app fetch, so its
+ * preview must render the same way — Dispatch always has the definition
+ * registered locally and a cross-app fetch would have no real appPath to hit.
+ */
+function useEmailPreviewQuery(appId: string, appPath: string, id: string) {
+  const isCore = appId === "core";
+  const local = useActionQuery<EmailPreview>(
+    "render-transactional-email-preview",
+    { id },
+    { enabled: isCore, retry: false },
+  );
+  const remote = useQuery({
+    queryKey: ["transactional-email-preview", appPath, id],
+    queryFn: () => fetchEmailPreview(appPath, id),
+    enabled: !isCore,
+    retry: false,
+  });
+  return isCore ? local : remote;
+}
+
+export function EmailPreviewPane({
+  appId,
+  appPath,
+  id,
+  name,
+}: {
+  appId: string;
+  appPath: string;
+  id: string;
+  name: string;
+}) {
+  const t = useT();
+  const preview = useEmailPreviewQuery(appId, appPath, id);
+
+  if (preview.isError) {
+    return (
+      <Alert variant="destructive">
+        <IconAlertTriangle className="size-4" />
+        <AlertTitle>
+          {t("dispatch.transactionalEmail.previewFailed")}
+        </AlertTitle>
+        <AlertDescription>
+          {preview.error instanceof Error
+            ? preview.error.message
+            : String(preview.error)}
+        </AlertDescription>
+      </Alert>
+    );
+  }
+  if (preview.isLoading || !preview.data) {
+    return <Skeleton className="h-96 w-full" />;
+  }
+  return (
+    <div className="space-y-3">
+      <div>
+        <div className="text-xs text-muted-foreground">
+          {t("dispatch.transactionalEmail.subject")}
+        </div>
+        <div className="text-sm font-medium text-foreground">
+          {preview.data.subject}
+        </div>
+      </div>
+      {/* sandbox="" (no allow-scripts) keeps arbitrary email HTML from
+          running script in the Dispatch origin. */}
+      <iframe
+        title={t("dispatch.transactionalEmail.previewFrameTitle", { name })}
+        sandbox=""
+        srcDoc={preview.data.html}
+        // guard:allow-raw-color — the frame previews email HTML, which renders on white in mail clients regardless of app theme.
+        className="h-96 w-full rounded-xl border bg-white"
+      />
+    </div>
+  );
+}

package/src/routes/index.ts

@@ -47,6 +47,11 @@ export const dispatchRoutes: RouteConfig = [
   route("workspace", "./pages/workspace.js"),
   route("messaging", "./pages/messaging.js"),
   route("destinations", "./pages/destinations.js"),
+  route("transactional-email", "./pages/transactional-email.js"),
+  route(
+    "transactional-email/:appId/:id",
+    "./pages/transactional-email.$appId.$id.js",
+  ),
   route("identities", "./pages/identities.js"),
   route("approval", "./pages/approval.js"),
   route("approvals", "./pages/approvals.js"),

package/src/routes/pages/transactional-email.$appId.$id.tsx

@@ -0,0 +1,362 @@
+import { callAction, useActionQuery } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+import { IconAlertTriangle, IconArrowLeft } from "@tabler/icons-react";
+import { useQueries, useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { Link, useParams } from "react-router";
+
+import {
+  aggregateSharedEmails,
+  callAppAction,
+  fetchAppEmailCatalog,
+  type AppEmailCatalog,
+  type AppTransactionalEmail,
+  type LocalTransactionalEmailCatalog,
+} from "../../client/transactional-emails";
+import { ActionQueryError } from "../../components/action-query-error";
+import { DispatchShell } from "../../components/dispatch-shell";
+import {
+  ActivityTable,
+  type EmailActivityEntry,
+} from "../../components/transactional-email-activity";
+import {
+  OpenRateCell,
+  SendsCell,
+  LastSentCell,
+  type EmailEngagement,
+  type ProviderMetricsResult,
+} from "../../components/transactional-email-metrics";
+import { EmailPreviewPane } from "../../components/transactional-email-preview";
+import { Alert, AlertDescription, AlertTitle } from "../../components/ui/alert";
+import { Button } from "../../components/ui/button";
+import { Skeleton } from "../../components/ui/skeleton";
+
+export function meta() {
+  return [{ title: "Transactional email detail — Dispatch" }];
+}
+
+const WINDOW_DAYS = 30;
+const ACTIVITY_LIMIT = 50;
+
+interface WorkspaceAppRef {
+  id: string;
+  name: string;
+  path: string;
+  status?: "ready" | "pending";
+}
+
+/**
+ * Resolves the one email this page shows, plus the app name/path to display.
+ * The "core" appId is Dispatch's own registry, not a cross-app fetch — see
+ * the same split in transactional-email.tsx.
+ */
+function useEmailDetail(appId: string, id: string) {
+  const isCore = appId === "core";
+  const t = useT();
+
+  const localQuery = useActionQuery<LocalTransactionalEmailCatalog>(
+    "list-transactional-emails",
+    { windowDays: WINDOW_DAYS },
+    { enabled: isCore },
+  );
+
+  const appsQuery = useActionQuery<WorkspaceAppRef[]>("list-workspace-apps", {
+    includeAgentCards: false,
+  });
+  const readyApps = useMemo(
+    () =>
+      (appsQuery.data ?? []).filter(
+        (candidate) => candidate.status !== "pending",
+      ),
+    [appsQuery.data],
+  );
+  const app = useMemo(
+    () => readyApps.find((candidate) => candidate.id === appId),
+    [readyApps, appId],
+  );
+  const coreCatalogQueries = useQueries({
+    queries: readyApps.map((candidate) => ({
+      queryKey: ["transactional-email-catalog", candidate.id, WINDOW_DAYS],
+      queryFn: () => fetchAppEmailCatalog(candidate, WINDOW_DAYS),
+      enabled: isCore,
+      staleTime: Infinity,
+    })),
+  });
+  const remoteQuery = useQuery({
+    queryKey: ["transactional-email-catalog", appId, WINDOW_DAYS],
+    queryFn: () => fetchAppEmailCatalog(app!, WINDOW_DAYS),
+    enabled: !isCore && !!app,
+    staleTime: Infinity,
+  });
+
+  if (isCore) {
+    const appCatalogs = coreCatalogQueries
+      .map((query) => query.data)
+      .filter((catalog): catalog is AppEmailCatalog => Boolean(catalog));
+    const aggregate = localQuery.data
+      ? aggregateSharedEmails(localQuery.data, appCatalogs)
+      : undefined;
+    const email = aggregate?.emails.find((candidate) => candidate.id === id);
+    const catalogError = coreCatalogQueries.find(
+      (query) => query.data?.error || query.data?.statsError,
+    )?.data;
+    const queryError = coreCatalogQueries.find((query) => query.isError)?.error;
+    const isLoading =
+      localQuery.isLoading ||
+      appsQuery.isLoading ||
+      coreCatalogQueries.some((query) => query.isLoading);
+    const isError =
+      localQuery.isError || appsQuery.isError || Boolean(queryError);
+    return {
+      isLoading,
+      isError,
+      error: localQuery.error ?? appsQuery.error ?? queryError,
+      onRetry: () => {
+        void localQuery.refetch();
+        void appsQuery.refetch();
+        for (const query of coreCatalogQueries) void query.refetch();
+      },
+      appName: t("dispatch.transactionalEmail.sharedTitle"),
+      appPath: t("dispatch.transactionalEmail.sharedSubtitle"),
+      email,
+      catalogError:
+        aggregate?.statsError ??
+        catalogError?.error ??
+        catalogError?.statsError ??
+        null,
+      notFound: !isLoading && !isError && !email,
+    };
+  }
+
+  const notFound =
+    !appsQuery.isLoading &&
+    !appsQuery.isError &&
+    (!app ||
+      (!remoteQuery.isLoading &&
+        !remoteQuery.isError &&
+        !remoteQuery.data?.error &&
+        !remoteQuery.data?.emails.some((candidate) => candidate.id === id)));
+
+  return {
+    isLoading: appsQuery.isLoading || remoteQuery.isLoading,
+    isError: appsQuery.isError || remoteQuery.isError,
+    error: appsQuery.error ?? remoteQuery.error,
+    onRetry: () => {
+      void appsQuery.refetch();
+      void remoteQuery.refetch();
+    },
+    appName: app?.name ?? appId,
+    appPath: app?.path ?? "",
+    email: remoteQuery.data?.emails.find((candidate) => candidate.id === id),
+    catalogError: remoteQuery.data?.error ?? null,
+    notFound,
+  };
+}
+
+export default function TransactionalEmailDetailRoute() {
+  const t = useT();
+  const params = useParams<{ appId: string; id: string }>();
+  const appId = params.appId ?? "";
+  const id = params.id ?? "";
+
+  const detail = useEmailDetail(appId, id);
+
+  const sharedProviderReason = t(
+    "dispatch.transactionalEmail.sharedProviderMetricsUnavailable",
+  );
+  const engagementQuery = useQuery({
+    queryKey: ["list-email-engagement", detail.appPath, id, WINDOW_DAYS],
+    queryFn: () =>
+      callAppAction<ProviderMetricsResult<EmailEngagement[]>>(
+        detail.appPath,
+        "list-email-engagement",
+        { templateIds: [id], windowDays: WINDOW_DAYS },
+        "POST",
+      ),
+    enabled: appId !== "core" && id.length > 0 && detail.appPath.length > 0,
+  });
+  const engagementResult = engagementQuery.data;
+  const engagementUnavailable =
+    appId === "core"
+      ? sharedProviderReason
+      : engagementResult && !engagementResult.available
+        ? engagementResult.reason
+        : engagementQuery.isError
+          ? engagementQuery.error instanceof Error
+            ? engagementQuery.error.message
+            : String(engagementQuery.error)
+          : null;
+  const engagement = engagementResult?.available
+    ? engagementResult.data.find((entry) => entry.templateId === id)
+    : undefined;
+
+  const activityQuery = useQuery({
+    queryKey: ["list-email-activity", detail.appPath, id, ACTIVITY_LIMIT],
+    queryFn: () =>
+      callAppAction<ProviderMetricsResult<EmailActivityEntry[]>>(
+        detail.appPath,
+        "list-email-activity",
+        { templateId: id, limit: ACTIVITY_LIMIT },
+        "GET",
+      ),
+    enabled:
+      appId !== "core" &&
+      id.length > 0 &&
+      detail.appPath.length > 0 &&
+      !engagementUnavailable,
+  });
+
+  return (
+    <DispatchShell
+      title={detail.email?.name ?? t("dispatch.transactionalEmail.title")}
+      description={t("dispatch.transactionalEmail.description")}
+    >
+      <div className="max-w-3xl space-y-4">
+        <Button asChild size="sm" variant="ghost" className="-ml-2">
+          <Link to="/transactional-email">
+            <IconArrowLeft size={15} className="mr-1.5" />
+            {t("dispatch.transactionalEmail.title")}
+          </Link>
+        </Button>
+
+        {detail.isError ? (
+          <ActionQueryError error={detail.error} onRetry={detail.onRetry} />
+        ) : detail.isLoading ? (
+          <div className="space-y-3">
+            <Skeleton className="h-6 w-64" />
+            <Skeleton className="h-32 w-full" />
+          </div>
+        ) : detail.notFound || !detail.email ? (
+          <Alert variant="destructive">
+            <IconAlertTriangle className="size-4" />
+            <AlertTitle>
+              {t("dispatch.transactionalEmail.emailNotFound")}
+            </AlertTitle>
+            <AlertDescription>
+              {detail.catalogError ??
+                t("dispatch.transactionalEmail.emailNotFoundDescription")}
+            </AlertDescription>
+          </Alert>
+        ) : (
+          <>
+            <section className="rounded-2xl bg-card p-5">
+              <div className="text-lg font-semibold text-foreground">
+                {detail.email.name}
+              </div>
+              <div className="mt-1 font-mono text-xs text-muted-foreground">
+                {detail.email.id}
+              </div>
+              <div className="mt-1 text-xs text-muted-foreground">
+                {detail.appName}
+                {detail.appPath ? ` · ${detail.appPath}` : ""}
+              </div>
+
+              <dl className="mt-4 space-y-3 text-sm">
+                <div>
+                  <dt className="text-xs font-medium text-muted-foreground">
+                    {t("dispatch.transactionalEmail.trigger")}
+                  </dt>
+                  <dd className="mt-1 text-foreground">
+                    {detail.email.trigger}
+                  </dd>
+                </div>
+                <div>
+                  <dt className="text-xs font-medium text-muted-foreground">
+                    {t("dispatch.transactionalEmail.recipient")}
+                  </dt>
+                  <dd className="mt-1 text-foreground">
+                    {detail.email.recipient}
+                  </dd>
+                </div>
+                <div>
+                  <dt className="text-xs font-medium text-muted-foreground">
+                    {t("dispatch.transactionalEmail.sender")}
+                  </dt>
+                  <dd className="mt-1 text-foreground">
+                    {detail.email.sender}
+                  </dd>
+                </div>
+              </dl>
+
+              <div className="mt-4 flex flex-wrap gap-6 border-t pt-4 text-sm">
+                <div>
+                  <div className="text-xs font-medium text-muted-foreground">
+                    {t("dispatch.transactionalEmail.sends")}
+                  </div>
+                  <div className="mt-1">
+                    <SendsCell
+                      sent={detail.email.sent}
+                      failed={detail.email.failed}
+                    />
+                  </div>
+                </div>
+                <div>
+                  <div className="text-xs font-medium text-muted-foreground">
+                    {t("dispatch.transactionalEmail.openRate")}
+                  </div>
+                  <div className="mt-1">
+                    <OpenRateCell
+                      engagement={engagement}
+                      unavailableReason={engagementUnavailable}
+                      loading={engagementQuery.isLoading}
+                    />
+                  </div>
+                </div>
+                <div>
+                  <div className="text-xs font-medium text-muted-foreground">
+                    {t("dispatch.transactionalEmail.lastSent")}
+                  </div>
+                  <div className="mt-1">
+                    <LastSentCell
+                      lastSentAt={detail.email.lastSentAt}
+                      sent={detail.email.sent}
+                    />
+                  </div>
+                </div>
+              </div>
+            </section>
+
+            <section className="rounded-2xl bg-card p-5">
+              <h2 className="text-sm font-medium text-foreground">
+                {t("dispatch.transactionalEmail.preview")}
+              </h2>
+              <p className="mt-1 text-xs text-muted-foreground">
+                {t("dispatch.transactionalEmail.previewDescription")}
+              </p>
+              <div className="mt-4">
+                <EmailPreviewPane
+                  appId={appId}
+                  appPath={detail.appPath}
+                  id={detail.email.id}
+                  name={detail.email.name}
+                />
+              </div>
+            </section>
+
+            <section className="rounded-2xl bg-card p-5">
+              <h2 className="text-sm font-medium text-foreground">
+                {t("dispatch.transactionalEmail.activityLink")}
+              </h2>
+              <p className="mt-1 text-xs text-muted-foreground">
+                {t("dispatch.transactionalEmail.retentionNote")}
+              </p>
+              <div className="mt-4">
+                <ActivityTable
+                  result={
+                    engagementUnavailable
+                      ? { available: false, reason: engagementUnavailable }
+                      : activityQuery.data
+                  }
+                  isLoading={activityQuery.isLoading}
+                  isError={activityQuery.isError}
+                  error={activityQuery.error}
+                  onRetry={() => void activityQuery.refetch()}
+                />
+              </div>
+            </section>
+          </>
+        )}
+      </div>
+    </DispatchShell>
+  );
+}