@ravi-hq/ravi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ravi HQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# @ravi-hq/openclaw-plugin
+
+[![npm version](https://img.shields.io/npm/v/@ravi-hq/openclaw-plugin)](https://www.npmjs.com/package/@ravi-hq/openclaw-plugin)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+OpenClaw plugin for [Ravi](https://ravi.app) -- identity provider for AI agents.
+Gives your agent a real email address, phone number, password manager, and
+encrypted vault through a single plugin.
+
+## Features
+
+- **2 messaging channels** -- real-time email and SMS via Server-Sent Events
+- **17 agent tools** -- manage identities, inboxes, passwords, vault secrets, and more
+- **E2E encryption** -- PIN-based Argon2id + NaCl SealedBox, compatible with Ravi CLI
+- **DM policy controls** -- allowlist or open policy per channel account
+- **Lazy crypto** -- encryption keys derived on first use, not at startup
+
+## Installation
+
+```bash
+openclaw plugins install @ravi-hq/openclaw-plugin
+```
+
+## Quick Start
+
+### 1. Install and authenticate
+
+```bash
+openclaw plugins install @ravi-hq/openclaw-plugin
+openclaw ravi login
+```
+
+This opens a browser for device-code authentication. Copy the access token from the output.
+
+### 2. Add your token and PIN to the plugin config
+
+```yaml
+# In your OpenClaw config
+plugins:
+  ravi:
+    token: "eyJhbGciOiJIUzI1NiIs..."   # From 'openclaw ravi login'
+    pin: "123456"                        # Your 6-digit E2E encryption PIN
+```
+
+### 3. Run setup to configure channels
+
+```bash
+openclaw ravi setup
+```
+
+This lists your identities and generates a channel configuration snippet you
+can paste into your OpenClaw config.
+
+## Configuration
+
+```yaml
+plugins:
+  ravi:
+    # Ravi API base URL (default: https://ravi.app)
+    apiUrl: "https://ravi.app"
+
+    # JWT access token (required)
+    token: "your-access-token"
+
+    # 6-digit E2E encryption PIN (required)
+    pin: "123456"
+
+    # Channel accounts (from 'openclaw ravi setup')
+    channels:
+      ravi-email:
+        accounts:
+          "identity-uuid-here":
+            identityUuid: "identity-uuid-here"
+            identityName: "My Agent"
+            email: "agent@in.ravi.app"
+            dm:
+              policy: "allowlist"           # "allowlist" or "open"
+              allowFrom:
+                - "you@gmail.com"
+
+      ravi-sms:
+        accounts:
+          "identity-uuid-here":
+            identityUuid: "identity-uuid-here"
+            identityName: "My Agent"
+            phone: "+15551234567"
+            dm:
+              policy: "allowlist"           # "allowlist" or "open"
+              allowFrom:
+                - "+15559876543"
+```
+
+## Channels
+
+### Ravi Email
+
+Real-time email channel powered by SSE events from the Ravi backend.
+
+- **Threading model:** Each email thread maps 1:1 to an OpenClaw session. A new
+  `thread_id` creates a new session; subsequent messages in that thread resume it.
+- **Session key format:** `agent:{agentId}:ravi-email:{accountId}:thread:{threadId}`
+- **DM policy:** Set `policy: "allowlist"` to restrict incoming email to specific
+  sender addresses, or `"open"` to accept all senders.
+- **Outbound:** Replies are sent via the Ravi API and threaded correctly in the
+  original email conversation.
+
+### Ravi SMS
+
+Real-time SMS channel powered by the same SSE stream.
+
+- **Threading model:** All messages from one phone number form a single session.
+  A new `from_number` creates a new session; subsequent messages from that number
+  resume it.
+- **Session key format:** `agent:{agentId}:ravi-sms:{accountId}:dm:{phoneNumber}`
+- **DM policy:** Set `policy: "allowlist"` to restrict incoming SMS to specific
+  phone numbers (E.164 format), or `"open"` to accept all senders.
+- **Outbound:** Replies are sent via the Ravi API as plain-text SMS.
+
+## Agent Tools
+
+The plugin registers 17 tools that agents can invoke.
+
+### Identity
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `ravi_identity_list` | List all identities for the authenticated user | -- |
+| `ravi_identity_create` | Create a new identity (provisions email + phone + vault) | `name` (string, required) |
+| `ravi_get_info` | Get the active identity's email and phone number | -- |
+
+### Email Inbox
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `ravi_inbox_email` | List email threads, optionally unread only | `unread` (boolean) |
+| `ravi_read_email` | Read all messages in an email thread | `thread_id` (string, required) |
+| `ravi_email_compose` | Compose and send a new email | `to`, `subject`, `body` (all required) |
+| `ravi_email_reply` | Reply to an existing email | `message_id` (number, required), `body` (required), `reply_all` |
+
+### SMS Inbox
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `ravi_inbox_sms` | List SMS conversations, optionally unread only | `unread` (boolean) |
+| `ravi_read_sms` | Read all messages in an SMS conversation | `conversation_id` (string, required) |
+
+### Passwords
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `ravi_passwords_list` | List all saved passwords (passwords hidden in list view) | -- |
+| `ravi_passwords_get` | Get a specific password entry with decrypted password | `uuid` (string, required) |
+| `ravi_passwords_create` | Create a new password (encrypted) | `domain` (required), `username`, `password`, `notes` |
+| `ravi_passwords_delete` | Delete a password entry | `uuid` (string, required) |
+
+### Vault
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `ravi_vault_list` | List all secret keys in the vault | -- |
+| `ravi_vault_get` | Get a secret by key (auto-decrypted) | `key` (string, required) |
+| `ravi_vault_set` | Store a secret (auto-encrypted) | `key` (string, required), `value` (string, required) |
+
+### Feedback
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `ravi_feedback` | Submit feedback about Ravi | `message` (required), `category` (bug/feature/help/other) |
+
+## CLI Commands
+
+Run these via `openclaw ravi <command>`:
+
+| Command | Description |
+|---------|-------------|
+| `login` | Authenticate via device-code flow (opens browser) |
+| `status` | Show auth status and list available identities |
+| `setup` | Generate channel configuration from your identities |
+
+## E2E Encryption
+
+All sensitive data (passwords, vault secrets, email content at rest) is encrypted
+end-to-end using a 6-digit PIN.
+
+- **Key derivation:** PIN + server-stored salt -> Argon2id (time=3, mem=64MB, threads=1) -> 32-byte seed
+- **Encryption:** NaCl SealedBox (ephemeral X25519 keypair + Poly1305 MAC)
+- **Ciphertext format:** `e2e::<base64>` -- same format used by the Ravi CLI
+- **PIN verification:** On first use, the plugin derives the keypair and verifies
+  it against the server's stored verifier before proceeding
+
+The crypto layer is lazy-initialized: keys are only derived when a tool actually
+needs encryption or decryption.
+
+## Architecture
+
+```text
+Agent (OpenClaw runtime)
+   |
+   +-- Channels (ravi-email, ravi-sms)
+   |     '-- SSE stream --> GET /api/events/stream/
+   |           Events arrive in plaintext (server decrypts before dispatch)
+   |
+   +-- Tools (17 agent tools)
+   |     '-- REST calls --> GET/POST/DELETE /api/...
+   |           Identity-scoped via X-Ravi-Identity header
+   |
+   '-- Crypto layer (lazy-initialized)
+         PIN + salt --> Argon2id --> NaCl SealedBox
+         Decrypts historical data from REST ("e2e::<base64>" fields)
+         Encrypts vault/password writes before sending to server
+```
+
+Key points:
+
+- **SSE events are plaintext** -- the server decrypts before pushing to the stream.
+  No client-side decryption needed for real-time channel messages.
+- **REST data may be encrypted** -- historical email content, passwords, and vault
+  secrets can contain `"e2e::<base64>"` ciphertext that the plugin decrypts
+  client-side using the PIN-derived keypair.
+- **Authentication** uses unbound JWTs. The `X-Ravi-Identity` header scopes each
+  API request to a specific identity.
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm
+
+### Setup
+
+```bash
+npm install
+```
+
+### Scripts
+
+```bash
+npm run build        # Compile TypeScript to dist/
+npm test             # Run tests (vitest, single run)
+npm run test:watch   # Run tests in watch mode
+npm run lint         # Type-check without emitting (tsc --noEmit)
+```
+
+### Project structure
+
+```text
+src/
+  index.ts            # Plugin entry point and registration
+  types.ts            # TypeScript interfaces for API responses and SSE events
+  client.ts           # RaviClient -- typed HTTP client for all REST endpoints
+  sse.ts              # RaviSSEClient -- SSE with auto-reconnect and heartbeat
+  crypto.ts           # E2E encryption (Argon2id + NaCl SealedBox)
+  service.ts          # Background listener service (manages SSE connections)
+  cli.ts              # CLI commands (login, status, setup)
+  channels/
+    email.ts          # ravi-email channel definition
+    sms.ts            # ravi-sms channel definition
+  tools/
+    identity.ts       # Identity management tools
+    inbox.ts          # Email and SMS inbox tools
+    email-send.ts     # Email compose and reply tools
+    passwords.ts      # Password manager tools
+    vault.ts          # Vault secret tools
+    feedback.ts       # Feedback tool
+  __tests__/          # Test files (*.test.ts)
+```
+
+## License
+
+MIT

package/dist/channels/email.d.ts

@@ -0,0 +1,221 @@
+import type { RaviClient } from "../client.js";
+import type { EmailEvent } from "../types.js";
+/** Configuration for a single email account within the ravi-email channel. */
+export interface EmailAccountConfig {
+    /** The identity UUID this account is bound to. */
+    identityUuid: string;
+    /** Human-readable identity name for display purposes. */
+    identityName: string;
+    /** The email address provisioned for this identity. */
+    email: string;
+}
+/**
+ * Thread context passed alongside outbound messages so the channel
+ * can thread replies correctly in the original email conversation.
+ */
+export interface EmailThreadContext {
+    /** The email thread identifier (maps 1:1 to an OpenClaw session). */
+    threadId: string;
+    /** Numeric ID of the last message in the thread (used for reply targeting). */
+    lastMessageId: number;
+    /** Subject line of the email thread. */
+    subject: string;
+}
+/** Normalized inbound message envelope produced by {@link normalizeInbound}. */
+export interface EmailInboundEnvelope {
+    /** Sender's email address (used as the sender ID). */
+    senderId: string;
+    /** Plain-text body extracted from the email (falls back to subject). */
+    text: string;
+    /** Thread ID that maps to the OpenClaw session key. */
+    threadId: string;
+    /** Additional email metadata passed through to the agent. */
+    metadata: {
+        senderType: string;
+        readOnly: boolean;
+        subject: string;
+        fromDisplayName: string;
+        htmlContent: string;
+        attachments: number;
+        inReplyTo: string | null;
+        lastMessageId: number;
+    };
+}
+/**
+ * Creates the ravi-email channel definition for OpenClaw.
+ *
+ * Each email thread maps to exactly one OpenClaw session (1:1):
+ * - A new `thread_id` triggers creation of a new session.
+ * - A known `thread_id` resumes the existing session.
+ *
+ * The channel is a plain object (not a class) following OpenClaw's
+ * declarative channel convention.
+ *
+ * @returns The ravi-email channel definition object.
+ */
+export declare function createEmailChannel(): {
+    id: "ravi-email";
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        blurb: string;
+        aliases: string[];
+    };
+    capabilities: {
+        chatTypes: readonly ["direct"];
+    };
+    config: {
+        /**
+         * List all configured account IDs (identity UUIDs) for the ravi-email channel.
+         *
+         * @param cfg - The full OpenClaw plugin configuration object.
+         * @returns Array of identity UUID strings.
+         */
+        listAccountIds: (cfg: Record<string, unknown>) => string[];
+        /**
+         * Resolve an account configuration by its ID (identity UUID).
+         *
+         * Returns a default empty config if the account is not found rather than
+         * throwing, so callers can handle missing accounts gracefully.
+         *
+         * @param cfg - The full OpenClaw plugin configuration object.
+         * @param accountId - The identity UUID to look up.
+         * @returns The resolved {@link EmailAccountConfig}.
+         */
+        resolveAccount: (cfg: Record<string, unknown>, accountId: string) => EmailAccountConfig;
+    };
+    /**
+     * Normalize an inbound SSE email event into a channel message envelope.
+     *
+     * All messages are passed through — the backend classifies senders via
+     * `sender_type`. External senders are marked read-only so the agent
+     * treats them as context without responding or using write tools.
+     *
+     * @param event - The raw {@link EmailEvent} from the SSE stream.
+     * @param account - The {@link EmailAccountConfig} for the receiving identity.
+     * @returns A normalized {@link EmailInboundEnvelope} (never null).
+     */
+    normalizeInbound(event: EmailEvent, account: EmailAccountConfig): EmailInboundEnvelope | null;
+    outbound: {
+        deliveryMode: "direct";
+        /**
+         * Send a reply to the email thread that triggered this session.
+         *
+         * Wraps the plain-text body in HTML and calls {@link RaviClient.replyToEmail}
+         * using the thread context to target the correct message for threading.
+         *
+         * @param params.text - Plain-text reply body.
+         * @param params.client - An authenticated {@link RaviClient} instance.
+         * @param params.threadContext - Thread context from the inbound event.
+         * @returns A result object indicating success or failure.
+         */
+        sendText: (params: {
+            text: string;
+            client: RaviClient;
+            threadContext?: EmailThreadContext;
+        }) => Promise<{
+            ok: boolean;
+            error?: string;
+        }>;
+    };
+    /**
+     * Generate the session key for this channel.
+     *
+     * The key uniquely identifies a session by combining the agent, account,
+     * and thread. OpenClaw uses this to route inbound events to the correct
+     * session and persist session state.
+     *
+     * Format: `agent:{agentId}:ravi-email:{accountId}:thread:{threadId}`
+     *
+     * @param agentId - The OpenClaw agent identifier.
+     * @param accountId - The identity UUID (account ID).
+     * @param threadId - The email thread identifier.
+     * @returns The deterministic session key string.
+     */
+    getSessionKey(agentId: string, accountId: string, threadId: string): string;
+};
+/** The singleton ravi-email channel instance. */
+export declare const raviEmailChannel: {
+    id: "ravi-email";
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        blurb: string;
+        aliases: string[];
+    };
+    capabilities: {
+        chatTypes: readonly ["direct"];
+    };
+    config: {
+        /**
+         * List all configured account IDs (identity UUIDs) for the ravi-email channel.
+         *
+         * @param cfg - The full OpenClaw plugin configuration object.
+         * @returns Array of identity UUID strings.
+         */
+        listAccountIds: (cfg: Record<string, unknown>) => string[];
+        /**
+         * Resolve an account configuration by its ID (identity UUID).
+         *
+         * Returns a default empty config if the account is not found rather than
+         * throwing, so callers can handle missing accounts gracefully.
+         *
+         * @param cfg - The full OpenClaw plugin configuration object.
+         * @param accountId - The identity UUID to look up.
+         * @returns The resolved {@link EmailAccountConfig}.
+         */
+        resolveAccount: (cfg: Record<string, unknown>, accountId: string) => EmailAccountConfig;
+    };
+    /**
+     * Normalize an inbound SSE email event into a channel message envelope.
+     *
+     * All messages are passed through — the backend classifies senders via
+     * `sender_type`. External senders are marked read-only so the agent
+     * treats them as context without responding or using write tools.
+     *
+     * @param event - The raw {@link EmailEvent} from the SSE stream.
+     * @param account - The {@link EmailAccountConfig} for the receiving identity.
+     * @returns A normalized {@link EmailInboundEnvelope} (never null).
+     */
+    normalizeInbound(event: EmailEvent, account: EmailAccountConfig): EmailInboundEnvelope | null;
+    outbound: {
+        deliveryMode: "direct";
+        /**
+         * Send a reply to the email thread that triggered this session.
+         *
+         * Wraps the plain-text body in HTML and calls {@link RaviClient.replyToEmail}
+         * using the thread context to target the correct message for threading.
+         *
+         * @param params.text - Plain-text reply body.
+         * @param params.client - An authenticated {@link RaviClient} instance.
+         * @param params.threadContext - Thread context from the inbound event.
+         * @returns A result object indicating success or failure.
+         */
+        sendText: (params: {
+            text: string;
+            client: RaviClient;
+            threadContext?: EmailThreadContext;
+        }) => Promise<{
+            ok: boolean;
+            error?: string;
+        }>;
+    };
+    /**
+     * Generate the session key for this channel.
+     *
+     * The key uniquely identifies a session by combining the agent, account,
+     * and thread. OpenClaw uses this to route inbound events to the correct
+     * session and persist session state.
+     *
+     * Format: `agent:{agentId}:ravi-email:{accountId}:thread:{threadId}`
+     *
+     * @param agentId - The OpenClaw agent identifier.
+     * @param accountId - The identity UUID (account ID).
+     * @param threadId - The email thread identifier.
+     * @returns The deterministic session key string.
+     */
+    getSessionKey(agentId: string, accountId: string, threadId: string): string;
+};
+//# sourceMappingURL=email.d.ts.map

