feat: Add Broadcasts (#445)

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: Krithika <[email protected]>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Vitor Capretz <[email protected]>
Co-authored-by: Vitor Capretz <[email protected]>

Author: 6 people

src/broadcasts/broadcasts.spec.ts

@@ -0,0 +1,225 @@
+import { enableFetchMocks } from 'jest-fetch-mock';
+import type { ErrorResponse } from '../interfaces';
+import { Resend } from '../resend';
+import type {
+  CreateBroadcastOptions,
+  CreateBroadcastResponseSuccess,
+} from './interfaces/create-broadcast-options.interface';
+
+enableFetchMocks();
+
+const resend = new Resend('re_zKa4RCko_Lhm9ost2YjNCctnPjbLw8Nop');
+
+describe('Broadcasts', () => {
+  afterEach(() => fetchMock.resetMocks());
+
+  describe('create', () => {
+    it('missing `from`', async () => {
+      const response: ErrorResponse = {
+        name: 'missing_required_field',
+        message: 'Missing `from` field.',
+      };
+
+      fetchMock.mockOnce(JSON.stringify(response), {
+        status: 422,
+        headers: {
+          'content-type': 'application/json',
+          Authorization: 'Bearer re_zKa4RCko_Lhm9ost2YjNCctnPjbLw8Nop',
+        },
+      });
+
+      const data = await resend.broadcasts.create({} as CreateBroadcastOptions);
+      console.log({ data });
+      expect(data).toMatchInlineSnapshot(`
+{
+  "data": null,
+  "error": {
+    "message": "Missing \`from\` field.",
+    "name": "missing_required_field",
+  },
+}
+`);
+    });
+
+    it('creates broadcast', async () => {
+      const response: CreateBroadcastResponseSuccess = {
+        id: '71cdfe68-cf79-473a-a9d7-21f91db6a526',
+      };
+      fetchMock.mockOnce(JSON.stringify(response), {
+        status: 200,
+        headers: {
+          'content-type': 'application/json',
+          Authorization: 'Bearer re_zKa4RCko_Lhm9ost2YjNCctnPjbLw8Nop',
+        },
+      });
+
+      const payload: CreateBroadcastOptions = {
+        from: '[email protected]',
+        audienceId: '0192f4ed-c2e9-7112-9c13-b04a043e23ee',
+        subject: 'Hello World',
+        html: '<h1>Hello world</h1>',
+      };
+
+      const data = await resend.broadcasts.create(payload);
+      expect(data).toMatchInlineSnapshot(`
+{
+  "data": {
+    "id": "71cdfe68-cf79-473a-a9d7-21f91db6a526",
+  },
+  "error": null,
+}
+`);
+    });
+
+    it('creates broadcast with multiple recipients', async () => {
+      const response: CreateBroadcastResponseSuccess = {
+        id: '124dc0f1-e36c-417c-a65c-e33773abc768',
+      };
+
+      fetchMock.mockOnce(JSON.stringify(response), {
+        status: 200,
+        headers: {
+          'content-type': 'application/json',
+          Authorization: 'Bearer re_924b3rjh2387fbewf823',
+        },
+      });
+
+      const payload: CreateBroadcastOptions = {
+        from: '[email protected]',
+        audienceId: '0192f4f1-d5f9-7110-8eb5-370552515917',
+        subject: 'Hello World',
+        text: 'Hello world',
+      };
+      const data = await resend.broadcasts.create(payload);
+      expect(data).toMatchInlineSnapshot(`
+{
+  "data": {
+    "id": "124dc0f1-e36c-417c-a65c-e33773abc768",
+  },
+  "error": null,
+}
+`);
+    });
+
+    it('creates broadcast with multiple replyTo emails', async () => {
+      const response: CreateBroadcastResponseSuccess = {
+        id: '124dc0f1-e36c-417c-a65c-e33773abc768',
+      };
+
+      fetchMock.mockOnce(JSON.stringify(response), {
+        status: 200,
+        headers: {
+          'content-type': 'application/json',
+          Authorization: 'Bearer re_924b3rjh2387fbewf823',
+        },
+      });
+
+      const payload: CreateBroadcastOptions = {
+        from: '[email protected]',
+        audienceId: '0192f4f1-d5f9-7110-8eb5-370552515917',
+        replyTo: ['[email protected]', '[email protected]'],
+        subject: 'Hello World',
+        text: 'Hello world',
+      };
+
+      const data = await resend.broadcasts.create(payload);
+      expect(data).toMatchInlineSnapshot(`
+{
+  "data": {
+    "id": "124dc0f1-e36c-417c-a65c-e33773abc768",
+  },
+  "error": null,
+}
+`);
+    });
+
+    it('throws an error when an ErrorResponse is returned', async () => {
+      const response: ErrorResponse = {
+        name: 'invalid_parameter',
+        message:
+          'Invalid `from` field. The email address needs to follow the `[email protected]` or `Name <[email protected]>` format',
+      };
+
+      fetchMock.mockOnce(JSON.stringify(response), {
+        status: 422,
+        headers: {
+          'content-type': 'application/json',
+          Authorization: 'Bearer re_924b3rjh2387fbewf823',
+        },
+      });
+
+      const payload: CreateBroadcastOptions = {
+        from: 'resend.com', // Invalid from address
+        audienceId: '0192f4f1-d5f9-7110-8eb5-370552515917',
+        replyTo: ['[email protected]', '[email protected]'],
+        subject: 'Hello World',
+        text: 'Hello world',
+      };
+
+      const result = resend.broadcasts.create(payload);
+
+      await expect(result).resolves.toMatchInlineSnapshot(`
+  {
+    "data": null,
+    "error": {
+      "message": "Invalid \`from\` field. The email address needs to follow the \`[email protected]\` or \`Name <[email protected]>\` format",
+      "name": "invalid_parameter",
+    },
+  }
+  `);
+    });
+
+    it('returns an error when fetch fails', async () => {
+      const originalEnv = process.env;
+      process.env = {
+        ...originalEnv,
+        RESEND_BASE_URL: 'http://invalidurl.noturl',
+      };
+
+      const result = await resend.broadcasts.create({
+        from: '[email protected]',
+        audienceId: '0192f4f1-d5f9-7110-8eb5-370552515917',
+        subject: 'Hello World',
+        text: 'Hello world',
+      });
+
+      expect(result).toEqual(
+        expect.objectContaining({
+          data: null,
+          error: {
+            message: 'Unable to fetch data. The request could not be resolved.',
+            name: 'application_error',
+          },
+        }),
+      );
+      process.env = originalEnv;
+    });
+
+    it('returns an error when api responds with text payload', async () => {
+      fetchMock.mockOnce('local_rate_limited', {
+        status: 422,
+        headers: {
+          Authorization: 'Bearer re_924b3rjh2387fbewf823',
+        },
+      });
+
+      const result = await resend.broadcasts.create({
+        from: '[email protected]',
+        audienceId: '0192f4f1-d5f9-7110-8eb5-370552515917',
+        subject: 'Hello World',
+        text: 'Hello world',
+      });
+
+      expect(result).toEqual(
+        expect.objectContaining({
+          data: null,
+          error: {
+            message:
+              'Internal server error. We are unable to process your request right now, please try again later.',
+            name: 'application_error',
+          },
+        }),
+      );
+    });
+  });
+});

src/broadcasts/broadcasts.ts

@@ -0,0 +1,67 @@
+import type * as React from 'react';
+import type { Resend } from '../resend';
+import type {
+  CreateBroadcastOptions,
+  CreateBroadcastRequestOptions,
+} from './interfaces/create-broadcast-options.interface';
+import type {
+  SendBroadcastOptions,
+  SendBroadcastResponse,
+  SendBroadcastResponseSuccess,
+} from './interfaces/send-broadcast-options.interface';
+
+export class Broadcasts {
+  private renderAsync?: (component: React.ReactElement) => Promise<string>;
+  constructor(private readonly resend: Resend) {}
+
+  async create(
+    payload: CreateBroadcastOptions,
+    options: CreateBroadcastRequestOptions = {},
+  ): Promise<SendBroadcastResponse> {
+    if (payload.react) {
+      if (!this.renderAsync) {
+        try {
+          const { renderAsync } = await import('@react-email/render');
+          this.renderAsync = renderAsync;
+        } catch (error) {
+          throw new Error(
+            'Failed to render React component. Make sure to install `@react-email/render`',
+          );
+        }
+      }
+
+      payload.html = await this.renderAsync(
+        payload.react as React.ReactElement,
+      );
+    }
+
+    const data = await this.resend.post<SendBroadcastResponseSuccess>(
+      '/broadcasts',
+      {
+        name: payload.name,
+        audience_id: payload.audienceId,
+        preview_text: payload.previewText,
+        from: payload.from,
+        html: payload.html,
+        reply_to: payload.replyTo,
+        subject: payload.subject,
+        text: payload.text,
+      },
+      options,
+    );
+
+    return data;
+  }
+
+  async send(
+    id: string,
+    payload: SendBroadcastOptions,
+  ): Promise<SendBroadcastResponse> {
+    const data = await this.resend.post<SendBroadcastResponseSuccess>(
+      `/broadcasts/${id}/send`,
+      { scheduled_at: payload.scheduledAt },
+    );
+
+    return data;
+  }
+}

src/broadcasts/interfaces/create-broadcast-options.interface.ts

@@ -0,0 +1,79 @@
+import type * as React from 'react';
+import type { PostOptions } from '../../common/interfaces';
+import type { RequireAtLeastOne } from '../../common/interfaces/require-at-least-one';
+import type { ErrorResponse } from '../../interfaces';
+
+interface EmailRenderOptions {
+  /**
+   * The React component used to write the message.
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  react: React.ReactNode;
+  /**
+   * The HTML version of the message.
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  html: string;
+  /**
+   * The plain text version of the message.
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  text: string;
+}
+
+interface CreateBroadcastBaseOptions {
+  /**
+   * The name of the broadcast
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  name?: string;
+  /**
+   * The id of the audience you want to send to
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  audienceId: string;
+  /**
+   * A short snippet of text displayed as a preview in recipients' inboxes, often shown below or beside the subject line.
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  previewText?: string;
+  /**
+   * Sender email address. To include a friendly name, use the format `"Your Name <[email protected]>"`
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  from: string;
+  /**
+   * Reply-to email address. For multiple addresses, send as an array of strings.
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  replyTo?: string | string[];
+  /**
+   * Email subject.
+   *
+   * @link https://resend.com/docs/api-reference/broadcasts/create#body-parameters
+   */
+  subject: string;
+}
+
+export type CreateBroadcastOptions = RequireAtLeastOne<EmailRenderOptions> &
+  CreateBroadcastBaseOptions;
+
+export interface CreateBroadcastRequestOptions extends PostOptions {}
+
+export interface CreateBroadcastResponseSuccess {
+  /** The ID of the newly sent broadcasts. */
+  id: string;
+}
+
+export interface CreateBroadcastResponse {
+  data: CreateBroadcastResponseSuccess | null;
+  error: ErrorResponse | null;
+}