@liveblocks/emails 2.13.2 → 2.13.3-emails2

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { CommentBodyText, CommentBodyLink, BaseUserMeta, DU, CommentBodyMention, ResolveUsersArgs, OptionalPromise, CommentBody, DRI } from '@liveblocks/core';
+import { CommentBodyText, CommentBodyLink, BaseUserMeta, DU, CommentBodyMention, ResolveUsersArgs, OptionalPromise, DRI, CommentBody } from '@liveblocks/core';
 export { ResolveUsersArgs } from '@liveblocks/core';
 import React from 'react';
 import { Properties } from 'csstype';
-import { Liveblocks, ThreadNotificationEvent } from '@liveblocks/node';
+import { Liveblocks, TextMentionNotificationEvent, ThreadNotificationEvent } from '@liveblocks/node';
 
 /**
  * CSS properties object.
@@ -95,20 +95,212 @@ declare type ConvertCommentBodyAsHtmlStyles = {
     link: CSSProperties;
 };
 
-declare type CommentEmailBaseData = {
+declare type ResolveRoomInfoArgs = {
+    /**
+     * The ID of the room to resolve
+     */
+    roomId: string;
+};
+
+/**
+ * Liveblocks Text Editor
+ *
+ * Expose common types to transform nodes from different editors like `Lexical` or `TipTap`
+ * and then convert them more easily as React or as html.
+ */
+
+declare type LiveblocksTextEditorTextFormat = {
+    bold: boolean;
+    italic: boolean;
+    strikethrough: boolean;
+    code: boolean;
+};
+declare type LiveblocksTextEditorTextNode = {
+    type: "text";
+    text: string;
+} & LiveblocksTextEditorTextFormat;
+declare type LiveblocksTextEditorMentionNode = {
+    type: "mention";
+    userId: string;
+};
+/**
+ * -------------------------------------------------------------------------------------------------
+ * `LiveblocksTextEditorNode` is common structure to represents text editor nodes coming from
+ * like `Lexical`, `TipTap` or so.
+ *
+ * This (simple) structure is made to be scalable and to accommodate with other text editors we could potentially
+ * want to support in the future.
+ *
+ * It allows to manipulate nodes more easily and converts them with ease either as React nodes or as an html safe string.
+ * From a DX standpoint it provides to developers the same structure to use when using custom React components or inline css
+ * to represents a text mention with its surrounding text.
+ * -------------------------------------------------------------------------------------------------
+ */
+declare type LiveblocksTextEditorNode = LiveblocksTextEditorTextNode | LiveblocksTextEditorMentionNode;
+declare type TextEditorContainerComponentProps = {
+    /**
+     * The nodes of the text editor
+     */
+    children: React.ReactNode;
+};
+declare type TextEditorMentionComponentProps<U extends BaseUserMeta = DU> = {
+    /**
+     * The mention element.
+     */
+    element: LiveblocksTextEditorMentionNode;
+    /**
+     * The mention's user info, if the `resolvedUsers` option was provided.
+     */
+    user?: U["info"];
+};
+declare type TextEditorTextComponentProps = {
+    /**
+     * The text element.
+     */
+    element: LiveblocksTextEditorTextNode;
+};
+declare type ConvertTextEditorNodesAsReactComponents<U extends BaseUserMeta = DU> = {
+    /**
+     *
+     * The component used to act as a container to wrap text editor nodes,
+     */
+    Container: React.ComponentType<TextEditorContainerComponentProps>;
+    /**
+     * The component used to display mentions.
+     */
+    Mention: React.ComponentType<TextEditorMentionComponentProps<U>>;
+    /**
+     * The component used to display text nodes.
+     */
+    Text: React.ComponentType<TextEditorTextComponentProps>;
+};
+declare type ConvertTextEditorNodesAsHtmlStyles = {
+    /**
+     * The default inline CSS styles used to display container element.
+     */
+    container: CSSProperties;
+    /**
+     * The default inline CSS styles used to display text `<strong />` elements.
+     */
+    strong: CSSProperties;
+    /**
+     * The default inline CSS styles used to display text `<code />` elements.
+     */
+    code: CSSProperties;
+    /**
+     * The default inline CSS styles used to display mentions.
+     */
+    mention: CSSProperties;
+};
+
+declare type MentionEmailBaseData = {
     id: string;
-    threadId: string;
     roomId: string;
     userId: string;
+    textEditorNodes: LiveblocksTextEditorNode[];
     createdAt: Date;
-    url?: string;
-    rawBody: CommentBody;
 };
