@nocobase/app-plugin-mail 1.0.0-beta.11 → 1.0.0-beta.12

package/skills/nocobase-app-plugin-mail/references/configuration-and-accounts.md

@@ -23,7 +23,9 @@ import { mailConfig } from '@nocobase/app-plugin-mail/server';
 export default mailConfig;
 ```
 
-Then add `import mail from './mail.js';`, `mail: ReturnType<typeof mail>;`, and `mail,` to `server/config/index.ts` alongside the existing application config factories. The Mail plugin falls back to built-in defaults when the whole namespace is absent, but provider instances still require this registration. If the application uses `MAIL_*` environment overrides, merge `mailEnvironmentMappings` from `@nocobase/app-plugin-mail/server` into its mappings in `server/environment.ts`; package metadata lists supported variables but does not activate them. The OAuth overrides are `MAIL_OAUTH_CALLBACK_URL` and `MAIL_OAUTH_RETURN_URL`.
+Register this factory under `mail` in `server/config/index.ts` through `defaultAppConfigs()`. The Mail plugin falls back to built-in defaults when the whole namespace is absent, but provider instances still require this registration. `mailConfig` already declares all seven `MAIL_*` environment overrides using section-relative paths, and `pnpm nocobase config env` discovers them. No application-level environment file or duplicated mappings are needed. `mailEnvironmentMappings` remains a compatibility export with fully prefixed `mail.*` paths for older application-level providers; never pass it directly as a section's `env`.
+
+Environment values override configuration files and code defaults. Before upgrading, review existing OAuth, sync, webhook and jobs variables that may previously have been inert. Undefined values keep defaults; empty or invalid integer values fail configuration loading, and Mail retains its numeric bounds. Existing application-level providers can coexist when their mappings match; section rules take priority over their custom transformations, so migrate custom parsers into the section rules when needed. A variable mapped to different paths in different sections is rejected even when unset. Mail configuration is not public browser configuration, and webhook secrets must not be exposed.
 
 `mail.providers` is a map keyed by stable instance names. The map key is the provider name; each value contains `type` and provider-specific options. Multiple instances of the same type can coexist. Renaming an instance breaks its existing account association. `enabled` defaults to `true`; disabling an instance also makes it unavailable to existing accounts.
 
@@ -94,7 +96,9 @@ Official references: [Gmail API quotas and quota-increase guidance](https://deve
 
 For IMAP/SMTP, `secure: true` means TLS from connection start; STARTTLS endpoints use the service's prescribed settings. TLS certificate verification defaults to enabled. Mail validates both endpoints before saving account credentials. Use the provider-required app password or authorization code where applicable.
 
-Provider secrets, endpoints and allowed OAuth `scopes` live in `mail.providers`. The top-level `MAIL_*` overrides below do not create per-provider credential environment mappings. Do not assume generic `${NAME}` interpolation in YAML; use the target application's supported server configuration mechanism. In applications generated from the OSS default template, merge `mailEnvironmentMappings` into the application-owned mappings in `server/environment.ts`. Keep actual secrets in private server configuration, out of committed examples and client bundles, and restart after changing configuration.
+The connection form's Username is the shared IMAP and SMTP login name, not the sender's display name. It is optional: an omitted, empty, or whitespace-only value uses the entered mailbox address. A supplied login name is trimmed without changing case or requiring email syntax. Mailbox address and password remain required.
+
+Provider secrets, endpoints and allowed OAuth `scopes` live in `mail.providers`. The top-level `MAIL_*` overrides below do not create per-provider credential environment mappings. Do not assume generic `${NAME}` interpolation in YAML; use the target application's supported server configuration mechanism. Keep actual secrets in private server configuration, out of committed examples and client bundles, and restart after changing configuration.
 
 ## Connect and manage accounts
 
@@ -114,7 +118,9 @@ https://mail.example.com/main/mail/oauth/callback
 
 Override through `mail.oauthCallbackUrl` or `MAIL_OAUTH_CALLBACK_URL`. A relative path receives the application prefix; an absolute HTTP(S) URL must already include it and reach the mounted callback. Register the exact resulting URL with the OAuth provider. Fragments are invalid. `oauthCallbackUrl` controls only the provider callback endpoint, not the page shown in the browser after authorization.
 
-Configure the browser destination through `mail.oauthReturnUrl` or `MAIL_OAUTH_RETURN_URL`. It defaults to `/`, the application root, because the plugin ships no page; point it at the application page that renders `MailAccountsPage`. A relative return path receives the application public base path, so `/mail/accounts` under `/main` becomes `/main/mail/accounts`; an absolute HTTP(S) URL is also supported and is treated as trusted server configuration. Fragments are invalid.
+Configure the browser destination through `mail.oauthReturnUrl` or `MAIL_OAUTH_RETURN_URL`. It defaults to the application's root (`/`), and the plugin registers no built-in Dev, settings or management pages or routes. Register an application-owned page rendering the public `MailAccountsPage`, such as `/mail/accounts`, and configure the return URL to match that personal account page. A relative return path receives the application public base path, so `/mail/accounts` under `/main` becomes `/main/mail/accounts`; an absolute HTTP(S) URL is also supported and is treated as trusted server configuration. Fragments are invalid.
+
+Mail warns once at production startup if the effective return destination targets the legacy `/dev/mail/accounts` page, including prefixed and absolute URL forms with query parameters. The current root (`/`) default does not trigger the warning. The warning does not change defaults, block startup, validate arbitrary client route existence, or expose full URLs or secrets. Production apps must register their own authenticated personal account page, such as `/mail/accounts`, with `page / mail.workspace / access` permission; reuse the public `MailAccountsPage`, which already reads authorization results and refreshes accounts. An application-owned administrator overview using the read-only all-user APIs is not a personal connection destination. See [Client integration](client-integration.md) for route composition. Set `MailWorkspacePage.accountsHref` separately: a navigation link does not configure the server's OAuth return.
 
 For a production application, configure the callback and return paths together so the provider callback and application page are not confused:
 
@@ -126,7 +132,7 @@ mail:
 
 With origin `https://mail.example.com` and public base path `/main`, the provider must redirect to `https://mail.example.com/main/mail/oauth/callback`, and the browser will finish at `https://mail.example.com/main/mail/accounts?mailAuthorization=success` or `https://mail.example.com/main/mail/accounts?mailAuthorization=failure`. Register the full callback URL with the selected OAuth provider, such as Google for Gmail or Microsoft Entra ID for Microsoft 365, not the return page URL.
 
