@nocobase/portal-template-default 1.0.15 → 1.0.17

package/src/extensions/nocobase-mail/README.md

@@ -0,0 +1,74 @@
+# NocoBase Mail
+
+Reusable mail inbox, compose, detail, and label components backed by the NocoBase mail API.
+
+After installation, import the components from `@/extensions/nocobase-mail`.
+
+- `MailInbox` full inbox with toolbar, table, detail panel, and compose.
+- `MailCompose` / `MailComposeForm` standalone compose dialog or embedded form,
+  with immediate and scheduled sending plus opt-in bulk mode, account-aware sender aliases,
+  server templates/signatures, recipient suggestions, reply/forward references, automatic draft
+  saving and recovery, and real attachment uploads.
+- `MailComposeAttachments` uploads files through `mail:messageAttachmentUpload`
+  with retry, removal, and the backend's 25 MB limit.
+- `MailFilters` folder, read-state, label, and todo-message filters.
+- `MailUnreadProvider` / `MailUnreadIndicator` / `MailUnreadIcon` reusable unread-count
+  display with interval, window-focus, and visibility refresh.
+- `MailDetail` threaded message detail with per-message Reply, conditional Reply all,
+  and Forward actions.
+- `MailSettingsDrawer` personal mailbox settings with Mailbox, Labels, Templates,
+  and Signature management tabs.
+- `MailMassTracking` bulk delivery tracking with recipient status, cancel, and resend.
+- `useMailMessages` hook for paginated message listing with search and filters.
+- `useMailCompose` hook to open compose from anywhere.
+- `MailLabelBadge` / `MailLabelsEditor` label display, assignment, and full CRUD.
+- `MailNoteEditor` per-message private notes.
+- `MailAttachmentList` attachment preview and download.
+- Message detail resolves authenticated `cid:` inline images and keeps those images out of the
+  regular attachment list.
+
+The mail API client (`mailApi`) uses the Starter's built-in `API_URL`, `getNocoBaseHeaders`, and `NOCOBASE_TOKEN_KEY` from `@/providers/constants`. A compatible NocoBase backend with the mail plugin enabled is required.
+
+## Send modes
+
+The standard compose form enables scheduled sending by default. Bulk sending is
+kept on the dedicated `/dev/mail/bulk` showcase page, where the bulk form and
+delivery jobs are visible together. Reusable compose forms can still opt into bulk mode:
+
+- **Schedule send** calls `mail:messageSend` with an ISO `scheduleSendAt` value.
+- **Bulk send** calls `mailMassMessages:send`, creates one separate message per
+  To recipient, and defaults to a 2-second interval between messages.
+
+```tsx
+<MailComposeForm
+  allowScheduleSend
+  allowBulkSend
+  defaultBulkIntervalMs={2000}
+/>
+```
+
+Bulk and scheduled sending are separate modes, matching the NocoBase email
+manager backend. Bulk sending requires at least two recipients and does not
+support a scheduled start time.
+
+Scheduled messages can be canceled back into drafts and edited or rescheduled.
+Opening a local draft enters compose mode with its uploaded attachments; local
+drafts can be updated or permanently deleted. Provider-backed drafts remain
+read-only and must be changed in the original mailbox so provider state and
+attachments are preserved. Trash actions are provider-backed: messages
+can be moved to trash, put back, or permanently deleted after confirmation.
+
+Templates are stored in `mailTemplates`; the backend model stores template
+content but no subject. Signatures are stored per mail account in
+`mailAccounts.config.signatures`, so changing the selected sender also changes
+the available/default signature. Use `recipientOptions` on the compose
+components to add application-specific record recipients alongside NocoBase
+users.
+
+Gmail aliases can be viewed and refreshed from Mail settings. Synced aliases are
+immediately available in the compose sender selector. Outlook does not expose
+sender aliases through this integration.
+
+Mailbox account creation, OAuth authorization, and provider settings are not
+part of this component package; they remain owned by the separate mail settings
+center.