-declare type ResolveRoomInfoArgs = {
+declare type PrepareTextMentionNotificationEmailBaseDataOptions = {
     /**
-     * The ID of the room to resolve
+     * A function that returns room info from room IDs.
      */
+    resolveRoomInfo?: (args: ResolveRoomInfoArgs) => OptionalPromise<DRI | undefined>;
+};
+declare type MentionEmailAsReactData<U extends BaseUserMeta = DU> = Omit<MentionEmailBaseData, "userId" | "textEditorNodes"> & {
+    author: U;
+    reactContent: React.ReactNode;
+};
+declare type MentionEmailAsHtmlData<U extends BaseUserMeta = DU> = Omit<MentionEmailBaseData, "userId" | "textEditorNodes"> & {
+    author: U;
+    htmlContent: string;
+};
+declare type PrepareTextMentionNotificationEmailAsReactOptions<U extends BaseUserMeta = DU> = PrepareTextMentionNotificationEmailBaseDataOptions & {
+    /**
+     * A function that returns info from user IDs.
+     */
+    resolveUsers?: (args: ResolveUsersArgs) => OptionalPromise<(U["info"] | undefined)[] | undefined>;
+    /**
+     * The components used to customize the resulting React nodes. Each components has
+     * priority over the base components inherited.
+     */
+    components?: Partial<ConvertTextEditorNodesAsReactComponents<U>>;
+};
+declare type TextMentionNotificationEmailData<U extends BaseUserMeta, M extends MentionEmailAsReactData<U> | MentionEmailAsHtmlData<U>> = {
+    mention: M;
+    roomInfo: DRI;
+};
+declare type TextMentionNotificationEmailDataAsReact = TextMentionNotificationEmailData<BaseUserMeta, MentionEmailAsReactData>;
+/**
+ * Prepares data from a `TextMentionNotificationEvent` and convert content as React nodes.
+ *
+ * @param client The `Liveblocks` node client
+ * @param event The `TextMentionNotificationEvent` received in the webhook handler
+ * @param options The optional options to provide to resolve users, resolve room info and customize comment bodies React components.
+ *
+ * It returns a `TextMentionNotificationEmailDataAsReact` or `null` if there are no existing text mention.
+ *
+ * @example
+ * import { Liveblocks} from "@liveblocks/node"
+ * import { prepareTextMentionNotificationEmailAsReact } from "@liveblocks/emails"
+ *
+ * const liveblocks = new Liveblocks({ secret: "sk_..." })
+ * const emailData = prepareTextMentionNotificationEmailAsReact(
+ *  liveblocks,
+ *  event,
+ *  {
+ *    resolveUsers,
+ *    resolveRoomInfo,
+ *    components,
+ *  }
+ * )
+ */
+declare function prepareTextMentionNotificationEmailAsReact(client: Liveblocks, event: TextMentionNotificationEvent, options?: PrepareTextMentionNotificationEmailAsReactOptions<BaseUserMeta>): Promise<TextMentionNotificationEmailDataAsReact | null>;
+declare type PrepareTextMentionNotificationEmailAsHtmlOptions<U extends BaseUserMeta = DU> = PrepareTextMentionNotificationEmailBaseDataOptions & {
+    /**
+     * A function that returns info from user IDs.
+     */
+    resolveUsers?: (args: ResolveUsersArgs) => OptionalPromise<(U["info"] | undefined)[] | undefined>;
+    /**
+     * The styles used to customize the html elements in the resulting html safe string.
+     * Each styles has priority over the base styles inherited.
+     */
+    styles?: Partial<ConvertTextEditorNodesAsHtmlStyles>;
+};
+declare type TextMentionNotificationEmailDataAsHtml = TextMentionNotificationEmailData<BaseUserMeta, MentionEmailAsHtmlData>;
+/**
+ * Prepares data from a `TextMentionNotificationEvent` and convert content  as an html safe string.
+ *
+ * @param client The `Liveblocks` node client
+ * @param event The `TextMentionNotificationEvent` received in the webhook handler
+ * @param options The optional options to provide to resolve users, resolve room info and customize comment bodies React components.
+ *
+ * It returns a `TextMentionNotificationEmailDataAsReact` or `null` if there are no existing text mention.
+ *
+ * @example
+ * import { Liveblocks} from "@liveblocks/node"
+ * import { prepareTextMentionNotificationEmailAsHtml } from "@liveblocks/emails"
+ *
+ * const liveblocks = new Liveblocks({ secret: "sk_..." })
+ * const emailData = prepareTextMentionNotificationEmailAsHtml(
+ *  liveblocks,
+ *  event,
+ *  {
+ *    resolveUsers,
+ *    resolveRoomInfo,
+ *    styles,
+ *  }
+ * )
+ */
+declare function prepareTextMentionNotificationEmailAsHtml(client: Liveblocks, event: TextMentionNotificationEvent, options?: PrepareTextMentionNotificationEmailAsHtmlOptions<BaseUserMeta>): Promise<TextMentionNotificationEmailDataAsHtml | null>;
+
+declare type CommentEmailBaseData = {
+    id: string;
+    threadId: string;
     roomId: string;
+    userId: string;
+    createdAt: Date;
+    url?: string;
+    rawBody: CommentBody;
 };
 declare type PrepareThreadNotificationEmailBaseDataOptions = {
     /**
@@ -213,4 +405,4 @@ declare type ThreadNotificationEmailDataAsReact = ThreadNotificationEmailData<Ba
  */
 declare function prepareThreadNotificationEmailAsReact(client: Liveblocks, event: ThreadNotificationEvent, options?: PrepareThreadNotificationEmailAsReactOptions<BaseUserMeta>): Promise<ThreadNotificationEmailDataAsReact | null>;
 
-export { type CommentBodyContainerComponentProps, type CommentBodyLinkComponentProps, type CommentBodyMentionComponentProps, type CommentBodyParagraphComponentProps, type CommentBodyTextComponentProps, type CommentEmailAsHtmlData, type CommentEmailAsReactData, type ConvertCommentBodyAsHtmlStyles, type ConvertCommentBodyAsReactComponents, type PrepareThreadNotificationEmailAsHtmlOptions, type PrepareThreadNotificationEmailAsReactOptions, type ResolveRoomInfoArgs, type ThreadNotificationEmailDataAsHtml, type ThreadNotificationEmailDataAsReact, prepareThreadNotificationEmailAsHtml, prepareThreadNotificationEmailAsReact };
+export { type CommentBodyContainerComponentProps, type CommentBodyLinkComponentProps, type CommentBodyMentionComponentProps, type CommentBodyParagraphComponentProps, type CommentBodyTextComponentProps, type CommentEmailAsHtmlData, type CommentEmailAsReactData, type ConvertCommentBodyAsHtmlStyles, type ConvertCommentBodyAsReactComponents, type ConvertTextEditorNodesAsHtmlStyles, type ConvertTextEditorNodesAsReactComponents, type MentionEmailAsHtmlData, type MentionEmailAsReactData, type PrepareTextMentionNotificationEmailAsHtmlOptions, type PrepareTextMentionNotificationEmailAsReactOptions, type PrepareThreadNotificationEmailAsHtmlOptions, type PrepareThreadNotificationEmailAsReactOptions, type ResolveRoomInfoArgs, type TextEditorContainerComponentProps, type TextEditorMentionComponentProps, type TextEditorTextComponentProps, type TextMentionNotificationEmailDataAsHtml, type TextMentionNotificationEmailDataAsReact, type ThreadNotificationEmailDataAsHtml, type ThreadNotificationEmailDataAsReact, prepareTextMentionNotificationEmailAsHtml, prepareTextMentionNotificationEmailAsReact, prepareThreadNotificationEmailAsHtml, prepareThreadNotificationEmailAsReact };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { CommentBodyText, CommentBodyLink, BaseUserMeta, DU, CommentBodyMention, ResolveUsersArgs, OptionalPromise, CommentBody, DRI } from '@liveblocks/core';
+import { CommentBodyText, CommentBodyLink, BaseUserMeta, DU, CommentBodyMention, ResolveUsersArgs, OptionalPromise, DRI, CommentBody } from '@liveblocks/core';
 export { ResolveUsersArgs } from '@liveblocks/core';
 import React from 'react';
 import { Properties } from 'csstype';
-import { Liveblocks, ThreadNotificationEvent } from '@liveblocks/node';
+import { Liveblocks, TextMentionNotificationEvent, ThreadNotificationEvent } from '@liveblocks/node';
 
 /**
  * CSS properties object.
@@ -95,20 +95,212 @@ declare type ConvertCommentBodyAsHtmlStyles = {
     link: CSSProperties;
 };
 
-declare type CommentEmailBaseData = {
+declare type ResolveRoomInfoArgs = {
+    /**
+     * The ID of the room to resolve
+     */
+    roomId: string;
+};
+
+/**
+ * Liveblocks Text Editor
+ *
+ * Expose common types to transform nodes from different editors like `Lexical` or `TipTap`
+ * and then convert them more easily as React or as html.
+ */
+
+declare type LiveblocksTextEditorTextFormat = {
+    bold: boolean;
+    italic: boolean;
+    strikethrough: boolean;
+    code: boolean;
+};
+declare type LiveblocksTextEditorTextNode = {
+    type: "text";
+    text: string;
+} & LiveblocksTextEditorTextFormat;
+declare type LiveblocksTextEditorMentionNode = {
+    type: "mention";
+    userId: string;
+};
+/**
+ * -------------------------------------------------------------------------------------------------
+ * `LiveblocksTextEditorNode` is common structure to represents text editor nodes coming from
+ * like `Lexical`, `TipTap` or so.
+ *
+ * This (simple) structure is made to be scalable and to accommodate with other text editors we could potentially
+ * want to support in the future.
+ *
+ * It allows to manipulate nodes more easily and converts them with ease either as React nodes or as an html safe string.
+ * From a DX standpoint it provides to developers the same structure to use when using custom React components or inline css
+ * to represents a text mention with its surrounding text.
+ * -------------------------------------------------------------------------------------------------
+ */
+declare type LiveblocksTextEditorNode = LiveblocksTextEditorTextNode | LiveblocksTextEditorMentionNode;
+declare type TextEditorContainerComponentProps = {
+    /**
+     * The nodes of the text editor
+     */
+    children: React.ReactNode;
+};
+declare type TextEditorMentionComponentProps<U extends BaseUserMeta = DU> = {
+    /**
+     * The mention element.
+     */
+    element: LiveblocksTextEditorMentionNode;
+    /**
+     * The mention's user info, if the `resolvedUsers` option was provided.
+     */
+    user?: U["info"];
+};
+declare type TextEditorTextComponentProps = {
+    /**
+     * The text element.
+     */
+    element: LiveblocksTextEditorTextNode;
+};
+declare type ConvertTextEditorNodesAsReactComponents<U extends BaseUserMeta = DU> = {
+    /**
+     *
+     * The component used to act as a container to wrap text editor nodes,
+     */
+    Container: React.ComponentType<TextEditorContainerComponentProps>;
+    /**
+     * The component used to display mentions.
+     */
+    Mention: React.ComponentType<TextEditorMentionComponentProps<U>>;
+    /**
+     * The component used to display text nodes.
+     */
+    Text: React.ComponentType<TextEditorTextComponentProps>;
+};
+declare type ConvertTextEditorNodesAsHtmlStyles = {
+    /**
+     * The default inline CSS styles used to display container element.
+     */
+    container: CSSProperties;
+    /**
+     * The default inline CSS styles used to display text `<strong />` elements.
+     */
+    strong: CSSProperties;
+    /**
+     * The default inline CSS styles used to display text `<code />` elements.
+     */
+    code: CSSProperties;
+    /**
+     * The default inline CSS styles used to display mentions.
+     */
+    mention: CSSProperties;
+};
+
+declare type MentionEmailBaseData = {
     id: string;
-    threadId: string;
     roomId: string;
     userId: string;
+    textEditorNodes: LiveblocksTextEditorNode[];
     createdAt: Date;
-    url?: string;
-    rawBody: CommentBody;
 };
-declare type ResolveRoomInfoArgs = {
+declare type PrepareTextMentionNotificationEmailBaseDataOptions = {
     /**
-     * The ID of the room to resolve
+     * A function that returns room info from room IDs.
      */
+    resolveRoomInfo?: (args: ResolveRoomInfoArgs) => OptionalPromise<DRI | undefined>;
+};
+declare type MentionEmailAsReactData<U extends BaseUserMeta = DU> = Omit<MentionEmailBaseData, "userId" | "textEditorNodes"> & {
+    author: U;
+    reactContent: React.ReactNode;
+};
+declare type MentionEmailAsHtmlData<U extends BaseUserMeta = DU> = Omit<MentionEmailBaseData, "userId" | "textEditorNodes"> & {
+    author: U;
+    htmlContent: string;
+};
+declare type PrepareTextMentionNotificationEmailAsReactOptions<U extends BaseUserMeta = DU> = PrepareTextMentionNotificationEmailBaseDataOptions & {
+    /**
+     * A function that returns info from user IDs.
+     */
+    resolveUsers?: (args: ResolveUsersArgs) => OptionalPromise<(U["info"] | undefined)[] | undefined>;
+    /**
+     * The components used to customize the resulting React nodes. Each components has
+     * priority over the base components inherited.
+     */
+    components?: Partial<ConvertTextEditorNodesAsReactComponents<U>>;
+};
+declare type TextMentionNotificationEmailData<U extends BaseUserMeta, M extends MentionEmailAsReactData<U> | MentionEmailAsHtmlData<U>> = {
+    mention: M;
+    roomInfo: DRI;
+};
+declare type TextMentionNotificationEmailDataAsReact = TextMentionNotificationEmailData<BaseUserMeta, MentionEmailAsReactData>;
+/**
+ * Prepares data from a `TextMentionNotificationEvent` and convert content as React nodes.
+ *
+ * @param client The `Liveblocks` node client
+ * @param event The `TextMentionNotificationEvent` received in the webhook handler
+ * @param options The optional options to provide to resolve users, resolve room info and customize comment bodies React components.
+ *
+ * It returns a `TextMentionNotificationEmailDataAsReact` or `null` if there are no existing text mention.
+ *
+ * @example
+ * import { Liveblocks} from "@liveblocks/node"
+ * import { prepareTextMentionNotificationEmailAsReact } from "@liveblocks/emails"
+ *
+ * const liveblocks = new Liveblocks({ secret: "sk_..." })
+ * const emailData = prepareTextMentionNotificationEmailAsReact(
+ *  liveblocks,
+ *  event,
+ *  {
+ *    resolveUsers,
+ *    resolveRoomInfo,
+ *    components,
+ *  }
+ * )
+ */
+declare function prepareTextMentionNotificationEmailAsReact(client: Liveblocks, event: TextMentionNotificationEvent, options?: PrepareTextMentionNotificationEmailAsReactOptions<BaseUserMeta>): Promise<TextMentionNotificationEmailDataAsReact | null>;
+declare type PrepareTextMentionNotificationEmailAsHtmlOptions<U extends BaseUserMeta = DU> = PrepareTextMentionNotificationEmailBaseDataOptions & {
+    /**
+     * A function that returns info from user IDs.
+     */
+    resolveUsers?: (args: ResolveUsersArgs) => OptionalPromise<(U["info"] | undefined)[] | undefined>;
+    /**
+     * The styles used to customize the html elements in the resulting html safe string.
+     * Each styles has priority over the base styles inherited.
+     */
+    styles?: Partial<ConvertTextEditorNodesAsHtmlStyles>;
+};
+declare type TextMentionNotificationEmailDataAsHtml = TextMentionNotificationEmailData<BaseUserMeta, MentionEmailAsHtmlData>;
+/**
+ * Prepares data from a `TextMentionNotificationEvent` and convert content  as an html safe string.
+ *
+ * @param client The `Liveblocks` node client
+ * @param event The `TextMentionNotificationEvent` received in the webhook handler
+ * @param options The optional options to provide to resolve users, resolve room info and customize comment bodies React components.
+ *
+ * It returns a `TextMentionNotificationEmailDataAsReact` or `null` if there are no existing text mention.
+ *
+ * @example
+ * import { Liveblocks} from "@liveblocks/node"
+ * import { prepareTextMentionNotificationEmailAsHtml } from "@liveblocks/emails"
+ *
+ * const liveblocks = new Liveblocks({ secret: "sk_..." })
+ * const emailData = prepareTextMentionNotificationEmailAsHtml(
+ *  liveblocks,
+ *  event,
+ *  {
+ *    resolveUsers,
+ *    resolveRoomInfo,
+ *    styles,
+ *  }
+ * )
+ */
+declare function prepareTextMentionNotificationEmailAsHtml(client: Liveblocks, event: TextMentionNotificationEvent, options?: PrepareTextMentionNotificationEmailAsHtmlOptions<BaseUserMeta>): Promise<TextMentionNotificationEmailDataAsHtml | null>;
+
+declare type CommentEmailBaseData = {
+    id: string;
+    threadId: string;
     roomId: string;
+    userId: string;
+    createdAt: Date;
+    url?: string;
+    rawBody: CommentBody;
 };
 declare type PrepareThreadNotificationEmailBaseDataOptions = {
     /**
@@ -213,4 +405,4 @@ declare type ThreadNotificationEmailDataAsReact = ThreadNotificationEmailData<Ba
  */
 declare function prepareThreadNotificationEmailAsReact(client: Liveblocks, event: ThreadNotificationEvent, options?: PrepareThreadNotificationEmailAsReactOptions<BaseUserMeta>): Promise<ThreadNotificationEmailDataAsReact | null>;
 
-export { type CommentBodyContainerComponentProps, type CommentBodyLinkComponentProps, type CommentBodyMentionComponentProps, type CommentBodyParagraphComponentProps, type CommentBodyTextComponentProps, type CommentEmailAsHtmlData, type CommentEmailAsReactData, type ConvertCommentBodyAsHtmlStyles, type ConvertCommentBodyAsReactComponents, type PrepareThreadNotificationEmailAsHtmlOptions, type PrepareThreadNotificationEmailAsReactOptions, type ResolveRoomInfoArgs, type ThreadNotificationEmailDataAsHtml, type ThreadNotificationEmailDataAsReact, prepareThreadNotificationEmailAsHtml, prepareThreadNotificationEmailAsReact };
+export { type CommentBodyContainerComponentProps, type CommentBodyLinkComponentProps, type CommentBodyMentionComponentProps, type CommentBodyParagraphComponentProps, type CommentBodyTextComponentProps, type CommentEmailAsHtmlData, type CommentEmailAsReactData, type ConvertCommentBodyAsHtmlStyles, type ConvertCommentBodyAsReactComponents, type ConvertTextEditorNodesAsHtmlStyles, type ConvertTextEditorNodesAsReactComponents, type MentionEmailAsHtmlData, type MentionEmailAsReactData, type PrepareTextMentionNotificationEmailAsHtmlOptions, type PrepareTextMentionNotificationEmailAsReactOptions, type PrepareThreadNotificationEmailAsHtmlOptions, type PrepareThreadNotificationEmailAsReactOptions, type ResolveRoomInfoArgs, type TextEditorContainerComponentProps, type TextEditorMentionComponentProps, type TextEditorTextComponentProps, type TextMentionNotificationEmailDataAsHtml, type TextMentionNotificationEmailDataAsReact, type ThreadNotificationEmailDataAsHtml, type ThreadNotificationEmailDataAsReact, prepareTextMentionNotificationEmailAsHtml, prepareTextMentionNotificationEmailAsReact, prepareThreadNotificationEmailAsHtml, prepareThreadNotificationEmailAsReact };