package/dist/channels/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../src/channels/email.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;CAEf;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,gFAAgF;AAChF,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,EAAE;QACR,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,eAAe,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB;;;;;;;;;;;;;QAkB5B;;;;;WAKG;8BACmB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,EAAE;QAOxD;;;;;;;;;WASG;8BAEI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aACjB,MAAM,KAChB,kBAAkB;;IAgBvB;;;;;;;;;;OAUG;4BAEM,UAAU,WACR,kBAAkB,GAC1B,oBAAoB,GAAG,IAAI;;;QAuB5B;;;;;;;;;;WAUG;2BACsB;YACvB,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,UAAU,CAAC;YACnB,aAAa,CAAC,EAAE,kBAAkB,CAAC;SACpC,KAAG,OAAO,CAAC;YAAE,EAAE,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;;IAoB9C;;;;;;;;;;;;;OAaG;2BACoB,MAAM,aAAa,MAAM,YAAY,MAAM,GAAG,MAAM;EAI9E;AAED,iDAAiD;AACjD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;QAvIvB;;;;;WAKG;8BACmB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,EAAE;QAOxD;;;;;;;;;WASG;8BAEI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aACjB,MAAM,KAChB,kBAAkB;;IAgBvB;;;;;;;;;;OAUG;4BAEM,UAAU,WACR,kBAAkB,GAC1B,oBAAoB,GAAG,IAAI;;;QAuB5B;;;;;;;;;;WAUG;2BACsB;YACvB,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,UAAU,CAAC;YACnB,aAAa,CAAC,EAAE,kBAAkB,CAAC;SACpC,KAAG,OAAO,CAAC;YAAE,EAAE,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;;IAoB9C;;;;;;;;;;;;;OAaG;2BACoB,MAAM,aAAa,MAAM,YAAY,MAAM,GAAG,MAAM;CAO3B,CAAC"}

