@templatical/editor 0.21.2 → 0.23.0

package/dist/index.d.ts

@@ -28,6 +28,8 @@ import { SaveResult } from '@templatical/types';
 import { Template } from '@templatical/types';
 import { TemplateContent } from '@templatical/types';
 import { TemplateDefaults } from '@templatical/types';
+import { TestEmailPayload } from '@templatical/types';
+import { TestEmailProvider } from '@templatical/types';
 import { ThemeOverrides } from '@templatical/types';
 import { UiTheme } from '@templatical/types';
 import { ViewportSize } from '@templatical/types';
@@ -100,6 +102,23 @@ export declare interface EditorCapabilities {
         canUpdate: ComputedRef<boolean>;
         canDelete: ComputedRef<boolean>;
     };
+    /**
+     * Present only when a `TestEmailProvider` is configured — in OSS via
+     * `init({ testEmail })`, in Cloud whenever cloud mode is active (or when a
+     * consumer supplied their own sender to `initCloud()`).
+     */
+    testEmail?: {
+        /** Open the send dialog. A no-op while {@link isAvailable} is false. */
+        open(): void;
+        /**
+         * Whether the feature is usable right now. Reactive for the same reason as
+         * `savedBlocks.isAvailable`: Cloud resolves its plan entitlement and its
+         * allowed-recipient list *after* capabilities are provided, and an
+         * explicitly empty allowlist makes the feature unusable. UI must gate on
+         * this or it renders a button that does nothing.
+         */
+        isAvailable: ComputedRef<boolean>;
+    };
 }
 
 export declare interface FontOption {
@@ -318,7 +337,28 @@ export declare interface TemplaticalCloudEditorConfig {
     onComment?: (event: CommentEvent) => void;
     onUnmount?: () => void;
     onRequestMedia?: (context: MediaRequestContext) => Promise<MediaItem | null>;
+    /**
+     * Transform the rendered HTML just before Cloud sends a test email.
+     *
+     * Cloud-only, and deliberately so: it exists because *Cloud* renders the HTML,
+     * so a consumer needs a seam into it. A consumer-supplied {@link testEmail}
+     * provider *is* that seam, and this hook is not applied to it.
+     */
     onBeforeTestEmail?: (html: string) => string | Promise<string>;
+    /**
+     * Sending backend for test emails.
+     *
+     * - **omitted** — sent by Templatical Cloud, gated on the `test_email` plan
+     *   feature and its signed allowed-recipient list.
+     * - **a {@link TestEmailProvider}** — sent by *you* instead, which is what to
+     *   reach for when mail must leave your own infrastructure for compliance or
+     *   data-residency reasons.
+     *
+     * The same type `init()` takes, so moving an OSS integration to Cloud means
+     * deleting this key (to adopt Cloud's sender) or leaving it exactly as-is (to
+     * keep your own) — never rewriting it.
+     */
+    testEmail?: TestEmailProvider;
     /**
      * Template linter (`@templatical/quality`) configuration. Runs every
      * linter exported by the package (accessibility + structure). Cloud
@@ -518,6 +558,36 @@ export declare interface TemplaticalEditorConfig {
      * block *types* with their own templates and field schemas.
      */
     savedBlocks?: SavedBlocksProvider;
+    /**
+     * Sending backend for **test emails** — letting a user mail themselves the
+     * template they're editing.
+     *
+     * The editor owns the trigger, the dialog, recipient validation and the
+     * sending/success/error states; you own delivery. One method is enough:
+     *
+     * ```ts
+     * init({
+     *   container,
+     *   testEmail: {
+     *     send: ({ recipient, content }) =>
+     *       fetch("/api/test-email", {
+     *         method: "POST",
+     *         headers: { "Content-Type": "application/json" },
+     *         body: JSON.stringify({ recipient, content }),
+     *       }).then((r) => {
+     *         if (!r.ok) throw new Error("Could not send the test email");
+     *       }),
+     *   },
+     * });
+     * ```
+     *
+     * **Omitted by default.** With no provider the feature is entirely off — no
+     * button, and none of its UI code is downloaded.
+     *
+     * `allowedRecipients` restricts the picker but is **not** a security boundary:
+     * it lives in the user's browser. Validate the recipient on your server.
+     */
+    testEmail?: TestEmailProvider;
     blockDefaults?: BlockDefaults;
     templateDefaults?: TemplateDefaults;
     theme?: ThemeOverrides;
@@ -556,6 +626,10 @@ export declare interface TemplaticalEditorConfig {
     lint?: LintOptions;
 }
 
+export { TestEmailPayload }
+
+export { TestEmailProvider }
+
 export { ThemeOverrides }
 
 export { UiTheme }