package/src/extensions/nocobase-mail/components/index.ts

@@ -0,0 +1,79 @@
+export * from "./types";
+export { mailApi } from "./mail-api";
+export { MailInbox } from "./mail-inbox";
+export type { MailInboxProps } from "./mail-inbox";
+export { MailToolbar } from "./mail-toolbar";
+export { MailTable } from "./mail-table";
+export { MailDetail } from "./mail-detail";
+export { MailCompose, MailComposeForm } from "./mail-compose";
+export type {
+  ComposeInitialValues,
+  ComposeReference,
+  ComposeMode,
+  ComposeVariant,
+  MailComposeFormProps,
+  MailComposeProps,
+} from "./mail-compose";
+export { MailSendActions } from "./mail-send-actions";
+export type { MailSendActionsProps } from "./mail-send-actions";
+export { MailRecipientInput } from "./mail-recipient-input";
+export type { MailRecipientInputProps } from "./mail-recipient-input";
+export { MailComposeAttachments } from "./mail-compose-attachments";
+export type { MailComposeAttachmentsProps } from "./mail-compose-attachments";
+export { getMailSenderCandidates, resolveMailSender } from "./mail-senders";
+export type { MailSenderCandidate } from "./mail-senders";
+export { MailRichEditor } from "./mail-rich-editor";
+export type { MailRichEditorProps } from "./mail-rich-editor";
+export { useMailSignatures } from "./use-mail-signatures";
+export type { MailSignatureValues } from "./use-mail-signatures";
+export { MailSignatureManager } from "./mail-signature-manager";
+export type { MailSignatureManagerProps } from "./mail-signature-manager";
+export { applySignature } from "./mail-signatures";
+export { useMailTemplates } from "./use-mail-templates";
+export type { MailTemplateValues } from "./use-mail-templates";
+export { MailTemplateManager } from "./mail-template-manager";
+export type { MailTemplateManagerProps } from "./mail-template-manager";
+export { useMailMessages } from "./use-mail-messages";
+export type {
+  UseMailMessagesOptions,
+  UseMailMessagesResult,
+} from "./use-mail-messages";
+export {
+  useMailCompose,
+  buildComposeInitial,
+  canReplyAll,
+} from "./use-mail-compose";
+export type { UseMailComposeOptions } from "./use-mail-compose";
+export { MailLabelBadge } from "./mail-label-badge";
+export { MailLabelsEditor } from "./mail-labels-editor";
+export { MailLabelManager } from "./mail-label-manager";
+export type { MailLabelManagerProps } from "./mail-label-manager";
+export { MailNoteEditor } from "./mail-note-editor";
+export { MailAttachmentList } from "./mail-attachment-list";
+export { createDebouncedDraftSaver } from "./mail-draft-autosave";
+export type { DebouncedDraftSaver } from "./mail-draft-autosave";
+export { serializeReplyQuote, splitReplyQuote } from "./mail-reply-quote";
+export type { MailReplyContent } from "./mail-reply-quote";
+export {
+  collectInlineContentIds,
+  filterInlineAttachments,
+  normalizeContentId,
+  replaceInlineImageSources,
+} from "./mail-inline-images";
+export { MailEmpty } from "./mail-empty";
+export {
+  MailUnreadIcon,
+  MailUnreadIndicator,
+  MailUnreadProvider,
+  useMailUnread,
+} from "./mail-unread";
+export type {
+  MailUnreadIndicatorProps,
+  MailUnreadProviderProps,
+} from "./mail-unread";
+export { MailSettingsDrawer } from "./mail-settings-drawer";
+export type { MailSettingsDrawerProps } from "./mail-settings-drawer";
+export { MailMassTracking } from "./mail-mass-tracking";
+export { useMailMassMessages } from "./use-mail-mass-messages";
+export { MailFilters } from "./mail-filters";
+export type { MailFilterValue, MailFiltersProps } from "./mail-filters";

