@remit/imap-worker

SQS-driven Lambda worker for handling IMAP lifecycle events in the Remit system.

Features

• Event Driven: Processes events from SQS (SYNC_MAILBOXES, SYNC_MESSAGES, etc.)
• CLI Tool: Includes a CLI for manually triggering events during development
• Bundled: Built with esbuild for optimal Lambda performance

Installation

npm install
npm run bundle

Usage

Lambda Handler

The package exports a standard AWS Lambda SQS handler:

import { handler } from "@remit/imap-worker";

CLI (Local Development)

Trigger events manually using the included CLI:

# Sync all mailboxes for an account
npm run cli -- -t SYNC_MAILBOXES -a <accountId>

# Sync messages in a mailbox
npm run cli -- -t SYNC_MESSAGES -a <accountId> -m <mailboxId>

# Force full sync (ignore lastSyncUid)
npm run cli -- -t SYNC_MESSAGES -a <accountId> -m <mailboxId> --fullSync

# Sync message bodies for specific messages
npm run cli -- -t SYNC_MESSAGE_BODY -a <accountId> -m <mailboxId> --messageIds id1,id2,id3

Environment Variables

| Variable | Required | Description | | ----------------------------- | -------- | -------------------------------------------------------- | | DATA_BACKEND | Yes | Relational backend to run against (sqlite) | | SQLITE_DB_PATH | Yes | Path to the shared SQLite database file | | SQS_QUEUE_URL_MAILBOXES | Yes | FIFO queue URL for SYNC_MAILBOXES events | | SQS_QUEUE_URL_MESSAGES | Yes | FIFO queue URL for SYNC_MESSAGES events | | SQS_QUEUE_URL_BODY | Yes | FIFO queue URL for SYNC_MESSAGE_BODY events | | SQS_QUEUE_URL_FLAGS | Yes | FIFO queue URL for SYNC_FLAGS events | | SQS_QUEUE_URL_MAILBOX_MGMT | Yes | Standard queue URL for mailbox management events | | SQS_QUEUE_URL_MESSAGE_MGMT | Yes | Standard queue URL for message management events | | S3_BUCKET | Yes | S3 bucket for storing raw message content | | NODE_ENV | No | Set to development for local execution | | LOG_LEVEL | No | Logging level (default: info) |

Event Types

| Event | Description | Required Fields | | ------------------- | ---------------------------------------------- | --------------------------------------- | | SYNC_MAILBOXES | Discovers and syncs mailboxes for an account | accountId | | SYNC_MESSAGES | Fetches new messages for a mailbox (one batch) | accountId, mailboxId | | SYNC_MESSAGE_BODY | Fetches and stores message bodies in batch | accountId, mailboxId, messageIds |

Event Schema

All events share a base schema:

interface BaseEvent {
  accountId: string;
  eventId: string;    // Idempotency key
  timestamp: number;  // Unix timestamp
}

Architecture

SQS Queue
    │
    ▼
┌───────────────┐
│  Lambda/CLI   │
│   (index.ts)  │
└───────┬───────┘
        │
        ▼
┌───────────────┐
│   processor   │  ─── Routes events to handlers
└───────┬───────┘
        │
        ├──► syncMailboxes
        ├──► syncMessages
        └──► syncMessageBody