package/dist/channels/email.js

@@ -0,0 +1,143 @@
+import { wrapInHtml } from "../utils.js";
+// ─── Channel Definition ──────────────────────────────────────────────────────
+/**
+ * Creates the ravi-email channel definition for OpenClaw.
+ *
+ * Each email thread maps to exactly one OpenClaw session (1:1):
+ * - A new `thread_id` triggers creation of a new session.
+ * - A known `thread_id` resumes the existing session.
+ *
+ * The channel is a plain object (not a class) following OpenClaw's
+ * declarative channel convention.
+ *
+ * @returns The ravi-email channel definition object.
+ */
+export function createEmailChannel() {
+    return {
+        id: "ravi-email",
+        meta: {
+            id: "ravi-email",
+            label: "Ravi Email",
+            selectionLabel: "Ravi Email (AI Agent Identity)",
+            blurb: "Email channel via Ravi identity provider. Each email thread becomes a separate agent session.",
+            aliases: ["ravi-mail"],
+        },
+        capabilities: {
+            chatTypes: ["direct"],
+        },
+        config: {
+            /**
+             * List all configured account IDs (identity UUIDs) for the ravi-email channel.
+             *
+             * @param cfg - The full OpenClaw plugin configuration object.
+             * @returns Array of identity UUID strings.
+             */
+            listAccountIds: (cfg) => {
+                const channels = cfg.channels;
+                return Object.keys(channels?.["ravi-email"]?.accounts ?? {});
+            },
+            /**
+             * Resolve an account configuration by its ID (identity UUID).
+             *
+             * Returns a default empty config if the account is not found rather than
+             * throwing, so callers can handle missing accounts gracefully.
+             *
+             * @param cfg - The full OpenClaw plugin configuration object.
+             * @param accountId - The identity UUID to look up.
+             * @returns The resolved {@link EmailAccountConfig}.
+             */
+            resolveAccount: (cfg, accountId) => {
+                const channels = cfg.channels;
+                const found = channels?.["ravi-email"]?.accounts?.[accountId];
+                if (!found) {
+                    console.warn(`[ravi] Email account ${accountId} not found in config — using empty defaults`);
+                }
+                return found ?? {
+                    identityUuid: accountId,
+                    identityName: "",
+                    email: "",
+                };
+            },
+        },
+        /**
+         * Normalize an inbound SSE email event into a channel message envelope.
+         *
+         * All messages are passed through — the backend classifies senders via
+         * `sender_type`. External senders are marked read-only so the agent
+         * treats them as context without responding or using write tools.
+         *
+         * @param event - The raw {@link EmailEvent} from the SSE stream.
+         * @param account - The {@link EmailAccountConfig} for the receiving identity.
+         * @returns A normalized {@link EmailInboundEnvelope} (never null).
+         */
+        normalizeInbound(event, account) {
+            const isReadOnly = event.sender_type !== "owner" && event.sender_type !== "self";
+            return {
+                senderId: event.from_email,
+                text: event.text_content || event.subject,
+                threadId: event.thread_id,
+                metadata: {
+                    senderType: event.sender_type,
+                    readOnly: isReadOnly,
+                    subject: event.subject,
+                    fromDisplayName: event.from_display_name,
+                    htmlContent: event.html_content,
+                    attachments: event.attachments,
+                    inReplyTo: event.in_reply_to,
+                    lastMessageId: Number(event.id) || 0,
+                },
+            };
+        },
+        outbound: {
+            deliveryMode: "direct",
+            /**
+             * Send a reply to the email thread that triggered this session.
+             *
+             * Wraps the plain-text body in HTML and calls {@link RaviClient.replyToEmail}
+             * using the thread context to target the correct message for threading.
+             *
+             * @param params.text - Plain-text reply body.
+             * @param params.client - An authenticated {@link RaviClient} instance.
+             * @param params.threadContext - Thread context from the inbound event.
+             * @returns A result object indicating success or failure.
+             */
+            sendText: async (params) => {
+                const { text, client, threadContext } = params;
+                if (!threadContext?.lastMessageId) {
+                    return {
+                        ok: false,
+                        error: "No email thread context — cannot reply without a message to reply to",
+                    };
+                }
+                try {
+                    await client.replyToEmail(threadContext.lastMessageId, wrapInHtml(text));
+                    return { ok: true };
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : "Unknown error";
+                    return { ok: false, error: `Failed to send email reply: ${message}` };
+                }
+            },
+        },
+        /**
+         * Generate the session key for this channel.
+         *
+         * The key uniquely identifies a session by combining the agent, account,
+         * and thread. OpenClaw uses this to route inbound events to the correct
+         * session and persist session state.
+         *
+         * Format: `agent:{agentId}:ravi-email:{accountId}:thread:{threadId}`
+         *
+         * @param agentId - The OpenClaw agent identifier.
+         * @param accountId - The identity UUID (account ID).
+         * @param threadId - The email thread identifier.
+         * @returns The deterministic session key string.
+         */
+        getSessionKey(agentId, accountId, threadId) {
+            return `agent:${agentId}:ravi-email:${accountId}:thread:${threadId}`;
+        },
+    };
+}
+/** The singleton ravi-email channel instance. */
+export const raviEmailChannel = createEmailChannel();
+//# sourceMappingURL=email.js.map

