@templatical/types - npm Package Compare versions

Comparing version 0.22.0 to 0.23.0

dist/index.d.ts

@@ -400,18 +400,2 @@ //#region src/blocks.d.ts
 //#endregion
-//#region src/guards.d.ts
-declare function isSection(block: Block): block is SectionBlock;
-declare function isTitle(block: Block): block is TitleBlock;
-declare function isParagraph(block: Block): block is ParagraphBlock;
-declare function isImage(block: Block): block is ImageBlock;
-declare function isButton(block: Block): block is ButtonBlock;
-declare function isDivider(block: Block): block is DividerBlock;
-declare function isVideo(block: Block): block is VideoBlock;
-declare function isSocialIcons(block: Block): block is SocialIconsBlock;
-declare function isSpacer(block: Block): block is SpacerBlock;
-declare function isHtml(block: Block): block is HtmlBlock;
-declare function isMenu(block: Block): block is MenuBlock;
-declare function isTable(block: Block): block is TableBlock;
-declare function isCountdown(block: Block): block is CountdownBlock;
-declare function isCustomBlock(block: Block): block is CustomBlock;
-//#endregion
 //#region src/defaults.d.ts
@@ -497,2 +481,119 @@ type BlockDefaultsFor<T> = Partial<Omit<T, "id" | "type">>;
 //#endregion
+//#region src/test-email.d.ts
+/**
+ * What a {@link TestEmailProvider} receives when the user asks to send a test.
+ */
+interface TestEmailPayload {
+  recipient: string;
+  /**
+   * The editor's current content, exactly as `getContent()` would return it.
+   * Always present.
+   */
+  content: TemplateContent;
+  /**
+   * The template rendered to MJML.
+   *
+   * Present only when {@link TestEmailProvider.includeMjml} is set **and**
+   * `@templatical/renderer` resolved. Always guard for absence: opting in
+   * without the renderer installed still sends, just without this field (the
+   * editor logs one warning naming the package).
+   *
+   * You still have to compile MJML to HTML — the editor never does, and
+   * deliberately doesn't bundle a compiler.
+   */
+  mjml?: string;
+  /**
+   * Echo of {@link TestEmailProvider.allowedRecipients}, present only when one
+   * was configured.
+   *
+   * **Untrusted.** It is read out of the browser and carries no signature, so it
+   * is not authoritative about anything. Two things it is genuinely useful for:
+   * keeping one `send` implementation portable between your own backend and
+   * Templatical Cloud, and comparing it against `recipient` server-side — a
+   * mismatch means the client was tampered with or is buggy, which is worth
+   * logging. Never treat it *as* the allowlist; that list belongs on your
+   * server.
+   */
+  allowedRecipients?: string[];
+}
+/**
+ * Sending contract for test emails. Implement it to let users send a test of the
+ * template they're editing through your own infrastructure — the editor owns the
+ * trigger, the dialog, recipient validation and the sending/success/error
+ * states; you own delivery.
+ *
+ * Pass an implementation as `testEmail` to `init()`. When omitted the feature
+ * stays off entirely and no trigger renders.
+ *
+ * ```ts
+ * const provider: TestEmailProvider = {
+ *   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");
+ *     }),
+ * };
+ * ```
+ */
+interface TestEmailProvider {
+  /**
+   * Deliver a test of the current template.
+   *
+   * Resolve on success — the dialog confirms, then closes. Reject with a
+   * **user-presentable** message on failure: the dialog renders `error.message`
+   * inline and stays open so the user can retry.
+   */
+  send(payload: TestEmailPayload): Promise<void>;
+  /**
+   * Also render the template to MJML and pass it as
+   * {@link TestEmailPayload.mjml}, saving you a `renderToMjml()` call.
+   *
+   * **Requires `@templatical/renderer`**, an optional peer dependency. If it
+   * isn't installed the send still happens with JSON only and one warning is
+   * logged — opting in never breaks sending. A *rendering* failure is different:
+   * that fails the send, because it means the template itself is broken and
+   * silently sending without the MJML would hide it.
+   */
+  includeMjml?: boolean;
+  /**
+   * Restrict who may be sent to:
+   *
+   * - **omitted** — the dialog accepts free text, validated for shape only;
+   * - **one entry** — a read-only field, pre-filled with it;
+   * - **several** — a picker of exactly those addresses;
+   * - **empty array** — nobody may be sent to, so the feature reports itself
+   *   unavailable and no trigger renders. `[]` is read as a decision, not as
+   *   "unset".
+   *
+   * A picker constraint, **not a security boundary**: this array lives in the
+   * user's browser and is trivially edited there. Validate the recipient on your
+   * server regardless of what the dialog offered.
+   */
+  allowedRecipients?: string[];
+  /**
+   * Pre-fills the recipient field. Ignored when it isn't in
+   * {@link allowedRecipients}.
+   */
+  defaultRecipient?: string;
+}
+//#endregion
+//#region src/guards.d.ts
+declare function isSection(block: Block): block is SectionBlock;
+declare function isTitle(block: Block): block is TitleBlock;
+declare function isParagraph(block: Block): block is ParagraphBlock;
+declare function isImage(block: Block): block is ImageBlock;
+declare function isButton(block: Block): block is ButtonBlock;
+declare function isDivider(block: Block): block is DividerBlock;
+declare function isVideo(block: Block): block is VideoBlock;
+declare function isSocialIcons(block: Block): block is SocialIconsBlock;
+declare function isSpacer(block: Block): block is SpacerBlock;
+declare function isHtml(block: Block): block is HtmlBlock;
+declare function isMenu(block: Block): block is MenuBlock;
+declare function isTable(block: Block): block is TableBlock;
+declare function isCountdown(block: Block): block is CountdownBlock;
+declare function isCustomBlock(block: Block): block is CustomBlock;
+//#endregion
 //#region src/merge-tags.d.ts