package/src/extensions/nocobase-mail/components/mail-api.ts

@@ -0,0 +1,423 @@
+import { nocobaseClient } from "@/lib/nocobase/client";
+import type {
+  MailAccount,
+  MailIdentity,
+  MailLabel,
+  MailListParams,
+  MailListResponse,
+  MailMassSendSettings,
+  MailMassListResponse,
+  MailMassMessage,
+  MailMessage,
+  MailNote,
+  MailSendPayload,
+  MailTemplate,
+  MailUploadedAttachment,
+  MailUserRecord,
+} from "./types";
+
+function parseListResponse(payload: unknown): MailListResponse {
+  if (!payload || typeof payload !== "object") return { rows: [], count: 0 };
+  const obj = payload as {
+    data?: unknown;
+    meta?: { count?: number };
+    rows?: unknown;
+    count?: number;
+  };
+  if (Array.isArray(obj.data)) {
+    return { rows: obj.data, count: obj.meta?.count ?? obj.data.length };
+  }
+  if (Array.isArray(obj.rows)) {
+    return { rows: obj.rows, count: obj.count ?? obj.rows.length };
+  }
+  if (Array.isArray(payload)) {
+    return { rows: payload, count: payload.length };
+  }
+  return { rows: [], count: 0 };
+}
+
+export const mailApi = {
+  listMessages(params: MailListParams = {}): Promise<MailListResponse> {
+    const filter: Record<string, unknown> = {};
+    if (params.boxType) filter.boxType = { $in: [params.boxType] };
+    if (params.isRead !== undefined) filter.isRead = params.isRead;
+    if (params.labelId) filter["labels.id"] = { $in: [params.labelId] };
+    if (params.userId !== undefined) filter.userId = params.userId;
+    if (params.search) {
+      filter.$or = [
+        { subject: { $includes: params.search } },
+        { from: { $includes: params.search } },
+        { to: { $includes: params.search } },
+      ];
+    }
+    if (params.filter) Object.assign(filter, params.filter);
+
+    const action = params.scope === "personal" ? "listPerson" : "list";
+
+    return nocobaseClient
+      .action<unknown>("mailMessages", action, {
+        query: {
+          page: params.page ?? 1,
+          pageSize: params.pageSize ?? 20,
+          subjectMerge: true,
+          appends: "user",
+          ...(Object.keys(filter).length
+            ? { filter: JSON.stringify(filter) }
+            : {}),
+          sort: params.sort ?? "-relatedMessageLatestDate",
+        },
+        unwrap: "none",
+      })
+      .then(parseListResponse);
+  },
+
+  getMessage(id: number | string): Promise<MailMessage> {
+    return nocobaseClient.action<MailMessage>("mailMessages", "get", {
+      query: { filterByTk: id, appends: "children,labels,note" },
+    });
+  },
+
+  trashMessages(
+    ids: (number | string)[],
+    moveToTrash = true
+  ): Promise<unknown> {
+    return nocobaseClient.action("mailMessages", "trash", {
+      body: { filterByTk: ids, moveToTrash },
+    });
+  },
+
+  destroyMessages(ids: (number | string)[]): Promise<unknown> {
+    return nocobaseClient.action("mailMessages", "destroy", {
+      query: { filterByTk: ids },
+    });
+  },
+
+  cancelScheduled(id: number | string): Promise<unknown> {
+    return nocobaseClient.action("mailMessages", "cancelTimelySend", {
+      query: { id },
+    });
+  },
+
+  setRead(mailIds: string[], isRead: boolean): Promise<unknown> {
+    return nocobaseClient.action("mail", "messageSetReaded", {
+      body: { mailIds, isRead },
+    });
+  },
+
+  send(payload: MailSendPayload): Promise<unknown> {
+    return nocobaseClient.action("mail", "messageSend", { body: payload });
+  },
+
+  massSend(
+    payload: MailSendPayload,
+    settings: MailMassSendSettings = {}
+  ): Promise<unknown> {
+    return nocobaseClient.action("mailMassMessages", "send", {
+      body: {
+        data: payload,
+        mailSendSetting: settings,
+      },
+    });
+  },
+
+  async listMassMessages(
+    parentId: number | null = null
+  ): Promise<MailMassListResponse> {
+    const pageSize = 100;
+    const rows: MailMassMessage[] = [];
+    let page = 1;
+    let count = 0;
+
+    do {
+      const payload = await nocobaseClient.action<unknown>(
+        "mailMassMessages",
+        "list",
+        {
+          query: {
+            page,
+            pageSize,
+            filter: JSON.stringify({ parentId }),
+            sort: "-createdAt",
+          },
+          unwrap: "none",
+        }
+      );
+      const parsed = parseListResponse(payload);
+      const nextRows = parsed.rows as unknown as MailMassMessage[];
+      rows.push(...nextRows);
+      count = parsed.count;
+      if (!nextRows.length) break;
+      page += 1;
+    } while (rows.length < count);
+
+    return { rows, count };
+  },
+
+  cancelMassMessage(id: number | string): Promise<unknown> {
+    return nocobaseClient.action("mailMassMessages", "cancel", {
+      body: { id },
+    });
+  },
+
+  resendMassMessage(id: number | string): Promise<unknown> {
+    return nocobaseClient.action("mailMassMessages", "resend", {
+      body: { id },
+    });
+  },
+
+  uploadAttachment(file: File): Promise<MailUploadedAttachment> {
+    const formData = new FormData();
+    formData.append("file", file);
+    return nocobaseClient
+      .action<MailUploadedAttachment>("mail", "messageAttachmentUpload", {
+        body: formData,
+      })
+      .then((attachment) => ({
+        ...attachment,
+        // Google reads originalname/mimetype; Microsoft reads filename/mimeType.
+        // Keep both pairs aligned so recipients see the real file name and type.
+        filename: attachment.originalname,
+        mimeType: attachment.mimetype,
+      }));
+  },
+
+  saveDraft(payload: MailSendPayload): Promise<{ id: number }> {
+    return nocobaseClient.action<{ id: number }>("mail", "messageSavingDraft", {
+      body: payload,
+    });
+  },
+
+  sync(emails: string[]): Promise<unknown> {
+    return nocobaseClient.action("mail", "messagesSync", { body: { emails } });
+  },
+
+  unreadCount(): Promise<number> {
+    return nocobaseClient
+      .action<unknown>("mail", "messageUnreadCount")
+      .then((value) => {
+        if (typeof value === "number") return value;
+        if (value && typeof value === "object" && "count" in value) {
+          const count = Number((value as { count?: unknown }).count);
+          return Number.isFinite(count) ? count : 0;
+        }
+        return 0;
+      });
+  },
+
+  getAccounts(): Promise<MailAccount[]> {
+    return nocobaseClient.action<MailAccount[]>("mail", "getMailAccounts");
+  },
+
+  findDraft(values: {
+    accountEmail: string;
+    identityEmail: string;
+    to: string[];
+  }): Promise<MailMessage | undefined> {
+    return nocobaseClient
+      .action<MailMessage | undefined>("mailMessages", "get", {
+        query: {
+          filter: JSON.stringify({
+            isDraft: true,
+            from: values.identityEmail,
+            email: values.accountEmail,
+            to: values.to,
+          }),
+          appends: "labels,note",
+        },
+      })
+      .then((draft) => draft || undefined);
+  },
+
+  getOAuthUrl(
+    type: "google" | "microsoft",
+    options: { email?: string; reauthorize?: boolean } = {}
+  ): Promise<string> {
+    return nocobaseClient
+      .action<{ url?: string }>("mail", "oauth2url", {
+        query: { type, ...options },
+      })
+      .then((response) => response.url || "");
+  },
+
+  deleteAccount(email: string): Promise<unknown> {
+    return nocobaseClient.action("mail", "deleteMailAccount", {
+      body: { email },
+    });
+  },
+
+  resyncAccount(email: string): Promise<unknown> {
+    return nocobaseClient.action("mail", "messagesResync", {
+      body: { email },
+    });
+  },
+
+  syncAliases(email: string): Promise<MailIdentity[]> {
+    return nocobaseClient
+      .action<MailIdentity[]>("mail", "accountIdentitiesSync", {
+        body: { email },
+      })
+      .then((identities) => (Array.isArray(identities) ? identities : []));
+  },
+
+  getUsers(): Promise<MailUserRecord[]> {
+    return nocobaseClient
+      .action<MailUserRecord[]>("users", "list", {
+        query: { pageSize: 100 },
+      })
+      .then((res) => (Array.isArray(res) ? res : []));
+  },
+
+  getLabels(userId?: number | string): Promise<MailLabel[]> {
+    const filter =
+      userId !== undefined ? { createdBy: { id: userId } } : undefined;
+    return nocobaseClient
+      .action<MailLabel[]>("mailMessageLabels", "list", {
+        query: {
+          paginate: false,
+          ...(filter ? { filter: JSON.stringify(filter) } : {}),
+        },
+      })
+      .then((res) => (Array.isArray(res) ? res : []));
+  },
+
+  createLabel(values: {
+    label: string;
+    color: string;
+    description?: string;
+  }): Promise<MailLabel> {
+    return nocobaseClient.action<MailLabel>("mailMessageLabels", "create", {
+      body: values,
+    });
+  },
+
+  updateLabel(
+    id: number | string,
+    values: { label: string; color: string; description?: string }
+  ): Promise<MailLabel> {
+    return nocobaseClient.action<MailLabel>("mailMessageLabels", "update", {
+      query: { filterByTk: id },
+      body: values,
+    });
+  },
+
+  deleteLabel(id: number | string): Promise<unknown> {
+    return nocobaseClient.action("mailMessageLabels", "destroy", {
+      query: { filterByTk: id },
+    });
+  },
+
+  getTemplates(): Promise<MailTemplate[]> {
+    return nocobaseClient
+      .action<MailTemplate[]>("mailTemplates", "list", {
+        query: { paginate: false, sort: "createdAt" },
+      })
+      .then((res) => (Array.isArray(res) ? res : []));
+  },
+
+  createTemplate(values: {
+    name: string;
+    content: string;
+  }): Promise<MailTemplate> {
+    return nocobaseClient.action<MailTemplate>("mailTemplates", "create", {
+      body: values,
+    });
+  },
+
+  updateTemplate(
+    id: number | string,
+    values: { name: string; content: string }
+  ): Promise<MailTemplate> {
+    return nocobaseClient.action<MailTemplate>("mailTemplates", "update", {
+      query: { filterByTk: id },
+      body: values,
+    });
+  },
+
+  deleteTemplate(id: number | string): Promise<unknown> {
+    return nocobaseClient.action("mailTemplates", "destroy", {
+      query: { filterByTk: id },
+    });
+  },
+
+  updateAccount(
+    id: number | string,
+    values: Partial<MailAccount>
+  ): Promise<MailAccount> {
+    return nocobaseClient.action<MailAccount>("mailAccounts", "update", {
+      query: { filterByTk: id },
+      body: values,
+    });
+  },
+
+  setMessageLabels(
+    messageId: number | string,
+    labelIds: number[]
+  ): Promise<unknown> {
+    return nocobaseClient.action("mailMessages", "update", {
+      query: { filterByTk: messageId },
+      body: { labels: labelIds },
+    });
+  },
+
+  setTodo(messageId: number | string, isTodo: boolean): Promise<unknown> {
+    return nocobaseClient.action("mailMessages", "update", {
+      query: { filterByTk: messageId },
+      body: { isTodo },
+    });
+  },
+
+  setBoxType(messageId: number | string, boxType: string): Promise<unknown> {
+    return nocobaseClient.action("mailMessages", "update", {
+      query: { filterByTk: messageId },
+      body: { boxType },
+    });
+  },
+
+  createNote(messageId: number | string, note: string): Promise<MailNote> {
+    return nocobaseClient.action<MailNote>("mailMessageNotes", "create", {
+      body: { mailMessageId: messageId, note },
+    });
+  },
+
+  updateNote(
+    noteId: number | string,
+    messageId: number | string,
+    note: string
+  ): Promise<MailNote> {
+    return nocobaseClient.action<MailNote>("mailMessageNotes", "update", {
+      query: { filterByTk: noteId },
+      body: { mailMessageId: messageId, note },
+    });
+  },
+
+  attachmentUrl(messageId: number | string, attachmentId: string): string {
+    return nocobaseClient
+      .buildUrl("mail:messageAttachmentGet", {
+        id: messageId,
+        attachmentId,
+      })
+      .toString();
+  },
+
+  inlineImageUrl(messageId: number | string, contentId: string): string {
+    return nocobaseClient
+      .buildUrl("mail:messageContentPreview", { messageId, contentId })
+      .toString();
+  },
+
+  async fetchInlineImage(
+    messageId: number | string,
+    contentId: string
+  ): Promise<Blob> {
+    const response = await fetch(this.inlineImageUrl(messageId, contentId), {
+      headers: nocobaseClient.getHeaders({
+        withAclMeta: false,
+        headers: { Accept: "image/*" },
+      }),
+    });
+    if (!response.ok) {
+      throw new Error(`Inline image request failed (${response.status})`);
+    }
+    return response.blob();
+  },
+};