package/dist/channels/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../../src/channels/email.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAmDzC,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,EAAE,EAAE,YAAqB;QAEzB,IAAI,EAAE;YACJ,EAAE,EAAE,YAAY;YAChB,KAAK,EAAE,YAAY;YACnB,cAAc,EAAE,gCAAgC;YAChD,KAAK,EACH,+FAA+F;YACjG,OAAO,EAAE,CAAC,WAAW,CAAC;SACvB;QAED,YAAY,EAAE;YACZ,SAAS,EAAE,CAAC,QAAQ,CAAU;SAC/B;QAED,MAAM,EAAE;YACN;;;;;eAKG;YACH,cAAc,EAAE,CAAC,GAA4B,EAAY,EAAE;gBACzD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAER,CAAC;gBACd,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,YAAY,CAAC,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC;YAC/D,CAAC;YAED;;;;;;;;;eASG;YACH,cAAc,EAAE,CACd,GAA4B,EAC5B,SAAiB,EACG,EAAE;gBACtB,MAAM,QAAQ,GAAG,GAAG,CAAC,QAER,CAAC;gBACd,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC,SAAS,CAAC,CAAC;gBAC9D,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,OAAO,CAAC,IAAI,CAAC,wBAAwB,SAAS,6CAA6C,CAAC,CAAC;gBAC/F,CAAC;gBACD,OAAO,KAAK,IAAI;oBACd,YAAY,EAAE,SAAS;oBACvB,YAAY,EAAE,EAAE;oBAChB,KAAK,EAAE,EAAE;iBACV,CAAC;YACJ,CAAC;SACF;QAED;;;;;;;;;;WAUG;QACH,gBAAgB,CACd,KAAiB,EACjB,OAA2B;YAE3B,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,KAAK,OAAO,IAAI,KAAK,CAAC,WAAW,KAAK,MAAM,CAAC;YAEjF,OAAO;gBACL,QAAQ,EAAE,KAAK,CAAC,UAAU;gBAC1B,IAAI,EAAE,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,OAAO;gBACzC,QAAQ,EAAE,KAAK,CAAC,SAAS;gBACzB,QAAQ,EAAE;oBACR,UAAU,EAAE,KAAK,CAAC,WAAW;oBAC7B,QAAQ,EAAE,UAAU;oBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,eAAe,EAAE,KAAK,CAAC,iBAAiB;oBACxC,WAAW,EAAE,KAAK,CAAC,YAAY;oBAC/B,WAAW,EAAE,KAAK,CAAC,WAAW;oBAC9B,SAAS,EAAE,KAAK,CAAC,WAAW;oBAC5B,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC;iBACrC;aACF,CAAC;QACJ,CAAC;QAED,QAAQ,EAAE;YACR,YAAY,EAAE,QAAiB;YAE/B;;;;;;;;;;eAUG;YACH,QAAQ,EAAE,KAAK,EAAE,MAIhB,EAA4C,EAAE;gBAC7C,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC;gBAE/C,IAAI,CAAC,aAAa,EAAE,aAAa,EAAE,CAAC;oBAClC,OAAO;wBACL,EAAE,EAAE,KAAK;wBACT,KAAK,EAAE,sEAAsE;qBAC9E,CAAC;gBACJ,CAAC;gBAED,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,aAAa,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;oBACzE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;gBACtB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;oBACzE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,+BAA+B,OAAO,EAAE,EAAE,CAAC;gBACxE,CAAC;YACH,CAAC;SACF;QAED;;;;;;;;;;;;;WAaG;QACH,aAAa,CAAC,OAAe,EAAE,SAAiB,EAAE,QAAgB;YAChE,OAAO,SAAS,OAAO,eAAe,SAAS,WAAW,QAAQ,EAAE,CAAC;QACvE,CAAC;KACF,CAAC;AACJ,CAAC;AAED,iDAAiD;AACjD,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,EAAE,CAAC"}