-When deployment values come from environment variables, use `MAIL_OAUTH_CALLBACK_URL=/mail/oauth/callback` and `MAIL_OAUTH_RETURN_URL=/mail/accounts` as the values and explicitly map them to `mail.oauthCallbackUrl` and `mail.oauthReturnUrl` in the application's `server/environment.ts`. Declaring the variables in the Mail package metadata does not replace the application's mapping, and generic `${NAME}` interpolation must not be assumed.
+When deployment values come from environment variables, use `MAIL_OAUTH_CALLBACK_URL=/mail/oauth/callback` and `MAIL_OAUTH_RETURN_URL=/mail/accounts` without repeating `/main`. Composing `mailConfig` as `mail` activates these overrides automatically. Current templates use configuration-section rules, not an application-level environment file. A wrapper that customizes defaults must explicitly retain `env: mailConfig.rules?.env`; merely calling `mailConfig(runtime)` returns defaults, not its environment rules. To customize parsing, spread those section rules and override the selected variable using a section-relative path. Do not pass the legacy full-path `mailEnvironmentMappings` as a section's `env`.
 
 The plugin preserves query parameters already present in the configured return URL and adds or replaces `mailAuthorization=success` or `mailAuthorization=failure`. The application-owned return page can use this status to show a result and refresh its account state.
 

package/skills/nocobase-app-plugin-mail/references/public-api.md

@@ -16,7 +16,7 @@ The package root is a Server alias retained for plugin registration and applicat
 
 ### Plugin and configuration
 
-The Server entry exports the default plugin, `mailConfig`, `DEFAULT_MAIL_CONFIG`, `mailEnvironmentMappings`, `resolveMailConfig`, and the `MailConfig`/provider configuration types. Applications register the plugin and explicitly compose its configuration factory as described in [Configuration and accounts](configuration-and-accounts.md).
+The Server entry exports the default plugin, `mailConfig`, `DEFAULT_MAIL_CONFIG`, `mailEnvironmentMappings`, `resolveMailConfig`, and the `MailConfig`/provider configuration types. Applications register the plugin and explicitly compose its configuration factory as described in [Configuration and accounts](configuration-and-accounts.md). `mailConfig.rules.env` supplies seven section-relative `MAIL_*` mappings; wrappers must retain those rules explicitly. `mailEnvironmentMappings` preserves fully prefixed `mail.*` paths and parsing for legacy application-level environment providers, not section-level `env`. Neither interface makes private Mail configuration public.
 
 ### Supported tokens
 
