npm package: @mailvideo/backend
Description: This package is used to handle MailVideo in the backend.
Author: MailVideo
Latest version: 0.1.4

# @mailvideo/backend

[![npm (@mailvideo/backend)](https://img.shields.io/npm/v/@mailvideo/backend)](https://www.npmjs.com/package/@mailvideo/backend)

This package is designed for server-side integration of MailVideo, facilitating actions like handling webhook events, creating JWT and processing custom videos for MailVideo users.

-   [Install](#install)
-   [Features](#features)
-   [Prerequisites](#prerequisites)
-   [Example](#example)
-   [Usage](#usage)
-   [API](#api)
-   [Webhook Handling](#webhook-handling)

## Install

```bash
pnpm i @mailvideo/backend
```

## Features

-   Handle MailVideo webhook events.
-   Create JWT for white label SDK users.
-   Process videos and upload to S3.

## Prerequisites

To use this package, a secret key from MailVideo is required. Please contact MailVideo to obtain your secret key.

## Example

-   [GitHub Repository](https://github.com/Onboardr/mailvideo-sdk-example)

## Usage

### Creating a JWT

```javascript
import { MailVideo } from '@mailvideo/backend';

const mailvideo = new MailVideo({
	secret: process.env.MAILVIDEO_SECRET,
	verbose: process.env.NODE_ENV === 'development',
});

// create a jwt with info about the current user and tenant
const jwt = await mailvideo.createJWT({
	account: {
		id: 'account-id',
		firstName: 'John',
		lastName: 'Doe',
		email: 'johndoe@email.com',
	},
	tenant: {
		id: tenantId,
		name: 'Tenant Name',
	},
});

// send JWT to client
```

### Handling Webhooks

```javascript
import { constructAndHandleMailVideoEvent } from '@mailvideo/backend';

const signature = request.headers['mailvideo-signature'];
if (!signature) {
	throw new Error('Missing signature');
}

await constructAndHandleMailVideoEvent({
	payload: request.body,
	signature,
	secret: process.env.MAILVIDEO_WEBHOOK_SECRET,
	actions: {
		'video-processed-success': (payload) => {
			// Handle successful video processing
		},
		'video-processed-failed': (payload) => {
			// Handle failed video processing
		},
		'video-viewed': (payload) => {
			// Handle video viewed event
		},
	},
});
```

## API

### Methods

-   `createJWT(options: CreateJWTOptions): Promise<CreateJWTResponse>`
-   `processVideo(options: StartVideoProcessOptions): Promise<StartVideoProcessResponse>`
-   `constructEvent(options: MailVideoConstructEventOptions): MailVideoEvent`
-   `handleEvent(event: MailVideoEvent, actions: EventHandlerActions): Promise<void>`
-   `constructAndHandleEvent(options: MailVideoConstructEventOptions & { actions: EventHandlerActions }): Promise<void>`

## Webhook Handling

When handling webhooks, use the `constructAndHandleMailVideoEvent` method to validate the event and process it with defined actions.

## Interfaces

### ViewerData

Metadata about the viewer that watches the video.

You can force strong typing by adding a d.ts file to your project.

Example:

```ts
declare namespace MailVideo {
	interface ViewerData {
		name: string;
		email: string;
	}
}
```

## Configuring a Custom S3 Bucket for MailVideo

If you want to host the videos in your own Amazon S3 bucket. This setup is crucial to ensure that MailVideo can store and stream videos effectively.

Steps

1. Access Your S3 Bucket
   Go to the AWS Management Console and navigate to the S3 service. Select the bucket you intend to use with MailVideo.

2. Set Permissions
   Navigate to the Permissions tab of your selected S3 bucket.

3. Add a Bucket Policy
   Under the Bucket Policy section, you need to add the following policy:

```json
{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"AWS": "arn:aws:iam::102512246328:root"
			},
			"Action": ["s3:GetObject", "s3:PutObject"],
			"Resource": "arn:aws:s3:::your-bucket-name/*"
		}
	]
}
```

Replace your-bucket-name with the actual name of your S3 bucket.

4. Configure CORS
   Navigate to the CORS configuration section in the S3 bucket settings. Add the following configuration:

```json
[
	{
		"AllowedHeaders": ["Content-Type"],
		"AllowedMethods": ["PUT"],
		"AllowedOrigins": [
			"https://app.mailvideo.dev",
			"https://app.stage.mailvideo.com",
			"https://app.mailvideo.com"
		],
		"ExposeHeaders": ["ETag"],
		"MaxAgeSeconds": 3000
	}
]
```