@@ -1157,3 +1258,3 @@ interface SyntaxPreset {
 //#endregion
-export { type AiChatMessage, type AiConfig, type AiGenerateOptions, type AiScoreOptions, type AiStreamEvent, type ApiError, type ApiResponse, type AuthConfig, type AuthRequestOptions, BUTTON_BLOCK_DEFAULTS, type BaseBlock, type Block, type BlockDefaults, type BlockStyles, type BlockType, type BlockVisibility, type ButtonBlock, COUNTDOWN_BLOCK_DEFAULTS, type CategoryScore, type CollaborationConfig, type Collaborator, type ColorsConfig, type ColumnLayout, type Comment, type CommentEvent, type CommentEventType, type CommentThread, type CountdownBlock, type CreateCommentData, type CustomBlock, type CustomBlockBooleanField, type CustomBlockColorField, type CustomBlockDefinition, type CustomBlockField, type CustomBlockFieldBase, type CustomBlockFieldType, type CustomBlockImageField, type CustomBlockNumberField, type CustomBlockRepeatableField, type CustomBlockSelectField, type CustomBlockTextField, type CustomBlockTextareaField, type CustomFont, DEFAULT_BLOCK_DEFAULTS, DEFAULT_TEMPLATE_DEFAULTS, DIVIDER_BLOCK_DEFAULTS, type DataSourceConfig, type DataSourceFetchContext, type DirectAuthConfig, type DisplayCondition, type DisplayConditionsConfig, type DividerBlock, type EditorState, EventEmitter, type ExportResult, type FindingSeverity, type FontsConfig, HEADING_LEVEL_FONT_SIZE, HTML_BLOCK_DEFAULTS, type HeadingLevel, type HealthCheckResult, type HtmlBlock, IMAGE_BLOCK_DEFAULTS, type ImageBlock, type LogicPair, type LogicTag, type LogicTagsConfig, MENU_BLOCK_DEFAULTS, type McpConfig, type McpOperation, type McpOperationPayload, type MediaResult, type MenuBlock, type MenuItemData, type MergeTag, type MergeTagsConfig, PARAGRAPH_BLOCK_DEFAULTS, type ParagraphBlock, type PlanConfig, type PlanFeatures, type PlanLimits, type ProxyAuthConfig, type RewriteData, SECTION_BLOCK_DEFAULTS, SOCIAL_ICONS_BLOCK_DEFAULTS, SOCIAL_ICON_GLYPHS, SPACER_BLOCK_DEFAULTS, SYNTAX_PRESETS, type SaveResult, type SavedBlock, type SavedBlockInput, type SavedBlockPatch, type SavedBlocksListParams, type SavedBlocksProvider, type ScoringCategory, type ScoringFinding, type ScoringResult, type SdkAuthConfig, SdkError, type SectionBlock, type SectionWrapper, type SelectOption, type SocialIcon, type SocialIconGlyph, type SocialIconSize, type SocialIconStyle, type SocialIconsBlock, type SocialPlatform, type SpacerBlock, type SpacingValue, type SyntaxPreset, type SyntaxPresetName, TABLE_BLOCK_DEFAULTS, TITLE_BLOCK_DEFAULTS, type TableBlock, type TableCellData, type TableRowData, type Template, type TemplateContent, type TemplateDefaults, type TemplateSettings, type TemplateSnapshot, type TestEmailConfig, type ThemeOverrides, type TitleBlock, type TokenData, type UiTheme, type UpdateCommentData, type UserConfig, VIDEO_BLOCK_DEFAULTS, type VideoBlock, type ViewportSize, type WebSocketServerConfig, cloneBlock, containsMergeTag, createBlock, createButtonBlock, createCountdownBlock, createCustomBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, createVideoBlock, deepMergeDefaults, generateId, getLogicMergeTagKeyword, getMergeTagLabel, getSyntaxClosingChar, getSyntaxTriggerChar, isButton, isCountdown, isCustomBlock, isDivider, isHtml, isImage, isLogicMergeTagValue, isMenu, isMergeTagValue, isParagraph, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, resolveHtmlLogicMergeTagLabels, resolveHtmlMergeTagLabels, resolveSyntax, restoreMergeTagMarkup, safeClone };
+export { type AiChatMessage, type AiConfig, type AiGenerateOptions, type AiScoreOptions, type AiStreamEvent, type ApiError, type ApiResponse, type AuthConfig, type AuthRequestOptions, BUTTON_BLOCK_DEFAULTS, type BaseBlock, type Block, type BlockDefaults, type BlockStyles, type BlockType, type BlockVisibility, type ButtonBlock, COUNTDOWN_BLOCK_DEFAULTS, type CategoryScore, type CollaborationConfig, type Collaborator, type ColorsConfig, type ColumnLayout, type Comment, type CommentEvent, type CommentEventType, type CommentThread, type CountdownBlock, type CreateCommentData, type CustomBlock, type CustomBlockBooleanField, type CustomBlockColorField, type CustomBlockDefinition, type CustomBlockField, type CustomBlockFieldBase, type CustomBlockFieldType, type CustomBlockImageField, type CustomBlockNumberField, type CustomBlockRepeatableField, type CustomBlockSelectField, type CustomBlockTextField, type CustomBlockTextareaField, type CustomFont, DEFAULT_BLOCK_DEFAULTS, DEFAULT_TEMPLATE_DEFAULTS, DIVIDER_BLOCK_DEFAULTS, type DataSourceConfig, type DataSourceFetchContext, type DirectAuthConfig, type DisplayCondition, type DisplayConditionsConfig, type DividerBlock, type EditorState, EventEmitter, type ExportResult, type FindingSeverity, type FontsConfig, HEADING_LEVEL_FONT_SIZE, HTML_BLOCK_DEFAULTS, type HeadingLevel, type HealthCheckResult, type HtmlBlock, IMAGE_BLOCK_DEFAULTS, type ImageBlock, type LogicPair, type LogicTag, type LogicTagsConfig, MENU_BLOCK_DEFAULTS, type McpConfig, type McpOperation, type McpOperationPayload, type MediaResult, type MenuBlock, type MenuItemData, type MergeTag, type MergeTagsConfig, PARAGRAPH_BLOCK_DEFAULTS, type ParagraphBlock, type PlanConfig, type PlanFeatures, type PlanLimits, type ProxyAuthConfig, type RewriteData, SECTION_BLOCK_DEFAULTS, SOCIAL_ICONS_BLOCK_DEFAULTS, SOCIAL_ICON_GLYPHS, SPACER_BLOCK_DEFAULTS, SYNTAX_PRESETS, type SaveResult, type SavedBlock, type SavedBlockInput, type SavedBlockPatch, type SavedBlocksListParams, type SavedBlocksProvider, type ScoringCategory, type ScoringFinding, type ScoringResult, type SdkAuthConfig, SdkError, type SectionBlock, type SectionWrapper, type SelectOption, type SocialIcon, type SocialIconGlyph, type SocialIconSize, type SocialIconStyle, type SocialIconsBlock, type SocialPlatform, type SpacerBlock, type SpacingValue, type SyntaxPreset, type SyntaxPresetName, TABLE_BLOCK_DEFAULTS, TITLE_BLOCK_DEFAULTS, type TableBlock, type TableCellData, type TableRowData, type Template, type TemplateContent, type TemplateDefaults, type TemplateSettings, type TemplateSnapshot, type TestEmailConfig, type TestEmailPayload, type TestEmailProvider, type ThemeOverrides, type TitleBlock, type TokenData, type UiTheme, type UpdateCommentData, type UserConfig, VIDEO_BLOCK_DEFAULTS, type VideoBlock, type ViewportSize, type WebSocketServerConfig, cloneBlock, containsMergeTag, createBlock, createButtonBlock, createCountdownBlock, createCustomBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, createVideoBlock, deepMergeDefaults, generateId, getLogicMergeTagKeyword, getMergeTagLabel, getSyntaxClosingChar, getSyntaxTriggerChar, isButton, isCountdown, isCustomBlock, isDivider, isHtml, isImage, isLogicMergeTagValue, isMenu, isMergeTagValue, isParagraph, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, resolveHtmlLogicMergeTagLabels, resolveHtmlMergeTagLabels, resolveSyntax, restoreMergeTagMarkup, safeClone };
 //# sourceMappingURL=index.d.ts.map

package.json

 {
   "name": "@templatical/types",
   "description": "Shared TypeScript types, block factory functions, and event emitter for Templatical email editor",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "bugs": "https://github.com/templatical/sdk/issues",
@@ -9,3 +9,3 @@ "devDependencies": {
     "vitest": "^4.1.10",
-    "@templatical/media-library": "0.22.0"
+    "@templatical/media-library": "0.23.0"
   },
@@ -12,0 +12,0 @@ "exports": {

No alert changes

Improved metrics

Total package byte prevSize

153040

2.66%

Lines of code

1991

5.34%

No dependency changes