package/src/extensions/nocobase-mail/components/mail-attachment-list.tsx

@@ -0,0 +1,67 @@
+import { Download, FileText, Image as ImageIcon, Paperclip } from "lucide-react";
+import type { MailAttachment } from "./types";
+import { mailApi } from "./mail-api";
+import { cn } from "@/lib/utils";
+
+function formatSize(size?: number) {
+  if (!size) return "";
+  if (size < 1024) return `${size} B`;
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`;
+  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function isImage(mimeType: string) {
+  return mimeType.startsWith("image/");
+}
+
+export function MailAttachmentList({
+  messageId,
+  attachments,
+  className,
+}: {
+  messageId: number | string;
+  attachments: MailAttachment[];
+  className?: string;
+}) {
+  if (!attachments?.length) return null;
+
+  return (
+    <div className={cn("flex flex-col gap-2", className)}>
+      <div className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
+        <Paperclip className="size-3.5" />
+        {attachments.length} attachment{attachments.length > 1 ? "s" : ""}
+      </div>
+      <div className="flex flex-wrap gap-2">
+        {attachments.map((att) => (
+          <a
+            key={att.attachmentId}
+            href={mailApi.attachmentUrl(messageId, att.attachmentId)}
+            target="_blank"
+            rel="noreferrer"
+            className={cn(
+              "group flex items-center gap-2.5 rounded-lg border border-border/80 bg-card px-3 py-2",
+              "shadow-[0_1px_2px_rgba(0,0,0,0.04)] transition-all hover:border-primary/40 hover:shadow-[0_2px_8px_rgba(0,0,0,0.06)]"
+            )}
+          >
+            {isImage(att.mimeType) ? (
+              <ImageIcon className="size-4 shrink-0 text-sky-500" />
+            ) : (
+              <FileText className="size-4 shrink-0 text-muted-foreground" />
+            )}
+            <div className="min-w-0">
+              <div className="max-w-[180px] truncate text-xs font-medium text-foreground">
+                {att.filename}
+              </div>
+              {att.size ? (
+                <div className="text-[10px] text-muted-foreground">
+                  {formatSize(att.size)}
+                </div>
+              ) : null}
+            </div>
+            <Download className="size-3.5 shrink-0 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100" />
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+}