@liveblocks/emails 0.0.1 → 2.9.2-emails1

package/README.md

@@ -0,0 +1,59 @@
+<p align="center">
+  <a href="https://liveblocks.io#gh-light-mode-only">
+    <img src="https://raw.githubusercontent.com/liveblocks/liveblocks/main/.github/assets/header-light.svg" alt="Liveblocks" />
+  </a>
+  <a href="https://liveblocks.io#gh-dark-mode-only">
+    <img src="https://raw.githubusercontent.com/liveblocks/liveblocks/main/.github/assets/header-dark.svg" alt="Liveblocks" />
+  </a>
+</p>
+
+# `@liveblocks/emails`
+
+<p>
+  <a href="https://npmjs.org/package/@liveblocks/emails">
+    <img src="https://img.shields.io/npm/v/@liveblocks/emails?style=flat&label=npm&color=c33" alt="NPM" />
+  </a>
+  <a href="https://bundlephobia.com/package/@liveblocks/emails">
+    <img src="https://img.shields.io/bundlephobia/minzip/@liveblocks/emails?style=flat&label=size&color=09f" alt="Size" />
+  </a>
+  <a href="https://github.com/liveblocks/liveblocks/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/liveblocks/liveblocks?style=flat&label=license&color=f80" alt="License" />
+  </a>
+</p>
+
+`@liveblocks/emails` provides a set of functions and utilities to make sending
+emails based on [Liveblocks](https://liveblocks.io) notification events easy.
+
+## Installation
+
+```
+npm install @liveblocks/node @liveblocks/emails
+```
+
+## Documentation
+
+...
+
+## Examples
+
+...
+
+## Releases
+
+See the [latest changes](https://github.com/liveblocks/liveblocks/releases) or
+learn more about
+[upcoming releases](https://github.com/liveblocks/liveblocks/milestones).
+
+## Community
+
+- [Discord](https://liveblocks.io/discord) - To get involved with the Liveblocks
+  community, ask questions and share tips.
+- [X](https://x.com/liveblocks) - To receive updates, announcements, blog posts,
+  and general Liveblocks tips.
+
+## License
+
+Licensed under the Apache License 2.0, Copyright © 2021-present
+[Liveblocks](https://liveblocks.io).
+
+See [LICENSE](../../LICENSE) for more information.

package/dist/index.d.mts

@@ -0,0 +1,215 @@
+import { CommentBodyText, CommentBodyLink, BaseUserMeta, DU, CommentBodyMention, ResolveUsersArgs, OptionalPromise, CommentBody, DRI } from '@liveblocks/core';
+import React from 'react';
+import { Properties } from 'csstype';
+import { Liveblocks, ThreadNotificationEvent } from '@liveblocks/node';
+
+/**
+ * CSS properties object.
+ * Type alias for DX purposes.
+ *
+ */
+declare type CSSProperties = Properties;
+
+declare type CommentBodyContainerComponentProps = {
+    /**
+     * The blocks of the comment body
+     */
+    children: React.ReactNode;
+};
+declare type CommentBodyParagraphComponentProps = {
+    /**
+     * The text content of the paragraph.
+     */
+    children: React.ReactNode;
+};
+declare type CommentBodyTextComponentProps = {
+    /**
+     * The text element.
+     */
+    element: CommentBodyText;
+};
+declare type CommentBodyLinkComponentProps = {
+    /**
+     * The link element.
+     */
+    element: CommentBodyLink;
+    /**
+     * The absolute URL of the link.
+     */
+    href: string;
+};
+declare type CommentBodyMentionComponentProps<U extends BaseUserMeta = DU> = {
+    /**
+     * The mention element.
+     */
+    element: CommentBodyMention;
+    /**
+     * The mention's user info, if the `resolvedUsers` option was provided.
+     */
+    user?: U["info"];
+};
+declare type ConvertCommentBodyAsReactComponents<U extends BaseUserMeta = DU> = {
+    /**
+     *
+     * The component used to act as a container to wrap comment body blocks,
+     */
+    Container: React.ComponentType<CommentBodyContainerComponentProps>;
+    /**
+     * The component used to display paragraphs.
+     */
+    Paragraph: React.ComponentType<CommentBodyParagraphComponentProps>;
+    /**
+     * The component used to display text elements.
+     */
+    Text: React.ComponentType<CommentBodyTextComponentProps>;
+    /**
+     * The component used to display links.
+     */
+    Link: React.ComponentType<CommentBodyLinkComponentProps>;
+    /**
+     * The component used to display mentions.
+     */
+    Mention: React.ComponentType<CommentBodyMentionComponentProps<U>>;
+};
+declare type ConvertCommentBodyAsHtmlStyles = {
+    /**
+     * The default inline CSS styles used to display paragraphs.
+     */
+    paragraph: 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 links.
+     */
+    mention: CSSProperties;
+    /**
+     * The default inline CSS styles used to display mentions.
+     */
+    link: CSSProperties;
+};
+
+declare type CommentEmailBaseData = {
+    id: string;
+    threadId: string;
+    roomId: string;
+    userId: string;
+    createdAt: Date;
+    url?: string;
+    rawBody: CommentBody;
+};
+declare type ResolveRoomInfoArgs = {
+    /**
+     * The ID of the room to resolve
+     */
+    roomId: string;
+};
+declare type PrepareThreadNotificationEmailBaseDataOptions = {
+    /**
+     * A function that returns room info from room IDs.
+     */
+    resolveRoomInfo?: (args: ResolveRoomInfoArgs) => OptionalPromise<DRI | undefined>;
+};
+declare type CommentEmailAsHtmlData<U extends BaseUserMeta = DU> = Omit<CommentEmailBaseData, "userId" | "rawBody"> & {
+    author: U;
+    htmlBody: string;
+};
+declare type CommentEmailAsReactData<U extends BaseUserMeta = DU> = Omit<CommentEmailBaseData, "userId" | "rawBody"> & {
+    author: U;
+    reactBody: React.ReactNode;
+};
+declare type ThreadNotificationEmailUnreadRepliesData<U extends BaseUserMeta, C extends CommentEmailAsHtmlData<U> | CommentEmailAsReactData<U>> = {
+    type: "unreadReplies";
+    comments: C[];
+};
+declare type ThreadNotificationEmailUnreadMentionsData<U extends BaseUserMeta, C extends CommentEmailAsHtmlData<U> | CommentEmailAsReactData<U>> = {
+    type: "unreadMention";
+    comment: C;
+};
+declare type ThreadNotificationEmailData<U extends BaseUserMeta, C extends CommentEmailAsHtmlData<U> | CommentEmailAsReactData<U>> = (ThreadNotificationEmailUnreadRepliesData<U, C> | ThreadNotificationEmailUnreadMentionsData<U, C>) & {
+    roomInfo: DRI;
+};
+declare type PrepareThreadNotificationEmailAsHtmlOptions<U extends BaseUserMeta = DU> = PrepareThreadNotificationEmailBaseDataOptions & {
+    /**
+     * 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 inside a comment body.
+     * Each styles has priority over the base styles inherited.
+     */
+    styles?: Partial<ConvertCommentBodyAsHtmlStyles>;
+};
+declare type ThreadNotificationEmailDataAsHtml = ThreadNotificationEmailData<BaseUserMeta, CommentEmailAsHtmlData>;
+/**
+ * Prepares data from a `ThreadNotificationEvent` and convert comment bodies as an html safe string.
+ *
+ * @param client The `Liveblocks` node client
+ * @param event The `ThreadNotificationEvent` received in the webhook handler
+ * @param options The optional options to provide to resolve users, resolve room info
+ * and customize comment bodies html elements styles with inline CSS.
+ *
+ * It returns a `ThreadNotificationEmailDataAsHtml` or `null` if there are no unread comments (mention or replies).
+ *
+ * @example
+ * import { Liveblocks} from "@liveblocks/node"
+ * import { prepareThreadNotificationEmailAsHtml } from "@liveblocks/emails"
+ *
+ * const liveblocks = new Liveblocks({ secret: "sk_..." })
+ * const emailData = prepareThreadNotificationEmailAsHtml(
+ *  liveblocks,
+ *  event,
+ *  {
+ *    resolveUsers,
+ *    resolveRoomInfo,
+ *    styles,
+ *  }
+ * )
+ *
+ */
+declare function prepareThreadNotificationEmailAsHtml(client: Liveblocks, event: ThreadNotificationEvent, options?: PrepareThreadNotificationEmailAsHtmlOptions<BaseUserMeta>): Promise<ThreadNotificationEmailDataAsHtml | null>;
+declare type PrepareThreadNotificationEmailAsReactOptions<U extends BaseUserMeta = DU> = PrepareThreadNotificationEmailBaseDataOptions & {
+    /**
+     * 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 inside a comment body.
+     * Each components has priority over the base components inherited internally defined.
+     */
+    components?: Partial<ConvertCommentBodyAsReactComponents<U>>;
+};
+declare type ThreadNotificationEmailDataAsReact = ThreadNotificationEmailData<BaseUserMeta, CommentEmailAsReactData>;
+/**
+ * Prepares data from a `ThreadNotificationEvent` and convert comment bodies as React nodes.
+ *
+ * @param client The `Liveblocks` node client
+ * @param event The `ThreadNotificationEvent` 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 `ThreadNotificationEmailDataAsReact` or `null` if there are no unread comments (mention or replies).
+ *
+ * @example
+ * import { Liveblocks} from "@liveblocks/node"
+ * import { prepareThreadNotificationEmailAsReact } from "@liveblocks/emails"
+ *
+ * const liveblocks = new Liveblocks({ secret: "sk_..." })
+ * const emailData = prepareThreadNotificationEmailAsReact(
+ *  liveblocks,
+ *  event,
+ *  {
+ *    resolveUsers,
+ *    resolveRoomInfo,
+ *    components,
+ *  }
+ * )
+ *
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+import { CommentBodyText, CommentBodyLink, BaseUserMeta, DU, CommentBodyMention, ResolveUsersArgs, OptionalPromise, CommentBody, DRI } from '@liveblocks/core';
+import React from 'react';
+import { Properties } from 'csstype';
+import { Liveblocks, ThreadNotificationEvent } from '@liveblocks/node';
+
+/**
+ * CSS properties object.
+ * Type alias for DX purposes.
+ *
+ */
+declare type CSSProperties = Properties;
+
+declare type CommentBodyContainerComponentProps = {
+    /**
+     * The blocks of the comment body
+     */
+    children: React.ReactNode;
+};
+declare type CommentBodyParagraphComponentProps = {
+    /**
+     * The text content of the paragraph.
+     */
+    children: React.ReactNode;
+};
+declare type CommentBodyTextComponentProps = {
+    /**
+     * The text element.
+     */
+    element: CommentBodyText;
+};
+declare type CommentBodyLinkComponentProps = {
+    /**
+     * The link element.
+     */
+    element: CommentBodyLink;
+    /**
+     * The absolute URL of the link.
+     */
+    href: string;
+};
+declare type CommentBodyMentionComponentProps<U extends BaseUserMeta = DU> = {
+    /**
+     * The mention element.
+     */
+    element: CommentBodyMention;
+    /**
+     * The mention's user info, if the `resolvedUsers` option was provided.
+     */
+    user?: U["info"];
+};
+declare type ConvertCommentBodyAsReactComponents<U extends BaseUserMeta = DU> = {
+    /**
+     *
+     * The component used to act as a container to wrap comment body blocks,
+     */
+    Container: React.ComponentType<CommentBodyContainerComponentProps>;
+    /**
+     * The component used to display paragraphs.
+     */
+    Paragraph: React.ComponentType<CommentBodyParagraphComponentProps>;
+    /**
+     * The component used to display text elements.
+     */
+    Text: React.ComponentType<CommentBodyTextComponentProps>;
+    /**
+     * The component used to display links.
+     */
+    Link: React.ComponentType<CommentBodyLinkComponentProps>;
+    /**
+     * The component used to display mentions.
+     */
+    Mention: React.ComponentType<CommentBodyMentionComponentProps<U>>;
+};
+declare type ConvertCommentBodyAsHtmlStyles = {
+    /**
+     * The default inline CSS styles used to display paragraphs.
+     */
+    paragraph: 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 links.
+     */
+    mention: CSSProperties;
+    /**
+     * The default inline CSS styles used to display mentions.
+     */
+    link: CSSProperties;
+};
+
+declare type CommentEmailBaseData = {
+    id: string;
+    threadId: string;
+    roomId: string;
+    userId: string;
+    createdAt: Date;
+    url?: string;
+    rawBody: CommentBody;
+};
+declare type ResolveRoomInfoArgs = {
+    /**
+     * The ID of the room to resolve
+     */
+    roomId: string;
+};
+declare type PrepareThreadNotificationEmailBaseDataOptions = {
+    /**
+     * A function that returns room info from room IDs.
+     */
+    resolveRoomInfo?: (args: ResolveRoomInfoArgs) => OptionalPromise<DRI | undefined>;
+};
+declare type CommentEmailAsHtmlData<U extends BaseUserMeta = DU> = Omit<CommentEmailBaseData, "userId" | "rawBody"> & {
+    author: U;
+    htmlBody: string;
+};
+declare type CommentEmailAsReactData<U extends BaseUserMeta = DU> = Omit<CommentEmailBaseData, "userId" | "rawBody"> & {
+    author: U;
+    reactBody: React.ReactNode;
+};
+declare type ThreadNotificationEmailUnreadRepliesData<U extends BaseUserMeta, C extends CommentEmailAsHtmlData<U> | CommentEmailAsReactData<U>> = {
+    type: "unreadReplies";
+    comments: C[];
+};
+declare type ThreadNotificationEmailUnreadMentionsData<U extends BaseUserMeta, C extends CommentEmailAsHtmlData<U> | CommentEmailAsReactData<U>> = {
+    type: "unreadMention";
+    comment: C;
+};
+declare type ThreadNotificationEmailData<U extends BaseUserMeta, C extends CommentEmailAsHtmlData<U> | CommentEmailAsReactData<U>> = (ThreadNotificationEmailUnreadRepliesData<U, C> | ThreadNotificationEmailUnreadMentionsData<U, C>) & {
+    roomInfo: DRI;
+};
+declare type PrepareThreadNotificationEmailAsHtmlOptions<U extends BaseUserMeta = DU> = PrepareThreadNotificationEmailBaseDataOptions & {
+    /**
+     * 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 inside a comment body.
+     * Each styles has priority over the base styles inherited.
+     */
+    styles?: Partial<ConvertCommentBodyAsHtmlStyles>;
+};
+declare type ThreadNotificationEmailDataAsHtml = ThreadNotificationEmailData<BaseUserMeta, CommentEmailAsHtmlData>;
+/**
+ * Prepares data from a `ThreadNotificationEvent` and convert comment bodies as an html safe string.
+ *
+ * @param client The `Liveblocks` node client
+ * @param event The `ThreadNotificationEvent` received in the webhook handler
+ * @param options The optional options to provide to resolve users, resolve room info
+ * and customize comment bodies html elements styles with inline CSS.
+ *
+ * It returns a `ThreadNotificationEmailDataAsHtml` or `null` if there are no unread comments (mention or replies).
+ *
+ * @example
+ * import { Liveblocks} from "@liveblocks/node"
+ * import { prepareThreadNotificationEmailAsHtml } from "@liveblocks/emails"
+ *
+ * const liveblocks = new Liveblocks({ secret: "sk_..." })
+ * const emailData = prepareThreadNotificationEmailAsHtml(
+ *  liveblocks,
+ *  event,
+ *  {
+ *    resolveUsers,
+ *    resolveRoomInfo,
+ *    styles,
+ *  }
+ * )
+ *
+ */
+declare function prepareThreadNotificationEmailAsHtml(client: Liveblocks, event: ThreadNotificationEvent, options?: PrepareThreadNotificationEmailAsHtmlOptions<BaseUserMeta>): Promise<ThreadNotificationEmailDataAsHtml | null>;
+declare type PrepareThreadNotificationEmailAsReactOptions<U extends BaseUserMeta = DU> = PrepareThreadNotificationEmailBaseDataOptions & {
+    /**
+     * 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 inside a comment body.
+     * Each components has priority over the base components inherited internally defined.
+     */
+    components?: Partial<ConvertCommentBodyAsReactComponents<U>>;
+};
+declare type ThreadNotificationEmailDataAsReact = ThreadNotificationEmailData<BaseUserMeta, CommentEmailAsReactData>;
+/**
+ * Prepares data from a `ThreadNotificationEvent` and convert comment bodies as React nodes.
+ *
+ * @param client The `Liveblocks` node client
+ * @param event The `ThreadNotificationEvent` 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 `ThreadNotificationEmailDataAsReact` or `null` if there are no unread comments (mention or replies).
+ *
+ * @example
+ * import { Liveblocks} from "@liveblocks/node"
+ * import { prepareThreadNotificationEmailAsReact } from "@liveblocks/emails"
+ *
+ * const liveblocks = new Liveblocks({ secret: "sk_..." })
+ * const emailData = prepareThreadNotificationEmailAsReact(
+ *  liveblocks,
+ *  event,
+ *  {
+ *    resolveUsers,
+ *    resolveRoomInfo,
+ *    components,
+ *  }
+ * )
+ *
+ */
+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 };