commune-ai 0.2.66 → 0.3.0

package/README.md

@@ -6,6 +6,21 @@ Email infrastructure for agents — set up an inbox and send your first email in
 npm install commune-ai
 ```
 
+## Table of Contents
+
+- [Quickstart](#quickstart-endtoend-in-one-file)
+- [Unified Inbox](#unified-inbox-what-your-webhook-receives)
+- [API Key](#api-key-required)
+- [Attachments](#attachments)
+- [Semantic Search](#semantic-search)
+- [Context](#context-conversation-state)
+- [Email Handling](#email-handling)
+- [Setup Instructions](#setup-instructions-dashboard-first)
+- [Structured Extraction](#structured-extraction-per-inbox)
+- [Webhook Verification](#webhook-verification-commune--your-app)
+- [Full Example](#full-example-single-file)
+- [Security](#security)
+
 ---
 
 ## Quickstart (end‑to‑end in one file)
@@ -34,7 +49,7 @@ const handler = createWebhookHandler({
     // Example inbound payload:
     // message = {
     //   channel: "email",
-    //   conversation_id: "thread_id",
+    //   thread_id: "thread_abc123",
     //   participants: [{ role: "sender", identity: "user@example.com" }],
     //   content: "Can you help with pricing?"
     // }
@@ -51,8 +66,7 @@ const handler = createWebhookHandler({
       channel: "email",
       to: sender,
       text: agentReply,
-      conversation_id: message.conversation_id,
-      domainId: context.payload.domainId,
+      thread_id: message.thread_id,
       inboxId: context.payload.inboxId,
     });
   },
@@ -77,7 +91,7 @@ Every inbound email arrives in this shape:
 export interface UnifiedMessage {
   channel: "email";
   message_id: string;
-  conversation_id: string; // email thread
+  thread_id: string; // email thread
   participants: { role: string; identity: string }[];
   content: string;
   metadata: { ... };
@@ -87,7 +101,7 @@ export interface UnifiedMessage {
 ---
 
 ## API key (required)
-All `/api/*` requests require an API key. Create one in the dashboard and reuse it in your client.
+All `/v1/*` requests require an API key. Create one in the dashboard and reuse it in your client.
 
 ```bash
 export COMMUNE_API_KEY="your_key_from_dashboard"
@@ -301,48 +315,6 @@ for (const result of withAttachments) {
 }
 ```
 
-## Spam Protection
-Commune includes built-in spam detection and protection to keep your agent safe from malicious emails and prevent abuse.
-
-### Automatic Spam Detection
-All incoming emails are automatically analyzed for spam patterns:
-- Content analysis (spam keywords, suspicious patterns)
-- URL validation (broken links, phishing detection)
-- Sender reputation tracking
-- Domain blacklist checking
-
-Spam emails are automatically rejected before reaching your webhook, protecting your agent from:
-- Phishing attempts
-- Malicious links
-- Mass spam campaigns
-- Fraudulent content
-
-### Outbound Protection
-Commune also protects your sending reputation:
-- Rate limiting per organization tier
-- Content validation for outbound emails
-- Burst detection for mass mailing
-- Automatic blocking of spam-like content
-
-This ensures your domain maintains high deliverability and isn't flagged by email providers.
-
-### Spam Reporting
-If a spam email gets through, you can report it:
-
-```ts
-import { CommuneClient } from "commune-ai";
-const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
-
-// Report a message as spam
-await client.reportSpam({
-  message_id: "msg_123",
-  reason: "Unsolicited marketing email",
-  classification: "spam" // or "phishing", "malware", "other"
-});
-```
-
-The system learns from reports and automatically blocks repeat offenders.
-
 ## Context (conversation state)
 Commune stores conversation state so your agent can respond with context.
 
@@ -351,7 +323,7 @@ import { CommuneClient } from "commune-ai";
 const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
 // Thread history (email thread)
-const thread = await client.messages.listByConversation(message.conversation_id, {
+const thread = await client.messages.listByThread(message.thread_id, {
   order: "asc",
   limit: 50,
 });
@@ -391,8 +363,7 @@ const handler = createWebhookHandler({
       channel: "email",
       to: sender,
       text: "Got it — thanks for the message.",
-      conversation_id: message.conversation_id,
-      domainId: context.payload.domainId,
+      thread_id: message.thread_id,
       inboxId: context.payload.inboxId,
     });
   },
@@ -432,8 +403,7 @@ await client.messages.send({
   channel: "email",
   to: "user@example.com",
   text: "Thanks — replying in thread.",
-  conversation_id: message.conversation_id,
-  domainId: context.payload.domainId,
+  thread_id: message.thread_id,
   inboxId: context.payload.inboxId,
 });
 ```
@@ -628,8 +598,7 @@ const handler = createWebhookHandler({
       subject: "Your receipt",
       text: "Thanks! Here's your receipt.",
       attachments: [attachment_id],
-      conversation_id: message.conversation_id,
-      domainId: context.payload.domainId,
+      thread_id: message.thread_id,
       inboxId: context.payload.inboxId,
     });
   },
@@ -639,3 +608,113 @@ const app = express();
 app.post("/commune/webhook", express.raw({ type: "*/*" }), handler);
 app.listen(3000, () => console.log("listening on 3000"));
 ```
+
+---
+
+## Security
+
+Commune is built as production email infrastructure — deliverability, authentication, and abuse prevention are handled at the platform level so you don't have to build them yourself.
+
+### Email Authentication (DKIM, SPF, DMARC)
+
+Every custom domain you verify through Commune is configured with proper email authentication records:
+
+- **DKIM** — All outbound emails are cryptographically signed. The signing keys are managed by Commune; you add the CNAME record to your DNS during domain setup.
+- **SPF** — Sender Policy Framework records authorize Commune's mail servers to send on behalf of your domain, preventing spoofing.
+- **DMARC** — Domain-based Message Authentication is configured to instruct receiving mail servers how to handle unauthenticated messages from your domain.
+
+When you verify a domain, the DNS records returned include all three. Once added and verified, your domain passes authentication checks at Gmail, Outlook, and other major providers.
+
+### Inbound Spam Protection
+
+All inbound email is analyzed before it reaches your inbox or webhook:
+
+- **Content analysis** — Subject and body are scored for spam patterns, phishing keywords, and suspicious formatting.
+- **URL validation** — Links are checked for phishing indicators, typosquatting, and low-authority domains.
+- **Sender reputation** — Each sender builds a reputation score over time. Repeat offenders are automatically blocked.
+- **Domain authority** — Sender domains are checked for MX records, SPF, DMARC, valid SSL, and structural red flags.
+- **DNSBL checking** — Sender IPs are checked against DNS-based blackhole lists.
+- **Mass attack detection** — Burst patterns (high volume + low quality) are detected per-organization and throttled automatically.
+
+Emails scoring above the reject threshold are silently dropped. Borderline emails are flagged with spam metadata in the message object so your agent can decide how to handle them.
+
+### Outbound Protection
+
+Outbound emails are validated before sending to protect your domain reputation:
+
+- **Content scanning** — Outgoing messages are checked for spam-like patterns before delivery.
+- **Recipient limits** — Maximum 50 recipients per message to prevent mass mailing.
+- **Redis-backed rate limiting** — Distributed sliding-window rate limiting powered by Redis (with in-memory fallback). Accurate across multiple server instances.
+- **Burst detection** — Real-time burst detection using Redis sorted sets with dual sliding windows (10-second and 60-second). Sudden spikes in send volume are automatically throttled with a `429` response.
+
+### Attachment Scanning
+
+All inbound attachments are scanned before storage:
+
+- **ClamAV integration** — When a ClamAV daemon is available (via `CLAMAV_HOST`), attachments are scanned using the INSTREAM protocol over TCP.
+- **Heuristic fallback** — When ClamAV is unavailable, a multi-layer heuristic scanner checks file extensions, MIME types, magic bytes, double extensions, VBA macros in Office documents, and suspicious archive files.
+- **Known threat database** — File hashes (SHA-256) are stored for all detected threats. Subsequent uploads of the same file are instantly blocked.
+- **Quarantine** — Dangerous attachments are quarantined (not stored) and flagged in the message metadata.
+
+### Encryption at Rest
+
+When `EMAIL_ENCRYPTION_KEY` is set (64 hex characters = 256 bits):
+
+- Email body (`content`, `content_html`) and subject are encrypted with **AES-256-GCM** before storage in MongoDB.
+- Attachment content stored in the database is also encrypted.
+- Each encrypted value uses a unique random IV and includes a GCM authentication tag for tamper detection.
+- Decryption is transparent — the API returns plaintext to authorized callers.
+- Existing unencrypted data continues to work (the system detects the `enc:` prefix).
+
+### DMARC Reporting
+
+Commune provides end-to-end DMARC aggregate report processing:
+
+- **Report ingestion** — Submit DMARC XML reports via `POST /v1/dmarc/reports` (supports XML, gzip, and zip formats).
+- **Automatic parsing** — Reports are parsed following RFC 7489 Appendix C, extracting per-record authentication results.
+- **Failure alerting** — Authentication failures above 10% trigger warnings in server logs.
+- **Summary API** — `GET /v1/dmarc/summary?domain=example.com&days=30` returns pass/fail rates, DKIM/SPF breakdowns, and top sending IPs.
+- **Auto-cleanup** — Reports older than 1 year are automatically removed via TTL index.
+
+### Delivery Metrics & Bounce Handling
+
+Bounces, complaints, and delivery events are tracked automatically:
+
+- **Automatic suppression** — Hard bounces and spam complaints automatically add recipients to the suppression list.
+- **Delivery metrics API** — `GET /v1/delivery/metrics?inbox_id=...&days=7` returns sent, delivered, bounced, complained, and failed counts with calculated rates.
+- **Event stream** — `GET /v1/delivery/events?inbox_id=...` lists recent delivery events for debugging.
+- **Suppression list** — `GET /v1/delivery/suppressions?inbox_id=...` shows all suppressed addresses.
+
+### Rate Limits
+
+| Tier | Emails/hour | Emails/day | Domains/day | Inboxes/day |
+|------|-------------|------------|-------------|-------------|
+| Free | 100 | 1,000 | 5 | 50 |
+| Pro | 10,000 | 100,000 | 50 | 500 |
+| Enterprise | Unlimited | Unlimited | Unlimited | Unlimited |
+
+Rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`) are included in API responses.
+
+### API Key Security
+
+- API keys use the `comm_` prefix followed by 64 cryptographically random hex characters.
+- Keys are **bcrypt-hashed** before storage — the raw key is only shown once at creation.
+- Each key has **granular permission scopes**: `domains:read`, `domains:write`, `inboxes:read`, `inboxes:write`, `threads:read`, `messages:read`, `messages:write`, `attachments:read`, `attachments:write`.
+- Keys are scoped to a single organization and can be revoked or rotated at any time from the dashboard.
+- Maximum 10 active keys per organization.
+
+### Webhook Verification
+
+Inbound webhook payloads from Commune are signed with your inbox webhook secret. Always verify the signature before processing — see the [Webhook Verification](#webhook-verification-commune--your-app) section above for the full implementation.
+
+### Attachment Security
+
+- Uploaded attachments are stored in secure cloud storage with per-object access control.
+- Download URLs are **temporary** (default 1 hour, configurable up to 24 hours) and expire automatically.
+- Attachments are scoped to the organization that uploaded them.
+
+---
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -22,9 +22,37 @@ export declare class CommuneClient {
         status: (domainId: string) => Promise<Record<string, unknown>>;
     };
     inboxes: {
-        list: (domainId: string) => Promise<InboxEntry[]>;
-        create: (domainId: string, payload: {
+        /**
+         * List inboxes.
+         *
+         * @param domainId - Optional domain ID to filter by. If omitted, lists all inboxes across all domains.
+         * @example
+         * // List all inboxes
+         * const allInboxes = await commune.inboxes.list();
+         *
+         * // List inboxes for a specific domain
+         * const domainInboxes = await commune.inboxes.list('domain-id');
+         */
+        list: (domainId?: string) => Promise<InboxEntry[]>;
+        /**
+         * Create a new inbox.
+         *
+         * @param payload - Inbox configuration
+         * @example
+         * // Simple creation with auto-resolved domain (recommended)
+         * const inbox = await commune.inboxes.create({
+         *   localPart: 'support',
+         * });
+         *
+         * // With explicit domain (for custom domains)
+         * const inbox = await commune.inboxes.create({
+         *   localPart: 'support',
+         *   domainId: 'my-domain-id',
+         * });
+         */
+        create: (payload: {
             localPart: string;
+            domainId?: string;
             agent?: InboxEntry["agent"];
             webhook?: InboxEntry["webhook"];
             status?: string;
@@ -60,7 +88,10 @@ export declare class CommuneClient {
     messages: {
         send: (payload: SendMessagePayload) => Promise<Record<string, unknown>>;
         list: (params: MessageListParams) => Promise<UnifiedMessage[]>;
-        listByConversation: (conversationId: string, params?: MessageListParams) => Promise<UnifiedMessage[]>;
+        listByThread: (threadId: string, params?: {
+            limit?: number;
+            order?: "asc" | "desc";
+        }) => Promise<UnifiedMessage[]>;
     };
     conversations: {
         search: (query: string, filter: SearchFilter, options?: SearchOptions) => Promise<SearchResult[]>;

package/dist/client.js

@@ -1,5 +1,5 @@
 import { SearchClient } from './client/search.js';
-const DEFAULT_BASE_URL = 'https://web-production-3f46f.up.railway.app';
+const DEFAULT_BASE_URL = 'https://api.commune.email';
 const buildQuery = (params) => {
     const query = new URLSearchParams();
     Object.entries(params).forEach(([key, value]) => {
@@ -15,71 +15,110 @@ export class CommuneClient {
     constructor(options) {
         this.domains = {
             list: async () => {
-                const response = await this.request(`/api/domains`);
+                const response = await this.request(`/v1/domains`);
                 if (Array.isArray(response)) {
                     return response;
                 }
                 return Array.isArray(response.data) ? response.data : [];
             },
             create: async (payload) => {
-                return this.request(`/api/domains`, {
+                return this.request(`/v1/domains`, {
                     method: 'POST',
                     json: payload,
                 });
             },
             get: async (domainId) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}`);
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}`);
             },
             verify: async (domainId) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/verify`, { method: 'POST' });
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}/verify`, { method: 'POST' });
             },
             records: async (domainId) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/records`);
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}/records`);
             },
             status: async (domainId) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/status`);
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}/status`);
             },
         };
         this.inboxes = {
+            /**
+             * List inboxes.
+             *
+             * @param domainId - Optional domain ID to filter by. If omitted, lists all inboxes across all domains.
+             * @example
+             * // List all inboxes
+             * const allInboxes = await commune.inboxes.list();
+             *
+             * // List inboxes for a specific domain
+             * const domainInboxes = await commune.inboxes.list('domain-id');
+             */
             list: async (domainId) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/inboxes`);
-            },
-            create: async (domainId, payload) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/inboxes`, {
+                if (domainId) {
+                    return this.request(`/v1/domains/${encodeURIComponent(domainId)}/inboxes`);
+                }
+                return this.request(`/v1/inboxes`);
+            },
+            /**
+             * Create a new inbox.
+             *
+             * @param payload - Inbox configuration
+             * @example
+             * // Simple creation with auto-resolved domain (recommended)
+             * const inbox = await commune.inboxes.create({
+             *   localPart: 'support',
+             * });
+             *
+             * // With explicit domain (for custom domains)
+             * const inbox = await commune.inboxes.create({
+             *   localPart: 'support',
+             *   domainId: 'my-domain-id',
+             * });
+             */
+            create: async (payload) => {
+                const { domainId, ...rest } = payload;
+                // If domainId provided, use domain-scoped endpoint for explicit control
+                if (domainId) {
+                    return this.request(`/v1/domains/${encodeURIComponent(domainId)}/inboxes`, {
+                        method: 'POST',
+                        json: rest,
+                    });
+                }
+                // Otherwise use simple auto-resolved endpoint
+                return this.request(`/v1/inboxes`, {
                     method: 'POST',
                     json: payload,
                 });
             },
             update: async (domainId, inboxId, payload) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}`, {
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}`, {
                     method: 'PUT',
                     json: payload,
                 });
             },
             remove: async (domainId, inboxId) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}`, { method: 'DELETE' });
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}`, { method: 'DELETE' });
             },
             setWebhook: async (domainId, inboxId, payload) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}/webhook`, { method: 'POST', json: payload });
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}/webhook`, { method: 'POST', json: payload });
             },
             setExtractionSchema: async (payload) => {
                 const { domainId, inboxId, schema } = payload;
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}/extraction-schema`, { method: 'PUT', json: schema });
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}/extraction-schema`, { method: 'PUT', json: schema });
             },
             removeExtractionSchema: async (payload) => {
                 const { domainId, inboxId } = payload;
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}/extraction-schema`, { method: 'DELETE' });
+                return this.request(`/v1/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}/extraction-schema`, { method: 'DELETE' });
             },
         };
         this.messages = {
             send: async (payload) => {
-                return this.request('/api/messages/send', {
+                return this.request('/v1/messages/send', {
                     method: 'POST',
                     json: payload,
                 });
             },
             list: async (params) => {
-                return this.request(`/api/messages${buildQuery({
+                return this.request(`/v1/messages${buildQuery({
                     sender: params.sender,
                     channel: params.channel,
                     before: params.before,
@@ -90,8 +129,8 @@ export class CommuneClient {
                     inbox_id: params.inbox_id,
                 })}`);
             },
-            listByConversation: async (conversationId, params) => {
-                return this.request(`/api/conversations/${encodeURIComponent(conversationId)}/messages${buildQuery({
+            listByThread: async (threadId, params) => {
+                return this.request(`/v1/threads/${encodeURIComponent(threadId)}/messages${buildQuery({
                     limit: params?.limit,
                     order: params?.order,
                 })}`);
@@ -99,7 +138,7 @@ export class CommuneClient {
         };
         this.conversations = {
             search: async (query, filter, options) => {
-                return this.request('/api/search', {
+                return this.request('/v1/search', {
                     method: 'POST',
                     json: {
                         query,
@@ -109,7 +148,7 @@ export class CommuneClient {
                 });
             },
             index: async (organizationId, conversation) => {
-                return this.request('/api/search/index', {
+                return this.request('/v1/search/index', {
                     method: 'POST',
                     json: {
                         organizationId,
@@ -118,7 +157,7 @@ export class CommuneClient {
                 });
             },
             indexBatch: async (organizationId, conversations) => {
-                return this.request('/api/search/index/batch', {
+                return this.request('/v1/search/index/batch', {
                     method: 'POST',
                     json: {
                         organizationId,
@@ -157,7 +196,7 @@ export class CommuneClient {
         };
         this.attachments = {
             upload: async (content, filename, mimeType) => {
-                return this.request('/api/attachments/upload', {
+                return this.request('/v1/attachments/upload', {
                     method: 'POST',
                     body: JSON.stringify({ content, filename, mimeType }),
                 });
@@ -165,9 +204,9 @@ export class CommuneClient {
             get: async (attachmentId, options) => {
                 if (options?.url) {
                     const expiresIn = options.expiresIn || 3600;
-                    return this.request(`/api/attachments/${encodeURIComponent(attachmentId)}/url?expiresIn=${expiresIn}`);
+                    return this.request(`/v1/attachments/${encodeURIComponent(attachmentId)}/url?expires_in=${expiresIn}`);
                 }
-                return this.request(`/api/attachments/${encodeURIComponent(attachmentId)}`);
+                return this.request(`/v1/attachments/${encodeURIComponent(attachmentId)}`);
             },
         };
         this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { CommuneClient } from './client.js';
-export type { ApiError, ApiResponse, AttachmentRecord, Channel, ConversationListParams, CreateDomainPayload, Direction, DomainEntry, DomainWebhook, InboxEntry, InboxWebhook, InboundEmailWebhookPayload, MessageListParams, MessageMetadata, Participant, ParticipantRole, SendMessagePayload, SvixHeaders, Thread, ThreadListParams, ThreadListResponse, UnifiedMessage, } from './types.js';
-export { verifyResendWebhook } from './webhooks.js';
+export type { ApiError, ApiResponse, AttachmentRecord, Channel, ConversationListParams, CreateDomainPayload, CreateInboxPayload, Direction, DomainEntry, DomainWebhook, InboxEntry, InboxWebhook, InboundEmailWebhookPayload, MessageListParams, MessageMetadata, Participant, ParticipantRole, SendMessagePayload, SvixHeaders, Thread, ThreadListParams, ThreadListResponse, UnifiedMessage, } from './types.js';
+export { verifyResendWebhook, verifyCommuneWebhook, computeCommuneSignature } from './webhooks.js';
+export type { CommuneWebhookHeaders } from './webhooks.js';
 export { createWebhookHandler } from './listener.js';
 export type { CommuneWebhookEvent, CommuneWebhookHandlerContext, CreateWebhookHandlerOptions, } from './listener.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { CommuneClient } from './client.js';
-export { verifyResendWebhook } from './webhooks.js';
+export { verifyResendWebhook, verifyCommuneWebhook, computeCommuneSignature } from './webhooks.js';
 export { createWebhookHandler } from './listener.js';

package/dist/types.d.ts

@@ -18,12 +18,21 @@ export interface MessageMetadata {
     provider?: 'resend' | 'email' | string;
     raw?: unknown;
     extracted_data?: Record<string, any>;
+    spam_score?: number | null;
+    spam_action?: 'accept' | 'flag' | 'reject' | string | null;
+    spam_flagged?: boolean | null;
+    delivery_status?: 'sent' | 'delivered' | 'bounced' | 'failed' | 'complained' | null;
+    prompt_injection_checked?: boolean;
+    prompt_injection_detected?: boolean;
+    prompt_injection_risk?: 'none' | 'low' | 'medium' | 'high' | 'critical';
+    prompt_injection_score?: number;
+    prompt_injection_signals?: string;
 }
 export interface UnifiedMessage {
     _id?: string;
     channel: Channel;
     message_id: string;
-    conversation_id: string;
+    thread_id: string;
     direction: Direction;
     participants: Participant[];
     content: string;
@@ -81,6 +90,7 @@ export interface InboxEntry {
     id: string;
     localPart: string;
     address?: string;
+    displayName?: string;
     agent?: {
         id?: string;
         name?: string;
@@ -96,6 +106,38 @@ export interface InboxEntry {
     createdAt?: string;
     status?: string;
 }
+/**
+ * Payload for creating a new inbox.
+ *
+ * @example
+ * // Simple creation with auto-resolved domain
+ * const payload: CreateInboxPayload = {
+ *   localPart: 'support',
+ * };
+ *
+ * // With explicit domain
+ * const payload: CreateInboxPayload = {
+ *   localPart: 'support',
+ *   domainId: 'domain-id',
+ * };
+ */
+export interface CreateInboxPayload {
+    /** The part before @ in the email address (e.g., "support" → support@domain.com) */
+    localPart: string;
+    /** Optional domain ID. If omitted, Commune auto-assigns to an available domain. */
+    domainId?: string;
+    /** Optional agent configuration */
+    agent?: {
+        name?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /** Optional webhook configuration */
+    webhook?: InboxWebhook;
+    /** Optional status */
+    status?: string;
+    /** Optional display name shown in email clients */
+    displayName?: string;
+}
 export interface DomainEntry {
     id: string;
     name?: string;
@@ -107,7 +149,7 @@ export interface DomainEntry {
     inboxes?: InboxEntry[];
 }
 export interface SendMessagePayload {
-    conversation_id?: string;
+    thread_id?: string;
     to: string | string[];
     text?: string;
     html?: string;
@@ -143,6 +185,7 @@ export interface MessageListParams {
     domain_id?: string;
     inbox_id?: string;
 }
+/** @deprecated Use ThreadListParams instead */
 export interface ConversationListParams {
     limit?: number;
     order?: 'asc' | 'desc';
@@ -154,6 +197,21 @@ export interface SvixHeaders {
     timestamp: string;
     signature: string;
 }
+export interface WebhookSecurityContext {
+    spam: {
+        checked: boolean;
+        score: number;
+        action: string;
+        flagged: boolean;
+    };
+    prompt_injection: {
+        checked: boolean;
+        detected: boolean;
+        risk_level: 'none' | 'low' | 'medium' | 'high' | 'critical';
+        confidence: number;
+        summary?: string;
+    };
+}
 export interface InboundEmailWebhookPayload {
     domainId: string;
     inboxId?: string;
@@ -163,6 +221,7 @@ export interface InboundEmailWebhookPayload {
     message: UnifiedMessage;
     extractedData?: Record<string, any>;
     attachments?: AttachmentMetadata[];
+    security?: WebhookSecurityContext;
 }
 export interface ApiError {
     message?: string;
@@ -202,7 +261,7 @@ export interface SearchResult {
         attachmentCount?: number;
     };
 }
-export interface ConversationMetadata {
+export interface ThreadMetadata {
     subject: string;
     organizationId: string;
     inboxId: string;
@@ -219,7 +278,7 @@ export interface IndexConversationPayload {
     id: string;
     subject: string;
     content: string;
-    metadata: ConversationMetadata;
+    metadata: ThreadMetadata;
 }
 export type SearchType = 'vector' | 'agent';
 export interface Thread {

package/dist/webhooks.d.ts

@@ -1,2 +1,50 @@
 import type { SvixHeaders } from './types.js';
 export declare const verifyResendWebhook: (payload: string, headers: SvixHeaders, secret: string) => unknown;
+export interface CommuneWebhookHeaders {
+    /** The `x-commune-signature` header value, e.g. `"v1=5a3f2b..."` */
+    signature: string;
+    /** The `x-commune-timestamp` header value (Unix milliseconds) */
+    timestamp: string;
+}
+/**
+ * Compute the expected `v1=` HMAC-SHA256 signature for a Commune webhook.
+ *
+ * Matches the backend's `computeSignature(body, timestamp, secret)`.
+ */
+export declare const computeCommuneSignature: (body: string, timestamp: string, secret: string) => string;
+/**
+ * Verify a Commune outbound webhook signature.
+ *
+ * Commune signs every webhook delivery with HMAC-SHA256:
+ * ```
+ * x-commune-signature: v1={HMAC-SHA256(secret, "{timestamp}.{body}")}
+ * x-commune-timestamp: {unix_ms}
+ * ```
+ *
+ * @param rawBody - The raw request body string
+ * @param timestamp - The `x-commune-timestamp` header (Unix ms)
+ * @param signature - The `x-commune-signature` header (`v1=...`)
+ * @param secret - Your inbox webhook secret
+ * @param toleranceMs - Max age in milliseconds (default 300000 = 5 min)
+ * @returns `true` if valid
+ * @throws Error if signature is invalid or timestamp is too old
+ *
+ * @example
+ * ```ts
+ * import { verifyCommuneWebhook } from "commune-ai";
+ *
+ * const isValid = verifyCommuneWebhook({
+ *   rawBody: req.body,
+ *   timestamp: req.headers["x-commune-timestamp"],
+ *   signature: req.headers["x-commune-signature"],
+ *   secret: process.env.COMMUNE_WEBHOOK_SECRET!,
+ * });
+ * ```
+ */
+export declare const verifyCommuneWebhook: (params: {
+    rawBody: string;
+    timestamp: string;
+    signature: string;
+    secret: string;
+    toleranceMs?: number;
+}) => boolean;

package/dist/webhooks.js

@@ -1,3 +1,4 @@
+import crypto from 'crypto';
 import { Webhook } from 'svix';
 export const verifyResendWebhook = (payload, headers, secret) => {
     const webhook = new Webhook(secret);
@@ -8,3 +9,67 @@ export const verifyResendWebhook = (payload, headers, secret) => {
     };
     return webhook.verify(payload, svixHeaders);
 };
+/**
+ * Compute the expected `v1=` HMAC-SHA256 signature for a Commune webhook.
+ *
+ * Matches the backend's `computeSignature(body, timestamp, secret)`.
+ */
+export const computeCommuneSignature = (body, timestamp, secret) => {
+    const digest = crypto
+        .createHmac('sha256', secret)
+        .update(`${timestamp}.${body}`, 'utf8')
+        .digest('hex');
+    return `v1=${digest}`;
+};
+/**
+ * Verify a Commune outbound webhook signature.
+ *
+ * Commune signs every webhook delivery with HMAC-SHA256:
+ * ```
+ * x-commune-signature: v1={HMAC-SHA256(secret, "{timestamp}.{body}")}
+ * x-commune-timestamp: {unix_ms}
+ * ```
+ *
+ * @param rawBody - The raw request body string
+ * @param timestamp - The `x-commune-timestamp` header (Unix ms)
+ * @param signature - The `x-commune-signature` header (`v1=...`)
+ * @param secret - Your inbox webhook secret
+ * @param toleranceMs - Max age in milliseconds (default 300000 = 5 min)
+ * @returns `true` if valid
+ * @throws Error if signature is invalid or timestamp is too old
+ *
+ * @example
+ * ```ts
+ * import { verifyCommuneWebhook } from "commune-ai";
+ *
+ * const isValid = verifyCommuneWebhook({
+ *   rawBody: req.body,
+ *   timestamp: req.headers["x-commune-timestamp"],
+ *   signature: req.headers["x-commune-signature"],
+ *   secret: process.env.COMMUNE_WEBHOOK_SECRET!,
+ * });
+ * ```
+ */
+export const verifyCommuneWebhook = (params) => {
+    const { rawBody, timestamp, signature, secret, toleranceMs = 5 * 60 * 1000 } = params;
+    if (!signature)
+        throw new Error('Missing x-commune-signature header');
+    if (!timestamp)
+        throw new Error('Missing x-commune-timestamp header');
+    if (!secret)
+        throw new Error('Missing webhook secret');
+    const expected = computeCommuneSignature(rawBody, timestamp, secret);
+    // Constant-time comparison
+    if (expected.length !== signature.length) {
+        throw new Error('Invalid webhook signature');
+    }
+    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
+        throw new Error('Invalid webhook signature');
+    }
+    // Replay protection
+    const age = Date.now() - parseInt(timestamp, 10);
+    if (Number.isNaN(age) || age > toleranceMs) {
+        throw new Error(`Webhook timestamp too old (${Math.round(age / 1000)}s)`);
+    }
+    return true;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commune-ai",
-  "version": "0.2.66",
+  "version": "0.3.0",
   "description": "Email infrastructure for agents — set up an inbox and send your first email in 30 seconds. Programmatic inboxes (~1 line), consistent threads, custom domains, attachments, and structured data.",
   "type": "module",
   "main": "dist/index.js",