@@ -62,10 +62,13 @@ Output status, folder-type and Provider error category/reason types have `Known.
 ### Composition and data access
 
 - The default export registers the Mail Client plugin.
-- `MailWorkspacePage` and `MailWorkspacePageProps` provide the full workspace. `accountsHref` names the application's accounts page, relative to its base path, so a user with no account is linked there; without it the empty state shows no link. `templateVariables` supplies an allowlisted record context for saved template placeholders; it does not associate messages with application records.
+- `MailWorkspacePage` and `MailWorkspacePageProps` provide the full workspace. `title` and `description` customize the heading; `templateVariables` supplies an allowlisted record context for saved template placeholders and does not associate messages with application records. `accountsHref` is an optional application-internal personal account path without a deployment prefix: the workspace resolves it with `resolveAppUrl()`, shows a connection link when no usable accounts exist, and a Mail accounts link in its header otherwise. Without it no account link is generated. `headerActions?: ReactNode` appends actions after Compose, Sync and the optional account link without replacing them.
+- `MailAccountsPage` and `MailAccountsPageProps` provide the personal connection and management page for application-owned production routes. The administrator's read-only account overview is not a replacement.
 - `MailClient` and `mailClientToken` expose the typed client data layer. Resolve the app-owned instance with `useMailClient()` in React or `app.services.resolve(mailClientToken)` elsewhere; do not construct a separate `MailClient` for normal UI integration.
+- `useMailUnreadCount(): MailUnreadCountState` exposes the current user's count, loading state and latest request error through the host Mail/realtime services. Until the first successful response, `unreadCount` is `undefined`, not zero; refresh failures retain the last successful count. It shares the navigation icon's local/realtime/reconnect/focus/polling refresh logic and instance-local debounce/serialization. Mount in a session-owned scope that remounts on user changes; there is no shared global cache or automatic session observer. See [custom unread menus](client-integration.md#unread-counts-on-custom-menus). Low-level event/subscription implementation files remain private.
 - `mailErrorMessage(cause, fallback)` returns the text to show for a failed call: the server's `localizedMessage`, or `fallback`. Code that must react to a specific failure branches on `ApiClientError.reason` from `@nocobase/app-client` instead.
 - `renderMailTemplate()`, `plainTextToMailHtml()`, and `htmlToPlainText()` are supported template/body helpers. `MailTemplateVariables` and `RenderedMailTemplate` describe their data.
+- `prepareMailReply(mail, message): Promise<MailComposerRequest>` prepares a browser-side reply using the original account/local message ID, Reply-To or From, and a single `Re:` prefix. It retries incomplete content and copies referenced CID images into owned `uploads`, rejects preparation failures, and does not carry ordinary attachments, open a composer, save or send mail. The returned request preserves the separate reply quote for shared composer sending and draft recovery. `MailComposerRequest` is exported here and from `/client/components`. See [custom reply integration](client-integration.md#prepare-replies-on-custom-pages) for network effects, sandbox rendering and caller-owned concurrency guards.
 - `MAIL_PLUGIN_NS`, `MAIL_REALTIME_TOPIC`, and `MailRealtimeEvent` expose the translation namespace and invalidation event contract.
 - `MAIL_VIRTUAL_FOLDER_IDS` provides stable query identifiers for built-in cross-account folders. `MAIL_LABEL_COLORS` and `DEFAULT_MAIL_LABEL_COLOR` provide the supported user-label palette and default.
 
@@ -87,27 +90,29 @@ The TypeScript signatures are the request/result source of truth. For direct HTT
 
 All components below are exported from `@nocobase/app-plugin-mail/client/components`. Components that call `useMailClient()` require the Mail Client plugin to be registered in the host application.
 
-| Component                           | Exported props and related types                                                                                                                                                                            |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MailAccountCard`                   | `MailAccountCardProps`                                                                                                                                                                                      |
-| `MailAccountConnector`              | `MailAccountConnectorProps`, `MailAccountConnectorLabels`, `MailAccountCredentials`                                                                                                                         |
-| `MailConversationView`              | `MailConversationViewProps`, `MailConversationViewLabels`                                                                                                                                                   |
-| `MailMessageList`                   | `MailMessageListProps`, `MailMessageListLabels`                                                                                                                                                             |
-| `MailProviderCard`                  | `MailProviderCardProps`                                                                                                                                                                                     |
-| `MailRichTextEditor`                | `MailRichTextEditorProps`, `MailRichTextValue`, `MailRichTextEditorLabels`, `MailRichTextEditorInsertOption`, `MailRichTextEditorInsertMenu`, `MailRichTextEditorInsertActions`                             |
-| `MailNavigationIcon`                | No props; displays the user's unread count using the host app services.                                                                                                                                     |
-| `MailLabelManager`                  | No props; reads and edits the current user's labels.                                                                                                                                                        |
-| `MailLabelTag`, `MailLabelColorDot` | `MailLabelTagProps`, `MailLabelColorDotProps`                                                                                                                                                               |
-| `MailSignatureManager`              | `MailSignatureManagerProps`                                                                                                                                                                                 |
-| `MailStatusBadge`                   | `MailStatusBadgeProps`, `MailStatusTone`                                                                                                                                                                    |
-| `MailSyncPolicyFields`              | `MailSyncPolicyFieldsProps`, `MailSyncPolicyValue`                                                                                                                                                          |
-| `MailTemplateManager`               | No props; reads and edits the current user's templates.                                                                                                                                                     |
-| `MailboxSidebar`                    | `MailboxSidebarProps`, `MailboxSidebarLabels`, `MailboxFolderGroup`, `MailboxSmartView`                                                                                                                     |
-| `MailComposer`                      | `MailComposerComponentProps` and shared `MailComposerProps`, `MailComposerRequest`, `MailComposerState`, `MailComposerCompletionResult`, `MailForwardQuote`, `MailTemplateVariables`, `EMPTY_MAIL_COMPOSER` |
-| `MailWorkspaceComposer`             | `MailWorkspaceComposerProps` and the shared composer contracts above.                                                                                                                                       |
+| Component                           | Exported props and related types                                                                                                                                                                                                                                                                                 |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MailAccountCard`                   | `MailAccountCardProps`                                                                                                                                                                                                                                                                                           |
+| `MailAccountConnector`              | `MailAccountConnectorProps`, `MailAccountConnectorLabels`, `MailAccountCredentials`                                                                                                                                                                                                                              |
+| `MailConversationView`              | `MailConversationViewProps`, `MailConversationViewLabels`                                                                                                                                                                                                                                                        |
+| `MailMessageList`                   | `MailMessageListProps`, `MailMessageListLabels`                                                                                                                                                                                                                                                                  |
+| `MailProviderCard`                  | `MailProviderCardProps`                                                                                                                                                                                                                                                                                          |
+| `MailRichTextEditor`                | `MailRichTextEditorProps`, `MailRichTextValue`, `MailRichTextEditorLabels`, `MailRichTextEditorInsertOption`, `MailRichTextEditorInsertMenu`, `MailRichTextEditorInsertActions`                                                                                                                                  |
+| `MailNavigationIcon`                | No props; displays the user's unread count using the host app services.                                                                                                                                                                                                                                          |
+| `MailLabelManager`                  | No props; reads and edits the current user's labels.                                                                                                                                                                                                                                                             |
+| `MailLabelTag`, `MailLabelColorDot` | `MailLabelTagProps`, `MailLabelColorDotProps`                                                                                                                                                                                                                                                                    |
+| `MailSignatureManager`              | `MailSignatureManagerProps`                                                                                                                                                                                                                                                                                      |
+| `MailStatusBadge`                   | `MailStatusBadgeProps`, `MailStatusTone`                                                                                                                                                                                                                                                                         |
+| `MailSyncPolicyFields`              | `MailSyncPolicyFieldsProps`, `MailSyncPolicyValue`                                                                                                                                                                                                                                                               |
+| `MailTemplateManager`               | No props; reads and edits the current user's templates.                                                                                                                                                                                                                                                          |
+| `MailboxSidebar`                    | `MailboxSidebarProps`, `MailboxSidebarLabels`, `MailboxFolderGroup`, `MailboxSmartView`                                                                                                                                                                                                                          |
+| `MailComposer`                      | `MailComposerComponentProps` and shared `MailComposerProps`, `MailComposerRequest`, `MailComposerState`, `MailComposerCompletionResult`, `MailComposerCompletionCallback`, `MailComposerCompletionDetails`, `MailComposerSubmissionSnapshot`, `MailForwardQuote`, `MailTemplateVariables`, `EMPTY_MAIL_COMPOSER` |
+| `MailWorkspaceComposer`             | `MailWorkspaceComposerProps` and the shared composer contracts above.                                                                                                                                                                                                                                            |
 
 `MailComposer` renders one supplied account/request. `MailWorkspaceComposer` also manages account and sender identity selection across eligible accounts. Completion results are open strings; callers should handle known results and provide a fallback for future outcomes.
 
+The shared `onComplete(result, rejectedRecipients?, error?, details?)` uses `MailComposerCompletionCallback` to support synchronous and asynchronous completion while retaining legacy return-discarding callbacks. Its optional fourth argument is discriminated by `kind`: `normal` or `bulk` includes the detached actual client request and every returned `MailSubmissionView`, while `draft` contains only a separate draft reference and no submissions. A response-less unknown outcome has no submission IDs. The first three arguments retain their existing summary semantics, not delivery guarantees. Optional `onCompletionError` isolates callback throws/rejections without delaying closing or retrying mail. See [business-record completion](client-integration.md#associate-composer-completion-with-business-records) for idempotent integration and snapshot boundaries.
+
 ## HTTP and realtime
 
 The authenticated `/api/mail` routes, payloads, paging, permission resources, error reasons, OAuth callback and Provider webhook are documented in [HTTP API](http-api.md). Prefer `MailClient` for application code. The `mail:messages` realtime event is a user-scoped invalidation signal with no message body; refresh affected Mail data after receiving it or reconnecting.