npm package: @quickguidehealth/connector-logto-novu
Description: Logto email connector that integrates with Novu for passwordless authentication flows
Author: QuickGuide Health
Latest version: 0.1.3

# Logto Connector: Novu Email

[![npm version](https://img.shields.io/npm/v/@quickguidehealth/connector-logto-novu.svg)](https://www.npmjs.com/package/@quickguidehealth/connector-logto-novu)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Logto email connector that integrates with [Novu](https://novu.co) to send verification codes during user authentication flows.

## Features

- 🔐 Passwordless email authentication via Novu
- 📧 Support for all Logto email flows:
  - User Registration
  - Sign In
  - Password Recovery
  - Continue Flow
  - Generic Verification
- 🎨 Flexible workflow configuration
- ⚡ Built with TypeScript and Zod validation
- 🌍 Multi-language support

## Installation

```bash
npm install @quickguidehealth/connector-logto-novu
```

## Prerequisites

Before using this connector, you need:

1. A [Novu account](https://novu.co) with an API key
2. Configured Novu workflows for each authentication flow you want to support
3. A running Logto instance

## Configuration

### Step 1: Create Novu Workflows

In your Novu dashboard, create workflows for each authentication flow. Each workflow should:

- Have an **Email** step configured
- Accept a `code` payload variable
- Be published and active

Example workflow configuration:
- **Trigger Identifier**: `user-registration-verification`
- **Email Template**: Include `{{code}}` where the verification code should appear

### Step 2: Configure the Connector in Logto

When setting up the connector in your Logto Admin Console, use the following JSON configuration format:

```json
{
  "secretKey": "your-novu-secret-key",
  "serverUrl": "https://eu.api.novu.co",
  "templates": [
    {
      "usageType": "Register",
      "workflowId": "user-registration-verification",
      "workflowName": "User Registration"
    },
    {
      "usageType": "SignIn",
      "workflowId": "user-signin-verification",
      "workflowName": "User Sign In"
    },
    {
      "usageType": "ForgotPassword",
      "workflowId": "password-recovery-verification",
      "workflowName": "Password Recovery"
    },
    {
      "usageType": "Generic",
      "workflowId": "generic-verification",
      "workflowName": "Generic Verification"
    },
    {
      "usageType": "OrganizationInvitation",
      "workflowId": "org-invitation",
      "workflowName": "Organization Invitation"
    },
    {
      "usageType": "UserPermissionValidation",
      "workflowId": "permission-validation",
      "workflowName": "Permission Validation"
    },
    {
      "usageType": "BindNewIdentifier",
      "workflowId": "bind-identifier",
      "workflowName": "Bind New Identifier"
    },
    {
      "usageType": "MfaVerification",
      "workflowId": "mfa-verification",
      "workflowName": "MFA Verification"
    },
    {
      "usageType": "BindMfa",
      "workflowId": "bind-mfa",
      "workflowName": "Bind MFA"
    }
  ],
  "fromEmail": "[email protected]",
  "fromName": "Your App Name"
}
```

### Configuration Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `secretKey` | string | Yes | Your Novu API secret key |
| `serverUrl` | string | No | Novu server URL (default: `https://eu.api.novu.co`) |
| `templates` | array | Yes | Array of template configurations (at least one required) |
| `fromEmail` | string | No | Override the default from email address |
| `fromName` | string | No | Override the default from name |

### Server URL Options

| Region | URL |
|--------|-----|
| EU (default) | `https://eu.api.novu.co` |
| US | `https://api.novu.co` |
| Self-hosted | `https://novu.your-domain.com` |

### Template Configuration

Each template in the `templates` array must include:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `usageType` | enum | Yes | See "Usage Type Guide" below |
| `workflowId` | string | Yes | The Novu workflow identifier to trigger |
| `workflowName` | string | No | Human-readable name for documentation |

## Usage Type Guide

- **Register**: Sent when a new user signs up
- **SignIn**: Sent when an existing user signs in with passwordless authentication
- **ForgotPassword**: Sent when a user requests a password reset
- **Generic**: Sent for generic verification purposes
- **OrganizationInvitation**: Sent when inviting users to an organization
- **UserPermissionValidation**: Sent to verify identity for sensitive operations
- **BindNewIdentifier**: Sent when binding a new email to an account
- **MfaVerification**: Sent for MFA challenges during login
- **BindMfa**: Sent when setting up email-based MFA

## How It Works

1. When a user triggers an authentication flow in Logto that requires email verification
2. Logto calls this connector's `sendMessage` method
3. The connector finds the appropriate Novu workflow based on the usage type
4. A Novu workflow is triggered with the verification code
5. Novu delivers the email to the user
6. The user enters the code to complete authentication

## Novu Workflow Payload

When the connector triggers a Novu workflow, it sends the following payload:

```typescript
{
  to: {
    subscriberId: "[email protected]",
    email: "[email protected]"
  },
  payload: {
    code: "123456",
    email: "[email protected]",
    type?: "Register" | "SignIn" | "ForgotPassword" | "Continue" | "Generic"
  },
  overrides?: {
    email: {
      from?: "[email protected]",
      senderName?: "Your App Name"
    }
  }
}
```

In your Novu email templates, you can access:
- `{{code}}` - The verification code
- `{{email}}` - The recipient's email address
- `{{type}}` - The authentication flow type

## Troubleshooting

### "Cannot find Novu workflow template for usage type"

**Cause**: The configuration doesn't include a template for the requested usage type.

**Solution**: Add a template configuration for the missing usage type in your connector configuration.

### "Failed to send email via Novu"

**Cause**: Novu API request failed.

**Possible solutions**:
- Verify your Novu secret key is correct
- Check that the workflow IDs exist and are published in Novu
- Ensure your Novu account is active and not rate-limited
- Check Novu's dashboard for error logs

### "Verification code is required in payload"

**Cause**: Logto didn't provide a verification code in the request.

**Solution**: This is usually a Logto configuration issue. Ensure your authentication flow is properly configured.

## Development

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Clean Build Artifacts

```bash
npm run clean
```

## Related Links

- [Logto Documentation](https://docs.logto.io/)
- [Logto Connector Development Guide](https://docs.logto.io/logto-oss/develop-your-connector/)
- [Novu Documentation](https://docs.novu.co/)
- [Novu TypeScript SDK](https://docs.novu.co/platform/sdks/server/typescript)

## License

MIT © QuickGuide Health

## Support

For issues and questions:
- GitHub Issues: https://github.com/QuickGuideHealth/quickguide-packages/issues
- Logto Discord: https://discord.gg/logto
- Novu Discord: https://discord.gg/novu

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.